API Reference

This page provides an auto-generated summary of esmlab’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

Utilities

datasets.open_dataset(name[, cache, …])

Load a dataset from the online repository (requires access to internet).

Configuration

config.get(key[, default, config])

Get elements from global config

config.set([arg, config, lock])

Temporarily set configuration values within a context manager

Statistics functions

statistics.mae

statistics.mse

statistics.rmse

statistics.weighted_sum(data[, dim, weights])

Compute weighted sum for xarray objects

statistics.weighted_mean(data[, dim, weights])

Compute weighted mean for xarray objects

statistics.weighted_std(data[, dim, weights])

Compute weighted standard deviation for xarray objects

statistics.weighted_rmsd(x, y[, dim, weights])

Compute weighted root mean square deviation between two xarray DataArrays

statistics.weighted_cov(x, y[, dim, weights])

Compute weighted covariance between two xarray DataArrays.

statistics.weighted_corr(x, y[, dim, …])

Compute weighted correlation between two xarray.DataArray.

Climatologies

core.climatology(dset, freq[, time_coord_name])

Compute climatologies for a specified time frequency

Anomalies

core.anomaly(dset, clim_freq[, …])

Compute anomalies for a specified time frequency

Resample

core.resample(dset, freq[, weights, …])

Resample given dataset and computes the mean for specified sampling time frequecy

esmlab.datasets.open_dataset(name, cache=True, cache_dir='/home/docs/.esmlab/sample_data', github_url='https://github.com/NCAR/esmlab-data', branch='master', **kwargs)

Load a dataset from the online repository (requires access to internet).

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

Parameters
namestr

Name of the netcdf file containing the dataset ie. ‘air_temperature’

cache_dirstring, optional

The directory in which to search for and write cached data.

cacheboolean, optional

If True, then cache data locally for use on subsequent calls

github_urlstring

Github repository where the data is stored

branchstring

The git branch to download from

kwargsdict, optional

Passed to xarray.open_dataset

esmlab.config.get(key, default='__no_default__', config={'esmlab': {'sample-data-dir': '/home/docs/.esmlab/sample_data'}})

Get elements from global config

Use ‘.’ for nested access

Examples

>>> from esmlab import config
>>> config.get('foo')  # doctest: +SKIP
{'x': 1, 'y': 2}
>>> config.get('foo.x')  # doctest: +SKIP
1
>>> config.get('foo.x.y', default=123)  # doctest: +SKIP
123
esmlab.config.set(arg=None, config={'esmlab': {'sample-data-dir': '/home/docs/.esmlab/sample_data'}}, lock=<unlocked _thread.lock object>, **kwargs)

Temporarily set configuration values within a context manager

Examples

>>> import esmlab
>>> with esmlab.config.set({'foo': 123}):
...     pass
esmlab.config.collect(paths=['/home/docs/.esmlab'], env=None)

Collect configuration from paths and environment variables

Parameters
pathsList[str]

A list of paths to search for yaml config files

envdict

The system environment variables

Returns
config: dict

See also

esmlab.config.refresh

collect configuration and update into primary config

esmlab.config.refresh(config={'esmlab': {'sample-data-dir': '/home/docs/.esmlab/sample_data'}}, defaults=[], **kwargs)

Update configuration by re-reading yaml files and env variables

This mutates the global esmlab.config.config, or the config parameter if passed in.

This goes through the following stages:

  1. Clearing out all old configuration

  2. Updating from the stored defaults from downstream libraries (see update_defaults)

  3. Updating from yaml files and environment variables

Note that some functionality only checks configuration once at startup and may not change behavior, even if configuration changes. It is recommended to restart your python process if convenient to ensure that new configuration changes take place.

See also

esmlab.config.collect

for parameters

esmlab.config.update_defaults
esmlab.statistics.weighted_sum(data, dim=None, weights=None)

Compute weighted sum for xarray objects

Parameters
dataxarray.Dataset or xarray.DataArray

xarray object for which to compute weighted sum

dimstr or sequence of str, optional

Dimension(s) over which to apply sum.

weightsxarray.DataArray or array-like

weights to apply. Shape must be broadcastable to shape of data.

Returns
reducedxarray.Dataset or xarray.DataArray

New xarray object with weighted sum applied to its data and the indicated dimension(s) removed.

esmlab.statistics.weighted_mean(data, dim=None, weights=None)

