API References

Reference documentation for both eof2 interfaces is available:

Note

The solver classes eof2.Eof and eof2.EofSolver are made available at the top level of eof2, but are actually defined in separate modules eof2.eofwrap and eof2.eofsolve respectively.

Metadata-enabled interface

Meta-data preserving EOF analysis for cdms2 variables.

class eof2.eofwrap.Eof(dataset, weights='none', center=True, ddof=1)[source]

EOF analysis (meta-data enabled cdms2 interface).

Create an Eof object.

Argument:

dataset
A cdms2 variable containing the data to be analyzed. Time must be the first dimension. Missing values are allowed provided that they are constant with time (e.g., values of an oceanographic field over land).

Optional arguments:

weights

Sets the weighting method. The following values are accepted:

  • “area” : Square-root of grid cell area normalized by total area. Requires a latitude-longitude grid to be present in the input cdms2 variable dataset. This is a fairly standard weighting strategy. If you are unsure which method to use and you have gridded data then this should be your first choice.
  • “coslat” : Square-root of cosine of latitude (“cos_lat” is also accepted). Requires a latitude dimension to be present in the input cdms2 variable dataset.
  • “none” : Equal weights for all grid points (default).
  • None : Same as “none”.
An array of weights may also be supplied instead of specifying a weighting method.
center
If True, the mean along the first axis of the input data set (the time-mean) will be removed prior to analysis. If False, the mean along the first axis will not be removed. Defaults to True (mean is removed). Generally this option should be set to True as the covariance interpretation relies on input data being anomalies with a time-mean of 0. A valid reson for turning this off would be if you have already generated an anomaly data set. Setting to True has the useful side-effect of propagating missing values along the time-dimension, ensuring the solver will work even if missing values occur at different locations at different times.
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.

Examples:

EOF analysis with area-weighting for the input field:

>>> from eof2 import Eof
>>> eofobj = Eof(field, weights="area")
pcs(pcscaling=0, npcs=None)[source]

Principal component time series (PCs).

Returns the ordered PCs in a a cdms2 variable.

Optional arguments:

pcscaling

Set the scaling of the retrieved PCs. The following values are accepted:

  • 0 : Un-scaled principal components (default).
  • 1 : Principal components are scaled to unit variance (divided by the square-root of their eigenvalue).
  • 2 : Principal components are multiplied by the square-root of their eigenvalue.
npcs : Number of principal components to retrieve. Defaults to
all the principal components.

Examples:

All un-scaled PCs:

>>> pcs = eofobj.pcs()

First 3 PCs scaled to unit variance:

>>> pcs = eofobj.pcs(npcs=3, pcscaling=1) 
eofs(eofscaling=0, neofs=None)[source]

Emipirical orthogonal functions.

Returns a the ordered EOFs in a cdms2 variable.

Optional arguments:

eofscaling

Sets the scaling of the EOFs. The following values are accepted:

  • 0 : Un-scaled EOFs (default).
  • 1 : EOFs are divided by the square-root of their eigenvalues.
  • 2 : EOFs are multiplied by the square-root of their eigenvalues.

neofs – Number of EOFs to return. Defaults to all EOFs.

Examples:

All EOFs with no scaling:

>>> eofs = eofobj.eofs()

First 3 EOFs with scaling applied:

>>> eofs = eofobj.eofs(neofs=3, eofscaling=1)
eigenvalues(neigs=None)[source]

Eigenvalues (decreasing variances) associated with each EOF.

Returns the ordered eigenvalues in a cdms2 variable.

Optional argument:

neigs
Number of eigenvalues to return. Defaults to all eigenvalues.

Examples:

All eigenvalues:

>>> lambdas = eofobj.eigenvalues()

The first eigenvalue:

>>> lambda1 = eofobj.eigenvalues(neigs=1)
eofsAsCorrelation(neofs=None)[source]

EOFs scaled as the correlation of the PCs with the original field.

Returns the ordered correlation EOFs in a cdms2 variable.

Optional argument:

neofs
Number of EOFs to return. Defaults to all EOFs.

Note:

These are only the EOFs expressed as correlation and are not related to EOFs computed using the correlation matrix.

Examples:

All EOFs:

>>> eofs = eofobj.eofsAsCorrelation()

