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.cdms

Supplementary tools for the cdms EOF analysis interface.

eofs.tools.cdms.weights_array(dataset, scheme)

Weights for a data set on a grid.

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

Arguments:

dataset

A cdms2 variable 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 cdms2 variable).

Examples:

Area weights for a cdms2 variable on 2D grid:

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

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

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

eofs.tools.cdms.cdms2_name(variable)

Return a human-readable name of a cdms2 variable.

First it tries ‘standard_name’, then ‘long_name’ then ‘id’.

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

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

Given a set of PCs in a cdms2 variable (e.g., as output from eofs.cdms.Eof.pcs) and a spatial-temporal field in a cdms variable, 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 in a cdms2 variable.

field

Spatial-temporal field in a cdms2 variable.

Returns:

correlation_maps

A cdms2 variable containing the correlation maps.

Examples:

Compute correlation maps for each PC:

pcs = eofobj.pcs(pcscaling=1)
cormaps = correlation_map(pcs, field)

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

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

Given a set of PCs in a cdms2 variable (e.g., as output from pcs) and a spatial-temporal field in a cdms2 variable, 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 in a cdms2 variable.

field

Spatial-temporal field in a cdms2 variable.

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

A cdms2 variable containing the covariance maps.

Examples:

Compute covariance maps for each PC:

pcs = eofobj.pcs(pcscaling=1)
covmaps = covariance_map(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)