First draft of stationary extreme value analysis module

.github/workflows/dependency-review.yml

@@ -4,7 +4,7 @@
 # Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
 #
 # Source repository: https://github.com/actions/dependency-review-action
-# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
+# Public doc: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
 name: 'Dependency Review'
 on:
   pull_request:

.github/workflows/main.yml

@@ -42,7 +42,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.x"
+          - "3.12"  # FIXME: This will be adjusted in cookiecutter
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
@@ -92,29 +92,37 @@ jobs:
           disable-sudo: true
           egress-policy: block
           allowed-endpoints: >
+            185.125.188.54:443
+            185.125.188.55:443
+            185.125.188.58:443
+            185.125.188.59:443
             ai4edataeuwest.blob.core.windows.net:443
+            api.github.com:443
             cdn.proj.org:443
             conda.anaconda.org:443
             elevationeuwest.blob.core.windows.net:443
             files.pythonhosted.org:443
             github.com:443
             objects.githubusercontent.com:443
+            pkg.julialang.org:443
             planetarycomputer.microsoft.com:443
             pypi.org:443
             raw.githubusercontent.com:443
             s3.us-east-2.wasabisys.com:443
             s3.wasabisys.com:443
+            storage.julialang.net:443
+            us-east.pkg.julialang.org:443
+            us-west.pkg.julialang.org:443
       - name: Checkout Repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Setup Conda (Micromamba) with Python${{ matrix.python-version }}
         uses: mamba-org/setup-micromamba@617811f69075e3fd3ae68ca64220ad065877f246 # v2.0.0
         with:
           cache-downloads: true
-          cache-environment: false
+          cache-environment: true
           environment-file: environment-dev.yml
           create-args: >-
             python=${{ matrix.python-version }}
-          micromamba-version: "1.5.10-0"  # pinned to avoid the breaking changes with mamba and micromamba (2.0.0).
       - name: Install xHydro
         run: |
           python -m pip install --no-deps .
@@ -127,6 +135,7 @@ jobs:
         run: |
           make test
         env:
+          CI: "1"
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   test-conda:
@@ -142,6 +151,11 @@ jobs:
       matrix:
         os: [ 'ubuntu-latest' ]
         python-version: [ "3.10", "3.11", "3.12" ]
+        julia: [ false ]
+        include: # Only run the latest Python version on push
+          - os: 'ubuntu-latest'
+            python-version: "3.12"
+            julia: true
     defaults:
       run:
         shell: bash -l {0}
@@ -152,31 +166,41 @@ jobs:
           disable-sudo: true
           egress-policy: block
           allowed-endpoints: >
+            185.125.188.54:443
+            185.125.188.55:443
+            185.125.188.58:443
+            185.125.188.59:443
             ai4edataeuwest.blob.core.windows.net:443
+            api.github.com:443
             cdn.proj.org:443
             conda.anaconda.org:443
             coveralls.io:443
             elevationeuwest.blob.core.windows.net:443
             files.pythonhosted.org:443
             github.com:443
             objects.githubusercontent.com:443
-            planetarycomputer.microsoft.com:443
+            pkg.julialang.org:443
             pypi.org:443
             raw.githubusercontent.com:443
             s3.us-east-2.wasabisys.com:443
             s3.wasabisys.com:443
+            storage.julialang.net:443
+            us-east.pkg.julialang.org:443
+            us-west.pkg.julialang.org:443
       - name: Checkout Repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Setup Conda (Micromamba) with Python${{ matrix.python-version }}
         uses: mamba-org/setup-micromamba@617811f69075e3fd3ae68ca64220ad065877f246 # v2.0.0
         with:
           cache-downloads: true
-          cache-environment: false
+          cache-environment: true
           environment-file: environment-dev.yml
           create-args: >-
-            lmoments3
             python=${{ matrix.python-version }}
-          micromamba-version: "1.5.10-0"  # pinned to avoid the breaking changes with mamba and micromamba (2.0.0).
+      - name: Install PyJuliaCall
+        if: ${{ matrix.julia == true }}
+        run: |
+          micromamba install -c conda-forge "pyjuliacall>=0.9.20"
       - name: Install xHydro
         run: |
           python -m pip install --no-deps .
@@ -192,6 +216,7 @@ jobs:
         run: |
           python -m coveralls
         env:
+          CI: "1"
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COVERALLS_FLAG_NAME: run-Python${{ matrix.python-version }}-conda
           COVERALLS_PARALLEL: true
