Merge bb43690 into 3617649

.github/workflows/ci.yml

@@ -29,12 +29,11 @@ jobs:
           fetch-depth: 0
       - uses: conda-incubator/setup-miniconda@v2
         with:
-          miniconda-version: "latest"
-          auto-update-conda: true
+          miniforge-variant: Mambaforge
+          miniforge-version: "latest"
           channel-priority: flexible
           python-version: ${{ matrix.python-version }}
           environment-file: ${{ matrix.ymlfile }}
-          mamba-version: "*"
           activate-environment: pytesmo # todo: must match with name in environment.yml
           auto-activate-base: false
       - name: Print Infos
@@ -59,7 +58,7 @@ jobs:
       - name: Install package and test
         shell: bash -l {0}
         run: |
-          pip install -e .
+          pip install -e .[testing]
           pytest --cache-clear
       - name: Upload Coverage
         shell: bash -l {0}

.readthedocs.yml

@@ -5,8 +5,13 @@ build:
   tools:
     python: mambaforge-4.10
 
+python:
+  install:
+    - method: pip
+      path: .
+
 sphinx:
   configuration: docs/conf.py
 
 conda:
-  environment: docs/rtd_env.yml
+  environment: docs/env.yml

CHANGELOG.rst

@@ -4,15 +4,15 @@ Changelog
 
 Unreleased changes in master
 ============================
--
+- Adapters for metric calculatores were introduced. The here implemented adapters compute metrics based on temporal subsets of the time series, which can be used for rolling window metrics, seasonal metrics or multiple arbitrary sub-periods. (PR `#266 <https://github.com/TUW-GEO/pytesmo/pull/266>`_),
 
 Version 0.15.2, 2023-06-14
 ==========================
-- Add kwarg to `time_series.anomaly.calc_climatology` to compute the standard deviation of the climatology (e.g. for anomaly z-scores)
+- Add kwarg to `time_series.anomaly.calc_climatology` to compute the standard deviation of the climatology (e.g. for anomaly z-scores) (PR `#290 <https://github.com/TUW-GEO/pytesmo/pull/290>`_)
 
 Version 0.15.1, 2023-03-29
 ==========================
-- Adding scikit-learn as installation dependency.
+- Adding scikit-learn as installation dependency. (PR `#298 <https://github.com/TUW-GEO/pytesmo/pull/298>`_)
 
 Version 0.15.0, 2023-03-28
 ==========================

README.rst

@@ -49,13 +49,12 @@ This package should be installable through `pip
 <https://pip.pypa.io/en/latest/installing.html>`__ which downloads the package
 from the `python package repository Pypi <https://pypi.python.org/>`__.
 However, pytesmo also needs some packages that depend on C or Fortran libraries (like ``netCDF4``).
-They should be installed first with conda. See http://conda.pydata.org/docs/ on how to use it.
-We recommend using either `Anaconda <https://www.anaconda.com/>`__ or
-`Miniconda <https://conda.io/en/latest/miniconda.html>`__.
+They should be installed first with conda or mamba. We recommend installing `Mambaforge <https://github.com/conda-forge/miniforge#mambaforge>`__.
+Then the following command should install all dependencies:
 
 .. code-block:: bash
 
-    conda install -c conda-forge numpy scipy pandas netCDF4 cython pyresample
+    mamba install -c conda-forge numpy scipy pandas netCDF4 cython pyresample
 
 Afterwards ``pytesmo`` can be installed via pip.
 
@@ -71,17 +70,11 @@ clone the Github repository and install from source:
 
     git clone https://github.com/TUW-GEO/pytesmo.git --recursive
     cd pytesmo
-    conda create -n pytesmo python=3.7 # or any supported python version
-    source activate pytesmo
-    conda env update -f environment.yml -n pytesmo
+    mamba create -n pytesmo python=3.10 # or any supported python version
+    conda activate pytesmo
+    mamba env update -f environment.yml -n pytesmo
     pip install -e .
 
