Merge branch 'master' into enh/add_jinja_for_indicator_templating

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,7 +7,6 @@
   - [ ] (If applicable) Documentation has been added / updated (for bug fixes / features)
 - [ ] HISTORY.rst has been updated (with summary of main changes)
   - [ ] Link to issue (:issue:`number`) and pull request (:pull:`number`) has been added
-- [ ] `bumpversion patch` has been called on this branch
 - [ ] The relevant author information has been added to `.zenodo.json`
 
 ### What kind of change does this PR introduce?

.github/workflows/bump-version.yml

@@ -0,0 +1,48 @@
+name: "Bump Patch Version"
+
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - HISTORY.rst
+      - Makefile
+      - MANIFEST.in
+      - requirements_upstream.txt
+      - setup.cfg
+      - setup.py
+      - tox.ini
+      - xclim/__init__.py
+      - docs/**.ipynb
+      - docs/*.py
+      - docs/*.rst
+      - .github/**.yml
+      - .pre-commit-config.yaml
+
+jobs:
+  bump_patch_version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - name: Config Commit Bot
+        run: |
+          git config --local user.email "bumpversion[bot]@ouranos.ca"
+          git config --local user.name "bumpversion[bot]"
+      - name: Current Version
+        run: echo "current_version=$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
+      - name: Bump Patch Version
+        run: |
+          pip install bump2version
+          echo "running `bump2version patch`"
+          echo "new_version=$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
+      - name: Push Changes
+        uses: ad-m/github-push-action@master
+        with:
+          force: false
+          github_token: ${{ secrets.BUMPVERSION_TOKEN }}
+          branch: ${{ github.ref }}

.github/workflows/codeql-analysis.yml

@@ -4,6 +4,20 @@ on:
   push:
     branches:
       - master
+    paths-ignore:
+      - HISTORY.rst
+      - Makefile
+      - MANIFEST.in
+      - requirements_upstream.txt
+      - setup.cfg
+      - setup.py
+      - tox.ini
+      - xclim/__init__.py
+      - docs/**.ipynb
+      - docs/**.py
+      - docs/**.rst
+      - .github/**.yml
+      - .pre-commit-config.yaml
   schedule:
     - cron: '30 23 * * 5'
 

.github/workflows/main.yml

@@ -1,9 +1,14 @@
-name: xclim
+name: "xclim Testing Suite"
 
 on:
   push:
     branches:
       - master
+    paths-ignore:
+      - HISTORY.rst
+      - setup.cfg
+      - setup.py
+      - xclim/__init__.py
   pull_request:
 
 jobs:
@@ -14,8 +19,8 @@ jobs:
         uses: styfle/cancel-workflow-action@0.9.1
         with:
           access_token: ${{ github.token }}
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install tox
@@ -27,8 +32,8 @@ jobs:
     needs: black
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install tox
@@ -40,9 +45,9 @@ jobs:
     needs: black
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python 3.8
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install tox
@@ -57,7 +62,36 @@ jobs:
           flag-name: run-py38-xarray-lm3
           parallel: true
 
-  test:
+  test-py38-sbck-slow-conda:
+    needs: black
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup conda
+        uses: conda-incubator/setup-miniconda@v2.1.1
+        with:
+          activate-environment: sbck-experimental
+          channels: conda-forge,defaults
+          mamba-version: "*"
+          python-version: "3.8"
+      - name: Install tox
+        shell: bash -l {0}
+        run: mamba install -n sbck-experimental tox-conda tox
+      - name: Test with tox
+        shell: bash -l {0}
+        run: |
+          conda activate sbck-experimental
+          tox -e sbck-slow
+        env:
+          CONDA_EXE: mamba
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: report coverage
+        uses: AndreMiras/coveralls-python-action@develop
+        with:
+          flag-name: run-sbck
+          parallel: true
+
+  tests:
     needs: black
     runs-on: ubuntu-latest
     strategy:
@@ -72,7 +106,7 @@ jobs:
           - tox-env: py310
             python-version: "3.10-dev"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       # Python3.10-dev headers not available in Ubuntu-20.04 Bionic
       - name: Set up Python3.10 (deadsnakes version)
         if: "endsWith(matrix.python-version, '-dev')"
@@ -81,7 +115,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Set up Python ${{ matrix.python-version }}
         if: "!endsWith(matrix.python-version, '-dev')"
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install tox
@@ -98,8 +132,9 @@ jobs:
 
   finish:
     needs:
-      - test
+      - tests
       - doctests
+      - test-py38-sbck-slow-conda
     runs-on: ubuntu-latest
     steps:
       - name: Coveralls Finished

.github/workflows/publish-pypi.yml

@@ -1,4 +1,4 @@
-name: Publish Python 🐍 distributions 📦 to PyPI
+name: "Publish Python 🐍 distributions 📦 to PyPI"
 
 on:
   release:

.github/workflows/tag-testpypi.yml

@@ -1,4 +1,4 @@
-name: Publish Python 🐍 distributions 📦 to TestPyPI
+name: "Publish Python 🐍 distributions 📦 to TestPyPI"
 
 on:
   push:

.pre-commit-config.yaml

@@ -27,7 +27,7 @@ repos:
         additional_dependencies: [ 'flake8-rst-docstrings' ]
         args: [ '--config=setup.cfg' ]
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.6.0
     hooks:
       - id: black
         args: [ "--target-version=py38" ]

.zenodo.json

@@ -72,6 +72,11 @@
       "name": "Labonté, Marie-Pier",
       "orcid": "0000-0003-0738-3940"
     },
+    {
+      "affiliation": "Helmholtz-Zentrum Hereon",
+      "name": "Lierhammer, Ludwig",
+      "orcid": "0000-0002-7207-0003"
+    },
     {
       "name": "Low, Jwen-Fai"
     },

HISTORY.rst

@@ -2,39 +2,60 @@
 History
 =======
 
-0.37.0 (unreleased)
+0.38.0 (unreleased)
 -------------------
-Contributors to this version:  Abel Aoun (:user:`bzah`), Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`), Gabriel Rondeau-Genesse (:user:`RondeauG`), Juliette Lavoie (:user:`juliettelavoie`).
+Contributors to this version: Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`).
+
+New features and enhancements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Adjustment methods of `SBCK <https://github.com/yrobink/SBCK>`_ are wrapped into xclim when that package is installed. (:issue:`1109`, :pull:`1115`).
+    - Wrapped SBCK tests are also properly run in the tox testing ensemble. (:pull:`1119`).
+
+Internal changes
+^^^^^^^^^^^^^^^^
+* Marked a test (``test_release_notes_file_not_implemented``) that can only pass when source files are available so that it can easily be skipped on conda-forge build tests. (:issue:`1116`, :pull:`1117`).
+* Split a few YAML strings found in the virtual modules that regularly issued warnings on the code checking CI steps. (:pull:`1118`).
+
+0.37.0 (20 June 2022)
+---------------------
+Contributors to this version: Abel Aoun (:user:`bzah`), Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`), Gabriel Rondeau-Genesse (:user:`RondeauG`), Juliette Lavoie (:user:`juliettelavoie`), Ludwig Lierhammer (:user:`ludwiglierhammer`).
 
 Announcements
 ^^^^^^^^^^^^^
 * `xclim` is now compliant with `PEP 563 <https://peps.python.org/pep-0563>`_. Python3.10-style annotations are now permitted. (:issue:`1065`, :pull:`1071`).
 * `xclim` is now fully compatible with `xarray`'s `flox`-enabled ``GroupBy`` and ``resample`` operations. (:pull:`1081`).
 * `xclim` now (properly) enforces docstring compliance checks using `pydocstyle` with modified `numpy`-style docstrings. Docstring errors will now cause build failures. See the `pydocstyle documentation <http://www.pydocstyle.org/en/stable/error_codes.html>`_ for more information. (:pull:`1074`).
+* `xclim` now uses GitHub Actions to manage patch version bumping. Merged Pull Requests that modify `xclim` code now trigger version-bumping automatically when pushed to the main development branch. Running `$ bump2version patch` within development branches is no longer necessary. (:pull:`1102`).
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Add "Celsius" to aliases of "celsius" unit. (:issue:`1067`, :pull:`1068`).
 * All indicators now have indexing enabled, except those computing statistics on spells. (:issue:`1069`, :pull:`1070`).
 * A convenience function for returning the version numbers for relevant xclim dependencies (``xclim.testing.show_versions``) is now offered. (:pull:`1073`).
-    - A CLI version of this function is also available from the command line: `$ xclim show_version_info`. (:pull:`1073`).
+    - A CLI version of this function is also available from the command line (`$ xclim show_version_info`). (:pull:`1073`).
 * New "keep_attrs" option to control the handling of the attributes within the indicators. (:issue:`1026`, :pull:`1076`).
 * Added a notebook showcasing some simple examples of Spatial Analogues. (:issue:`585`, :pull:`1075`).
 * ``create_ensembles`` now accepts a glob string to find datasets. (:pull:`1081`).
 * Improved percentile based indicators metadata with the window, threshold and climatology period used to compute percentiles. (:issue:`1047`, :pull:`1050`).
 * New ``xclim.core.calendar.construct_offset``, the inverse operation of ``parse_offset``. (:pull:`1090`).
 * Rechunking operations in ``xclim.indices.run_length.rle`` are now synchronized with dask's options. (:pull:`1090`).
-* A convenience recipe for installing key development branches of some dependencies has been added (`$ pip install xclim[upstream]`). (:issue:`1088`, :pull:`1092`).
 * A mention of the "missing" checks and options is added to the history attribute of indicators, where appropriate. (:issue:`1100`, :pull:`1103`).
 
 Breaking changes
 ^^^^^^^^^^^^^^^^
 * ``xclim.atmos.water_budget`` has been separated into ``water_budget`` (calculated directly with 'evspsblpot') and ``water_budget_from_tas`` (original function). (:pull:`1086`).
 * Injected parameters in indicators are now left out of a function's signature and will not be included in the history attribute. (:pull:`1086`).
-* The signature for the following Indicators:
+* The signature for the following Indicators have been modified (:pull:`1050`):
     - cold_spell_duration_index, tg90p, tg10p, tx90p, tx10p, tn90p, tn10p, warm_spell_duration_index, days_over_precip_doy_thresh, days_over_precip_thresh, fraction_over_precip_doy_thresh, fraction_over_precip_thresh, cold_and_dry_days, warm_and_dry_days, warm_and_wet_days, cold_and_wet_days
-  have been modified. The parameter for percentiles values is now named after the variable it is supposed to be computed upon. (:pull:`1050`)
+* The parameter for percentile values is now named after the variable it is supposed to be computed upon. (:pull:`1050`).
 * `pytest-runner` has been removed as a dependency (it was never needed for `xclim` development). (:pull:`1074`).
+* `xclim.testing._utils.py` has been renamed to `xclim.testing.utils.py` for added documentation visibility. (:pull:`1074`).
+    - Some unused functions and classes (``as_tuple``, ``TestFile``, ``TestDataSet``) have been removed. (:pull:`1107`).
+
+New indicators
+^^^^^^^^^^^^^^
+* ``universal_thermal_climate_index`` and ``mean_radiant_temperature`` for computing the universal thermal climate index from the near-surface temperature, relative humidity, near-surface windspeed and radiation. (:issue:`1060`, :pull:`1062`).
+    - A new method ``ITS90`` has also been added for calculating saturation water vapour pressure. (:issue:`1060`, :pull:`1062`).
 
 Internal changes
 ^^^^^^^^^^^^^^^^
@@ -44,6 +65,9 @@ Internal changes
 * Code snippets within documentation are now checked and reformatted to `black` conventions with `blackdoc`. A `pre-commit` hook is now in place to run these checks. (:pull:`1098`).
 * Test coverage statistic no longer includes coverage of the test files themselves. Coverage now reflects lines of usable code covered. (:pull:`1101`).
 * Reordered listed authors alphabetically. Promoted :user:`bzah` to core contributor. (:pull:`1105`).
+* Tests have been added for some functions in `xclim.testing.utils.py`; some previously uncaught bugs in ``list_input_variables``, ``publish_release_notes``, and ``show_versions`` have been patched. (:issue:`1078`, :pull:`1107`).
+* A convenience command for installing xclim with key development branches of some dependencies has been added (`$ make upstream`). (:issue:`1088`, :pull:`1092`; amended in :issue:`1113`, :pull:`1114`).
+    - This build configuration is also available in `tox` for local development purposes (`$ tox -e pyXX-upstream`).
 
 Bug fixes
 ^^^^^^^^^

MANIFEST.in

@@ -4,6 +4,7 @@ include HISTORY.rst
 include LICENSE
 include README.rst
 include requirements_dev.txt
+include requirements_upstream.txt
 
 recursive-include xclim *.txt *.json *.yml *.py
 recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif

Makefile

@@ -106,3 +106,6 @@ install: clean ## install the package to the active Python's site-packages
 
 develop: clean ## install the package and development dependencies in editable mode to the active Python's site-packages
 	python -m pip install --no-user --editable ".[dev]"
+
+upstream: clean develop ## install the GitHub-based development branches of dependencies in editable mode to the active Python's site-packages
+	python -m pip install --no-user --requirement requirements_upstream.txt

docs/indices.rst

@@ -18,6 +18,9 @@ Indices submodules
    :show-inheritance:
    :noindex:
 
+.. automodule:: xclim.indices.helpers
+   :members:
+
 .. automodule:: xclim.indices.run_length
    :members:
    :undoc-members:

docs/installation.rst

@@ -34,7 +34,8 @@ To install the xclim Anaconda binary, run this command in your terminal:
 
 Extra dependencies
 ------------------
-To improve performance of xclim, we highly recommend you also install `flox`_ (see: :doc:`flox API <flox:api>`). This package integrates into xarray and significantly improves the performance of the grouping and resampling algorithms, especially when using `dask` on large datasets.
+To improve performance of xclim, we highly recommend you also install `flox`_ (see: :doc:`flox API <flox:api>`).
+This package integrates into xarray and significantly improves the performance of the grouping and resampling algorithms, especially when using `dask` on large datasets.
 
 We also recommend using the subsetting tools in `clisops`_ (see: :doc:`clisops.core.subset API <clisops:api>`) for spatial manipulation of geospatial data.
 
@@ -43,11 +44,29 @@ For convenience, these libraries can be installed alongside `xclim` using the fo
 
 .. code-block::
 
-    $ pip install -e ".[upstream]"
+    $ pip install -r requirements_upstream.txt
+    # Or, alternatively:
+    $ make upstream
 
 .. _flox: https://github.com/dcherian/flox
 .. _clisops: https://github.com/roocs/clisops
 
+Another optional library is `SBCK`_, which provides experimental adjustment methods to extend
+:ref:`xclim.sdba <Bias adjustment and downscaling algorithms>`. It can't be installed directly
+from pip or conda and has one complex dependency : `Eigen`_. Please refer to Eigen's and SBCK's
+docs for the recommended installation instructions. However, Eigen is available on conda, so one can do:
+
+.. code-block::
+
+   $ conda install -c conda-forge eigen pybind11
+   $ pip install "git+https://github.com/Ouranosinc/SBCK.git@easier-install#egg=sbck&subdirectory=python"
+
+The last line will install SBCK>=v0.4.0 from Ouranos' fork which implements a small fix that allows this
+direct installation from pip within a virtual environment.
+
+.. _SBCK: https://github.com/yrobink/SBCK
+.. _Eigen: https://eigen.tuxfamily.org/index.php
+
 From sources
 ------------
 .. Warning::
@@ -93,4 +112,4 @@ To create a conda development environment including all xclim dependencies, ente
 
     $ conda create -n my_xclim_env python=3.8 --file=environment.yml
     $ conda activate my_xclim_env
-    (my_xclim_env) $ pip install .[dev]
+    (my_xclim_env) $ pip install ".[dev]"

requirements_upstream.txt

@@ -0,0 +1,4 @@
+git+https://github.com/pydata/bottleneck.git@master#egg=bottleneck
+git+https://github.com/Unidata/cftime.git@master#egg=cftime
+git+https://github.com/dcherian/flox.git@main#egg=flox
+git+https://github.com/pydata/xarray.git@main#egg=xarray

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.36.10-beta
+current_version = 0.37.4-beta
 commit = True
 tag = False
 parse = (?P<major>\d+)\.(?P<minor>\d+).(?P<patch>\d+)(\-(?P<release>[a-z]+))?