API Reference

Xarray accessor

A pair of xarray accessors for working with pint units and CF variables, calculating transformed and derived quantities, and reducing dimensions in myrid ways.

ClimoAccessor(data[, registry])	Accessor with properties and methods shared by xarray.DataArrays and xarray.Datasets.
ClimoDataArrayAccessor(data[, registry])	Accessor for xarray.DataArrays.
ClimoDatasetAccessor(data[, registry])	Accessor for xarray.Datasets.
register_derivation(dest, /, *[, assign_name])	Register a function that derives one variable from one or more others, for use with ClimoDatasetAccessor.get.
register_transformation(src, dest, /, *[, …])	Register a function that transforms one variable to another, for use with ClimoDataArrayAccessor.to_variable.

Unit registry

A pint unit registry for climate scientists and tools for parsing and formatting CF-compliant unit strings.

ureg	The default pint.UnitRegistry used throughout climopy.
units	Alias for the default pint.UnitRegistry ureg.
parse_units(units, /)	Translate unit string into pint units, with support for CF compliant constructs.
encode_units(units, /)	Convert pint.Unit units to an unambiguous unit string.
latex_units(units, /, *[, long_form])	Fussily the format unit string or pint.Unit object into TeX-compatible form suitable for (e.g.) matplotlib figure text.

Variable registry

Tools for managing CF-style variable metadata. Includes a class for holding variable metadata and grouping variables into related hierarchies, and a registry for storing variables.

vreg	The default CFVariableRegistry paired with ClimoDataArrayAccessor xarray accessor instances.
variables	Alias for the default CFVariableRegistry vreg.
CFVariable(name, *args[, registry])	Lightweight CF-style representation of physical variables.
CFVariableRegistry()	Container of CFVariable instances supporting aliases and ad hoc generation of CFVariable copies with properties modified by the coordinate cell methods.

Finite differences

Various finite difference schemes.

integral(x, y, /[, y0, axis])	Return the integral approximation along an arbitrary axis.
deriv_even(h, y, /[, order, axis, accuracy, …])	Return an estimate of the first, second, or third order derivative along an arbitrary axis using centered finite differencing.
deriv_half(x, y, /[, order, axis, cyclic])	Return an arbitrary order finite difference approximation by taking successive half-level differences.
deriv_uneven(x, y, /[, order, axis, …])	Return an arbitrary order centered finite difference approximation for arbitrarily spaced coordinates using the [For88] method.

Variability analysis

Analyses of variance and trends. Many of these are adapted from examples and course notes provided by Professors Elizabeth Barnes and Dennis Hartmann.

autocorr(dt, z[, axis])	Return the autocorrelation spectrum at a single lag or successive lags.
autocovar(dt, z[, axis])	Return the autocovariance spectrum at a single lag or successive lags.
corr(dt, z1, z2[, axis])	Return the correlation spectrum at a single lag or successive lags.
covar(dt, z1, z2[, axis])	Return the covariance spectrum at a single lag or successive lags.
eof(data, /[, neof, axis_time, axis_space, …])	Calculate the first N EOFs using the scipy algorithm for Hermetian matrices on the covariance matrix.
eot(data[, neof])	EOTs, whatever they are.
reof(data[, neof])	Rotated EOFs, e.g.
gaussian(z[, mean, stdev, sigma])	Returns sample points on Gaussian curve.
hist(bins, y, /[, axis])	Get the histogram along axis axis.
linefit(x, y, /[, axis])	Get linear regression along axis, ignoring NaNs.
rednoise(a[, ntime, nsamples, mean, stdev, …])	Return one or more artificial red noise time series with prescribed mean and standard deviation.
rednoisefit(dt, a, /[, maxlag, imaxlag, …])	Return the \(e\)-folding autocorrelation timescale for the input autocorrelation spectra along an arbitrary axis.
wilks(percentiles[, alpha])	Return the precentile threshold from an array of percentiles that satisfies the given false discovery rate.

Spectral analysis

Spectral analysis tools. Many of these are adapted from examples and course notes provided by Professors Elizabeth Barnes and Dennis Hartmann.

Note

The convention for this package is to use linear wave properties, i.e. the wavelength in <units> per \(2\pi\) radians, and wavenumber \(2\pi\) radians per <units>.

