stateVector.metadata

Specify how to process metadata along dimensions of state vector variables

Syntax



obj = obj.metadata(-1, …)


obj = obj.metadata(v, …)


obj = obj.metadata(variableNames, …)


obj = obj.metadata(variables, dimensions, metadataType, …)


obj = obj.metadata(variables, dimensions, 0|”r”|”raw”)


obj = obj.metadata(variables, dimensions, 1|”s”|”set”, alternateMetadata)


obj = obj.metadata(variables, dimensions, 2|”c”|”convert”, conversionFunction)


obj = obj.metadata(variables, dimensions, 2|”c”|”convert”, conversionFunction, conversionArgs)

Description



obj = obj.metadata(-1, …)


obj = obj.metadata(v, …)


obj = obj.metadata(variableNames, …)

Specifies how to process metadata for the listed variables. If the first input is -1, applies the settings to all variables currently in the state vector.



obj = obj.metadata(variables, dimensions, metadataType, …)

Specify how to process metadata for the indicated dimensions of the listed variables. This metadata is used when building ensemble members of a state vector ensemble. The metadata is used to ensure that coupled variables within an ensemble member all correspond to the same point. This check proceeds by searching for matching metadata along the ensemble dimensions of coupled variables, and pinning the variables at matching metadata points. In the default case, this metadata is extracted from the gridfile metadata for each ensemble dimension.

However, different variables can use different metadata formats within their gridfiles, which can prevent the metadata check from finding matching metadata. This method allows you to specify alternate metadata, or a metadata conversion method, to facilitate the comparison of metadata in different formats.

This method is perhaps most commonly used to combine variables on different time steps. If this describes your scenario, check out the HOW-TO page on combining annual and seasonal data, which is located in the documentation.



obj = obj.metadata(variables, dimensions, 0|”r”|”raw”)

Use raw gridfile metadata for the indicated dimensions of the variables. Metadata for each dimension is extracted from the gridfile metadata for the dimension. This is the default behavior.



obj = obj.metadata(variables, dimensions, 1|”s”|”set”, alternateMetadata)

Specify an alternate set of metadata to use for a dimension, which will be used instead of the gridfile metadata. The metadata must be a matrix, and the number of rows must match the number of state/reference indices for the dimension.



obj = obj.metadata(variables, dimensions, 2|”c”|”convert”, conversionFunction)


obj = obj.metadata(variables, dimensions, 2|”c”|”convert”, conversionFunction, conversionArgs)

Specify a function that can be used to convert gridfile metadata to a different format. The function must accept the metadata being converted as its first argument. You may use any built-in or user-defined function, which should be input as a function handle.

You may optionally provide additional arguments to be passed to the conversion function. These arguments should be organized in a cell vector. These input arguments will be passed to the conversion function in order, after the metadata argument. If you provide N optional arguments, they will be passed to the conversion function as input arguments 2 to N+1, as per the following:

convertedMetadata = conversionFunction(gridfile metadata, args{1}, args{2}, … arg{N})

Input Arguments

v

logical vector | linear indices | -1
The indices of variables in the state vector that should have metadata updated. Either a logical vector with one element per state vector variable, or a vector of linear indices. If linear indices, may not contain repeated indices. If -1, selects all variables in the state vector.

variableNames

string vector
The names of variables in the state vector that should have metadata updated. May not contain repeated variable names.

dimensions

string vector [nDimensions]
The names of the ensemble dimensions that should have their metadata updated. Each dimension must be an ensemble dimension in all listed variables. Cannot have repeated dimension names.

metadataType

scalar integer | scalar string
Specifies how the metadata for the dimensions should be processed.

[0|”r”|”raw” (default)]: Use gridfile metadata

[1|”s”|”set”]: Use an alternate set of user-specified metadata

[2|”c”|”convert”]: Apply a conversion function to gridfile metadata

alternateMetadata

cell vector [nDimensions]{matadata matrix [nIndices x ?]}
Alternate metadata to use for the dimensions. Each element should hold a metadata matrix, and the number of metadata rows for each matrix should match the length of the corresponding gridfile dimension. Each metadata matrix should have unique rows.

Metadata matrices may have a numeric, logical, char, string, cellstring, or datetime data type. They cannot contain NaN or NaT elements. Cellstring metadata will be converted to string.

If only a single dimension is indicated, you may provide the alternate metadata directly, instead of as a scalar cell. However, the scalar cell syntax is also permitted.

conversionFunction

cell vector [nDimensions], {scalar function*_*handle}
The conversion functions to use for each of the indicated dimensions. A cell vector with one element per listed dimension. Each element holds a function handle for the conversion function to use for the dimension. If only a single dimension is listed, you may also provide the function handle directly, instead of in a scalar cell.

conversionArgs

cell vector [nDimensions, {cell vector {function args}}
Additional arguments to each conversion function. A cell vector with one element per conversion function handle. Each element holds the additional arguments to the conversion function. If a conversion function has no additional arguments, the corresponding element of conversionArgs should hold an empty cell. If only a single dimension is listed, you may provide the additional arguments for the conversion function directly as a cell vector, instead of within a scalar cell.

Output Arguments

obj

scalar stateVector object
The state vector with updated metadata specifications.