kalmanFilter.setCovariance

Directly set the covariance for the Kalman filter

Syntax



obj = obj.setCovariance(C, Ycov)


obj = obj.setCovariance(C, Ycov, whichSet)


[C, Ycov, whichSet] = obj.setCovariance


obj = obj.setCovariance(‘reset’)

Description



obj = obj.setCovariance(C, Ycov)

Directly sets the covariance used by the Kalman Filter. If directly setting the covariance, the Kalman filter will not calculate the covariances between the ensemble and observation estimates. Instead, it will use the directly specified values. This approach can be useful when the default covariance matrices include many NaN elements (for example, as may happen for deep-time assimilations with changing continental configurations. You cannot implement inflation, localization, or blending when directly setting the covariance.

The first input provides the covariance between the state vector elements and the observation sites. It should be a3D array with one row per state vector element, and one column per observation site. The second input provides the covariance between the observation sites and one another. It should be a 3D array with one row and one column per observation site. Each element along the third dimension of Ycov must be a symmetric matrix.

The two inputs must have the same number of elements along the third dimension. If the third dimension has one element (i.e. both inputs are matrices), then the same covariance is used for each assimilation time step. Otherwise, the third dimension must have one element per time step (although see the next syntax for relaxing this requirement). C may contain NaN elements, although the filter will return a NaN update at any state vector rows with a NaN covariance. Ycov cannot include NaN elements.



obj = obj.setCovariance(C, Ycov, whichSet)

Indicates which set of covariances to use as the covariance in each assimilated time step. This syntax allows the number of specified covariances to differ from the number of time steps.



[C, Ycov, whichSet] = obj.setCovariance

Returns the current set of directly specified covariances for the filter.



obj = obj.setCovariance(‘reset’)

Deletes any directly specified covariances from the current filter.

Input Arguments

C

numeric 3*D* array [nState x nSite x 1|*nTime*|*nSet*]
The covariance to use between the state vector elements and the observation sites. A 3D array with one row per state vector element, and one column per observation site. If using a single set of covariances, should have a single element along the third dimension. If the number of elements along the third dimension matches the number of time steps, uses the indicated set of covariance in each time step. If the number of elements is neither 1 nor the number of time steps, use the whichSet input to indicate which set of covariances to use in each time step. May include NaN values, but the filter will return a NaN update for state vector elements with NaN covariances.

Ycov

numeric 3*D* array [nSite x nSite x 1|*nTime*|*nSet*]
The covariance to use between the observation sites and each other. A 3D array with one site and one column per observation site. The number of elements along the third dimension must match the number of elements for the C input. Cannot include NaN values. Each element along the third dimension must be a symmetric matrix and the diagonal elements must all be positive.

whichSet

vector, linear indices [nTime]
Indicates which set of covariances to use in each time step. Must have one element per assimilation time step. Each element is the index of one of the sets of covariances.

Output Arguments

obj

scalar kalmanFilter object
The kalmanFilter object with updated covariances

C

numeric 3*D* array [nState x nSite x 1|*nTime*|*nSet*] | []
The current directly-set covariances between the state vector elements and observation sites for the filter. If you have not directly set the covariance, returns an empty array.

Ycov

numeric 3*D* array [nSite x nSite x 1|*nTime*|*nSet*] | []
The current directly-set covariances between the observation sites and one another for the filter. If you have not directly set the covariance, returns an empty array.

whichSet

vector, linear indices [nTime]
Indicates which set of covariances will be used in each time step. If there is a single set of covariances, returns an empty array.