butterworth(dx, order, cutoff, /[, btype])	Applies Butterworth filter to data.
copower(dx, y1, y2, /[, axis])	Return the co-spectral decomposition and related quantities for two real-valued arrays along an arbitrary axis.
copower2d(dx_lon, dx_time, y1, y2, /[, …])	Return the 2D spectral decomposition of two real-valued arrays with along an arbitrary time dimension and cyclic dimension.
filter(x, b, /[, a, n, axis, center, pad, …])	Apply scipy.signal.lfilter to data.
harmonics(y, n, /[, axis])	Select the first Fourier harmonics of the time series.
highpower(y, n, /[, axis])	Select only the highest power frequencies.
lanczos(dx, width, cutoff, /)	Returns coefficients for Lanczos high-pass filter with desired wavelength specified.
power(dx, y1, /[, axis])	Return the spectral decomposition of a real-valued array along an arbitrary axis.
power2d(dx_lon, dx_time, y, /[, axis_lon, …])	Return the spectral decomposition of a real-valued array along an arbitrary axis.
response(dx, b[, a, n, simple])	Calculate the response function given the a and b coefficients for some analog filter.
runmean(y, n, /[, wintype, axis, pad])	Apply running average to array.
waves(x, /[, wavenums, wavelengths, phase, …])	Compose array of sine waves.
window(n, /[, wintype])	Retrieve the get_window weighting function window.

Wave diagnostics

Various diagnostics for quantifying wave activity, tracking wave packets, and detecting blocking patterns. Incorporates code developed by Clare Huang.

Warning

This submodule out of date and poorly tested. It will eventually be cleaned up. In the meantime, feel free to copy and modify it.

eqlat(lon, lat, q[, skip, sigma])	Get equivalent latitudes corresponding to PV levels evenly sampled from the distribution of sorted PVs.
waq(lon, lat, q[, sigma, omega, flip, skip])	Return the finite-amplitude wave activity.
waqlocal(lon, lat, q[, omega, sigma, flip, skip])	Return the local finite-amplitude wave activity.

Spherical coordinates

Mathematical operations on the surface of the sphere.

Warning

This submodule out of date and poorly tested. It will eventually be cleaned up. In the meantime, feel free to copy and modify it.

geopad(lon, lat, data, /[, nlon, nlat])	Return array padded circularly along longitude and over the poles for finite difference methods.
geomean(lon, lat, data, /[, box, weights, …])	Take area mean of data time series.
geogradient(lon, lat, data, /)	Calculate gradient in spherical coordinates.
geolaplacian(lon, lat, data, /[, accuracy])	Calculate Laplacian in spherical coordinates.
haversine(lon1, lat1, lon2, lat2, /)	Calculate the great circle distance between two points on Earth, specified in degrees.

Dataset downloads

Convenient wrappers for python APIs used to download climatological datasets.

Warning

This submodule out of date and poorly tested. It will eventually be cleaned up. In the meantime, feel free to copy and modify it.

cmip()	Download CMIP5 model data.
era(params, stream, levtype[, daterange, …])	Retrieves ERA reanalysis data using the provided API.
merra()	Download MERRA data.
ncar()	Download NCAR CFSL data.
satellite()	Download satellite data.

Miscellaneous utilities

Includes miscellaneous mathematical functions.

calendar(dt, /)	Convert an array of datetime64 values to a calendar array of years, months, days, hours, minutes, and seconds.
find(x, y, /[, axis, axis_track, track, …])	Find the location of zero values or extrema for a given data array.
intersection(x, y1, y2, /[, xlog])	Find the (first) intersection point for two line segments.
linetrack(xs[, ys, ntrack, seed, sep])	Track individual “lines” across lists of coordinates.
match(*args)	Return the overlapping segment from a series of vectors with common coordinate spacings but different start or end points.

Physical constants

A variety of physical constants.

a	Earth mean radius
c	Speed of light in a vacuum
cp	Specific heat capacity at constant pressure for dry air at \(0^{\circ}\mathrm{C}\)
cv	Specific heat capacity at constant volume for dry air at \(0^{\circ}\mathrm{C}\)
e	Euler’s number
G	Gravitational constant
g	Standard acceleration due to gravity
H	Rule-of-thumb 7km atmospheric scale height
h	Planck constant
kappa	Poisson constant for dry air.
kb	Boltzmann constant
Lf	Latent heat of fusion at \(0^{\circ}\mathrm{C}\)
Ls	Latent heat of sublimation at \(0^{\circ}\mathrm{C}\)
Lv	Latent heat of vaporization at \(0^{\circ}\mathrm{C}\)
Md	Dry air molar mass
Mw	Water vapor molar mass
Na	Avogadro constant.
Omega	Earth rotation rate
p0	Standard reference pressure
pi	\(\pi\) (3.14159…)
psfc	Earth mean sea-level pressure
R	Ideal gas constant
Rd	Dry air gas constant
Rm	Water vapor gas constant
sigma	Stefan-Boltzmann constant
tau	\(\tau\) (6.28318…)