xclim.testing package

Helpers for testing xclim.

Submodules

xclim.testing.diagnostics module

SDBA Diagnostic Testing Module

This module is meant to compare results with those expected from papers, or create figures illustrating the behavior of sdba methods and utilities.

xclim.testing.diagnostics.adapt_freq_graph()[source]

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

xclim.testing.diagnostics.cannon_2015_figure_2()[source]

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

xclim.testing.diagnostics.synth_rainfall(shape, scale=1, wet_freq=0.25, size=1)[source]

Return gamma distributed rainfall values for wet days.

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.

xclim.testing.helpers module

Module for loading testing data.

xclim.testing.helpers.PREFETCH_TESTING_DATA = False

Indicates whether the testing data should be downloaded when running tests.

Notes

When running tests multiple times, this flag allows developers to significantly speed up the pytest suite by preventing sha256sum checks for all downloaded files. Proceed with caution.

This can be set for both pytest and tox by exporting the variable:

$ export XCLIM_PREFETCH_TESTING_DATA=1

or setting the variable at runtime:

$ env XCLIM_PREFETCH_TESTING_DATA=1 pytest
xclim.testing.helpers.TESTDATA_BRANCH = 'main'

Sets the branch of Ouranosinc/xclim-testdata to use when fetching testing datasets.

Notes

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

$ export XCLIM_TESTDATA_BRANCH="my_testing_branch"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_BRANCH="my_testing_branch" pytest
xclim.testing.helpers.add_example_file_paths(cache_dir)[source]

Create a dictionary of relevant datasets to be patched into the xdoctest namespace.

Return type:

dict[str]

xclim.testing.helpers.assert_lazy = <dask.callbacks.Callback object>

Context manager that raises an AssertionError if any dask computation is triggered.

xclim.testing.helpers.generate_atmos(cache_dir)[source]

Create the atmosds synthetic testing dataset.

xclim.testing.helpers.populate_testing_data(temp_folder=None, branch='main', _local_cache=PosixPath('/home/docs/.cache/xclim-testdata'))[source]

Perform _get_file or get_local_dataset calls to GitHub to download or copy relevant testing data.

xclim.testing.helpers.test_timeseries(values, variable, start='2000-07-01', units=None, freq='D', as_dataset=False, cftime=False)[source]

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

xclim.testing.sdba_utils module

SDBA Testing Utilities Module

xclim.testing.sdba_utils.cannon_2015_dist()[source]
xclim.testing.sdba_utils.cannon_2015_rvs(n, random=True)[source]
xclim.testing.sdba_utils.nancov(X)[source]

Numpy’s cov but dropping observations with NaNs.

xclim.testing.sdba_utils.series(values, name, start='2000-01-01')[source]

Create a DataArray with time, lon and lat dimensions.

xclim.testing.utils module

Testing and Tutorial Utilities’ Module

xclim.testing.utils.get_file(name, github_url='https://github.com/Ouranosinc/xclim-testdata', branch='main', cache_dir=PosixPath('/home/docs/.cache/xclim-testdata'))[source]

Return a file from an online GitHub-like repository.

If a local copy is found then always use that to avoid network traffic.

Parameters:

  • name (str | os.PathLike | Sequence[str | os.PathLike]) – Name of the file or list/tuple of names of files containing the dataset(s) including suffixes.

  • github_url (str) – URL to GitHub repository where the data is stored.

  • branch (str, optional) – For GitHub-hosted files, the branch to download from.

  • cache_dir (Path) – The directory in which to search for and write cached data.

Return type:

Path | list[Path]

Returns:

Path | list[Path]

xclim.testing.utils.get_local_testdata(patterns, temp_folder, branch='master', _local_cache=PosixPath('/home/docs/.cache/xclim-testdata'))[source]

Copy specific testdata from a default cache to a temporary folder.

Return files matching pattern in the default cache dir and move to a local temp folder.

Parameters:

  • patterns (str | Sequence[str]) – Glob patterns, which must include the folder.

  • temp_folder (str | os.PathLike) – Target folder to copy files and filetree to.

  • branch (str) – For GitHub-hosted files, the branch to download from.

  • _local_cache (str | os.PathLike) – Local cache of testing data.

Return type:

Path | list[Path]

Returns:

Path | list[Path]

xclim.testing.utils.list_datasets(github_repo='Ouranosinc/xclim-testdata', branch='main')[source]

Return a DataFrame listing all xclim test datasets available on the GitHub repo for the given branch.

The result includes the filepath, as passed to open_dataset, the file size (in KB) and the html url to the file. This uses an unauthenticated call to GitHub’s REST API, so it is limited to 60 requests per hour (per IP). A single call of this function triggers one request per subdirectory, so use with parsimony.

xclim.testing.utils.list_input_variables(submodules=None, realms=None)[source]

List all possible variables names used in xclim’s indicators.

Made for development purposes. Parses all indicator parameters with the xclim.core.utils.InputKind.VARIABLE or OPTIONAL_VARIABLE kinds.

Parameters:

  • realms (Sequence of str, optional) – Restrict the output to indicators of a list of realms only. Default None, which parses all indicators.

  • submodules (str, optional) – Restrict the output to indicators of a list of submodules only. Default None, which parses all indicators.

Return type:

dict

Returns:

dict – A mapping from variable name to indicator class.

xclim.testing.utils.open_dataset(name, suffix=None, dap_url=None, github_url='https://github.com/Ouranosinc/xclim-testdata', branch='main', cache=True, cache_dir=PosixPath('/home/docs/.cache/xclim-testdata'), **kwargs)[source]

Open a dataset from the online GitHub-like repository.

If a local copy is found then always use that to avoid network traffic.

Parameters:

  • name (str or os.PathLike) – Name of the file containing the dataset.

  • suffix (str, optional) – If no suffix is given, assumed to be netCDF (‘.nc’ is appended). For no suffix, set “”.

  • dap_url (str, optional) – URL to OPeNDAP folder where the data is stored. If supplied, supersedes github_url.

  • github_url (str) – URL to GitHub repository where the data is stored.

  • branch (str, optional) – For GitHub-hosted files, the branch to download from.

  • cache_dir (Path) – The directory in which to search for and write cached data.

  • cache (bool) – If True, then cache data locally for use on subsequent calls.

  • **kwargs – For NetCDF files, keywords passed to xarray.open_dataset().

Return type:

Dataset

Returns:

Union[Dataset, Path]

See also

xarray.open_dataset

xclim.testing.utils.publish_release_notes(style='md', file=None, changes=None)[source]

Format release notes in Markdown or ReStructuredText.

Parameters:

  • style ({“rst”, “md”}) – Use ReStructuredText formatting or Markdown. Default: Markdown.

  • file ({os.PathLike, StringIO, TextIO}, optional) – If provided, prints to the given file-like object. Otherwise, returns a string.

  • changes ({str, os.PathLike}, optional) – If provided, manually points to the file where the changelog can be found. Assumes a relative path otherwise.

Return type:

str | None

Returns:

str, optional

Notes

This function is used solely for development and packaging purposes.

xclim.testing.utils.show_versions(file=None, deps=None)[source]

Print the versions of xclim and its dependencies.

Parameters:

  • file ({os.PathLike, StringIO, TextIO}, optional) – If provided, prints to the given file-like object. Otherwise, returns a string.

  • deps (list, optional) – A list of dependencies to gather and print version information from. Otherwise, prints xclim dependencies.

Return type:

str | None

Returns:

str or None