xclim

xclim is a climate services library designed for researchers working with Climate and Forecast Conventions (CF-Conventions) compliant datasets. It is optimized for Big Data in climate science and can be used in two primary ways:

1. Independent Library: For performing one-off climate analyses within Jupyter Notebooks.
2. Backend Engine: As a computational engine for Web Processing Services (WPS) (e.g., when used with Finch).

Primary Use Cases:

• Calculating climate indicators.
• Performing statistical correction or bias adjustment of climate model output variables/simulations.
• Performing climate model simulation ensemble statistics.

xclim is an operational Python library designed for climate services. It provides tools for:

• Climate Indicators: A collection of numerous climate-related indicators and an extensible framework to construct custom ones.
• Statistical Downscaling and Bias Adjustment (SDBA): Tools for downscaling and bias-adjusting climate model simulations.
• Ensemble Analysis: Tools for analyzing climate model ensembles.

xclim is built on top of xarray and leverages dask for parallelization, allowing users to process large climate datasets and perform bias adjustments over large spatial domains efficiently.

xclim is a Python library designed for computing climate indicators over large, heterogeneous datasets. It is built on top of xarray and leverages dask for parallelized, distributed computation.

Key architectural characteristics:

• Xarray-based: Uses xarray objects and operations as its primary data model.
• Dask-integrated: Seamlessly benefits from dask for handling large-scale data and parallelization.
• Metadata-driven: Relies on community conventions for data formatting and metadata attributes, specifically complying with Climate and Forecast (CF) metadata Conventions.
• Ecosystem integration: Designed to work alongside libraries like clisops (spatiotemporal subsetting/averaging) and xESMF (spatial regridding).

To ensure a coherent interface, xclim follows specific data conventions:

• Variable Attributes: Input data should follow CF conventions whenever possible.
• Variable Names: xclim typically uses variable names consistent with CMIP6 standards.
• Temporal Coordinate: xclim always assumes the temporal coordinate is named "time".

If your dataset uses a different name for the time dimension (e.g., "T"), you must rename it before using xclim functions:

ds = ds.rename(T="time")

Climate indicators in xclim are implemented using an Indicator class centered around a compute function.

When computing an indicator, xclim automatically performs several tasks:

1. Health Checks: Validates input data for correct units, time frequency, and outlier detection.
2. Missing Values: Handles missing values within the dataset.
3. Metadata Assignment: Assigns attributes to the output that comply with CF metadata Conventions.

Customization Options: You can customize indicators using three methods:

• Using a context manager.
• Through class inheritance.
• Via a YAML file, which allows for creating custom collections of indicators for batch processing.

Spatial analogues are maps that identify present-day regions with climates similar to the future climate of a specific target location. This is used for climate adaptation planning (e.g., a temperate city learning from a currently hot city how to manage future heatwaves).

To compute spatial analogues, you must define four key components:

1. Climate indices of interest: The specific metrics being compared (e.g., frost-free season length, growing degree-days).
2. Dissimilarity metrics: The mathematical method used to measure the difference between index distributions.
3. Reference data: The dataset used to compute base indices for candidate regions.
4. Future climate scenario: The dataset used to compute target indices for the location of interest.

The xclim.ensembles subpackage provides utilities for analyzing results from multiple climate models. It includes functionality for:

• Ensemble Reduction: Using clustering algorithms to reduce ensemble size.
• Robustness Metrics: Calculating metrics to evaluate ensemble robustness.
• Signal Significance: Determining the significance of climate change signals within an ensemble.

The xclim.sdba subpackage provides algorithms to adjust the distribution of simulated variables to match observed variables. It follows a train / adjust paradigm:

1. Train: Calculate correction factors based on the relationship between simulated and observed data.
2. Adjust: Apply those corrections to target data or save them for future use.

Supported Features:

• Correction Types: Supports both additive and multiplicative corrections.
• Time Groupings: Supports seasonal, monthly, or daily groupings (including rolling windows).
• Interpolation: Correction factors can be interpolated between time groupings to prevent discontinuities in the corrected data.

In xclim, Indices are the low-level driving mechanisms used to calculate specific climate metrics. They are best used when:

• You need to tweak default settings that are otherwise fixed in an Indicator.
• You do not require complete metadata (like standard_name or long_name).
• You are designing a custom virtual module from existing indices.

For general-purpose use and high-level climate analysis, the developers recommend using Climate Indicators (xclim.indicators) instead. Indicators wrap indices and provide missing value checks and CF-Convention attributes (e.g., long_name, description, cell_methods).

xclim is designed to work with the latest stable versions of the following libraries:

• xarray (Core dependency)
• dask (Core dependency)
• numpy
• scipy
• pandas

xclim follows the deprecation policies of the Scientific Python ecosystem (such as NEP-29 or SPEC-0). The minimum supported versions of these libraries are defined in the xclim package metadata and are updated periodically to align with ecosystem recommendations.

xclim aims for backwards compatibility. When breaking changes are necessary, they are adopted gradually using deprecation notices.

• Breaking Changes: Dropping support for older versions of dependency libraries is considered a breaking change. Significant API changes are documented in the changelog.
• Deprecation Policy: When features are deprecated, warnings are issued in the code. Support for these features is typically maintained for two or three stable releases, but users should migrate to the new API as soon as possible.

As of xclim==0.57, the SDBA (Statistical Downscaling and Bias Adjustment) utilities have been moved to a dedicated package called xsdba.

Important Notes:

• While xclim.sdba is still available in xclim for convenience to maintain compatibility, it now exposes functionality from the xsdba package.
• Some algorithms may have been slightly modified in the transition.
• It is recommended to use the xsdba package directly for new development. Documentation for xsdba can be found at :doc:xsdba API <xsdba:apidoc/xsdba>.