eofs.cdms
¶
Metadata preserving EOF analysis for cdms2
.

class
eofs.cdms.
Eof
(dataset, weights=None, center=True, ddof=1)[source]¶ EOF analysis (metadata enabled
cdms2
interface)Create an Eof object.
The EOF solution is computed at initialization time. Method calls are used to retrieve computed quantities.
Argument:
 dataset
 A
cdms2
variable containing the data to be analysed. 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 predefined weighting methods are available:
 ‘area’ : Squareroot of grid cell area normalized by
total grid area. Requires a latitudelongitude grid to be
present in the
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’ : Squareroot of cosine of latitude. Requires a
latitude dimension to be present in the
cdms2
variable dataset.  None : Equal weights for all grid points (‘none’ is also accepted).
Alternatively an array of weights whose shape is compatible with thecdms2
variable dataset may be supplied instead of specifying a weighting method. ‘area’ : Squareroot of grid cell area normalized by
total grid area. Requires a latitudelongitude grid to be
present in the
 center
If True, the mean along the first axis of dataset (the timemean) will be removed prior to analysis. If False, the mean along the first axis will not be removed. Defaults to True (mean is removed).
The covariance interpretation relies on the input data being anomalies with a timemean of 0. Therefore this option should usually be set to True. Setting this option to True has the useful side effect of propagating missing values along the time dimension, ensuring that a solution can be found even if missing values occur in 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.
Returns:
 solver
 An
Eof
instance.
Examples:
EOF analysis with gridcellarea weighting for the input field:
from eofs.cdms import Eof solver = Eof(dataset, weights='area')

neofs
= None¶ Number of EOFs in the solution.

pcs
(pcscaling=0, npcs=None)[source]¶ Principal component time series (PCs).
Optional arguments:
 pcscaling
Set the scaling of the retrieved PCs. The following values are accepted:
 0 : Unscaled principal components (default).
 1 : Principal components are scaled to unit variance (divided by the squareroot of their eigenvalue).
 2 : Principal components are multiplied by the squareroot of their eigenvalue.
 npcs
 Number of PCs to retrieve. Defaults to all the PCs. If the number of requested PCs is more than the number that are available, then all available PCs will be returned.
Returns:
 pcs
 A
cdms2
variable containing the ordered PCs. The PCs are numbered from 0 to npcs  1.
Examples:
All unscaled PCs:
pcs = solver.pcs()
First 3 PCs scaled to unit variance:
pcs = solver.pcs(npcs=3, pcscaling=1)

eofs
(eofscaling=0, neofs=None)[source]¶ Emipirical orthogonal functions (EOFs).
Optional arguments:
 eofscaling
Sets the scaling of the EOFs. The following values are accepted:
 0 : Unscaled EOFs (default).
 1 : EOFs are divided by the squareroot of their eigenvalues.
 2 : EOFs are multiplied by the squareroot of their eigenvalues.
 neofs
 Number of EOFs to return. Defaults to all EOFs. If the number of EOFs requested is more than the number that are available, then all available EOFs will be returned.
Returns:
 eofs
 A
cdms2
variable containing the ordered EOFs. The EOFs are numbered from 0 to neofs  1.
Examples:
All EOFs with no scaling:
eofs = solver.eofs()
First 3 EOFs with scaling applied:
eofs = solver.eofs(neofs=3, eofscaling=1)

eofsAsCorrelation
(neofs=None)[source]¶ Empirical orthogonal functions (EOFs) expressed as the correlation between the principal component time series (PCs) and the time series of the
Eof
input dataset at each grid point.Note
These are not related to the EOFs computed from the correlation matrix.
Optional argument:
 neofs
 Number of EOFs to return. Defaults to all EOFs. If the number of EOFs requested is more than the number that are available, then all available EOFs will be returned.
Returns:
 eofs
 A
cdms2
variable containing the ordered EOFs. The EOFs are numbered from 0 to neofs  1.
Examples:
All EOFs:
eofs = solver.eofsAsCorrelation()
The leading EOF:
eof1 = solver.eofsAsCorrelation(neofs=1)

eofsAsCovariance
(neofs=None, pcscaling=1)[source]¶ Empirical orthogonal functions (EOFs) expressed as the covariance between the principal component time series (PCs) and the time series of the
Eof
input dataset at each grid point.Optional arguments:
 neofs
 Number of EOFs to return. Defaults to all EOFs. If the number of EOFs requested is more than the number that are available, then all available EOFs will be returned.
 pcscaling
Set the scaling of the PCs used to compute covariance. The following values are accepted:
 0 : Unscaled PCs.
 1 : PCs are scaled to unit variance (divided by the squareroot of their eigenvalue) (default).
 2 : PCs are multiplied by the squareroot of their eigenvalue.
The default is to divide PCs by the squareroot of their eigenvalue so that the PCs are scaled to unit variance (option 1).
Returns:
 eofs
 A
