Merge pull request #35 from Ouranosinc/ensemble-selection

Aggregation functions and other changes
Ouranosinc · Aug 22, 2022 · 4b20db1 · 4b20db1
2 parents 5f323f8 + ffc3791
commit 4b20db1
Show file tree

Hide file tree

Showing 27 changed files with 1,866 additions and 1,175 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -15,14 +15,20 @@ New features and enhancements
 * New function ``clean_up`` added. (:issue:`22`, :pull:`24`).
 * `parse_directory`: Fixes to `xr_open_kwargs` and support for wildcards (*) in the directories. (:pull:`19`).
 * New function ``xscen.ensemble.ensemble_stats`` added. (:issue:`3`, :pull:`28`).
+* New functions ``spatial_mean``, ``climatological_mean`` and ``deltas`` added. (:issue:`4`, :pull:`35`).
 * Add argument ``intermediate_reg_grids`` to ``xscen.regridding.regrid``. (:issue:`34`, :pull:`39`).
 * Add argument ``moving_yearly_window`` to ``xscen.biasadjust.adjust``. (:pull:`39`).
-* Many adjustments to ``parse_directory``: better wildcards (:issue:`24`), allow custom columns, fastpaths for ``parse_from_ds``, and more (:pull:`30`, :pull:`47`).
+* Many adjustments to ``parse_directory``: better wildcards (:issue:`24`), allow custom columns, fastpaths for ``parse_from_ds``, and more (:pull:`30`).
+* Documentation now makes better use of autodoc to generate package index. (:pull:`41`).
+* `periods` argument added to `compute_indicators` to support datasets with jumps in time (:pull:`35`).
 
 Breaking changes
 ^^^^^^^^^^^^^^^^
 * Patterns in ``parse_directory`` start at the end of the paths in ``directories``. (:pull:`30`).
 * Argument ``extension`` of ``parse_directory`` has been renamed ``globpattern``. (:pull:`30`).
+* The ``xscen`` API and filestructure have been significantly refactored. (:issue:`40`, :pull:`41`). The following functions are available from the top-level:
+    - ``adjust``, ``train``, ``ensemble_stats``, ``clisops_subset``, ``dispatch_historical_to_future``, ``extract_dataset``, ``resample``, ``restrict_by_resolution``, ``restrict_multimembers``, ``search_data_catalogs``, ``save_to_netcdf``, ``save_to_zarr``, ``rechunk``, ``compute_indicators``, ``regrid_dataset``, and ``create_mask``.
+* xscen now requires geopandas and shapely (:pull:`35`).
 
 Internal changes
 ^^^^^^^^^^^^^^^^
@@ -33,9 +39,10 @@ Internal changes
 * Add ``align_on = 'year'`` argument in bias adjustment converting of calendars. (:pull:`39`).
 * GitHub Actions using Ubuntu-22.04 images are now configured for running testing ensemble using `tox-conda`. (:pull:`44`).
 * `import xscen` smoke test is now run on all pull requests. (:pull:`44`).
+* Fix for `create_mask` removing attributes (:pull:`35`).
 
 v0.2.0 (first official release)
