ensembleMetadata.latlon

Return latitude-longitude coordinates for state vector elements

Syntax



coordinates = obj.latlon


coordinates = obj.latlon(siteColumns)


coordinates = obj.latlon(siteColumns, variableNames)


coordinates = obj.latlon(siteColumns, v)

Description



coordinates = obj.latlon

Returns a latitude-longitude coordinate for each row of a state vector. The output is a matrix with two columns - the first column holds the latitude coordinate for each state vector row, and the second holds the longitude coordinate. This method is a convenience function intended to facilitate covariance localization. It prioritizes returning outputs suitable for covariance localization over strictly reporting metadata. Consider the “ensembleMetadata.rows” method for more rigorous metadata, or if covariance localization is not your intent.

This method is designed for the case where latitude-longitude metadata is stored along the “lat”, “lon”, and/or “site” dimensions. Coordinates that are not well-described by numeric scalars are returned as NaN.

The method acts by obtaining “lat” and “lon” metadata for each state vector element. To return a non-NaN coordinate for a state vector element, the “lat” and “lon” metadata for the element must be numeric scalars, string scalars, or char row vectors. In the case of string scalars or char rows vectors, the strings are converted to numeric coordinates using Matlab’s “str2double” function. If the state vector element does not have “lat” or “lon” metadata, the metadata is not one of the described formats, or the metadata cannot be converted to numeric coordinates, then the coordinates for the state vector element are returned as NaN. If a state vector element implements a mean over the “lat” or “lon” dimension, then the coordinate for the dimension is also set to NaN.



coordinates = obj.latlon(siteColumns)

This syntax allows the method to also extract coordinates that are stored along the “site” dimension. The input is a row vector with two elements. The two elements indicate which columns of the “site” metadata should be used for latitude and longitude coordinates.

Note that this syntax prioritizes “lat” and “lon” metadata over “site” metadata. The metadata will only extract coordinates from the “site” dimension when a state vector element has neither “lat” nor “lon” as a state dimension. If the element also does not have “site” metadata, the “site” metadata does not have the specified columns, the “site” metadata cannot be converted to numeric coordinates, or there is a mean over the “site” dimension, then the latitude-longitude coordinate is returned as NaN.

Indicate which columns of “site” metadata to use for specific variables. If the first input has a single row, then uses the same columns for all listed variables. Otherwise, the first input should have one row per listed variable.

This syntax prioritizes “site” metadata for the listed variables. For these variables, the method will only extract coordinates from “site” metadata and will ignore “lat” and “lon” metadata even if the state vector element does not have “site” as a state dimension. For all other variables, the method will only extract coordinates from “lat” and “lon”, even if the other variables have “site” as a state dimension.

Input Arguments

siteColumns

positive integers, vector [2] | matrix [nVariables x 2]
Indicates the columns of “site” metadata that should be used as latitude and longitude coordinates. If a vector, uses the same columns for all variables with “site” metadata. The first element is the latitude column, and the second element is the longitude column. siteColumns must be vector when no variables are specified.

If site variables are also listed, siteColumns may either be a vector or a matrix. If a matrix, must have one row per listed variable and two columns. The first column lists latitude columns in the site metadata, and the second column lists longitude columns for each variable.

variableNames

string vector [nVariables]
The names of variables that should use “site” metadata to determine latitude-longitude coordinates. Cannot have repeated names.

v

-1 | logical vector | vector, linear indices
The indices of variable that should use “site” metadata to determine latitude-longitude coordinates. If -1, selects all variables. If a logical vector, must have one element per variable in the state vector. If linear indices, cannot have repeated elements.

Output Arguments

coordinates

numeric matrix [nRows x 2]
Latitude-longtidue coordinates for each row of the state vector. First column is latitude and second column is longitude. If coordinate metadata for a row is not an expected format, returns a NaN coordinate for that row. NaN coordinates are returned for rows that: are missing a required dimension, implement a mean over a dimension, use coordinates that are not numeric scalars / string scalars / char row vectors, or have string metadata that cannot be converted to numeric values.