cdms2
variable containing the ordered EOFs. The EOFs are numbered from 0 to neofs  1.
Examples:
All EOFs:
eofs = solver.eofsAsCovariance()
The leading EOF:
eof1 = solver.eofsAsCovariance(neofs=1)
The leading EOF using unscaled PCs:
eof1 = solver.eofsAsCovariance(neofs=1, pcscaling=0)

eigenvalues
(neigs=None)[source]¶ Eigenvalues (decreasing variances) associated with each EOF.
Optional argument:
 neigs
 Number of eigenvalues to return. Defaults to all eigenvalues.If the number of eigenvalues requested is more than the number that are available, then all available eigenvalues will be returned.
Returns:
 eigenvalues
 A
cdms2
variable containing the eigenvalues arranged largest to smallest.
Examples:
All eigenvalues:
eigenvalues = solver.eigenvalues()
The first eigenvalue:
eigenvalue1 = solver.eigenvalues(neigs=1)

varianceFraction
(neigs=None)[source]¶ Fractional EOF variances.
The fraction of the total variance explained by each EOF mode, values between 0 and 1 inclusive.
Optional argument:
 neigs
 Number of eigenvalues to return the fractional variance for. Defaults to all eigenvalues. If the number of eigenvalues requested is more than the number that are available, then fractional variances for all available eigenvalues will be returned.
Returns:
 variance_fractions
 A
cdms2
variable containing the fractional variances for each eigenvalue. The eigenvalues are numbered from 0 to neigs  1.
Examples:
The fractional variance represented by each eigenvalue:
variance_fractions = solver.varianceFraction()
The fractional variance represented by the first 3 eigenvalues:
variance_fractions = solver.VarianceFraction(neigs=3)

totalAnomalyVariance
()[source]¶ Total variance associated with the field of anomalies (the sum of the eigenvalues).
Returns:
 total_variance
 A scalar value (not a
cdms2
variable).
Example:
Get the total variance:
total_variance = solver.totalAnomalyVariance()

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
Eof.varianceFraction
. If False then no scaling is done. Defaults to False (no scaling).
Returns:
 errors
 A
cdms2
variable containing the typical errors for each eigenvalue. The egienvalues are numbered from 0 to neigs  1.
References
North G.R., T.L. Bell, R.F. Cahalan, and F.J. Moeng (1982) Sampling errors in the estimation of empirical orthogonal functions. Mon. Weather. Rev., 110, pp 669706.
Examples:
Typical errors for all eigenvalues:
errors = solver.northTest()
Typical errors for the first 3 eigenvalues scaled by the sum of the eigenvalues:
errors = solver.northTest(neigs=3, vfscaled=True)

reconstructedField
(neofs)[source]¶ Reconstructed data field based on a subset of EOFs.
If weights were passed to the
Eof
instance the returned reconstructed field will automatically have this weighting removed. Otherwise the returned field will have the same weighting as theEof
input dataset.Argument:
 neofs
 Number of EOFs to use for the reconstruction. Alternatively this argument can be an iterable of mode numbers (where the first mode is 1) in order to facilitate reconstruction with arbitrary modes.
Returns:
 reconstruction
 A
cdms2
variable with the same dimensionsEof
input dataset containing the reconstruction using neofs EOFs.
Example:
Reconstruct the input field using 3 EOFs:
reconstruction = solver.reconstructedField(3)
Reconstruct the input field using EOFs 1, 2 and 5:
reconstruction = solver.reconstuctedField([1, 2, 5])

projectField
(field, neofs=None, eofscaling=0, weighted=True)[source]¶ Project a field onto the EOFs.
Given a data set, projects it onto the EOFs to generate a corresponding set of pseudoPCs.
Argument:
 field
 A
cdms2
variable containing the field to project onto the EOFs. It must have the same corresponding spatial dimensions (including missing values in the same places) as theEof
input dataset. It may have a different length time dimension to theEof
input dataset or no time dimension at all. If a time dimension exists it must be the first dimension.
Optional arguments:
 neofs
 Number of EOFs to project onto. Defaults to all EOFs. If the number of EOFs requested is more than the number that are available, then the field will be projected onto all available EOFs.
 eofscaling
Set the scaling of the EOFs that are projected onto. The following values are accepted:
 0 : Unscaled EOFs (default).
 1 : EOFs are divided by the squareroot of their eigenvalue.
 2 : EOFs are multiplied by the squareroot of their eigenvalue.
 weighted
 If True then the field is weighted using the same weights used for the EOF analysis prior to projection. If False then no weighting is applied. Defaults to True (weighting is applied). Generally only the default setting should be used.
Returns:
 pseudo_pcs
 A
cdms2
variable containing the pseudoPCs. The PCs are numbered from 0 to neofs  1.
Examples:
Project a field onto all EOFs:
pseudo_pcs = solver.projectField(field)
Project fields onto the three leading EOFs:
pseudo_pcs = solver.projectField(field, neofs=3)