eofs.tools

Tools related to EOF analysis.

eofs.tools.standard

Supplementary tools for the numpy EOF analysis interface.

eofs.tools.standard.correlation_map(pcs, field)

Correlation maps for a set of PCs and a spatial-temporal field.

Given an array where the columns are PCs (e.g., as output from pcs) and an array containing spatial-temporal data where the first dimension represents time, one correlation map per PC is computed.

The field must have the same temporal dimension as the PCs. Any number of spatial dimensions (including zero) are allowed in the field and there can be any number of PCs.

Arguments:

pcs

PCs as the columns of an array.

field

Spatial-temporal field with time as the first dimension.

Returns:

correlation_maps

An array with the correlation maps along the first dimension.

Example:

Compute correlation maps for each PC:

pcs = solver.pcs(pcscaling=1)
correlation_maps = correlation_maps(pcs, field)

eofs.tools.standard.covariance_map(pcs, field, ddof=1)

Covariance maps for a set of PCs and a spatial-temporal field.

Given an array where the columns are PCs (e.g., as output from eofs.standard.Eof.pcs) and an array containing spatial-temporal data where the first dimension represents time, one covariance map per PC is computed.

The field must have the same temporal dimension as the PCs. Any number of spatial dimensions (including zero) are allowed in the field and there can be any number of PCs.

Arguments:

pcs

PCs as the columns of an array.

field

Spatial-temporal field with time as the first dimension.

Optional arguments:

ddof

‘Delta degrees of freedom’. The divisor used to normalize the covariance matrix is N - ddof where N is the number of samples. Defaults to 1.

Returns:

covariance_maps

An array with the covariance maps along the first dimension.

Example:

Compute covariance maps for each PC:

pcs = solver.pcs(pcscaling=1)
covariance_maps = covariance_maps(pcs, field)

eofs.tools.iris

Supplementary tools for the iris EOF analysis interface.

eofs.tools.iris.weights_array(cube, scheme)

Weights for a data set on a grid.

Returned weights are a numpy.ndarray broadcastable to the shape of the input cube.

Arguments:

cube

An Cube instance to generate weights for.

scheme

Weighting scheme to use. The following values are accepted:

• ‘coslat’ : Square-root of cosine of latitude.

• ‘area’Square-root of grid cell area normalized by total

  grid area.

Returns:

weights

An array contanining the weights (not a Cube).

Examples:

Area weights for a Cube on 2D grid:

weights = weights_array(cube, scheme=’area’)

Square-root of cosine of latitude weights for a Cube with a latitude dimension:

weights = weights_array(cube, scheme=’coslat’)

eofs.tools.iris.coord_and_dim(cube, coord, multiple=False)

Retrieve a coordinate dimension and its corresponding position from a Cube instance.

Arguments:

cube

An Cube instance to retrieve the dimension from.

coord

Name of the coordinate dimension to retrieve.

Returns:

coord_tuple

A 2-tuple of (coordinate_dimension, dimension_number).

Deprecated since version version: 1.2

The function get_time_coord is used instead for finding time coordinates. For other coordinates please use the iris built-in functionality for locating required cooridnates.

eofs.tools.iris.get_time_coord(cube)

Retrieve the time coordinate dimension and its corresponding position from a Cube instance.

Arguments:

cube

An Cube instance to retrieve the dimension from.

Returns:

coord_tuple

A 2-tuple of (coordinate_dimension, dimension_number).

eofs.tools.iris.classified_aux_coords(cube)

Classify a Cube’s auxiliary coordinates into those that span only the time dimension, those that span only space dimensions, and those that span both time and space dimensions.

Arguments:

cube

An Cube instance whose auxiliary coordinates should be classified.

Returns:

coord_sets

A 3-tuple of lists of coordinates. The first element is the list of all auxiliary coordinates spannning only the time dimension, the second element is the list of all auxiliary coordinates spannning only space dimensions, and the third element is the list of all auxiliary coordinates spannning both time and space dimensions.

eofs.tools.iris.common_items(item_set)

Given an iterable of lists, constructs a list of every item that is present in all of the lists.

Arguments:

item_set

An iterable containing lists of items.

Returns:

common

A list of the items which occur in all sublists in the input.

eofs.tools.iris.correlation_map(pcs, field)

Correlation between PCs and a field.

Computes maps of the correlation between each PC and the given field at each grid point.

Given a set of PCs contained in a Cube (e.g., as output from eofs.iris.Eof.pcs) and a field with a time dimension contained in a iris.cube.Cube, one correlation map per PC is computed.

