Merge branch 'main' into patch-1

.github/workflows/pre-commit.yml

@@ -3,15 +3,15 @@ name: pre-commit
 on:
   pull_request:
   push:
-    branches: [master]
+    branches: [main]
 
 jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions/setup-python@v4
-    - uses: actions/cache@v3
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+    - uses: actions/cache@v4
       with:
         path: ~/.cache/pre-commit
         key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}

.github/workflows/release.yaml

@@ -6,19 +6,23 @@ on: [push]
 
 jobs:
   release:
+    name: Upload release to PyPI
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/xroms
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
       - name: Install dependencies
         run: |
           python -m pip install -U pip wheel setuptools setuptools-scm twine
+        # python -m pip install -U pip wheel "setuptools<66.0.0" setuptools-scm twine
       - name: Build distributions
         run: python setup.py sdist bdist_wheel
 
       - name: Publish to PyPI
         if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-        uses: pypa/gh-action-pypi-publish@master
-        with:
-          user: ${{ secrets.PYPI_USERNAME }}
-          password: ${{ secrets.PYPI_PASSWORD }}
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yaml

@@ -17,20 +17,22 @@ jobs:
       fail-fast: false
       matrix:
         os: ["macos-latest", "ubuntu-latest", "windows-latest"]
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.9", "3.10", "3.11"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Cache conda
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         env:
           # Increase this value to reset cache if ci/environment.yml has not changed
           CACHE_NUMBER: 0
         with:
           path: ~/conda_pkgs_dir
           key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{ hashFiles('ci/environment-py${{ matrix.python-version }}.yml') }}
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: conda-incubator/setup-miniconda@v3
         with:
-          mamba-version: "*" # activate this to build with mamba.
+          # mamba-version: "*" # activate this to build with mamba.
+          python-version: ${{ matrix.python-version }}
+          miniforge-variant: Mambaforge
           channels: conda-forge, defaults # These need to be specified to use mamba
           channel-priority: true
           environment-file: ci/environment-py${{ matrix.python-version }}.yml
@@ -46,7 +48,7 @@ jobs:
         run: |
           pytest --cov=./ --cov-report=xml
       - name: Upload code coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           file: ./coverage.xml
           flags: unittests

.pre-commit-config.yaml

@@ -20,24 +20,19 @@ repos:
     - id: file-contents-sorter
       files: requirements-dev.txt
 
-- repo: https://gitlab.com/pycqa/flake8
+- repo: https://github.com/pycqa/flake8
   rev: 3.7.9
   hooks:
     - id: flake8
       exclude: docs/source/conf.py
       args: [--max-line-length=105, --ignore=E203,E501,W503, --select=select=C,E,F,W,B,B950]
 
-- repo: https://github.com/pre-commit/mirrors-isort
-  rev: v4.3.21
+- repo: https://github.com/pycqa/isort
+  rev: 5.12.0
   hooks:
-  - id: isort
-    additional_dependencies: [toml]
-    args: [--project=xroms, --multi-line=3, --lines-after-imports=2, --lines-between-types=1, --trailing-comma, --force-grid-wrap=0, --use-parentheses, --line-width=88]
-
-# - repo: https://github.com/asottile/seed-isort-config
-#   rev: v2.1.1
-#   hooks:
-#     - id: seed-isort-config
+    - id: isort
+      name: isort (python)
+      args: ["--profile", "black", "--filter-files", "--lines-after-imports=2", "--project=gcm_filters", "--multi-line=3", "--lines-between-types=1", "--trailing-comma", "--force-grid-wrap=0", "--use-parentheses", "--line-width=88"]
 
 - repo: https://github.com/psf/black
   rev: 22.3.0

.readthedocs.yaml

@@ -0,0 +1,25 @@
+version: 2
+
+# Build PDF only
+formats:
+  - pdf
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
+
+# uncomment to build from this exact version of package
+# the downside is the version listed in the docs will be a dev version
+# if uncommenting this, comment out installing pypi version of package in docs/env file
+# python:
+#   install:
+#     - method: pip
+#       path: ./
+
+conda:
+    environment: docs/environment.yml
+
+sphinx:
+  configuration: docs/conf.py
+  # fail_on_warning: true

README.md

@@ -1,14 +1,14 @@
 # `xroms`
