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.
Meta-data preserving EOF analysis for cdms2 variables.
EOF analysis (meta-data enabled cdms2 interface).
Create an Eof object.
Argument:
Optional arguments:
Sets the weighting method. The following values are accepted:
An array of weights may also be supplied instead of specifying a weighting method.
Examples:
EOF analysis with area-weighting for the input field:
>>> from eof2 import Eof
>>> eofobj = Eof(field, weights="area")
Principal component time series (PCs).
Returns the ordered PCs in a a cdms2 variable.
Optional arguments:
Set the scaling of the retrieved PCs. The following values are accepted:
Examples:
All un-scaled PCs:
>>> pcs = eofobj.pcs()
First 3 PCs scaled to unit variance:
>>> pcs = eofobj.pcs(npcs=3, pcscaling=1)
Emipirical orthogonal functions.
Returns a the ordered EOFs in a cdms2 variable.
Optional arguments:
Sets the scaling of the EOFs. The following values are accepted:
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 (decreasing variances) associated with each EOF.
Returns the ordered eigenvalues in a cdms2 variable.
Optional argument:
Examples:
All eigenvalues:
>>> lambdas = eofobj.eigenvalues()
The first eigenvalue:
>>> lambda1 = eofobj.eigenvalues(neigs=1)
EOFs scaled as the correlation of the PCs with the original field.
Returns the ordered correlation EOFs in a cdms2 variable.
Optional argument:
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)
EOFs scaled as the covariance of the PCs with the original field.
Returns the ordered covariance EOFs in a cdms2 variable.
Optional arguments:
Set the scaling of the PCs used to compute covariance. The following values are accepted:
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)
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:
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)
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()
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:
Examples:
Reconstruct the input field using 3 EOFs.
>>> rfield = eofobj.reconstructedField(neofs=3)
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:
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)
Weights used for the analysis.
Examples:
The 2D weights variable used for the analysis:
>>> wgt = eofobj.getWeights()
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:
Optional arguments:
Set the scaling of the EOFs that are projected onto. The following values are accepted:
Examples:
Project a field onto all EOFs:
>>> pcs = eofobj.projectField(field)
Project fields onto the three leading EOFs:
>>> pcs = eofobj.projectField(field, neofs=3)
EOF analysis for numpy array data.
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:
Optional arguments:
Principal component time series (PCs).
Returns an array where the columns are the ordered PCs.
Optional arguments:
Set the scaling of the retrieved PCs. The following values are accepted:
npcs : Number of PCs to retrieve. Defaults to all the PCs.
Empirical orthogonal functions (EOFs).
Returns an array with the ordered EOFs along the first dimension.
Optional arguments:
Sets the scaling of the EOFs. The following values are accepted:
neofs – Number of EOFs to return. Defaults to all EOFs.
Eigenvalues (decreasing variances) associated with each EOF.
Optional argument:
EOFs scaled as the correlation of the PCs with the original field.
Optional argument:
EOFs scaled as the covariance of the PCs with the original field.
Optional arguments:
Set the scaling of the PCs used to compute covariance. The following values are accepted:
Fractional EOF variances.
The fraction of the total variance explained by each EOF. This is a value between 0 and 1 inclusive.
Optional argument:
Total variance associated with the field of anomalies (the sum of the eigenvalues).
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:
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:
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.
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:
Optional arguments:
Set the scaling of the EOFs that are projected onto. The following values are accepted:
Supplementary tools for the meta-data enabled EOF analysis interface.
Weights for a data set on a grid.
Returned weights are a numpy.ndarray broadcastable against the input data shape.
Arguments:
Optional arguments:
Weighting scheme to use. The following values are accepted:
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")
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:
Examples:
Assuming eofobj is an instance of Eof, compute correlation maps for each PC:
>>> pcs = eofobj.pcs(pcscaling=1)
>>> cormaps = correlation_map(pcs, field)
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:
Optional arguments:
Examples:
Assuming eofobj is an instance of Eof, compute covariance maps for each PC:
>>> pcs = eofobj.pcs(pcscaling=1)
>>> covmaps = covariance_map(pcs, field)
Supplementary tools for the numpy EOF analysis interface.
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:
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:
Optional arguments: