ensembleMetadata.regrid

Regrids a variable in a state vector ensemble

Syntax



[V, metadata] = obj.regrid(variableName, X)


[V, metadata] = obj.regrid(v, X)


… = obj.regrid(…, ‘order’, dimensions)


… = obj.regrid(…, ‘dim’, d)


… = obj.regrid(…, ‘singletons’, singletons)


… = obj.regrid(…, ‘singletons’, “keep”|”k”|true)


… = obj.regrid(…, ‘singletons’, “remove”|”r”|false)

Description



[V, metadata] = obj.regrid(variableName, X)


[V, metadata] = obj.regrid(v, X)

Regrids a variable in a state vector ensemble. The variable is extracted from the overall state vector, and then reshaped into a gridded dataset. The method also returns metadata for the dimensions of the regridded dataset. This metadata will include metadata for any state dimensions or sequences used in the state vector. The metadata for sequence and standard state dimensions will have one row per element along the dimension. The metadata for state dimensions that implement a mean will have one row per data element used in the mean.

This method works on N-dimensional data arrays X. X can have any number of dimensions, but at least one dimension must have the same length as the state vector. By default, the method acts along the the first dimension with this length. Only this state vector dimension is reshaped into a gridded dataset. The dimensions before and after the state vector dimension are not reshaped. The returned metadata only includes information for the reshaped state vector dimensions. It does not include information for the other dimensions of X.

By default, the method removes any singleton regridded state vector dimensions (regridded state vector dimensions that have a length of 1). Neither the returned array nor the returned metadata will include these removed singleton dimensions. If all the regridded state vector dimensions are singleton (i.e. the variable has a length of 1), then the length of the regridded state vector dimension will be 1, but the metadata will not contain information on any dimension.



= obj.regrid(…, ‘order’, dimensions)

Returns the regridded data in a custom dimension order. The order of dimensions in the regridded dataset will match the order specified in the dimensions list. If the state vector has state dimensions or sequences that are not specified in the dimensions list, the unspecified dimensions are moved to the end of the order. If a singleton dimension is specified in the dimensions list, the singleton dimension will not be removed from the regridded dataset and metadata.



= obj.regrid(…, ‘dim’, d)

Indicate the dimension of X that should be used as the state vector dimension. The length of the dimension must match the length of the state vector.



= obj.regrid(…, ‘singletons’, singletons)


= obj.regrid(…, ‘singletons’, “keep”|”k”|true)


= obj.regrid(…, ‘singletons’, “remove”|”r”|false)

Specify how to treat regridded singleton dimensions. By default, singleton dimensions are removed from the regridded output unless they are listed in the dimension order. Use “keep”|”k”|true to keep all singleton dimensions in the regridded dataset. Using “remove”|”r”|false enacts the default behavior and removes singleton dimensions that are not listed in the dimension order.

Input Arguments

variableName

string scalar
The name of the variable to regrid

v

scalar linear index | logical vector
The index of the variable to regrid. If a logical vector, must have one element per variable in the state vector and exactly one true element.

X

N-dimensional array [leading dimensions x state vector dimension x trailing dimensions]
An N-dimensional array that includes the state vector containing the variable being regridded. Must have at least one dimension that matches the length of the state vector. If the “dim” input is specified, the length of that dimension must match the length of the state vector.

dimensions

string vector
The names of state dimensions in the order they should appear in the regridded variable.

d

scalar positive integer
The index of the dimension for input “X” that contains the state vector. If specified, the length of this dimension in X must match the length of the state vector.

singletons

string scalar | scalar logical
Specifies how to treat regridded singleton dimensions that are not listed in the “dimensions” input.

[“remove”|”r”|false (default)]: Unlisted singleton dimensions are removed from the regridded dataset.

[“keep”|”k”|true]: All singleton dimension are retained in the regridded dataset.

Output Arguments

V

N-dimensional array [leading dimensions x regridded dimensions x trailing dimensions]
The regridded variable. An N-dimensional array. The state vector dimension has been reshaped into a gridded dataset. Any dimensions preceding or following the state vector dimension are left unaltered. If the variable has no state dimensions (i.e. a singleton variable), the state vector dimension is retained as a singleton.

metadata

scalar gridMetadata object
A gridMetadata object describing the regridded state dimensions for the variable. The metadata for each dimension includes one row per element along the dimension. The order of dimensions in the metadata matches the order of dimensions for the regridded dataset. If a regridded dimension implements a mean, the metadata for the dimension will include one row per element used in the mean.