-.. note::
-
-    If you are using windows and conda is missing a package then always check
-    http://www.lfd.uci.edu/~gohlke/pythonlibs/ to see if there is already a
-    precompiled .exe or .whl file for you to easily install.
-
 Supported Products
 ==================
 
@@ -123,4 +116,3 @@ against our master branch for new features or bug fixes.
 
 Please follow the `developers guide
 <https://github.com/TUW-GEO/pytesmo/blob/master/DEVELOPERS_GUIDE.md>`_.
-

docs/conf.py

@@ -185,10 +185,13 @@
 # a list of builtin themes.
 html_theme = "sphinx_rtd_theme"
 
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"sidebar_width": "300px", "page_width": "1200px"}
+html_theme_options = {"sidebar_width": "300px", "page_width": "1200px",
+                      "show_navbar_depth": 2
+                      }
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/rtd_env.yml → docs/env.yml

@@ -1,10 +1,17 @@
 # To keep the RTD build as small as possible, we define a separate .yml here
-name: pytesmo_docs
+name: docs
 channels:
 - conda-forge
 - defaults
 dependencies:
-- python=3.9
+- python=3.10
 - ipykernel
 - nbsphinx
-# Note: RTD will add packages it needs automatically such as sphinx, sphinx_rtd_theme
+- mock
+- pillow
+- sphinx<7
+- sphinx_rtd_theme
+- pip
+- pip:
+  - recommonmark
+  - readthedocs-sphinx-ext

docs/index.rst

@@ -3,9 +3,17 @@
    :hidden:
    :glob:
 
+
    README <readme>
    Introduction <introduction>
-   Examples <examples/index>
+
+   Validation Framework <examples/validation_framework>
+   Temporal Collocation <examples/temporal_collocation>
+   Anomaly Computation <examples/anomalies>
+   Triple Collocation Analysis <examples/triple_collocation>
+   Soil Water Index Computation <examples/swi_calc>
+   Example: Validate ASCAT with ISMN <examples/compare_ASCAT_ISMN>
+
    License <license>
    Authors <authors>
    Changelog <changelog>

docs/introduction.rst

@@ -23,26 +23,8 @@ Features
   as more complex ones like :ref:`triple-collocation-example` or MSE as a
   decomposition of the RMSD see :mod:`pytesmo.metrics`
 
-Prerequisites
-=============
-
-Necessary Python packages
--------------------------
-
-In order to enjoy all pytesmo features, a recent Python 3 installtation with the
-conda/pip packages listed in :download:`requirements.txt <../requirements.txt>`
-should be installed:
-
-Some packages are optional:
-
-* pykdtree: https://github.com/storpipfugl/pykdtree
-
-	which makes Nearest Neighbor search faster
-
-* pyresample: https://github.com/pytroll/pyresample
-
-	for resampling of irregular images onto a regular grid for e.g. plotting
-
-* matplotlib with cartopy/basemap: http://matplotlib.org
-
-  for plotting maps of ISMN stations, maps in general
+Notebooks
+=========
+The following documentation is created from ipython notebooks in ``pytesmo/docs/examples``.
+The notebooks can be run interactively and the results can be reproduced locally using `jupyter <http://jupyter.org/>`__.
+Some of the examples require the packages `ascat` and `ismn`, which can be installed with `pip`.

environment.yml

@@ -10,17 +10,17 @@ dependencies:
   - numpy<=1.23.5  # v1.24 not yet supported by numba
   - scipy>=0.12
   - pandas>=0.11.0,!=0.15.2
-  - netcdf4>=1.0.1,!=1.6.2  # at v1.6.2 only defaults channel worked properly
+  - netcdf4>=1.0.1,!=1.6.2
   - cython>=0.29.21
   - scikit-learn
   - pykdtree
   - pyresample
   - numba
   - matplotlib>=1.2.0