-------------------------------
+-------------------------------
 Contributors to this version: Gabriel Rondeau-Genesse (:user:`RondeauG`), Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`), Juliette Lavoie (:user:`juliettelavoie`).
 
 Announcements

diff --git a/Makefile b/Makefile
@@ -62,8 +62,8 @@ test-all: ## run tests on every Python version with tox
 
 docs: ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs clean
+	sphinx-apidoc -o docs/ --module-first xscen
 	$(MAKE) -C docs html
-	$(BROWSER) docs/_build/html/index.html
 ifndef READTHEDOCS
 	$(BROWSER) docs/_build/html/index.html
 endif

diff --git a/docs/api.rst b/docs/api.rst
@@ -1,64 +1,93 @@
 API
 ===
 
+Aggregation
+-----------
+
+.. automodule:: xscen.aggregate
+   :members:
+   :noindex:
+
 Catalog
 -------
 
 .. automodule:: xscen.catalog
    :members:
+   :noindex:
 
 Extraction
 ----------
 
-.. automodule:: xscen.extraction
+.. automodule:: xscen
    :members:
+   :noindex:
 
-Controlled Vocabulary and mappings
+Controlled Vocabulary and Mappings
 ----------------------------------
 
 .. automodule:: xscen.CV
    :members:
+   :noindex:
 
 Regridding
 ----------
 
-.. automodule:: xscen.regridding
+.. automodule:: xscen
    :members:
+   :noindex:
 
-Bias adjustment
+Bias Adjustment
 ---------------
 
-.. automodule:: xscen.biasadjust
-   :members:
+.. automodule:: xscen
+   :members: adjust train
+   :noindex:
 
 Indicators
 ----------
 
 .. automodule:: xscen.indicators
    :members:
+   :noindex:
 
-Final product tweaks
---------------------
+Ensembles
+---------
 
-.. automodule:: xscen.finalize
+.. automodule:: xscen.ensembles
    :members:
+   :noindex:
 
-Quality Checks
---------------
+Diagnostics and Quality Checks
+------------------------------
 
-.. automodule:: xscen.checkups
+.. automodule:: xscen.diagnostics
    :members:
+   :noindex:
 
-Input / output
+Input / Output
 --------------
 
 .. automodule:: xscen.io
    :members:
+   :noindex:
 
-Script utilities
+Configuration Utilities
+-----------------------
+
+.. automodule:: xscen.config
+   :members:
+   :noindex:
+
+Script Utilities
 ----------------
 
-.. automodule:: xscen.common
+.. automodule:: xscen.scripting
    :members:
-.. automodule:: xscen.scr_utils
+   :noindex:
+
+Packaging Utilities
+-------------------
+
+.. automodule:: xscen.utils
    :members:
+   :noindex:
diff --git a/docs/conf.py b/docs/conf.py
@@ -53,6 +53,9 @@
     "special-members": False,
 }
 
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
+
 autosummary_generate = True
 nbsphinx_execute = "auto"
 
@@ -80,9 +83,9 @@
 intersphinx_mapping = {}
 
 extlinks = {
-    "issue": ("https://github.com/Ouranosinc/xscen/issues/%s", "GH/"),
-    "pull": ("https://github.com/Ouranosinc/xscen/pull/%s", "PR/"),
-    "user": ("https://github.com/%s", "@"),
+    "issue": ("https://github.com/Ouranosinc/xscen/issues/%s", "GH/%s"),
+    "pull": ("https://github.com/Ouranosinc/xscen/pull/%s", "PR/%s"),
+    "user": ("https://github.com/%s", "@%s"),
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -116,7 +119,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/docs/index.rst b/docs/index.rst
@@ -30,3 +30,15 @@ Features
     contributing
     authors
     history
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Public Modules
+
+   xscen
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Package Structure
+
+   modules
diff --git a/docs/notebooks b/docs/notebooks
diff --git a/environment-dev.yml b/environment-dev.yml
@@ -5,33 +5,35 @@ dependencies:
   # Don't forget to sync the changes here with environment.yml!
   # Some pins here are meant to accelerate conda and might not be related to real needs
   # Main packages
+  - cftime
+  - clisops
   - xarray
   - xclim>=0.37
   - xesmf>=0.6.3
   - dask
+  - geopandas
   - pandas
-  - clisops
   - rechunker
-  - cftime
+  - shapely
   - yaml
   # This ensures that the correct numpy is installed as of 2022-07-15.
   - numba>=0.55.2
   # Plotting
-  - matplotlib
   - cartopy
+  - matplotlib
   - nc-time-axis>=1.3.1
   # IO
   - h5netcdf
-  - zarr
   - netCDF4
   - pyarrow>=1.0.0  # For lighter in-memory catalogs
+  - zarr
   # For intake-esm (so that conda installs the dependencies and not pip)
   - fastprogress
   - fsspec
   - intake
   - pydantic
-  - xcollection
   - requests
+  - xcollection
   # Dev
   - ipykernel
   - ipython
@@ -40,6 +42,7 @@ dependencies:
   - pandoc
   - pooch
   - pre-commit
+  - pytest
   - sphinx
   - sphinx-autoapi
   - sphinx_rtd_theme

diff --git a/environment.yml b/environment.yml
@@ -3,33 +3,36 @@ channels:
   - conda-forge
   - defaults
 dependencies:
+  - python >=3.8
   # FIXME: These entries require versions
   # Don't forget to sync the changes here with environment-dev.yml!
   # Main packages
-  - xarray
-  - xclim>=0.37
-  - xesmf>=0.6.2
+  - cftime
+  - clisops
   - dask
+  - geopandas
   - pandas
-  - clisops
   - rechunker
-  - cftime
+  - shapely
+  - xarray
+  - xclim>=0.37
+  - xesmf>=0.6.2
   - yaml
   # Plotting
-  - matplotlib
   - cartopy
+  - matplotlib
   - nc-time-axis>=1.3.1
   # IO
   - h5py
-  - zarr
   - netCDF4
+  - zarr
   # For intake-esm (so that conda installs the dependencies and not pip)
   - fastprogress
   - fsspec
   - intake
   - pydantic
-  - xcollection
   - requests
+  - xcollection
   - pip
   - pip:
     - git+https://github.com/intake/intake-esm.git#egg=intake-esm
diff --git a/setup.py b/setup.py
@@ -15,20 +15,26 @@
 # this is only meant to make `pip check` work
 # xscen dependencies can only be installed through conda-forge.
 requirements = [
-    "intake_esm>=2021.8.17",
-    "xesmf>=0.6.2",  # This is not available on pypi.
-    "xarray",
-    "xclim>=0.37",
+    "cartopy",
+    "cftime",
+    "clisops",
     "dask",
+    "fsspec",
+    "geopandas",
+    "h5py",
+    "intake",
+    "intake_esm>=2021.8.17",
+    "matplotlib",
+    "netCDF4",
+    "numpy",
     "pandas",
-    "clisops",
-    "rechunker",
     "pyyaml",
-    "matplotlib",
-    "cartopy",
-    "h5py",
+    "rechunker",
+    "shapely",
+    "xarray",
+    "xclim>=0.37",
+    "xesmf>=0.6.2",  # This is not available on pypi.
     "zarr",
-    "netCDF4",
 ]
 
 setup(

diff --git a/tox.ini b/tox.ini
@@ -1,5 +1,5 @@
 [tox]
-envlist = black, py{37,38,39,310}, docs
+envlist = black, py{38,39,310}, docs
 requires = pip >= 20.0
 opts = --verbose