-[![DOI](https://zenodo.org/badge/265067025.svg)](https://zenodo.org/badge/latestdoi/265067025)
 
-[![Build Status](https://img.shields.io/github/workflow/status/xoceanmodel/xroms/Tests?logo=github&style=for-the-badge)](https://github.com/xoceanmodel/xroms/actions)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/xoceanmodel/xroms/test.yaml?branch=main&logo=github&style=for-the-badge)](https://github.com/xoceanmodel/xroms/actions)
 [![Code Coverage](https://img.shields.io/codecov/c/github/xoceanmodel/xroms.svg?style=for-the-badge)](https://codecov.io/gh/xoceanmodel/xroms)
 [![License:MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 [![Documentation Status](https://img.shields.io/readthedocs/xroms/latest.svg?style=for-the-badge)](https://xroms.readthedocs.io/en/latest/?badge=latest)
-[![Code Style Status](https://img.shields.io/github/workflow/status/xoceanmodel/xroms/linting%20with%20pre-commit?label=Code%20Style&style=for-the-badge)](https://github.com/xoceanmodel/xroms/actions)
+[![Code Style Status](https://img.shields.io/github/actions/workflow/status/xoceanmodel/xroms/pre-commit.yml?branch-main&label=Code%20Style&style=for-the-badge)](https://github.com/xoceanmodel/xroms/actions)
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/xroms.svg?style=for-the-badge)](https://anaconda.org/conda-forge/xroms)
 [![Python Package Index](https://img.shields.io/pypi/v/xroms.svg?style=for-the-badge)](https://pypi.org/project/xroms)
 
+[![DOI](https://zenodo.org/badge/265067025.svg?style=for-the-badge)](https://zenodo.org/badge/latestdoi/265067025)
 
 `xroms` contains functions for commonly used scripts for working with ROMS output in xarray.
 
@@ -20,6 +20,8 @@ There are functions to...
   * eddy kinetic energy
   * vertical shear
   * vertical vorticity
+  * horizontal divergence
+  * normalized surface divergence
   * Ertel potential vorticity
   * density as calculated in ROMS
   * potential density
@@ -51,20 +53,33 @@ There are functions to...
 
 You need to have `conda` installed for these installation instructions. You'll have best results if you use the channel `conda-forge`, which you can prioritize with `conda config --add channels conda-forge --force`.
 
-### Create environment if needed
+### Install, the easy way
+
+PyPI:
+
+  ```
+  pip install xroms
+  ```
 
-As a first step, you can create an environment for this package with conda if you want. If you do this, you'll need to git clone the package first as below.
+conda-forge:
 
-    conda create --name XROMS python=3.8 --file requirements.txt
+  ```
+  mamba install -c conda-forge xroms
+  ```
+
+### Create environment if needed
 
-### Install `xroms`
+As a first step, you can create an environment for this package with conda if you want. If you do this, you'll need to git clone the package first as below. Note that `mamba` and `conda` can be used interchangeably, but `mamba` is faster for installation.
+
+    mamba env create -f environment.yml
 
 You can choose to install with conda the optional dependencies for full functionality:
 
     conda install --file requirements-opt.txt
 
 and to install optional dependency `xcmocean`:
 
+
     pip install git+https://github.com/pangeo-data/xcmocean
 
 Then choose one of the following to install `xroms` from GitHub:
@@ -83,61 +98,3 @@ Then choose one of the following to install `xroms` from GitHub:
     pip install git+https://github.com/xoceanmodel/xroms
     ```
 
-### Optional additional installation for horizontal interpolation
-
-If you want to be able to horizontally interpolate with `xroms.interpll`, you should install xESMF. This is currently the only way that has worked.
-
-1. Install `ESMF` with mpi support.
-
-    For Mac:
-
-    ```
-    conda install esmf=8.0.1=mpi_openmpi_ha78a60a_0
-    ```
-
-    For Linux:
-
-    ```
-    conda install esmf=8.0.1=mpi_openmpi_hda7c4e6_0
-    ```
-
-1. Install esmpy
-
-    ```
-    conda install esmpy=8.0.1=mpi_openmpi_py38h51f2404_0
-    ```
-
-1. Install xESMF from github (pip version will not work)
-
-    ```
-    pip install git+https://github.com/pangeo-data/xESMF.git#egg=xESMF
-    ```
-
-### Recommended: Jupyter Lab extensions
-
-If you are using Jupyter Lab, the Table of Contents and Dask extensions are really helpful:
-
-```
-jupyter labextension install @jupyterlab/toc
-jupyter labextension install dask-labextension
-jupyter serverextension enable dask_labextension
-```
-
-Notes:
-* Additionally installing [bottleneck](https://github.com/pydata/bottleneck/) is supposed to improve the speed of `numpy`-based calculations.
-* Installing so that package is editable is not required but is convenient. You can remove the `-e` from any installation line to not do that.
-
-
-## Quick Start
-
-After installation, read in model output with one of three load methods:
- * `xroms.open_netcdf(filename)`: if model output is in a single netcdf file or at a single thredds address;
- * `xroms.open_mfnetcdf(filenames)`: if model output is available in multiple accessible local netcdf files;
- * `xroms.open_zarr(locations)`: if model output is available in multiple accessible zarr directories.
-More information about reading in model output is available in Jupyter notebook `examples/io.pynb`.
-
-Other common tasks to do with model output using `xroms` as well as other packages are demonstrated in additional Jupyter notebooks:
- * select_data
- * calc
- * interpolation
- * plotting

ci/environment-py3.10.yml

@@ -7,15 +7,19 @@ dependencies:
   - cartopy
   - cf_xarray
   - dask
+  # # https://github.com/h5py/h5py/issues/1880
+  # # https://github.com/conda-forge/h5py-feedstock/issues/92
+  # - h5py < 3.2
   - netcdf4
   - numba >= 0.49
   - numpy
+  - pooch
   - xarray
-  - xgcm == 0.5.1
-  - zarr
+  # - xgcm >= 0.8.1
   ##############
   - pytest
   - pip:
+    - xgcm >= 0.8.1
     - codecov
     - pytest-cov
     - coverage[toml]

ci/environment-py3.8.yml → ci/environment-py3.11.yml

@@ -2,20 +2,24 @@ name: test_env_intake-axds
 channels:
   - conda-forge
 dependencies:
-  - python=3.8
+  - python=3.11
   ############## These will have to be adjusted to your specific project
   - cartopy
   - cf_xarray
   - dask
+  # # https://github.com/h5py/h5py/issues/1880
+  # # https://github.com/conda-forge/h5py-feedstock/issues/92
+  # - h5py < 3.2
   - netcdf4
   - numba >= 0.49
   - numpy
+  - pooch
   - xarray
-  - xgcm == 0.5.1
-  - zarr
+  # - xgcm >= 0.8.1
   ##############
   - pytest
   - pip:
+    - xgcm >= 0.8.1
     - codecov
     - pytest-cov
     - coverage[toml]