xclim 1.0.0

v1.0.0

on Python PyPI

Contributors to this version: Trevor James Smith (@Zeitsperre), Pascal Bourgault (@aulemahal), Éric Dupuis (@coxipi), Sarah Gammon (@SarahG-579462), Baptiste Hamon (@baptistehamon), Juliette Lavoie (@juliettelavoie), Charles Lu (@Lu-Charles), Kobe Vandelanotte (@kobebryant432), Ludwig Lierhammer (@ludwiglierhammer).

Announcements

This release constitutes a major breaking change from the previous stable release (v0.x) and introduces several new features, enhancements, and API changes.
Users are strongly encouraged to review the breaking changes section below to ensure compatibility with their existing codebases.
Documentation has been updated to reflect these changes as well as to help existing users migrate to the new version.
See Differences between v0 and v1 for a summary of the breaking changes and guidance on how to transition to xclim v1.
The xclim library is now considered to be production-level stable.
xclim functions and objects have been fully overhauled for mypy/ty typing-compliance (GH/1719, PR/2425).

Major changes

• Module xclim.indices has been renamed to xclim.compute. The functions made to build indicators are now called "[index-like] compute functions" and the word "indices" is now avoided as much as possible. (GH/2320, PR/2330).
• Major refactor of xclim.indices.generic to reduce duplication and harmonize signatures. (PR/2258):
  • Generic functions from clix-meta are now in their own submodule xclim.indices.clix and some indicators in xclim.cf have changed to reflect changes in standards.
  • A summary of the changes can be found in this comment.
• Refactor of the xclim.core.indicator.Indicator class itself (PR/2397). Most breaking changes are:
  • Indicators return Dataset by default, option as_dataset is now True by default (GH/2410, PR/2414).
  • Output metadata are stored in Indicator.outputs (renamed from cf_attrs), which is a list of xclim.core.indicator.Output objects (not dictionaries), which have a .attrs property holding the attributes (PR/2426).
  • Renamed Indicator.translate_attrs to Indicator.translate.
  • The xclim.core.indicator.registry now holds Indicator instances (not classes) and is case-insensitive.
  • "Virtual submodules" were transformed into xclim.core.collection.IndicatorCollection instances (and not actual python modules). Indicators created this way automatically have the collection's name prepended to their identifier. Indicators created in the context of a collection are not registered by default. (PR/2415).
  • Copying/Subclassing an existing indicator is now done through Indicator.copy, method Indicator.from_dict is deprecated. (PR/2424).
  • Indicators will now add an xclim_description attribute to all their outputs. This is similar to the history that is now only appended to output datasets, but excludes datetime and xclim's version. It does not append any input metadata. (PR/2431).

New indicators and features

• The xclim command-line tool now accepts both -h and --help to show the help summary. (PR/2316).
• The select_time function has been improved. (GH/2365, GH/2393, PR/2374):
  • Open date_bounds and doy_bounds are now supported (i.e., None as start or end).
  • The include_doy_bounds_nans argument has been added to control whether NaN values in the bounds should be filled or not. When set to True, missing values in the start or end bounds are replaced by the start and end of the period, respectively.
  • The bounds_freq argument has been added to allow users to specify the frequency to use when using open date_bounds.
• Added multimember support through new argument 'dim' and new test 'signal-to-noise' for xclim.ensembles.robustness_fractions (PR/2411).
• IndicatorCollection yaml specifications updates:
  • New bases section for defining indicator classes to reuse in defining the ones in the indicators section (PR/2415).
  • Fields base and compute can now be a "qualified name" of an object to be imported dynamically, or the qualified name of an indicator with its submodule/realm. Ex: atmos.precip_accumulation, which was previously referred by its identifier prcptot (PR/2415).
• New arguments validity_ranges and hurs_cap_min in indicator universal_thermal_climate_index (UTCI).
  In accordance with recommendations from Bröde et al. (2012), default validity upper bounds were increased for tas - mrt (from 30°C to 70°C) and sfcWind (from 17 to 30.3 m/s) and capping is now enabled by default (sfcWind to a minimum of 0.5 m/s and of hurs to a minimum of 5 %). (GH/2400, PR/2432).
• xclim supports passing of all Quantified-like objects to all functions (GH/1726, PR/2425).

Bug fixes

• Handling of units_metadata has been updated. (PR/2431).
  • In convert_units_to, if the source is known to be "on-scale" or "difference" but the target is ambiguous, the source's metadata is preserved.
  • When "difference" units are formatted to string, CF symbols are more consistently used.
• potential_evapotranspiration with method="DA02" now returns NaN instead of 0 where inputs are missing. (GH/2448).

Breaking changes

• xclim has fully dropped Python 3.10 and numpy below v2.0. Python 3.11+ coding conventions are now accepted. (PR/2355).
• Legacy imports, links, and documentation for xsdba have been removed. (PR/2342).
• Installation recipes have been significantly modified to mimic conventions employed by xarray. (PR/2316). Most development-related recipes are now installed via dependency-groups (PEP-735) and optional-dependencies are as follows:
  • dependency-groups: lint (linting tools), notebooks (minimum for interactive notebooks), test (minimum for running tests), docs (minimum for building docs), test-notebooks (minimum for running notebook tests), dev (full suite for local development).
  • optional-dependencies: bias-adjustment (xsdba and others), performance (speedups), plot (plotting), types (static typing support).