+  - pip
   # optional, for documentation and testing:
   - nb_conda
-  - ipykernel
-  - pip
+  # ----------------------------------------
   - pip:
     - pynetcf>=0.4.0
     - pygeogrids
@@ -30,6 +30,8 @@ dependencies:
     - repurpose>=0.7.1
     - cadati>=0.0.2
     # optional, for documentation and testing:
+    - nbconvert
+    - ipykernel
     - ascat>=2.0
     - ismn>=1.2.0
     - pytest
@@ -38,3 +40,4 @@ dependencies:
     - pre-commit
     - flake8
     - yapf
+    # ----------------------------------------

setup.cfg

@@ -61,6 +61,14 @@ exclude =
 # `pip install pytesmo[PDF]` like:
 # PDF = ReportLab; RXP
 # Add here test requirements (semicolon/line-separated)
+testing =
+    pytest
+    pytest-cov
+    pytest-mpl
+    nbconvert
+    ipykernel
+    ascat>=2.0
+    ismn>=1.2.0
 
 [options.entry_points]
 # Add here console scripts like:

src/pytesmo/validation_framework/metric_calculators_adapters.py

@@ -145,7 +145,7 @@ class MonthsMetricsAdapter(SubsetsMetricsAdapter):
     Adapt MetricCalculators to calculate metrics for groups across months
     """
 
-    def __init__(self, calculator, sets=None):
+    def __init__(self, calculator, month_subsets=None, group_results='tuple'):
         """
         Add functionality to a metric calculator to calculate validation
         metrics for subsets of certain months in a time series (e.g. seasonal).
@@ -155,7 +155,7 @@ def __init__(self, calculator, sets=None):
         calculator : PairwiseIntercomparisonMetrics or TripleCollocationMetrics
             A metric calculator to adapt. Preferably an instance of a metric
              calculator listed in `_supported_metric_calculators`
-        sets : dict, optional (default: None)
+        month_subsets : dict, optional (default: None)
             Define groups of data. With group names as key and a list of
             months (1-12) that belong to the group as values.
 
@@ -166,27 +166,34 @@ def __init__(self, calculator, sets=None):
 
             The name will be used in the results to distinguish between the
             same metrics for different groups:
-            e.g. ('Group1', 'BIAS'): ..., ('Group2', 'BIAS'): ..., etc.
+            e.g. ('Group1', 'BIAS'): ..., ('Group2', 'BIAS'): ..., etc. or
+            'Group1|BIAS': ..., 'Group2|BIAS': ..., etc.
+            denpending on the chosen `group_results` parameter.
 
             The default groups are based on 4 seasons plus one group that uses
             all data (as the unadapted metric calculator would do):
             {'DJF': [12,1,2], 'MAM': [3,4,5], 'JJA': [6, 7, 8],
              'SON': [9, 10, 11], 'ALL': list(range(1, 13))}
+        group_results: str, optional (default: 'tuple')
+            How to group the results.
+            - 'tuple' will group the results by (group, metric)
+            - 'join' will join group and metric name with a '|'
         """
-        if sets is None:
-            sets = {
+        if month_subsets is None:
+            month_subsets = {
                 'DJF': [12, 1, 2],
                 'MAM': [3, 4, 5],
                 'JJA': [6, 7, 8],
                 'SON': [9, 10, 11],
                 'ALL': list(range(1, 13)),
             }
 
-        for name, months in sets.items():
+        for name, months in month_subsets.items():
             distr = TsDistributor(yearless_date_ranges=[(
                 YearlessDatetime(m, 1, 0, 0, 0),
                 YearlessDatetime(m, days_in_month(m), 23, 59, 59))
                                                        for m in months])
-            sets[name] = distr
+            month_subsets[name] = distr
 
-        super().__init__(calculator, subsets=sets)
+        super().__init__(calculator, subsets=month_subsets,
+                         group_results=group_results)