Xscen

--------------------
Contributors to this version: Gabriel Rondeau-Genesse (:user:`RondeauG`), Pascal Bourgault (:user:`aulemahal`), Éric Dupuis (:user:`coxipi`).

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``xs.io.make_toc`` now includes the global attributes of the dataset after the information about the variables. (:pull:`473`).
* New function ``xs.get_warming_level_from_period`` to get the warming level associated with a given time horizon. (:pull:`474`).
* Added ability to skip whole folders to ``xs.parse_directory`` with argument ``skip_dirs``. (:pull:`478`, :pull:`479`).
* `diagnostics.measures_improvement` now accepts `dim`, which specifies `dimension(s)` on which the proportion of improved pixels are computed. (:pull:`416`)
* The argument `indicators` in ``xs.produce_horizon`` is now optional. Added an argument `op` to control the climatological operation. (:pull:`483`).

Breaking changes
^^^^^^^^^^^^^^^^
* ``xs.get_warming_level`` has been renamed to ``xs.get_period_from_warming_level``. Its argument `return_horizon` was reversed and renamed `return_central_year` (:pull:`474`).
* Removed support for the deprecated `xclim` function `change_significance` in `ensemble_stats`. (:pull:`482`).
* The argument `indicators` in ``xs.produce_horizon`` is no longer positional. (:pull:`483`).

Bug fixes
^^^^^^^^^
* ``xs.io.save_to_table`` now correctly handles the case where the input is a `DataArray` or a `Dataset` with a single variable. (:pull:`473`).
* Fixed a bug in ``xs.utils.change_units`` where the original dataset was also getting modified. (:pull:`482`).
* Fixed a bug in ``xs.compute_indicators`` where the `cat:variable` attribute was not correctly set. (:pull:`483`).
* Fixed a bug in ``xs.climatological_op`` where kwargs were not passed to the operation function. (:pull:`486`).
* Fixed a bug in ``xs.climatological_op`` where `min_periods` was not passed when the operation was `linregress`. (:pull:`486`).

Internal changes
^^^^^^^^^^^^^^^^
* Include CF convention for temperature differences and on scale (:pull:`428`, :issue:`428`).
* Bumped the version of `xclim` to 0.53.2. (:pull:`482`).
* More tests added. (:pull:`486`).
* Fixed a bug in ``xs.testing.datablock_3d`` where some attributes of the rotated pole got reversed half-way through the creation of the dataset. (:pull:`486`).
* The function ``xs.regrid._get_grid_mapping`` was moved to ``xs.spatial.get_grid_mapping`` and is now a public function. (:pull:`486`).