• The complete recipe has been removed due to design issues. (PR/2355).
• For PEP-735 support, xclim now requires modern pip (>=25.2) and tox (>=4.34). (PR/2316).
• mypy has been replaced with ty as the type checking/inferencing tool and is now run on GitHub Workflows alongside pylint.
  While most checks are currently disabled, these will be progressively enforced in subsequent updates. (PR/2355).
• Previously deprecated indicators have been removed:
  • xclim.indicators.land.snd_to_snow -> xclim.indicators.convert.snd_to_snow
  • xclim.indicators.land.snow_to_snd -> xclim.indicators.convert.snow_to_snd
  • xclim.indicators.convert.tg -> xclim.indicators.convert.mean_temperature_from_max_and_min
• The required versions for many core dependencies have been updated: numba (>=0.60.0), numpy (>=2.0), pip (>=26.1), scikit-learn (>=1.5.0), xarray (>=2024.6.0,!=2024.10.0). (PR/2355).
• pre-commit has been replaced by prek. prek is a pre-commit-config.yml compatible reimplementation built in Rust. (PR/2355).
• The approximate method APP is no longer allowed when using the genextreme distribution for standardized indices (e.g. xclim.indicators.atmos.standardized_precipitation_index and similar indicators).
• The output of xclim.compute.stats.parametric_cdf has a dimension v instead cdf (cdf more appropriately describes the output variable).
• mask_between_doys has been renamed to select_between_doys. (PR/2374):
  • The function now returns the selected values instead of a boolean mask.
  • For array-like doy_bounds without time dimension, the start and end bounds must now be consecutive according to the frequency (default: freq="YS"). Otherwise, the indexing is invalid and no data are selected.
• Variable q has been renamed to rivo in hydrological indicators (xclim.indicators.land) to follow modern naming conventions. xclim.land.doy_q{min|max} are renamed to xclim.land.rivo_{min|max}_doy. (GH/2407, PR/2408).
• Translation: xclim.core.locales.get_local_attrs has been rewritten and only accepts a single "locale" now. Locale dictionaries are now case-insensitive. (PR/2397).
• Replace hard-coded length of period to actually use the length of the input in test ipcc-ar6-c of xclim.ensembles.robustness_fractions. (PR/2411, GH/2406).
• xclim.compute.fit now avoids adding an extra white space when there are more than one shape parameter, which changes the coordinate to be expected. (PR/2428).
• Documentation targets for functions, classes, and variables no longer link to the sphinx-autodoc module mappings. All historical hyperlinks to apidoc will no longer function as expected. The user api pages have been refactored to help navigation. (PR/2424).
• xclim.core.indicator has been refactored into its own submodule. All publicly-documented members remain accessible via xclim.core.indicator imports. (PR/2424).

Internal changes

• xclim.compute.run_length.keep_longest_run uses run boundaries to select the longest run for boolean and numeric 0/1 inputs, avoiding intermediate floating-point arrays while preserving existing results. (GH/2131, PR/2433).
• The Makefile has been adjusted to install libraries in advance (via python -m pip install --silent --group ...) when attempting to run commands reliant on specific Python tools. (PR/2316).
• tox.toml has been updated to use dependency-groups to determine necessary libraries needed for environments, and relies entirely on the Makefile for running checks. (PR/2316).
• Documentation has been adjusted to reflect changes to environment setup required by developers/contributors. (PR/2316).
• The Makefile now defines typing-relevant checks (make typing; dependent on make install-typing) that are enforced in GitHub Workflows. (PR/2355).
• Call signature typing for many indices have been better identified. The cast function (used to force expected variable types of internal objects) is now less prevalent within the code base. (PR/2355).
• tox.toml now uses the build-composition API, requiring tox >=4.52.0. (PR/2355).
• The LaTeX formulas and tables of many indices docstrings were failing to render in ReadTheDocs due to small syntax typos. These have been addressed. (PR/2355).
• A page has been added to the documentation (governance.rst) that describes the method through which decisions concerning xclim are made as well as the responsibilities of maintainers. (PR/2391).
• The security policy now details a brief security assurance that discusses the measures taken to ensure source code and package integrity. (PR/2391).
• Updated pylint to use v4.0+ standards and addressed several small linting issues. (PR/2409).
• Project metadata now compatible with flit >=4.0 standards. (PR/2412).
• On bump release, the CHANGELOG.rst file is now automatically updated to set the version title and release date. (PR/2413).
• AUTHORS.rst is now bundled in the license-files of packaged wheels. (PR/2413).
• make autodoc-custom-index has been removed in favour of make autodoc-noindex. make docs and other sphinx targets now use the new 'noindex' variant. (PR/2424).
• Testing of standardized_precipitation_index (SPI) was adjusted to re-enable bottleneck, which was disabled by xarray 2026.09. (PR/2446).
• The mypy type checking has been added to the pre-commit configurations (GH/1719, PR/2425).
• Many docstring, call signatures, and returns have been revised to ensure that internal typing is consistent across the entire library (PR/2425).
• xclim is now fully compliant with Semantic Versioning v2.0. The dev tag has been retired while -beta and -rc version tags will be used moving forward. (PR/2434):
  • bump-my-version has been updated to >=1.6.0 to make use of the bump version --to flag.
• Publishing workflows now use a two-step process and generate SLSA build provenance attestations (using actions/attest) when publishing distributions to TestPyPI and PyPI. (PR/2455)
• The minimum support version of pytest is now >=9.2.0. Running doctests now uses the new --confcutdir flag for selectively loading xclim/testing/conftest.py configurations. (PR/2455).