diff --git a/README.rst b/README.rst index 2e45865b..e4003f95 100644 --- a/README.rst +++ b/README.rst @@ -71,7 +71,7 @@ Install From Pre-built Packages ------------------------------- Python Package Index (PyPI) +++++++++++++++++++++++++++ -Starting with version 0.11.0a1 we provide a PyPI wheel package for HSP2 which +Starting with version 0.11.0a1 we provide `a PyPI wheel package for HSP2`_ which should work on any supported platform for Python 3.10, 3.11, and 3.12. .. code-block:: console @@ -113,13 +113,17 @@ Option 1: Install using "conda" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Follow these steps to install using the conda_ package manager. -1. Install the Anaconda Python Distribution +1. Install Miniconda or Anaconda Python Distribution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Install the `latest release`_ of the Anaconda Distribution, which includes the -conda package manager, a complete Python (and R) data science stack, and the -Anaconda Navigator GUI. Follow `Anaconda Installation`_ documentation. +We recommend installing the light-weight Miniconda_ that includes Python, the +conda_ environment and package management system, and their dependencies. + +NOTE: Follow conda defaults to install in your local user directory. DO NOT +install for all users, to avoid substantial headaches with permissions. + +If you have already installed the Anaconda Distribution, you can use it to +complete the next steps, but you may need to update to the `latest release`_. -A lighter-weight alternative is to install Miniconda_. 2. Create a Conda Environment for HSP2 Modeling (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -147,6 +151,14 @@ Install the necessary and optional packages for HSP2 in the new environment: cd /path/to/module/hsp2 pip install . # or "pip install -e ." to install in editable mode +**Alternately**, you can replace all of the create and install steps above by +creating the new environment from the included `environment.yml` file +from this single line of code: + +.. code-block:: console + + conda env create --file=environment.yml --solver=libmamba + You should now be able to run the Tutorials and create your own Jupyter Notebooks! @@ -223,6 +235,7 @@ The HSP2 API is designed to be used in Python scripts and Jupyter notebooks. .. _`initial release`: https://github.com/respec/HSPsquared/releases/tag/0.7.7 .. _`GNU Affero General Public License (AGPL), copyrighted 2017 by RESPEC`: https://github.com/respec/HSPsquared/blob/master/LICENSE .. _JupyterLab: https://jupyterlab.readthedocs.io/en/stable/ +.. _`a PyPI wheel package for HSP2`: https://pypi.org/project/hsp2/ .. _conda: https://docs.conda.io/en/latest/ .. _`latest release`: https://docs.anaconda.com/anaconda/reference/release-notes/ .. _`Anaconda Installation`: https://docs.anaconda.com/anaconda/install/ diff --git a/environment.yml b/environment.yml index b48ba137..0af2b998 100644 --- a/environment.yml +++ b/environment.yml @@ -1,58 +1,50 @@ --- -name: hsp2_py38 +name: hsp2_py310 channels: - - conda-forge + - conda-forge + - nodefaults # Speeds solving env, by limiting the number of options dependencies: - # Aligned with Anaconda 2021.05 (May 13, 2021) - # package management - - conda - - conda-build - - pip + # Python 3.10 was default for Anaconda 2023.03-0 (Mar 20, 2023) + # https://docs.anaconda.com/free/anaconda/release-notes/#anaconda-2023-03-0-mar-20-2023 + # package management + - conda + - conda-build + - conda-libmamba-solver + - pip - # Running HSP2 - - python =3.8* - - scipy # Scipy also installs numpy - # Pandas installs most scientific Python modules, such as Numpy, etc. - - pandas ==1.2.* - - numba ==0.53.1 - - numpy ==1.20.* # for compatibility with numba version <0.53 - # latest compatible with both versions of PyTables & h5py below - # - doesn't work with setup.py - - hdf5 ==1.10.6 - - pytables ==3.6.1 - - h5py >=3.1 - - hdf5plugin # HDF5 compression filters for h5py & jupyterlab_hdf - - cltoolbox + # Running HSP2 + - python =3.10 + - scipy # Scipy also installs numpy + # Pandas installs most scientific Python modules, such as Numpy, etc. + - pandas + - numba + - numpy + - hdf5 + - pytables + - h5py + - hdf5plugin # HDF5 compression filters for h5py & jupyterlab_hdf + - cltoolbox - # Interactivity & Visualization via Jupyter Notebooks - # (optional, but required for tutorials) - - jupyterlab ==3.0.* # also installs classic Jupyter notbook - - ipympl # jupyter-matplotlib, https://github.com/matplotlib/ipympl - - nodejs # required for many JupyterLab extensions - # Conda environment & package access extension from within Jupyter - - nb_conda - # HoloViz, https://holoviz.org - - hvplot # hvPlot installs most HoloViz libs, including matplotlib - - ipywidgets # Required for HoloViz interactivity in Jupyter notebooks + # Operational Model (om) + - pyparsing - # Dev tools (optional) - - python-language-server - # Includes both the server extension (jupyter-lsp) and pyls third-party - # server (python-language-server) - - jupyter-lsp-python - - jupyterlab-lsp # Docs at https://github.com/krassowski/jupyterlab-lsp + # Interactivity & Visualization via Jupyter Notebooks (optional, + # but required for tutorials) + - jupyterlab # also installs classic Jupyter notbook + - ipympl # jupyter-matplotlib, https://github.com/matplotlib/ipympl + - nodejs # required for many JupyterLab extensions + # HoloViz, https://holoviz.org + - hvplot # hvPlot installs most HoloViz libs, including matplotlib + - ipywidgets # Required for HoloViz interactivity in Jupyter notebooks + - ipywidgets_bokeh + - jupyter_bokeh # for VSCode - # Operational Model (om) - - pyparsing + # Dev tools (optional) + - python-lsp-server # Language Server Protocol (LSP) extension for Python (pylsp) + - jupyterlab-lsp # Provides both server extension and lab extension - # PIP install requirements only if it is not possible with conda - # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment - # Optional, but recommended for tutorials - - pip: - # https://github.com/lckr/jupyterlab-variableInspector - # - lckr-jupyterlab-variableinspector - # Explore HDF5 files in JupyterLab. Requires an additional step to install. - # - jupyterlab_hdf - # Installation instructions: - # https://github.com/jupyterlab/jupyterlab-hdf5#installation + # PIP install requirements only if it is not possible with conda + # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment + - pip: + - hsp2 diff --git a/environment_dev.yml b/environment_dev.yml index 85648071..878c42a5 100644 --- a/environment_dev.yml +++ b/environment_dev.yml @@ -1,47 +1,49 @@ --- name: hsp2_py311_dev channels: - - conda-forge - - nodefaults # Speeds solving env, by limiting the number of options + - conda-forge + - nodefaults # Speeds solving env, by limiting the number of options dependencies: - # Python 3.11 is supported by Anaconda since 2023.03-0 (Mar 20, 2023) - # https://docs.anaconda.com/free/anaconda/release-notes/#anaconda-2023-03-0-mar-20-2023 - # package management - - conda - - conda-build - - conda-libmamba-solver - - pip + # Python 3.11 was default for Anaconda 2023.07-0 (Jul 11, 2023) + # https://docs.anaconda.com/free/anaconda/release-notes/#anaconda-2023-03-0-mar-20-2023 + # package management + - conda + - conda-build + - conda-libmamba-solver + - pip - # Running HSP2 - - python =3.11 - - scipy # Scipy also installs numpy - # Pandas installs most scientific Python modules, such as Numpy, etc. - - pandas >=2.0 - - numba - - numpy - - hdf5 - - pytables - - h5py - - hdf5plugin # HDF5 compression filters for h5py & jupyterlab_hdf - # - dask # for future performance enhancements - - cltoolbox + # Running HSP2 + - python =3.11 + - scipy # Scipy also installs numpy + # Pandas installs most scientific Python modules, such as Numpy, etc. + - pandas >=2.0 + - numba + - numpy + - hdf5 + - pytables + - h5py + - hdf5plugin # HDF5 compression filters for h5py & jupyterlab_hdf + # - dask # for future performance enhancements + - cltoolbox - # Operational Model (om) - - pyparsing + # Operational Model (om) + - pyparsing - # Interactivity & Visualization via Jupyter Notebooks (optional, - # but required for tutorials) - - jupyterlab # also installs classic Jupyter notbook - - ipympl # jupyter-matplotlib, https://github.com/matplotlib/ipympl - - nodejs # required for many JupyterLab extensions - # HoloViz, https://holoviz.org - - hvplot # hvPlot installs most HoloViz libs, including matplotlib - - ipywidgets # Required for HoloViz interactivity in Jupyter notebooks + # Interactivity & Visualization via Jupyter Notebooks (optional, + # but required for tutorials) + - jupyterlab # also installs classic Jupyter notbook + - ipympl # jupyter-matplotlib, https://github.com/matplotlib/ipympl + - nodejs # required for many JupyterLab extensions + # HoloViz, https://holoviz.org + - hvplot # hvPlot installs most HoloViz libs, including matplotlib + - ipywidgets # Required for HoloViz interactivity in Jupyter notebooks + - ipywidgets_bokeh + - jupyter_bokeh # for VSCode - # Dev tools (optional) - # Language Server Protocol (LSP) extension for Python (pylsp) - - python-lsp-server + # Dev tools (optional) + # Language Server Protocol (LSP) extension for Python (pylsp) + - python-lsp-server # Rope for Completions and renaming # Pyflakes linter to detect various errors # McCabe linter for complexity checking @@ -51,9 +53,10 @@ dependencies: # YAPF for code formatting (preferred over autopep8) # flake8 for error checking (disabled by default) # pylint for code linting (disabled by default) - - jupyterlab-lsp # Provides both server extension and lab extension + - jupyterlab-lsp # Provides both server extension and lab extension - # PIP install requirements only if it is not possible with conda - # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment - - pip: + # PIP install requirements only if it is not possible with conda + # https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#using-pip-in-an-environment + - pip: + # For Dev environment, we recommend using the `conda build` command to install diff --git a/examples/1_Intro_to_HSP2.ipynb b/examples/1_Intro_to_HSP2.ipynb index ed350cf0..4faf5d70 100644 --- a/examples/1_Intro_to_HSP2.ipynb +++ b/examples/1_Intro_to_HSP2.ipynb @@ -34,56 +34,184 @@ "source": [ "# Installation and Setup\n", "\n", - "## Install HSP2\n", - "\n", - "Carefully follow our **[Installation Instructions](https://github.com/respec/HSPsquared#installation)**, especially including:\n", - "- Creating a virtual environment for HSP2 (step 3)\n", - "- Adding HSPsquared to your Python path (step 4)" + "This notebook is designed to be run from: \n", + "- a cloned or copied version of the [HSPsquared](https://github.com/respec/HSPsquared) respository and \n", + "- a custom virtual environment as described in our **[HSP2 Installation](https://github.com/respec/HSPsquared#hsp2-installation) Instructions**, especially including:\n", + " - Creating a virtual environment for HSP2 (step 3)\n", + " - Adding HSP2 to your Python path (step 4)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Python Imports" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### General Imports" ] }, { "cell_type": "code", "execution_count": 1, + "metadata": { + "execution": { + "iopub.execute_input": "2024-05-21T17:40:19.613424Z", + "iopub.status.busy": "2024-05-21T17:40:19.613169Z", + "iopub.status.idle": "2024-05-21T17:40:19.737150Z", + "shell.execute_reply": "2024-05-21T17:40:19.736693Z", + "shell.execute_reply.started": "2024-05-21T17:40:19.613404Z" + } + }, + "outputs": [], + "source": [ + "import os\n", + "from pathlib import Path\n", + "\n", + "import tables" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Import HSP2" + ] + }, + { + "cell_type": "code", + "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "'hsp2_py38'" + "'hsp2_py310'" ] }, - "execution_count": 1, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Confirm that your active environment for this notebook is the one you created for HSP2.\n", - "import os\n", - "\n", "os.environ[\"CONDA_DEFAULT_ENV\"]" ] }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "# Install HSP2, HSP2 Tools, and HSP2 IO Utillties\n", + "from hsp2 import hsp2, hsp2tools, hsp2io" + ] + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Import Python Dependencies\n", - "- Most dependancies get installed when you import the `HSP2` and `HSP2tools` modules. " + "### If you get `ModuleNotFoundError`\n", + "\n", + "If you get `ModuleNotFoundError`, you need to install hsp2 into your environment, either using \n", + "- `pip` (see [HSP2 Installation](https://github.com/respec/HSPsquared#hsp2-installation) Instructions) for normal use, or using\n", + "- [`conda develop`](https://docs.conda.io/projects/conda-build/en/latest/resources/commands/conda-develop.html) if you want to develop HSP2.\n", + "\n", + "If using the development environment, the following steps will install in develop mode:\n", + "1. Run the [`conda develop`](https://docs.conda.io/projects/conda-build/en/latest/resources/commands/conda-develop.html) command in your terminal with your local absolute path to the `src` directory of this repo.\n", + "2. Restart the kernel.\n", + "3. Rerun the import statements above." ] }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "PosixPath('/Users/aaufdenkampe/Documents/Python/respec.HSPsquared')" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Find project directory (i.e. the parent to `/examples` directory for this notebook)\n", + "project_path = Path.cwd().parent\n", + "project_path" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "PosixPath('/Users/aaufdenkampe/Documents/Python/respec.HSPsquared/src')" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Your source directory should be: \n", + "src_path = project_path / 'src' \n", + "src_path" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### To install in developer mode:\n", + "- Copy from the output of `src_path` from the cell above, and \n", + "- Paste it after `!conda develop` in the cell below (replacing the previous user's path). \n", + " - NOTE 1: If your path has any blank spaces, you must enclose the path with quotes.\n", + " - NOTE 2: The Jupyter `!` magic command runs a the follwoing terminal command from this notebook." + ] + }, + { + "cell_type": "code", + "execution_count": 6, "metadata": { "execution": { - "iopub.execute_input": "2024-05-21T17:40:19.613424Z", - "iopub.status.busy": "2024-05-21T17:40:19.613169Z", - "iopub.status.idle": "2024-05-21T17:40:19.737150Z", - "shell.execute_reply": "2024-05-21T17:40:19.736693Z", - "shell.execute_reply.started": "2024-05-21T17:40:19.613404Z" + "iopub.execute_input": "2024-05-21T17:40:25.655357Z", + "iopub.status.busy": "2024-05-21T17:40:25.654849Z", + "iopub.status.idle": "2024-05-21T17:40:25.768746Z", + "shell.execute_reply": "2024-05-21T17:40:25.768142Z", + "shell.execute_reply.started": "2024-05-21T17:40:25.655339Z" } }, + "outputs": [], + "source": [ + " # !conda develop '/Users/aaufdenkampe/Documents/Python/respec.HSPsquared/src'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You now need to **restart the Python kernel** for this notebook, if the path didn't already exist." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, "outputs": [ { "data": { @@ -116,10 +244,10 @@ "
\n", "8784 rows × 10 columns
\n", + "8784 rows × 15 columns
\n", "" ], "text/plain": [ - " DEP IVOL PRSUPY RO ROVOL SAREA \\\n", - "1976-01-01 01:00:00 0.822988 1.747608 0.0 7.371986 0.304628 2.052829 \n", - "1976-01-01 02:00:00 0.754730 0.428585 0.0 6.350832 0.567059 2.003019 \n", - "1976-01-01 03:00:00 0.604331 0.150780 0.0 4.385298 0.443642 1.893593 \n", - "1976-01-01 04:00:00 0.474719 0.066827 0.0 3.010308 0.305604 1.799683 \n", - "1976-01-01 05:00:00 0.376407 0.034621 0.0 2.013996 0.207616 1.728451 \n", - "... ... ... ... ... ... ... \n", - "1976-12-31 20:00:00 0.000000 0.000000 0.0 0.000000 0.000000 0.000000 \n", - "1976-12-31 21:00:00 0.000000 0.000000 0.0 0.000000 0.000000 0.000000 \n", - "1976-12-31 22:00:00 0.000000 0.000000 0.0 0.000000 0.000000 0.000000 \n", - "1976-12-31 23:00:00 0.000000 0.000000 0.0 0.000000 0.000000 0.000000 \n", - "1977-01-01 00:00:00 0.000000 0.000000 0.0 0.000000 0.000000 0.000000 \n", + " AVDEP AVVEL DEP HRAD IVOL \n", + "1976-01-01 01:00:00 0.702923 1.857768 0.822988 0.562775 1.747608 \\\n", + "1976-01-01 02:00:00 0.651220 1.770455 0.754730 0.526685 0.428585 \n", + "1976-01-01 03:00:00 0.534142 1.576605 0.604331 0.443217 0.150780 \n", + "1976-01-01 04:00:00 0.429286 1.416886 0.474719 0.365824 0.066827 \n", + "1976-01-01 05:00:00 0.346840 1.221629 0.376407 0.302669 0.034621 \n", + "... ... ... ... ... ... \n", + "1976-12-31 20:00:00 0.000000 0.000000 0.000000 0.000000 0.000000 \n", + "1976-12-31 21:00:00 0.000000 0.000000 0.000000 0.000000 0.000000 \n", + "1976-12-31 22:00:00 0.000000 0.000000 0.000000 0.000000 0.000000 \n", + "1976-12-31 23:00:00 0.000000 0.000000 0.000000 0.000000 0.000000 \n", + "1977-01-01 00:00:00 0.000000 0.000000 0.000000 0.000000 0.000000 \n", "\n", - " TAU USTAR VOL VOLEV \n", - "1976-01-01 01:00:00 0.088680 0.213918 1.442980 0.000000 \n", - "1976-01-01 02:00:00 0.082993 0.206945 1.304407 0.000100 \n", - "1976-01-01 03:00:00 0.069840 0.189840 1.011448 0.000097 \n", - "1976-01-01 04:00:00 0.057645 0.172471 0.772579 0.000092 \n", - "1976-01-01 05:00:00 0.047693 0.156879 0.599497 0.000087 \n", + " POTEV PRSUPY RO ROVOL SAREA TAU \n", + "1976-01-01 01:00:00 0.000583 0.0 7.371986 0.304628 2.052829 0.088680 \\\n", + "1976-01-01 02:00:00 0.000583 0.0 6.350832 0.567059 2.003019 0.082993 \n", + "1976-01-01 03:00:00 0.000583 0.0 4.385298 0.443642 1.893593 0.069840 \n", + "1976-01-01 04:00:00 0.000583 0.0 3.010308 0.305604 1.799683 0.057645 \n", + "1976-01-01 05:00:00 0.000583 0.0 2.013996 0.207616 1.728451 0.047693 \n", + "... ... ... ... ... ... ... \n", + "1976-12-31 20:00:00 0.000583 0.0 0.000000 0.000000 0.000000 0.000000 \n", + "1976-12-31 21:00:00 0.000583 0.0 0.000000 0.000000 0.000000 0.000000 \n", + "1976-12-31 22:00:00 0.000583 0.0 0.000000 0.000000 0.000000 0.000000 \n", + "1976-12-31 23:00:00 0.000583 0.0 0.000000 0.000000 0.000000 0.000000 \n", + "1977-01-01 00:00:00 0.000583 0.0 0.000000 0.000000 0.000000 0.000000 \n", + "\n", + " TWID USTAR VOL VOLEV \n", + "1976-01-01 01:00:00 5.645279 0.213918 1.442980 0.000000 \n", + "1976-01-01 02:00:00 5.508303 0.206945 1.304407 0.000100 \n", + "1976-01-01 03:00:00 5.207382 0.189840 1.011448 0.000097 \n", + "1976-01-01 04:00:00 4.949128 0.172471 0.772579 0.000092 \n", + "1976-01-01 05:00:00 4.753240 0.156879 0.599497 0.000087 \n", "... ... ... ... ... \n", "1976-12-31 20:00:00 0.000000 0.000000 0.000000 0.000000 \n", "1976-12-31 21:00:00 0.000000 0.000000 0.000000 0.000000 \n", @@ -786,7 +859,7 @@ "1976-12-31 23:00:00 0.000000 0.000000 0.000000 0.000000 \n", "1977-01-01 00:00:00 0.000000 0.000000 0.000000 0.000000 \n", "\n", - "[8784 rows x 10 columns]" + "[8784 rows x 15 columns]" ] }, "execution_count": 9, @@ -825,13 +898,18 @@ " \n", "