--------------------
Contributors to this version: Juliette Lavoie (:user:`juliettelavoie`), Pascal Bourgault (:user:`aulemahal`), Gabriel Rondeau-Genesse (:user:`RondeauG`), Trevor James Smith (:user:`Zeitsperre`).

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* The `mask` argument in ``stack_drop_nans`` can now be a list of dimensions. In that case, a `dropna(how='all')` operation will be used to create the mask on-the-fly. (:pull:`450`).
* Few changes to ``clean_up``:
* The `convert_calendar` function now uses `xarray` instead of `xclim`. (:pull:`450`).
* The `attrs_to_remove` and `remove_all_attrs_except` arguments now use real regex. (:pull:`450`).
* Multiple entries can now be given for `change_attr_prefix`. (:pull:`450`).
* ``minimum_calendar`` now accepts a list as input. (:pull:`450`).
* More calendars are now recognized in ``translate_time_chunk``. (:pull:`450`).
* `new_dim` in ``unstack_dates`` is now None by default and changes depending on the frequency. It becomes `month` if the data is exactly monthly, and keep the old default of `season` otherwise. (:pull:`450`).
* Updated the list of libraries in `show_versions` to reflect our current environment. (:pull:`450`).
* New ``xscen.catutils.patterns_from_schema`` to generate all possible patterns from a given schema (or one of xscen's default), to use with :py:func:`parse_directory`. (:pull:`431`).
* New ``DataCatalog.copy_files`` to copy all files of catalog to a new destination, unzipping if needed and returning a new catalog. (:pull:`431`).
* Convenience functions ``xs.io.zip_directory`` and ``xs.io.unzip_directory`` (for zarrs). (:pull:`431`).
* New argument ``compute_indicators``: ``rechunk_input`` to rechunk the inputs to resample-appropriate chunks before calling xclim. (:pull:`431`).
* New ``xs.indicators.get_indicator_outputs`` to retrieve what variable name(s) and frequency to expect from an xclim indicator. (:pull:`431`).
* `xscen` now supports launches tests from `pytest` with the `--numprocesses` option. See the `pytest-xdist documentation <https://pytest-xdist.readthedocs.io/en/stable/>`_ for more information. (:pull:`464`).
* Conservative regridding now supports oblique mercator projections. (:pull:`467`).
* The automatic name for the weight file in ``regrid_dataset`` is now more explicit to avoid errors, but now requires `cat:id` and `cat:domain` arguments for both the source and target datasets. (:pull:`467`).

Bug fixes
^^^^^^^^^
* Fixed bug with reusing weights. (:issue:`411`, :pull:`414`).
* Fixed bug in `update_from_ds` when "time" is a coordinate, but not a dimension. (:pull: `417`).
* Avoid modification of mutable arguments in ``search_data_catalogs`` (:pull:`413`).
* ``ensure_correct_time`` now correctly handles cases where timesteps are missing. (:pull:`440`).
* If using the argument `tile_buffer` with a `shape` method in ``spatial.subset``, the shapefile will now be reprojected to a WGS84 grid before the buffer is applied. (:pull:`440`).
* ``maybe_unstack`` now works if the dimension name is not the default. (:pull:`450`).
* ``unstack_fill_nan`` now works if given a dictionary that contains both dimensions and coordinates. (:pull:`450`).
* ``clean_up`` no longer modifies the original dataset. (:pull:`450`).
* ``unstack_dates`` now works correctly for yearly datasets when `winter_starts_year=True`, as well as multi-year datasets. (:pull:`450`).
* Fix ``xs.catalog.concat_data_catalogs`` for catalogs that have not been search yet. (:pull:`431`).
* Fix indicator computation using ``freq=2Q*`` by assuming this means a semiannual frequency anchored at the given month (pandas assumes 2 quarter steps, any of them anchored at the given month). (:pull:`431`).
* ``create_bounds_rotated_pole`` now uses the default value if the dataset has no `north_pole_grid_longitude` attribute, instead of crashing. (:pull:`455`).
* Rewrote the global tas data file with latest HDF5/h5py to avoid errors when using h5py 3.11 and hdf5 1.14.2. (:pull:`1861`).
* Remove reference of deprecated xclim functions (``convert_calendar``, ``get_calendar``) and adapt the code for supporting xclim 0.52.2 and its subsequent development version. (:pull:`465`).

Breaking changes
^^^^^^^^^^^^^^^^
* `convert_calendar` in ``clean_up`` now uses `xarray` instead of `xclim`. Keywords aren't compatible between the two, but given that `xclim` will abandon its function, no backwards compatibility was sought. (:pull:`450`).
* `attrs_to_remove` and `remove_all_attrs_except` in ``clean_up`` now use real regex. It should not be too breaking since a `fullmatch()` is used, but `*` is now `.*`. (:pull:`450`).
* Python 3.9 is no longer supported. (:pull:`456`).
* Functions and arguments that were deprecated in `xscen` v0.8.0 or earlier have been removed. (:pull:`461`).
* `pytest-xdist` is now a development dependency. (:pull:`464`).
* ``xs.regrid.create_bounds_rotated_pole`` has been renamed to ``xs.regrid.create_bounds_gridmapping``. (:pull:`467`).
* The `weights_location` argument in ``regrid_dataset`` is no longer positional. (:pull:`467`).
* The ``xs.regrid.create_mask`` function now requires explicit arguments instead of a dictionary. (:pull:`467`).

Internal changes
^^^^^^^^^^^^^^^^
* ``DataCatalog.to_dataset`` can now accept a ``preprocess`` argument even if ``create_ensemble_on`` is given. The user assumes calendar handling. (:pull:`431`).
* Include domain in `weight_location` in ``regrid_dataset``. (:pull:`414`).
* Added pins to `xarray`, `xclim`, `h5py`, and `netcdf4`. (:pull:`414`).
* Add ``.zip`` and ``.zarr.zip`` as possible file extensions for Zarr datasets. (:pull:`426`).
* Explicitly assign coords of multiindex in `xs.unstack_fill_nan`. (:pull:`427`).
* French translations are compiled offline. A new check ensures no PR are merged with missing messages. (:issue:`342`, :pull:`443`).
* Continued work to add tests. (:pull:`450`).
* Updated the cookiecutter template via `cruft`: (:pull:`452`)
* GitHub Workflows that use rely on `PyPI`-based dependencies now use commit hashes.
* `Dependabot` will now group updates by type.
* Dependencies have been updated and synchronized.
* Contributor guidance documentation has been adjusted.
* `numpydoc-validate` has been added to the linting tools.
* Linting checks are more reliant on `ruff` suggestions and stricter.
* `flake8-alphabetize` has been replaced by `ruff`.
* License information has been updated in the library top-level `__init__.py`.
* Docstrings have been adjusted to meet the `numpydoc` standard. (:pull:`452`).

CI changes
^^^^^^^^^^
* The `bump-version.yml` workflow now uses the Ouranosinc GitHub Helper Bot to sign bump version commits. (:pull:`462`).

-------------------
Contributors to this version: Pascal Bourgault (:user:`aulemahal`), Trevor James Smith (:user:`Zeitsperre`), Juliette Lavoie (:user:`juliettelavoie`).

Breaking changes
^^^^^^^^^^^^^^^^
* `xscen` now uses a `src layout <https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/>`_ in lieu of a flat layout. (:pull:`407`).

Bug fixes
^^^^^^^^^
* Fixed defaults for ``xr_combine_kwargs`` in ``extract_dataset`` (:pull:`402`).
* Fixed bug with `xs.utils.update_attr`(:issue:`404`, :pull:`405`).
* Fixed template 1 bugs due to changes in dependencies. ( :pull:`405`).

Internal changes
^^^^^^^^^^^^^^^^
* `cartopy` has been pinned above version '0.23.0' in order to address a licensing issue. (:pull:`403`).
* The cookiecutter template has been updated to the latest commit via `cruft`. (:pull:`407`).
* GitHub Workflows now point to commits rather than tags.
* `Dependabot` will now only update on a monthly schedule.
* Dependencies have been updated and synchronized.
* ``CHANGES.rst`` is now ``CHANGELOG.rst`` (see: ` KeepAChangelog <https://keepachangelog.com/en/1.0.0/>`_).
* The ``CODE_OF_CONDUCT.rst`` file adapted to `Contributor Covenant v2.1 <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>`_.
* Maintainer-specific directions are now found under ``releasing.rst``

-------------------
Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Pascal Bourgault (:user:`aulemahal`), Gabriel Rondeau-Genesse (:user:`RondeauG`), Juliette Lavoie (:user:`juliettelavoie`), Marco Braun (:user:`vindelico`).

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``xs.reduce_ensemble`` will now call ``xclim.ensembles.create_ensemble`` and ``xclim.ensembles.make_critera`` if required. (:pull:`386`).

Breaking changes
^^^^^^^^^^^^^^^^
* Removed support for the old instances of the `region` argument in ``spatial_mean``, ``extract_dataset``, and ``subset``. (:pull:`367`).
* Removed ``xscen.extract.clisops_subset``. (:pull:`367`).
* ``dtr`` (the function) was renamed to ``dtr_from_minmax`` to avoid confusion with the `dtr` variable. (:pull:`372`).
* The ``xscen.reduce`` module has been abandoned. (:pull:`386`).
* ``build_reduction_data`` has been made redundant by ``xclim.ensembles.make_critera`` and will be removed in a future release.
* ``xscen.reduce.reduce_ensemble`` has been moved to ``xscen.ensembles.reduce_ensemble``, as a module was no longer necessary.

Internal changes
^^^^^^^^^^^^^^^^
* Modified ``xscen.utils.change_unit`` to always adopt the name from the `variables_and_units dictionary` if the physical units are equal but their names are not (ex. degC <-> ˚C) (:pull:`373`).
* Updated the `cookiecutter` template to the latest version. (:pull:`358`):
* Addresses a handful of misconfigurations in the GitHub Workflows.
* Added a few free `grep`-based hooks for finding unwanted artifacts in the code base.
* Updated `ruff` to v0.2.0 and `black` to v24.2.0.
* Added more tests. (:pull:`366`, :pull:`367`, :pull:`372`).
* Refactored ``xs.spatial.subset`` into smaller functions. (:pull:`367`).
* An `encoding` argument was added to ``xs.config.load_config``. (:pull:`370`).
* Various small fixes to the code to address FutureWarnings. (:pull:`380`).
* ``xs.spatial.subset`` will try to guess CF coordinate if it can't find "latitude" or "longitude" in ``ds.cf``. (:pull:`384`).
* ``xs.extract_dataset`` and ``xs.DataCatalog.to_dataset`` will now default to opening datasets with option ``chunks={}``, which tries to respect chunking on disk. (:pull:`398`, :issue:`368`).

Bug fixes
^^^^^^^^^
* Fix ``unstack_dates`` for the new frequency syntax introduced by pandas v2.2. (:pull:`359`).
* ``subset_warming_level`` will not return partial subsets if the warming level is reached at the end of the timeseries. (:issue:`360`, :pull:`359`).
* Loading of training in `adjust` is now done outside of the periods loop. (:pull:`366`).
* Fixed bug for adding the preprocessing attributes inside the `adjust` function. (:pull:`366`).
* Fixed a bug to accept `group = False` in `adjust` function. (:pull:`366`).
* `creep_weights` now correctly handles the case where the grid is small, `n` is large, and `mode=wrap`. (:issue:`367`).
* Fixed a bug in ``tasmin_from_dtr`` and ``tasmax_from_dtr``, when `dtr` units differed from tasmin/max. (:pull:`372`).
* Fixed a bug where the requested chunking would be ignored when saving a dataset (:pull:`379`).
* The missing value check in ``health_checks`` will no longer crasg if a variable has no time dimension. (:pull:`382`).

-------------------
Contributors to this version: Juliette Lavoie (:user:`juliettelavoie`), Trevor James Smith (:user:`Zeitsperre`), Gabriel Rondeau-Genesse (:user:`RondeauG`), Pascal Bourgault (:user:`aulemahal`).

Announcements
^^^^^^^^^^^^^
* `xscen` now has a `security disclosure policy <https://github.com/Ouranosinc/xscen/tree/main?tab=security-ov-file#security-ov-file>`_. (:pull:`353`).
* Various frequency-related changes to match the new `pandas` naming conventions. (:pull:`351`).

Internal changes
^^^^^^^^^^^^^^^^
* Added tests for diagnostics. (:pull:`352`).
* Added a `SECURITY.md` file to the repository and the documentation. (:pull:`353`).
* Added `tox` modifier for testing builds against the `main` development branch of `xclim`. (:pull:`351`, :pull:`355`).
* Added a `requirements_upstream.txt` file to the repository to track the development branches of relevant dependencies. (:pull:`355`).
* Added a dedicated GitHub Workflow to evaluate compatibility with upstream dependencies. (:pull:`355`).

Breaking changes
^^^^^^^^^^^^^^^^
* `xscen` now requires `pandas` >= 2.2 and `xclim` >= 0.48.2. (:pull:`351`).
* Functions that output a dict with keys as xrfreq (such as ``extract_dataset``, ``compute_indicators``) will now return the new nomenclature (e.g. ``"YS-JAN"`` instead of ``"AS-JAN"``). (:pull:`351`).
* Going from `xrfreq` to frequencies or timedeltas will still work, but the opposite (frequency --> xrfreq/timedelta) will now only result in the new `pandas` nomenclature. (:pull:`351`).

-------------------
Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Pascal Bourgault (:user:`aulemahal`)

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Added a new argument ``indicators_kw`` to ``xs.ensembles.build_partition_data``. (:pull:`315`).
* `xscen` is `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`_ compliant. (:pull:`319`).
* `xesmf` made an optional dependency, making `xscen` easier to install with `pip`. (:pull:`337`).

Internal changes
^^^^^^^^^^^^^^^^
* Granular permissions and dependency scanning actions have been added to all GitHub CI Workflows. (:pull:`313`).
* Updated the list of dependencies to add missing requirements. (:pull:`314`).
* The `cookiecutter` template has been updated to the latest commit via `cruft`. (:pull:`319`):
* `actions-versions-updater.yml` has been replaced with `Dependabot <https://docs.github.com/en/code-security/dependabot/working-with-dependabot>`_ (it's just better).
* The OpenSSF `scorecard.yml` workflow has been added to the GitHub workflows to evaluate package security.
* Code formatting tools (`black`, `blackdoc`, `isort`) are now hard-pinned. These need to be kept in sync with changes from `pre-commit`. (Dependabot should perform this task automatically.)
* The versioning system has been updated to follow the Semantic Versioning 2.0.0 standard.
* Fixed an issue with `pytest -m "not requires_netcdf"` not working as expected. (:pull:`345`).