Merge pull request #36 from andersy005/master

Minor fixes prior first version release

.circleci/config.yml

@@ -39,7 +39,7 @@ shared: &shared
     - run:
         name: Running Tests
         command: |
-          pytest -n 2 --junitxml=test-reports/junit.xml --cov=./ --verbose
+          pytest --junitxml=test-reports/junit.xml --cov=./ --verbose
     - run:
         name: Uploading code coverage report
         command: |

.github/workflows/pythonpublish.yml

@@ -8,19 +8,19 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools setuptools-scm wheel twine
-    - name: Build and publish
-      env:
-        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
-        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-      run: |
-        python setup.py sdist bdist_wheel
-        twine upload dist/*
+      - uses: actions/checkout@v1
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: '3.x'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools setuptools-scm wheel twine
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          python setup.py sdist bdist_wheel
+          twine upload dist/* --skip-existing

README.rst

@@ -1,5 +1,6 @@
-POP-tools
-=========
+POP-tools: Tools to support analysis of POP2-CESM model solutions with xarray
+=============================================================================
+
 
 .. image:: https://img.shields.io/github/workflow/status/NCAR/pop-tools/code-style?label=Code%20Style&style=for-the-badge
     :target: https://github.com/NCAR/pop-tools/actions
@@ -27,14 +28,13 @@ POP-tools
 
 
 
-Tools to support analysis of POP2-CESM model solutions. See
-documentation_ for more information.
+See full documentation_ for more information.
 
 .. _documentation: https://pop-tools.readthedocs.io/en/latest/
 
 
-Installation (Coming Soon!)
-----------------------------
+Installation
+------------
 
 POP-tools can be installed from PyPI with pip:
 

ci/environment.yml

@@ -15,5 +15,5 @@ dependencies:
   - pyyaml
   - scipy
   - xarray
-  - pip:
-      - git+https://github.com/xgcm/xgcm.git
+  - xgcm
+  - watermark

docs/requirements.txt

@@ -14,4 +14,4 @@ numba
 fsspec
 watermark
 pooch
--e git+https://github.com/xgcm/xgcm.git#egg=xgcm
+xgcm

docs/source/examples.rst

@@ -4,6 +4,7 @@ Examples
 .. toctree::
     :maxdepth: 2
 
+    examples/sample-data.ipynb
     examples/get-model-grid.ipynb
     examples/eos.ipynb
     examples/region-mask.ipynb

docs/source/examples/eos.ipynb

@@ -17,7 +17,8 @@
    "source": [
     "%matplotlib inline\n",
     "import pop_tools\n",
-    "import xarray as xr"
+    "import xarray as xr\n",
+    "xr.set_options(display_style=\"html\")  # fancy HTML repr"
    ]
   },
   {
@@ -134,7 +135,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

docs/source/examples/lateral-fill-idealized.ipynb

@@ -22,7 +22,8 @@
     "\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "import pop_tools"
+    "import pop_tools\n",
+    "xr.set_options(display_style=\"html\")  # fancy HTML repr"
    ]
   },
   {
@@ -152,7 +153,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

docs/source/examples/lateral-fill-model-grid.ipynb

@@ -17,7 +17,9 @@
    "source": [
     "%matplotlib inline\n",
     "import numpy as np\n",
-    "import pop_tools"
+    "import pop_tools\n",
+    "import xarray as xr\n",
+    "xr.set_options(display_style=\"html\")  # fancy HTML repr"
    ]
   },
   {
@@ -93,7 +95,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

docs/source/examples/region-mask.ipynb

@@ -20,7 +20,9 @@
     "import numpy as np\n",
     "import matplotlib.pyplot as plt\n",
     "import matplotlib.colors as colors\n",
-    "import pop_tools"
+    "import pop_tools\n",
+    "import xarray as xr \n",
+    "xr.set_options(display_style=\"html\")  # fancy HTML repr"
    ]
   },
   {
@@ -300,7 +302,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

docs/source/examples/sample-data.ipynb

@@ -0,0 +1,115 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Sample Data\n",
+    "\n",
+    "`pop-tools` provides some sample data through the `pop_tools.datasets` module."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Where are my data files?\n",
+    "\n",
+    "The sample data files are downloaded automatically by [pooch](https://www.fatiando.org/pooch/latest/api/index.html#module-pooch) the first time you load them. \n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pop_tools\n",
+    "import xarray as xr\n",
+    "xr.set_options(display_style=\"html\")  # fancy HTML repr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To find which data files are available via `pop_tools`, you can run the following:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pop_tools.DATASETS.registry_files"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once you know which file you are interested in, you can pass the name to the `pop_tools.DATASETS.fetch()` function. \n",
+    "This function will download the file if it does not exist already on your local system. After the file has been downloaded, the fetch function returns the path: "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "filepath = pop_tools.DATASETS.fetch('cesm_pop_monthly.T62_g17.nc')\n",
+    "print(filepath)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we can pass the file path to the appropriate I/O package for loading the content of the file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = xr.open_dataset(filepath)\n",
+    "ds"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext watermark\n",
+    "%watermark -d -iv -m -g -h"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

pop_tools/xgcm_util.py

@@ -193,8 +193,13 @@ def to_xgcm_grid_dataset(ds, **kwargs):
         S_FLUX_ROFF_VSF  (time, z_w, nlat_t, nlon_t) float32 inf inf inf ... inf inf
 
     """
-    import xgcm
 
+    try:
+        import xgcm
+    except ImportError:
+        raise ImportError(
+            """to_xgcm_grid_dataset() function requires the `xgcm` package. \nYou can install it via PyPI or Conda"""
+        )
     ds_new = relabel_pop_dims(ds)
     grid = xgcm.Grid(ds_new, **kwargs)
     return grid, ds_new

requirements.txt

@@ -1,7 +1,5 @@
-numpy
-numba
+numba>=0.48
 pyyaml
-xarray
-dask
+xarray>=0.15.0
+dask>=2.10
 pooch>=0.7.0
-xgcm

setup.py

@@ -8,8 +8,8 @@
 
 from setuptools import setup
 
-if exists('README.md'):
-    with open('README.md') as f:
+if exists('README.rst'):
+    with open('README.rst') as f:
         long_description = f.read()
 else:
     long_description = ''
@@ -29,6 +29,7 @@
     'Programming Language :: Python :: 3',
     'Programming Language :: Python :: 3.6',
     'Programming Language :: Python :: 3.7',
+    'Programming Language :: Python :: 3.8',
     'Topic :: Scientific/Engineering',
 ]
 
@@ -40,7 +41,7 @@
     license='Apache License 2.0',
     long_description=long_description,
     classifiers=CLASSIFIERS,
-    keywords='ocean modeling',
+    keywords='ocean modeling cesm',
     name='pop-tools',
     packages=['pop_tools'],
     test_suite='tests',

tests/test_xgcm_util.py

@@ -1,3 +1,5 @@
+import sys
+
 import pytest
 import xarray as xr
 import xgcm
@@ -19,3 +21,13 @@ def test_to_xgcm_grid_dataset(file):
     for coord in new_spatial_coords:
         assert coord in ds_new.coords
         assert coord not in ds.coords
+
+
+def test_to_xgcm_grid_dataset_missing_xgcm():
+    from unittest import mock
+
+    with pytest.raises(ImportError):
+        with mock.patch.dict(sys.modules, {'xgcm': None}):
+            filepath = DATASETS.fetch('tend_zint_100m_Fe.nc')
+            ds = xr.open_dataset(filepath)
+            _, _ = pop_tools.to_xgcm_grid_dataset(ds, metrics=None)