The leading EOF:

>>> eof1 = eofobj.eofsAsCorrelation(neofs=1)
eofsAsCovariance(neofs=None, pcscaling=1)[source]

EOFs scaled as the covariance of the PCs with the original field.

Returns the ordered covariance EOFs in a cdms2 variable.

Optional arguments:

neofs
Number of EOFs to return. Defaults to all EOFs.
pcscaling

Set the scaling of the PCs used to compute covariance. The following values are accepted:

  • 0 : Un-scaled PCs.
  • 1 : PCs are scaled to unit variance (divided by the square-root of their eigenvalue) (default).
  • 2 : PCs are multiplied by the square-root of their eigenvalue.

Examples:

All EOFs:

>>> eofs = eofobj.eofsAsCovariance()

The leading EOF:

>>> eof1 = eofobj.eofsAsCovariance(neofs=1)

The leading EOF using un-scaled PCs:

>>> eof1 = eofobj.eofsAsCovariance(neofs=1, pcscaling=0)
varianceFraction(neigs=None)[source]

Fractional EOF variances.

The fraction of the total variance explained by each EOF, a value between 0 and 1 inclusive, in a cdms2 variable.

Optional argument:

neigs
Number of eigenvalues to return the fractional variance for. Defaults to all eigenvalues.

Examples:

The fractional variance represented by each eigenvalue:

>>> varfrac = eofobj.varianceFraction()

The fractional variance represented by the first 3 eigenvalues:

>>> varfrac = eofobj.VarianceFraction(neigs=3)
totalAnomalyVariance()[source]

Total variance associated with the field of anomalies (the sum of the eigenvalues).

Returns a scalar (not a cdms2 transient variable).

Examples:

>>> var = eofobj.totalAnomalyVariance()
reconstructedField(neofs)[source]

Reconstructed data field based on a subset of EOFs.

If weights were passed to the Eof instance then the returned reconstructed field will be automatically un-weighted. Otherwise the returned reconstructed field will be weighted in the same manner as the input to the Eof instance.

Argument:

neofs
Number of EOFs to use for the reconstruction.

Examples:

Reconstruct the input field using 3 EOFs.

>>> rfield = eofobj.reconstructedField(neofs=3)
northTest(neigs=None, vfscaled=False)[source]

Typical errors for eigenvalues.

Returns the typical error for each eigenvalue in a cdms2 variable.

The method of North et al. (1982) is used to compute the typical error for each eigenvalue. It is assumed that the number of times in the input data set is the same as the number of independent realizations. If this assumption is not valid then the result may be inappropriate.

Optional arguments:

neigs
The number of eigenvalues to return typical errors for. Defaults to typical errors for all eigenvalues.
vfscaled
If True scale the errors by the sum of the eigenvalues. This yields typical errors with the same scale as the values returned by the varianceFraction() method. If False then no scaling is done. Defaults to False (no scaling).

References

North, G. R., T. L. Bell, R. F. Cahalan, and F. J. Moeng, 1982: “Sampling errors in the estimation of empirical orthogonal functions”, Monthly Weather Review, 110, pages 669-706.

Examples:

Typical errors for all eigenvalues:

>>> errs = eofobj.northTest()

Typical errors for the first 3 eigenvalues scaled by the sum of the eigenvalues:

>>> errs = eofobj.northTest(neigs=3, vfscaled=True)
getWeights()[source]

Weights used for the analysis.

Examples:

The 2D weights variable used for the analysis:

>>> wgt = eofobj.getWeights()
projectField(field, neofs=None, eofscaling=0, weighted=True)[source]

Project a field onto the EOFs.

Returns projected time series in a cdms2 variable.

Given a field, projects it onto the EOFs to generate a corresponding set of time series in a cdms2 variable. The field can be projected onto all the EOFs or just a subset. The field must have the same corresponding spatial dimensions (including missing values in the same places) as the original input to the Eof instance. The field may have a different length time dimension to the original input field (or no time dimension at all). The time dimension must be first if present.

Argument:

field
A field (cdms2 variable) to project onto the EOFs.

Optional arguments:

neofs
Number of EOFs to project onto. Defaults to all EOFs.
eofscaling