Compute weighted mean for xarray objects

Parameters
dataxarray.Dataset or xarray.DataArray

xarray object for which to compute weighted mean

dimstr or sequence of str, optional

Dimension(s) over which to apply mean.

weightsxarray.DataArray or array-like

weights to apply. Shape must be broadcastable to shape of data.

Returns
reducedxarray.Dataset or xarray.DataArray

New xarray object with weighted mean applied to its data and the indicated dimension(s) removed.

esmlab.statistics.weighted_std(data, dim=None, weights=None)

Compute weighted standard deviation for xarray objects

Parameters
dataxarray.Dataset or xarray.DataArray

xarray object for which to compute weighted std

dimstr or sequence of str, optional

Dimension(s) over which to apply standard deviation.

weightsxarray.DataArray or array-like

weights to apply. Shape must be broadcastable to shape of data.

Returns
reducedxarray.Dataset or xarray.DataArray

New xarray object with weighted standard deviation applied to its data and the indicated dimension(s) removed.

esmlab.statistics.weighted_rmsd(x, y, dim=None, weights=None)

Compute weighted root mean square deviation between two xarray DataArrays

Parameters
x, yxarray.DataArray

xarray DataArray for which to compute weighted_rmsd.

dimstr or sequence of str, optional

Dimension(s) over which to apply rmsd.

weightsxarray.DataArray or array-like

weights to apply. Shape must be broadcastable to shape of data.

Returns
reducedxarray.DataArray

New DataArray with root mean square deviation applied to x, y and the indicated dimension(s) removed.

esmlab.statistics.weighted_cov(x, y, dim=None, weights=None)

Compute weighted covariance between two xarray DataArrays.

Parameters
x, yxarray.DataArray

xarray DataArrays for which to compute weighted covariance.

dimstr or sequence of str, optional

Dimension(s) over which to apply covariance.

weightsxarray.DataArray or array-like

weights to apply. Shape must be broadcastable to shape of data.

Returns
reducedDataArray

New DataArray with covariance applied to x, y and the indicated dimension(s) removed.

esmlab.statistics.weighted_corr(x, y, dim=None, weights=None, return_p=True)

Compute weighted correlation between two xarray.DataArray.

Parameters
x, yxarray.DataArray

xarray DataArrays for which to compute weighted correlation.

dimstr or sequence of str, optional

Dimension(s) over which to apply correlation.

weightsxarray.DataArray or array-like

weights to apply. Shape must be broadcastable to shape of data.

return_pbool, default: True

If True, compute and return the p-value(s) associated with the correlation.

Returns
reducedxarray.DataArray

New DataArray with correlation applied to x, y and the indicated dimension(s) removed.

If return_p is True, appends the resulting p values to the returned Dataset.

esmlab.core.climatology(dset, freq, time_coord_name=None)

Compute climatologies for a specified time frequency

Parameters
dsetxarray.Dataset

The data on which to operate

freqstr

Frequency alias. Accepted alias:

  • mon: for monthly climatologies

time_coord_namestr

Name for time coordinate to use

Returns
computed_dsetxarray.Dataset

The computed climatology data

esmlab.core.anomaly(dset, clim_freq, slice_mon_clim_time=None, time_coord_name=None)

Compute anomalies for a specified time frequency

Parameters
dsetxarray.Dataset

The data on which to operate

clim_freqstr

Climatology frequency alias. Accepted alias:

  • mon: for monthly climatologies

slice_mon_clim_timeslice, optional

a slice object passed to dset.isel(time=slice_mon_clim_time) for subseting the time-period overwhich the climatology is computed

time_coord_namestr

Name for time coordinate to use

Returns
computed_dsetxarray.Dataset

The computed anomaly data

esmlab.core.resample(dset, freq, weights=None, time_coord_name=None)

Resample given dataset and computes the mean for specified sampling time frequecy

Parameters
dsetxarray.Dataset

The data on which to operate

freqstr

Time frequency alias. Accepted aliases:

  • mon: for monthly means

  • ann: for annual means

weightsarray_like, optional

weights to use for each time period. This argument is supported for annual means only! If None and dataset doesn’t have time_bound variable, every time period has equal weight of 1.

time_coord_namestr

Name for time coordinate to use

Returns
computed_dsetxarray.Dataset

The resampled data with computed mean