xsdba.testing package¶

Testing utilities for xsdba.

Submodules¶

xsdba.testing.diagnostics module¶

Diagnostics Testing Module

This module is meant to compare results with those expected from academic papers, or to aid in creating figures illustrating the behaviour of SDBA methods and utilities.

xsdba.testing.diagnostics.adapt_freq_graph()[source]¶

Create a graphic with the additive adjustment factors estimated after applying the adapt_freq method.

Returns:: The generated figure.
Return type:: plt.Figure

xsdba.testing.diagnostics.cannon_2015_figure_2() → Figure[source]¶

Create a graphic similar to figure 2 of Cannon et al. 2015.

The figure shows the distributions of the reference, historical and simulated data, as well as the future

Returns:: The generated figure.
Return type:: plt.Figure

xsdba.testing.diagnostics.synth_rainfall(shape: float, scale: float = 1.0, wet_freq: float = 0.25, size: int = 1) → ndarray[source]¶

Return gamma distributed rainfall values for wet days.

The returned values are zero for dry days.

Parameters:

shape (float) – The shape parameter of the gamma distribution.
scale (float) – The scale parameter of the gamma distribution.
wet_freq (float) – The frequency of wet days.
size (int) – The number of values to generate.

Returns:

The generated values.

Return type:

np.ndarray

Notes

The probability density for the Gamma distribution is:

\[p(x) = x^{k-1}\frac{e^{-x/\theta}}{\theta^k\Gamma(k)}\]

where \(k\) is the shape and \(\theta\) the scale, and \(\Gamma\) is the Gamma function.

xsdba.testing.helpers module¶

Helper functions for testing purposes.

xsdba.testing.helpers.test_cannon_2015_dist()[source]¶

xsdba.testing.helpers.test_cannon_2015_rvs(n, random=True)[source]¶

xsdba.testing.helpers.test_timelonlatseries(values, attrs=None, start='2000-01-01')[source]¶: Create a DataArray with time, lon and lat dimensions.

xsdba.testing.helpers.test_timeseries(values, start: str = '2000-07-01', units: str | None = None, freq: str = 'D', as_dataset: bool = False, cftime: bool = False, calendar: str | None = None) → DataArray | Dataset[source]¶

Create a generic timeseries object based on pre-defined dictionaries of existing variables.

Parameters:

values (np.ndarray) – The values of the DataArray.
start (str) – The start date of the time dimension. Default is “2000-07-01”.
units (str or None) – The units of the DataArray. Default is None.
freq (str) – The frequency of the time dimension. Default is daily/”D”.
as_dataset (bool) – Whether to return a Dataset or a DataArray. Default is False.
cftime (bool) – Whether to use cftime or not. Default is False.
calendar (str or None) – Whether to use a calendar. If a calendar is provided, cftime is used.

Returns:

A DataArray or Dataset with time, lon and lat dimensions.

Return type:

xr.DataArray or xr.Dataset

xsdba.testing.sdba_utils module¶

Testing utilities for xsdba (bias adjustment)

xsdba.testing.sdba_utils.cannon_2015_dist()[source]¶

Generate the distributions used in Cannon et al. 2015.

Returns:: The reference, historical and simulated distributions.
Return type:: tuple[gamma, gamma, gamma]

xsdba.testing.sdba_utils.cannon_2015_rvs(n: int, random: bool = True) → list[DataArray][source]¶

Generate the Random Variables used in Cannon et al. 2015.

Parameters:

n (int) – The number of random variables to generate.
random (bool) – If True, generate random variables. Otherwise, generate evenly spaced nodes.

Returns:

A list of DataArrays with time, lon and lat dimensions.

Return type:

list[xr.DataArray]

xsdba.testing.sdba_utils.timelonlatseries(values: ndarray, name: str, start: str = '2000-01-01')[source]¶

Create a DataArray with time, lon and lat dimensions.

Parameters:

values (np.ndarray) – The values of the DataArray.
name (str) – The name of the DataArray.
start (str) – The start date of the time dimension.

Returns:

A DataArray with time, lon and lat dimensions.

Return type:

xr.DataArray

xsdba.testing.utils module¶

Testing utilities for xsdba.

xsdba.testing.utils.TESTDATA_BRANCH = 'v2024.8.23'¶

