Xclim

--------------------

Announcements
^^^^^^^^^^^^^
* `xclim` no longer supports Python3.6. Code conventions and new features from Python3.7 (`PEP 537 Features <https://peps.python.org/pep-0537/#features-for-3-7>`_) are now accepted.

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* `core.calendar.doy_to_days_since` and `days_since_to_doy` to allow meaningful statistics on doy data.
* New bias second-order adjustment method "ExtremeValues", intended for re-adjusting extreme precipitation values.
* Virtual indicators modules can now be built from YAML files.
* Indicators can now be built from dictionaries.
* New generic indices, implementation of `clix-meta`'s index functions.
* On-the-fly generation of climate and forecasting convention (CF) checks with `xc.core.cfchecks.generate_cfcheck`, for a few known variables only.
* New `xc.indices.run_length.rle_statistics` for min, max, mean, std (etc) statistics on run lengths.
* New virtual submodule `cf`, with CF standard indices defined in `clix-meta <https://github.com/clix-meta/clix-meta>`_.
* Indices returning day-of-year data add two new attributes to the output: `is_dayofyear` (=1) and `calendar`.

Breaking changes
^^^^^^^^^^^^^^^^
* `xclim` now requires `xarray>=0.17`.
* Virtual submodules `icclim` and `anuclim` are not available at the top level anymore (only through `xclim.indicators`).
* Virtual submodules `icclim` and `anuclim` now provide *Indicators* and not indices.
* Spatial analog methods "KLDIV" and "Nearest Neighbor" now require `scipy>=1.6.0`.

Bug fixes
^^^^^^^^^
* `from_string` object creation in sdba has been removed. Now replaced with use of a new dependency, `jsonpickle`.

Internal Changes
^^^^^^^^^^^^^^^^
* `pre-commit` linting checks now run formatting hook `black==21.4b2`.
* Code cleaning (more accurate call signatures, more use of https links, docstring updates, and typo fixes).

--------------------

Announcements
^^^^^^^^^^^^^
* Deprecation: Release 0.25.0 of `xclim` will be the last version to explicitly support Python3.6 and `xarray<0.17.0`.