@@ -210,6 +235,11 @@ jobs:
       matrix:
         os: [ 'ubuntu-latest' ]
         python-version: [ "3.10", "3.11", "3.12" ]
+        julia: [ false ]
+        include:
+          - os: 'ubuntu-latest'
+            python-version: "3.10"
+            julia: true
     defaults:
       run:
         shell: bash -l {0}
@@ -220,30 +250,42 @@ jobs:
           disable-sudo: true
           egress-policy: block
           allowed-endpoints: >
+            185.125.188.54:443
+            185.125.188.55:443
+            185.125.188.58:443
+            185.125.188.59:443
             ai4edataeuwest.blob.core.windows.net:443
+            api.github.com:443
+            api.ipify.org:443
             cdn.proj.org:443
             conda.anaconda.org:443
             elevationeuwest.blob.core.windows.net:443
             files.pythonhosted.org:443
             github.com:443
             objects.githubusercontent.com:443
+            pkg.julialang.org:443
             planetarycomputer.microsoft.com:443
             pypi.org:443
             raw.githubusercontent.com:443
             s3.us-east-2.wasabisys.com:443
             s3.wasabisys.com:443
+            storage.julialang.net:443
+            us-east.pkg.julialang.org:443
+            us-west.pkg.julialang.org:443
       - name: Checkout Repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Setup Conda (Micromamba) with Python${{ matrix.python-version }}
-        uses: mamba-org/setup-micromamba@v2
+        uses: mamba-org/setup-micromamba@617811f69075e3fd3ae68ca64220ad065877f246 # v2.0.0
         with:
           cache-downloads: true
-          cache-environment: false
+          cache-environment: true
           environment-file: environment-dev.yml
           create-args: >-
-            lmoments3
             python=${{ matrix.python-version }}
-          micromamba-version: "1.5.10-0"  # pinned to avoid the breaking changes with mamba and micromamba (2.0.0).
+      - name: Install PyJuliaCall
+        if: ${{ matrix.julia == true }}
+        run: |
+          micromamba install -c conda-forge "pyjuliacall>=0.9.20"
       - name: Install xHydro
         run: |
           python -m pip install --no-deps .
@@ -252,7 +294,12 @@ jobs:
           micromamba list
           echo ESMF_VERSION=$(cat $ESMFMKFILE | grep "ESMF_VERSION_STRING=" | awk -F= '{print $2}' | tr -d "'")
           python -m pip check || true
-      - name: Test Notebooks
+      - name: Test Notebooks (no Julia)
+        if: ${{ matrix.julia == false }}
+        run: |
+          make test-notebooks-lax-noextremes
+      - name: Test Notebooks (Julia)
+        if: ${{ matrix.julia == true }}
         run: |
           make test-notebooks-lax
 

.gitignore

@@ -68,6 +68,7 @@ instance/
 docs/_build/
 docs/apidoc/modules.rst
 docs/apidoc/xhydro*.rst