The field must have the same length time dimension as the PCs. Any number of spatial dimensions (including zero) are allowed in the field and there can be any number of PCs.

Arguments:

pcs

PCs contained in a Cube.

field

Field Spatial-temporal field contained in a Cube.

Returns:

correlation_maps

A Cube containing the correlation maps.

Examples:

Assuming solver is an instance of eofs.iris.Eof, compute correlation maps for each PC:

pcs = solver.pcs(pcscaling=1)
correlation_maps = correlation_map(pcs, field)

eofs.tools.iris.covariance_map(pcs, field, ddof=1)

Covariance between PCs and a field.

Computes maps of the covariance between each PC and the given field at each grid point.

Given a set of PCs contained in a Cube (e.g., as output from eofs.iris.Eof.pcs) and a field with a time dimension contained in a iris.cube.Cube, one covariance map per PC is computed.

The field must have the same length time dimension as the PCs. Any number of spatial dimensions (including zero) are allowed in the field and there can be any number of PCs.

Arguments:

pcs

PCs contained in a Cube.

field

Field Spatial-temporal field contained in a Cube.

Keyword arguments:

ddof

‘Delta degrees of freedom’. The divisor used to normalize the covariance matrix is N - ddof where N is the number of samples. Defaults to 1.

Returns:

covariance_maps

A Cube containing the covariance maps.

Examples:

Compute covariance maps for each PC:

pcs = solver.pcs(pcscaling=1)
covariance_maps = covariance_map(pcs, field)

eofs.tools.xarray

Supplementary tools for the xarray EOF analysis interface.

eofs.tools.xarray.find_time_coordinates(array)

Find time dimension coordinates in an xarray.DataArray.

Time coordinates satisfy one or more of:

• Values have a dtype of numpy.datetime64.

• Name of the coordinate is ‘time’.

• The coordinate has an attribute ‘axis’ with value ‘T’.

Argument:

array

An xarray.DataArray.

Returns:

time_coords

A list of time dimension coordinates. The list may be empty if no coordinates were recognised as time.

eofs.tools.xarray.categorise_ndcoords(array, time_name)

Categorise all the non-dimension coordinates of an xarray.DataArray into those that span only time, those that span only space, and those that span both time and space.

Arguments:

array

An xarray.DataArray.

time_name

Name of the time dimension coordinate in the input array.

Returns:

time_coords

A list of coordinates that span only the time dimension.

space_coords

A list of coordinates that span only the space dimensions.

time_space_coords

A list of coordinates that span both the time and space coordinates.

eofs.tools.xarray.weights_array(array, scheme)

Generate a weights array for a given weighting scheme.

Note

Currently not implemented, will raise a ValueError().

eofs.tools.xarray.correlation_map(pcs, field)

Correlation between PCs and a field.

Computes maps of the correlation between each PC and the given field at each grid point.

Given a set of PCs contained in a DataArray (e.g., as output from eofs.xarray.Eof.pcs) and a field with a time dimension contained in a xarray.DataArray, one correlation map per PC is computed.

The field must have the same length time dimension as the PCs. Any number of spatial dimensions (including zero) are allowed in the field and there can be any number of PCs.

Arguments:

pcs

PCs contained in a DataArray.

field

Field Spatial-temporal field contained in a DataArray.

Returns:

correlation_maps

A DataArray containing the correlation maps.

Examples:

Assuming solver is an instance of eofs.xarray.Eof, compute correlation maps for each PC:

pcs = solver.pcs(pcscaling=1)
correlation_maps = correlation_map(pcs, field)

eofs.tools.xarray.covariance_map(pcs, field, ddof=1)

Covariance between PCs and a field.

Computes maps of the covariance between each PC and the given field at each grid point.

Given a set of PCs contained in a DataArray (e.g., as output from eofs.xarray.Eof.pcs) and a field with a time dimension contained in a xarray.DataArray, one covariance map per PC is computed.

The field must have the same length time dimension as the PCs. Any number of spatial dimensions (including zero) are allowed in the field and there can be any number of PCs.

Arguments:

pcs

PCs contained in a DataArray.

field

Field Spatial-temporal field contained in a DataArray.

Keyword arguments:

ddof

‘Delta degrees of freedom’. The divisor used to normalize the covariance matrix is N - ddof where N is the number of samples. Defaults to 1.

Returns:

covariance_maps

A DataArray containing the covariance maps.

Examples:

Assuming solver is an instance of eofs.xarray.Eof, compute covariance maps for each PC:

pcs = solver.pcs(pcscaling=1)
covariance_maps = covariance_map(pcs, field)