PSM.estimate
Compute observation estimates by applying forward models to a state vector ensemble
Syntax
Description
Computes observation estimates for a set of PSMs / forward models. For each PSM, uses the PSM’s rows to extract forward model inputs from the state vector ensemble. These inputs are used to run the PSM, and the PSM outputs are added to the output array of observation estimates.
Forward models should be provided either as a cell vector, where each element holds a scalar PSM object. If all the PSM objects are the same type of PSM, you may alternatively provide the PSM objects directly as PSM vector. Each PSM object is used to produce estimates for a particular observation site. Each row of the output array Ye holds the estimates for a particular PSM / observation site. The order of rows of Ye will match the order of input PSMs.
You can provide the state vector ensemble either directly as a numeric array, or as an ensemble object. If using a numeric array, the rows are treated as state vector elements and the columns are ensemble members. Any elements along the third dimension are treated as individual ensembles in an evolving set. If using an ensemble object, the object may implement either a static or an evolving ensemble. The number of columns of Ye will match the number of ensemble members, and the number of elements along the third dimension of Ye will match the number of evolving ensembles.
The method uses PSM rows to extract forward model inputs from the state vector ensemble. Thus, you must call the “rows” command on each input PSM object before using the “estimate” command. If any of the PSM objects defines different rows for different ensemble members, then all of the PSM objects must either 1. Define rows for the same number of ensemble members, or 2. Use the same rows for all ensemble members. Likewise, if any of the PSM objects defines different rows for different ensembles in an evolving set, then all of the PSM objects must either 1. Define rows for the same number of evolving ensembles, or 2. Use the same rows for all evolving ensembles.
If a PSM fails, the method issues a warning that the PSM failed in the console. The Ye values for the PSM will all be NaN.
Also estimates R error-variances from the PSMs whenever possible. Each row of the output array holds the estimated R error-variances for a particular site. If a forward model does not have the ability to estimate R variances, the R variances for the observation site will all be NaN. If a PSM fails, the R values for the PSM will all be NaN.
= PSM.estimate(…, ‘fail’, failureResponse)= PSM.estimate(…, ‘fail’, 0|’e’|’error’)= PSM.estimate(…, ‘fail’, 1|’s’|’skip’)= PSM.estimate(…, ‘fail’, 2|’w’|’warn’)
Indicate how the method should respond when a PSM fails to run. If 0|’e’|’error’, throws an error when a PSM fails. If 1|’s’|’skip’, skips over the failed PSM. If 2|’w’|’warn’, skips over the failed PSM and displays a warning in the console.
Indicate if the method should return a status report for each of the PSMs. The status report returns additional information about any PSMs that failed to run. This option allows users to obtain more information for troubleshooting PSMs that have failed. If true|’r’|’report’, returns a status report as the first output of the method. The status report is a struct with two fields: “.failed” and “.cause”. The “.failed” field whether each PSM ran successfully or failed. If the PSM ran successfully, .failed is 0 for the PSM. Otherwise, .failed is an integer that reports the type of failure that occurred. The “.cause” field reports the errors that caused any PSMs to failed. This field is a cell vector with one element per PSM. If the PSM ran successfully, the associated element is empty. If the PSM failed, the associated element contains the error that caused the failure.
Input Arguments
F
If any PSM objects define different rows for different ensemble members, then all PSM objects must either 1. Define rows for the same number of ensemnble members, or 2. Use the same rows for all ensemble members. If any PSM object define different rows for different ensembles in an evolving set, then all PSM objects must either 1. Define rows for the same number of evolving ensembles, or 2. Use the same rows for all evolving ensembles.
X
ens
failureResponse
[0|’e’|’error’]: Throw an error
[1|’s’|’skip’]: Skip the failed PSM, but do not issue a warning in the console
[2|’w’|’warn’]: Issue a warning in the console and skip the PSM
reportStatus
[true|’r’|’report’]: Return a status report as the first output
[false|’d’|’discard’]: Do not return a status report
Output Arguments
Ye
R
status
.failed (numeric vector [nSite]): Indicates the status of each forward model run [0]: The forward model ran successfully [1]: The inputs for the forward model failed to load [2]: The forward model issued an error while running [3]: The Ye outputs from the forward model were not valid [4]: The R uncertainties from the forward model were not valid
.cause (cell vector [nSite] {[] | scalar MException}): Reports the error that caused a PSM to fail. If the PSM ran successfully, the associated element is empty.