kalmanFilter.run
Runs a offline ensemble square root Kalman Filter
Syntax
Description
output = obj.run
Runs the Kalman filter. When calculating the Kalman Gain, implements any covariance adjustments implemented by the “inflate”, “localize”, “blend”, and/or “setCovariance” methods.
The output is a scalar struct with various fields. The output always includes the updated ensemble mean (“Amean”), and the calibration ratio (“calibrationRatio”). The output may optionally include variance across the posterior ensemble (“Avar”), percentiles of the posterior ensemble (“Aperc”), and the updated ensemble deviations (“Adev”), depending on the options specified by the “variance”, “percentiles”, and “deviations”, commands. The output will also include the full posterior for any climate indices specified via the “index” command.
This method uses an ensemble square root Kalman filter, which updates ensemble means separately from the deviations. Updating deviations is more computationally expensive than updating the mean, so the method will only update deviations when necessary. Updating the deviations is necessary when returning posterior variance, percentiles, deviations, or climate indices. Exploratory analyses that only require the ensemble mean can significantly improve run time by not returning these quantities.
If you would like details on the implementation of the algorithm, or for advice on troubleshooting large state vectors, please see the help text for the kalmanFilter class: >> help kalmanFilter
output = obj.run(…, ‘complex’, complexResponse)output = obj.run(…, ‘complex’, “error”|”e”|false)output = obj.run(…, ‘complex’, “skip”|”s”|true)
Indicates how the method should respond if the adjusted Kalman gain becomes complex valued. This most often occurs because the R uncertainty covariances have negative eigenvalues. This option indicates how the method should respond if the adjusted gain becomes complex valued. If “error”|”e”|false, the method throws an error (this is the default behavior). If “skip”|”s”|true, the method will continue and will use a NaN update for ensemble deviations associated with a complex adjusted Kalman gain. The output will contain the “updatedDeviations” field, which indicates which assimilation time steps received a normal update to the ensemble deviations, and which time steps received a NaN update.
Input Arguments
complexResponse
[“error”|”e”|false (default)]: Throws an error if the adjusted Kalman gain becomes complex valued
[“skip”|”s”|true]: Uses a NaN update for ensemble deviations with a complex valued adjusted Kalman gain
Output Arguments
output
.calibrationRatio (numeric matrix [nSite x nTime]): The calibration ratio for each site in each time step.
.Amean (numeric matrix [nState x nTime]): The updated ensemble mean in each assimilated time step. This is the best estimate for the updated state vector in each time step.
.Adev (numeric 3D array [nState x nMembers x nTime]): The updated ensemble deviations in each time step.
.Avar (numeric matrix [nState x nTime]): The variance across the updated ensemble in each time step.
.Aperc (numeric 3D array [nState x nPercentiles x nTime]): Percentiles of the updated ensemble in each assimilated time step.
.index_<name> (numeric matrix [nMembers x nTime]): The full posterior of a given climate index calculated from the updated ensemble.
.updatedDeviations (logical vector [nTime]): Included in the output if the adjusted Kalman gain becomes complex in any assimilation time steps. If the value for a time step is true, the gain for the time step was real valued and the ensemble deviations were updated. If the value is false, the gain for the time step was complex valued, and the ensemble deviations were given a NaN update.