+docs/notebooks/_data/*
 
 # PyBuilder
 target/
@@ -111,3 +112,4 @@ ENV/
 # IDE settings
 .vscode/
 .idea/
+.VSCodeCounter/

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ default_language_version:
 
 repos:
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.17.0
+    rev: v3.19.0
     hooks:
       - id: pyupgrade
         args: [ '--py310-plus' ]
@@ -21,7 +21,7 @@ repos:
       - id: check-yaml
         args: [ '--allow-multiple-documents' ]
   - repo: https://github.com/pappasam/toml-sort
-    rev: v0.23.1
+    rev: v0.24.2
     hooks:
       - id: toml-sort-fix
   - repo: https://github.com/pre-commit/pygrep-hooks
@@ -42,7 +42,7 @@ repos:
       - id: isort
         exclude: ^docs/
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.9
+    rev: v0.8.2
     hooks:
       - id: ruff
         args: [ '--fix' ]
@@ -65,17 +65,18 @@ repos:
         additional_dependencies: [ 'black==24.10.0' ]
       - id: blackdoc-autoupdate-black
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.7.1
+    rev: 0.8.1
     hooks:
       - id: nbstripout
         files: '.ipynb'
+        exclude: "docs/notebooks/extreme_value_analysis.ipynb"
         args: [ '--keep-count', '--keep-output', '--drop-empty-cells', '--extra-keys=metadata.kernelspec' ]
   - repo: https://github.com/nbQA-dev/nbQA
-    rev: 1.8.7
+    rev: 1.9.1
     hooks:
       - id: nbqa-pyupgrade
         args: [ '--py310-plus' ]
-        additional_dependencies: [ 'pyupgrade==3.17.0' ]
+        additional_dependencies: [ 'pyupgrade==3.19.0' ]
       - id: nbqa-black
         additional_dependencies: [ 'black==24.10.0' ]
       - id: nbqa-isort
@@ -91,7 +92,7 @@ repos:
       - id: numpydoc-validation
         exclude: ^docs/|^tests/
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.29.3
+    rev: 0.30.0
     hooks:
       - id: check-github-workflows
       - id: check-readthedocs

.zenodo.json

@@ -22,6 +22,9 @@
       "affiliation": "École de technologie supérieure, Montréal, Québec, Canada",
       "orcid": "0000-0003-2834-2750"
     },
+    {
+      "name": "Maarite, Kamil"
+    },
     {
       "name": "Arnal, Louise",
       "affiliation": "Ouranos, Montréal, Québec, Canada",

AUTHORS.rst

@@ -14,6 +14,7 @@ Co-Developers
 * Gabriel Rondeau-Genesse <[email protected]> `@RondeauG <https://github.com/RondeauG>`_
 * Sébastien Langlois `@sebastienlanglois <https://github.com/sebastienlanglois>`_
 * Julián Ospina `@ospinajulian <https://github.com/ospinajulian>`_
+* Kamil Maarite `@Sci-pio <https://github.com/Sci-pio>`_
 
 Contributors
 ------------

CHANGELOG.rst

@@ -6,6 +6,13 @@ v0.5.0 (unreleased)
 -------------------
 Contributors to this version: Thomas-Charles Fortier Filion (:user:`TC-FF`) Gabriel Rondeau-Genesse (:user:`RondeauG`), Trevor James Smith (:user:`Zeitsperre`).
 
+New features and enhancements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Added a new module `xhydro.extreme_value_analysis` that wraps the `Extremes.jl` package for Julia. (:pull:`175`).
+  * The module provides functions to fit extreme value distributions to data, compute return levels, and get uncertainty estimates.
+  * The module is designed to be optional and requires the user to have Julia installed with the `Extremes.jl` package, along with the `PyJuliaCall` package for Python.
+  * You can use `pip install xhydro[julia]` to install the required dependencies.
+
 Internal changes
 ^^^^^^^^^^^^^^^^
 * `"land_use_classification"` default collection has been changed to `"io-lulc-annual-v02"`, as the previous one will be deprecated in December 2024. (:pull:`227`).

CI/translator.py

@@ -4,7 +4,6 @@
 import re
 import time
 from pathlib import Path
-from typing import Union
 
 import deep_translator
 

Makefile

@@ -71,12 +71,18 @@ lint: lint/flake8 lint/black ## check style
 test: ## run tests quickly with the default Python
 	python -m pytest
 
+test-distributed: ## run tests quickly with the default Python and distibuted workers
+	python -m pytest --num-processes=logical
+
 test-notebooks: ## run tests on notebooks and compare outputs
 	pytest --no-cov --nbval --rootdir=tests/ docs/notebooks
 
 test-notebooks-lax: ## run tests on notebooks but don't be so strict about outputs
 	pytest --no-cov --nbval-lax --rootdir=tests/ docs/notebooks
 
+test-notebooks-lax-noextremes: ## run tests on notebooks but don't be so strict about outputs
+	pytest --no-cov --nbval-lax --rootdir=tests/ docs/notebooks --ignore='docs/notebooks/extreme_value_analysis.ipynb'
+
 test-all: ## run tests on every Python version with tox
 	python -m tox
 

docs/conf.py

@@ -62,13 +62,14 @@
     "special-members": False,
 }
 
-autodoc_mock_imports = ["esmpy", "xesmf"]
+autodoc_mock_imports = ["esmpy", "juliacall", "juliapkg", "xesmf"]
 
 # For styling class attributes
 napoleon_use_ivar = True
 
 # For external documentation links
 intersphinx_mapping = {
+    "pooch": ("https://www.fatiando.org/pooch/latest/", None),
     "xclim": ("https://xclim.readthedocs.io/en/latest/", None),
     "xscen": ("https://xscen.readthedocs.io/en/latest/", None),
 }