New indicators
^^^^^^^^^^^^^^
* `land.winter_storm` computes days with snow accumulation over threshold.
* `land.blowing_snow` computes days with both snow accumulation over last days and high wind speeds.
* `land.snow_melt_we_max` computes the maximum snow melt over n days, and `land.melt_and_precip_max` the maximum combined snow melt and precipitation.
* `snd_max_doy` returns the day of the year where snow depth reaches its maximum value.
* `atmos.high_precip_low_temp` returns days with freezing rain conditions (low temperature and precipitations).
* `land.snow_cover_duration` computes the number of days snow depth exceeds some minimal threshold.
* `land.continuous_snow_cover_start` and `land.continuous_snow_cover_end` identify the day of the year when snow depth crosses a threshold for a given period of time.
* `days_with_snow`, counts days with snow between low and high thresholds, e.g. days with high amount of snow (`indice` and `indicator` available).
* `fire_season`, creates a fire season mask from temperature and, optionally, snow depth time-series.

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* `generic.count_domain` counts values within low and high thresholds.
* `run_length.season` returns a dataset storing the start, end and length of a *season*.
* Fire Weather indices now support dask-backed data.
* Objects from the `xclim.sdba` submodule can be created from their string repr or from the dataset they created.
* Fire Weather Index submodule replicates the R code of `cffdrs`, including fire season determination and overwintering of the drought_code.
* New `run_bounds` and `keep_longest_run` utilities in `xclim.indices.run_length`.
* New bias-adjustment method: `PrincipalComponent` (based on Hnilica et al. 2017 https://doi.org/10.1002/joc.4890).

Internal changes
^^^^^^^^^^^^^^^^
* Small changes in the output of `indices.run_length.rle`.

--------------------

New indicators
^^^^^^^^^^^^^^
* `days_over_precip_thresh`, `fraction_over_precip_thresh`, `liquid_precip_ratio`, `warm_spell_duration_index`, all from eponymous indices.
* `maximum_consecutive_warm_days` from indice `maximum_consecutive_tx_days`.

Breaking changes
^^^^^^^^^^^^^^^^
* Numerous changes to `xclim.core.calendar.percentile_doy`:

* `per` now accepts a sequence as well as a scalar and as such the output has a percentiles axis.
* `per` argument is now expected to between 0-100 (not 0-1).
* input data must have a daily (or coarser) time frequency.

* Change in unit handling paradigm for indices, which as a result will lead to some indices returning values with different units. Note that related `Indicator` objects remain unchanged and will return units consistent with CF Convention. If you are concerned with code stability, please use `Indicator` objects. The change was necessary to resolve inconsistencies with xarray's `keep_attrs=True` context.

* Indice functions now return output units that preserve consistency with input units. That is, feeding inputs in Celsius will yield outputs in Celsius instead of casting to Kelvin. In all cases the dimensionality is preserved.
* Indice functions now accept non-daily data, but daily frequency is assumed by default if the frequency cannot be inferred.

* Removed the explicitly-installed `netCDF4` python library from the base installation, as this is never explicitly used (now only installed in the `docs` recipe for sdba documented example).
* Removed `xclim.core.checks`, which was deprecated since v0.18.

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Indicator now have docstrings generated from their metadata.
* Units and fixed choices set are parsed from indice docstrings into `Indicator.parameters`.
* Units of indices using the `declare_units` decorator are stored in `indice.in_units` and `indice.out_units`.
* Changes to `Indicator.format` and `Indicator.json` to ensure the resulting json really is serializable.

Internal changes
^^^^^^^^^^^^^^^^
* Leave `missing_options` undefined in `land.fit` indicator to allow control via `set_options`.
* Modified `xclim.core.calendar.percentile_doy` to improve performance.
* New `xclim.core.calendar.compare_offsets` for comparing offset strings.
* New `xclim.indices.generic.get_op` to retrieve a function from a string representation of that operator.
* The CI pipeline has been migrated from Travis CI to GitHub Actions. All stages are still built using `tox`.
* Indice functions must always set the units (the `declare_units` decorator does no check anymore).
* New `xclim.core.units.rate2amout` to convert rates like precipitation to amounts.
* `xclim.core.units.pint2cfunits` now removes ' * ' symbols and changes `Δ°` to `delta_deg`.
* New `xclim.core.units.to_agg_units` and `xclim.core.units.infer_sampling_units` for unit handling involving aggregation operations along the time dimension.
* Added an indicators API page to the docs and links to there from the `Climate Indicators` page.

Bug fixes
^^^^^^^^^
* The unit handling change resolved a bug that prevented the use of `xr.set_options(keep_attrs=True)` with indices.

--------------------

Breaking changes
^^^^^^^^^^^^^^^^
* Renamed indicator `atmos.degree_days_depassment_date` to `atmos.degree_days_exceedance_date`.
* In `degree_days_exceedance_date` : renamed argument `start_date` to `after_date`.
* Added cfchecks for Pr+Tas-based indicators.
* Refactored test suite to now be available as part of the standard library installation (`xclim.testing.tests`).
* Running `pytest` with `xdoctest` now requires the `rootdir` to point at `tests` location (`pytest --rootdir xclim/testing/tests/ --xdoctest xclim`).
* Development checks now require working jupyter notebooks (assessed via the `pytest --nbval` command).

New indicators
^^^^^^^^^^^^^^
* `rain_approximation` and `snowfall_approximation` for computing `prlp` and `prsn` from `pr` and `tas` (or `tasmin` or `tasmax`) according to some threshold and method.
* `solid_precip_accumulation` and `liquid_precip_accumulation` now accept a `thresh` parameter to control the binary snow/rain temperature threshold.
* `first_snowfall` and `last_snowfall` to compute the date of first/last snowfall exceeding a threshold in a period.

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* New `kind` entry in the `parameters` property of indicators, differentiating between [optional] variables and parameters.
* The git pre-commit hooks (`pre-commit run --all`) now clean the jupyter notebooks with `nbstripout` call.

Bug fixes
^^^^^^^^^
* Fixed a bug in `indices.run_length.lazy_indexing` that occurred with 1D coords and 0D indexes when using the dask backend.
* Fixed a bug with default frequency handling affecting `fit` indicator.
* Set missing method to 'skip' for `freq_analysis` indicator.
* Fixed a bug in `ensembles._ens_align_datasets` that occurred when inputs are `.nc` filepaths but files lack a time dimension.

Internal changes
^^^^^^^^^^^^^^^^
* `core.cfchecks.check_valid` now accepts a sequence of strings as its `expected` argument.
* Clean up in the tests to speed up testing. Addition of a marker to include "slow" tests when desired (`-m slow`).
* Fixes in the tests to support `sklearn>=0.24`, `clisops>=0.5` and build xarraymaster against python 3.7.
* Moved the testing suite to within xclim and simplified `tox` to manage its own tempdir.
* Indicator class now has a `default_freq` method.

--------------------

Breaking changes
^^^^^^^^^^^^^^^^
* Statistical functions (`frequency_analysis`, `fa`, `fit`, `parametric_quantile`) are now solely accessible via `indices.stats`.

New indicators
^^^^^^^^^^^^^^
* `atmos.degree_days_depassment_date`, the day of year when the degree days sum exceeds a threshold.

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Added unique titles to `atmos` calculations employing wrapped_partials.
* `xclim.core.calendar.convert_calendar` now accepts a `missing` argument.
* Added `xclim.core.calendar.date_range` and `xclim.core.calendar.date_range_like` wrapping pandas' `date_range` and xarray's `cftime_range`.
* `xclim.core.calendar.get_calendar` now accepts many different types of data, including datetime object directly.
* New module `xclim.analog` and method `xclim.analog.spatial_analogs` to compute spatial analogs.
* Indicators can now accept dataset in their new `ds` call argument. Variable arguments (that use the `DataArray` annotation) can now be given with strings that correspond to variable names in the dataset, and default to their own name.
* Clarification to `frequency_analysis` notebook.
* Now officially supporting PEP596 (Python3.9).
* New methods `xclim.ensembles.change_significance` and `xclim.ensembles.knutti_sedlacek` to qualify climate change agreement among members of an ensemble.

Bug fixes
^^^^^^^^^
* Fixed bug that prevented the use of `xclim.core.missing.MissingBase` and subclasses with an indexer and a cftime datetime coordinate.
* Fixed issues with metadata handling in statistical indices.
* Various small fixes to the documentation (re-establishment of some internally and externally linked documents).

Internal changes
^^^^^^^^^^^^^^^^
* Passing `align_on` to `xclim.core.calendar.convert_calendar` without using '360_day' calendars will not raise a warning anymore.
* Added formatting utilities for metadata attributes (`update_cell_methods`, `prefix_attrs` and `unprefix_attrs`).
* `xclim/ensembles.py` moved to `xclim/ensembles/*.py`, splitting stats/creation, reduction and robustness methods.
* With the help of the `mypy` library, added several typing fixes to better identify inputs/outputs, and reduce object type mutations.
* Fixed some doctests in `ensembles` and `set_options`.
* `clisops` v0.4.0+ is now an optional requirements for non-Windows builds.
* New `xclim.core.units.str2pint` method to convert quantity strings to quantity objects. Main improvement is to make "3 degC days" a valid string that converts to "3 K days".

--------------------

Breaking changes
^^^^^^^^^^^^^^^^
* Statistical functions (`frequency_analysis`, `fa`, `fit`, `parametric_quantile`) moved from `indices.generic` to `indices.stats` to make them more visible.

New indicators
^^^^^^^^^^^^^^

New features and enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* New xclim.testing.open_dataset method to read data from the remote testdata repo.
* Added a notebook, `ensembles-advanced.ipynb`, to the documentation detailing ensemble reduction techniques and showing how to make use of built-in figure-generating commands.
* Added a notebook, `frequency_analysis.ipynb`, with examples showcasing frequency analysis capabilities.

Bug fixes
^^^^^^^^^
* Fixed a bug in the attributes of `frost_season_length`.
* `indices.run_length` methods using dates now respect the array's calendar.
* Worked around an xarray bug in sdba.QuantileDeltaMapping when multidimensional arrays are used with linear or cubic interpolation.

Internal changes
^^^^^^^^^^^^^^^^^