Set the scaling of the EOFs that are projected onto. The following values are accepted:

  • 0 : Un-scaled EOFs (default).
  • 1 : EOFs are divided by the square-root of their eigenvalue.
  • 2 : EOFs are multiplied by the square-root of their eigenvalue.
weighted
If True then the field is weighted prior to projection. If False then no weighting is applied. Defaults to True (weighting is applied). Generally only the default setting should be used.

Examples:

Project a field onto all EOFs:

>>> pcs = eofobj.projectField(field)

Project fields onto the three leading EOFs:

>>> pcs = eofobj.projectField(field, neofs=3)

Non-metadata interface

EOF analysis for numpy array data.

class eof2.eofsolve.EofSolver(dataset, weights=None, center=True, ddof=1)[source]

EOF analysis (numpy interface).

Create an EofSolver object.

The EOF solution is computed at initialization time. Method calls are used to retrieve computed quantities.

Arguments:

dataset
A numpy.ndarray or numpy.ma.core.MasekdArray with two or more dimensions containing the data to be analysed. The first dimension is assumed to represent time. Missing values are permitted, either in the form of a masked array, or the value numpy.nan. Missing values must be constant with time (e.g., values of an oceanographic field over land).

Optional arguments:

weights
An array of weights whose shape is compatible with those of the input array dataset. The weights can have the same shape as the input data set or a shape compatible with an array broadcast operation (ie. the shape of the weights can can match the rightmost parts of the shape of the input array dataset). If the input array dataset does not require weighting then the value None may be used. Defaults to None (no weighting).
center
If True, the mean along the first axis of the input data set (the time-mean) will be removed prior to analysis. If False, the mean along the first axis will not be removed. Defaults to True (mean is removed). Generally this option should be set to True as the covariance interpretation relies on input data being anomalies with a time-mean of 0. A valid reson for turning this off would be if you have already generated an anomaly data set. Setting to True has the useful side-effect of propagating missing values along the time-dimension, ensuring the solver will work even if missing values occur at different locations at different times.
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.
pcs(pcscaling=0, npcs=None)[source]

Principal component time series (PCs).

Returns an array where the columns are the ordered PCs.

Optional arguments:

pcscaling

Set the scaling of the retrieved PCs. The following values are accepted:

  • 0 : Un-scaled PCs (default).
  • 1 : PCs are scaled to unit variance (divided by the square-root of their eigenvalue).
  • 2 : PCs are multiplied by the square-root of their eigenvalue.

npcs : Number of PCs to retrieve. Defaults to all the PCs.

eofs(eofscaling=0, neofs=None)[source]

Empirical orthogonal functions (EOFs).

Returns an array with the ordered EOFs along the first dimension.

Optional arguments:

eofscaling

Sets the scaling of the EOFs. The following values are accepted:

  • 0 : Un-scaled EOFs (default).
  • 1 : EOFs are divided by the square-root of their eigenvalues.
  • 2 : EOFs are multiplied by the square-root of their eigenvalues.

neofs – Number of EOFs to return. Defaults to all EOFs.

eigenvalues(neigs=None)[source]

Eigenvalues (decreasing variances) associated with each EOF.

Optional argument:

neigs
Number of eigenvalues to return. Defaults to all eigenvalues.
eofsAsCorrelation(neofs=None)[source]

EOFs scaled as the correlation of the PCs with the original field.

Optional argument:

neofs
Number of EOFs to return. Defaults to all EOFs.
eofsAsCovariance(neofs=None, pcscaling=1)[source]

EOFs scaled as the covariance of the PCs with the original field.

Optional arguments:

neofs
Number of EOFs to return. Defaults to all EOFs.
pcscaling

Set the scaling of the PCs used to compute covariance. The following values are accepted:

  • 0 : Un-scaled PCs.
  • 1 : PCs are scaled to unit variance (divided by the square-root of their eigenvalue) (default).
  • 2 : PCs are multiplied by the square-root of their eigenvalue.
varianceFraction(neigs=None)[source]

Fractional EOF variances.

The fraction of the total variance explained by each EOF. This is a value between 0 and 1 inclusive.

Optional argument:

neigs
Number of eigenvalues to return the fractional variance for. Defaults to all eigenvalues.
totalAnomalyVariance()[source]