Sets the branch of the testing data repository to use when fetching datasets.

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XSDBA_TESTDATA_BRANCH="my_testing_branch"

or setting the variable at runtime:

$ env XSDBA_TESTDATA_BRANCH="my_testing_branch" pytest

xsdba.testing.utils.TESTDATA_CACHE_DIR = PosixPath('/home/docs/.cache/xclim-testdata')¶

Sets the directory to store the testing datasets.

If not set, the default location will be used (based on platformdirs, see pooch.os_cache()).

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XSDBA_TESTDATA_CACHE_DIR="/path/to/my/data"

or setting the variable at runtime:

$ env XSDBA_TESTDATA_CACHE_DIR="/path/to/my/data" pytest

xsdba.testing.utils.TESTDATA_REPO_URL = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/'¶

Sets the URL of the testing data repository to use when fetching datasets.

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XSDBA_TESTDATA_REPO_URL="https://github.com/my_username/xclim-testdata"

or setting the variable at runtime:

$ env XSDBA_TESTDATA_REPO_URL="https://github.com/my_username/xclim-testdata" pytest

xsdba.testing.utils.audit_url(url: str, context: str | None = None) → str[source]¶

Check if the URL is well-formed.

Raises:: URLError – If the URL is not well-formed.

xsdba.testing.utils.default_testdata_cache = PosixPath('/home/docs/.cache/xclim-testdata')¶: Default location for the testing data cache.

xsdba.testing.utils.gather_testing_data(worker_cache_dir: str | PathLike[str] | Path, worker_id: str, _cache_dir: str | PathLike[str] | None = PosixPath('/home/docs/.cache/xclim-testdata'))[source]¶: Gather testing data across workers.

xsdba.testing.utils.gosset(repo: str = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/', branch: str = 'v2024.8.23', cache_dir: str | Path = PosixPath('/home/docs/.cache/xclim-testdata'), data_updates: bool = True)[source]¶

Pooch registry instance for xsdba test data.

Parameters:

repo (str) – URL of the repository to use when fetching testing datasets.
branch (str) – Branch of repository to use when fetching testing datasets.
cache_dir (str or Path) – The path to the directory where the data files are stored.
data_updates (bool) – If True, allow updates to the data files. Default is True.

Returns:

The Pooch instance for accessing the xsdba testing data.

Return type:

pooch.Pooch

Notes

There are three environment variables that can be used to control the behaviour of this registry:

XSDBA_TESTDATA_CACHE_DIR: If this environment variable is set, it will be used as the base directory to store the data files. The directory should be an absolute path (i.e., it should start with /). Otherwise,the default location will be used (based on platformdirs, see pooch.os_cache()).
XSDBA_TESTDATA_REPO_URL: If this environment variable is set, it will be used as the URL of the repository to use when fetching datasets. Otherwise, the default repository will be used.
XSDBA_TESTDATA_BRANCH: If this environment variable is set, it will be used as the branch of the repository to use when fetching datasets. Otherwise, the default branch will be used.

Examples

Using the registry to download a file:

import xarray as xr
from xsdba.testing.utilities import gosset

example_file = gosset().fetch("example.nc")
data = xr.open_dataset(example_file)

xsdba.testing.utils.load_registry(branch: str = 'v2024.8.23', repo: str = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/') → dict[str, str][source]¶

Load the registry file for the test data.

Returns:: Dictionary of filenames and hashes.
Return type:: dict

xsdba.testing.utils.populate_testing_data(temp_folder: Path | None = None, repo: str = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/', branch: str = 'v2024.8.23', local_cache: Path = PosixPath('/home/docs/.cache/xclim-testdata')) → None[source]¶

Populate the local cache with the testing data.

Parameters:

temp_folder (Path, optional) – Path to a temporary folder to use as the local cache. If not provided, the default location will be used.
repo (str, optional) – URL of the repository to use when fetching testing datasets.
branch (str, optional) – Branch of xclim-testdata to use when fetching testing datasets.
local_cache (Path) – The path to the local cache. Defaults to the location set by the platformdirs library. The testing data will be downloaded to this local cache.

Return type:

None

xsdba.testing.utils.testing_setup_warnings()[source]¶: Warn users about potential incompatibilities between xsdba and xclim-testdata versions.