Total variance associated with the field of anomalies (the sum of the eigenvalues).

reconstructedField(neofs)[source]

Reconstructed data field based on a subset of EOFs.

If weights were passed to the EofSolver instance then the returned reconstructed field will be automatically un-weighted. Otherwise the returned reconstructed field will be weighted in the same manner as the input to the EofSolver instance.

Argument:

neofs
Number of EOFs to use for the reconstruction.
northTest(neigs=None, vfscaled=False)[source]

Typical errors for eigenvalues.

The method of North et al. (1982) is used to compute the typical error for each eigenvalue. It is assumed that the number of times in the input data set is the same as the number of independent realizations. If this assumption is not valid then the result may be inappropriate.

Optional arguments:

neigs
The number of eigenvalues to return typical errors for. Defaults to typical errors for all eigenvalues.
vfscaled
If True scale the errors by the sum of the eigenvalues. This yields typical errors with the same scale as the values returned by the varianceFraction() method. If False then no scaling is done. Defaults to False (no scaling).

References

North, G. R., T. L. Bell, R. F. Cahalan, and F. J. Moeng, 1982: “Sampling errors in the estimation of empirical orthogonal functions”, Monthly Weather Review, 110, pages 669-706.

getWeights()[source]

Weights used for the analysis.

projectField(field, neofs=None, eofscaling=0, weighted=True)[source]

Project a field onto the EOFs.

Given a field, projects it onto the EOFs to generate a corresponding set of time series. The field can be projected onto all the EOFs or just a subset. The field must have the same corresponding spatial dimensions (including missing values in the same places) as the original input to the EofSolver instance. The field may have a different length time dimension to the original input field (or no time dimension at all).

Argument:

field
A field to project onto the EOFs. The field should be contained in a numpy.ndarray or a numpy.ma.core.MaskedArray.

Optional arguments:

neofs
Number of EOFs to project onto. Defaults to all EOFs.
eofscaling

Set the scaling of the EOFs that are projected onto. The following values are accepted:

  • 0 : Un-scaled EOFs (default).
  • 1 : EOFs are divided by the square-root of their eigenvalue.
  • 2 : EOFs are multiplied by the square-root of their eigenvalue.
weighted
If True then the field is weighted prior to projection. If False then no weighting is applied. Defaults to True (weighting is applied). Generally only the default setting should be used.

Extra tools (metadata-enabled)

Supplementary tools for the meta-data enabled EOF analysis interface.

eof2.tools.weights_array(dataset, scheme='area')[source]

Weights for a data set on a grid.

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

Arguments:

dataset
A cdms2 variable to generate weights for.

Optional arguments:

scheme

Weighting scheme to use. The following values are accepted:

  • “coslat” : Square-root of cosine of latitude. The value “cos_lat” is accepted as an alias.
  • “area” : Normalized area weights (default).

Examples:

Area weights for a cdms2 variable on 2D grid:

>>> wts = weights_array(var2d, scheme="area")

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

>>> wts = weights_array(var, scheme="coslat")
eof2.tools.correlation_map(pcs, field)[source]

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 eof2.Eof.pcs()) and a spatial-temporal field in a cmds2 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.

Examples:

Assuming eofobj is an instance of Eof, compute correlation maps for each PC:

>>> pcs = eofobj.pcs(pcscaling=1)
>>> cormaps = correlation_map(pcs, field)
eof2.tools.covariance_map(pcs, field, ddof=1)[source]

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 eof2.Eof.pcs()) and a spatial-temporal field in a cmds2 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.

Examples:

Assuming eofobj is an instance of Eof, compute covariance maps for each PC:

>>> pcs = eofobj.pcs(pcscaling=1)
>>> covmaps = covariance_map(pcs, field)

Extra tools (non-metadata)

Supplementary tools for the numpy EOF analysis interface.

eof2.nptools.correlation_map(pcs, field)[source]

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 eof2.EofSolve.pcs()) and an array containing a spatial-temporal where time is the first dimension, 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.
eof2.nptools.covariance_map(pcs, field, ddof=1)[source]

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 eof2.EofSolve.pcs()) and an array containing a spatial-temporal where time is the first dimension, 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.

Table Of Contents

Previous topic

Examples

This Page