stateVector

Design and build state vector ensembles

Description

The state vector class is used to design and build state vector ensembles. The class implements an object that describes how a state vector ensemble should look. Thus, the class allows users to design a state vector ensemble without manipulating any data. Once a user finishes designing a state vector ensemble, they can call the “build” command to automatically build the state vector ensemble from a set of gridfile data catalogues.

Concepts

The following is some vocabulary useful for designing state vector ensembles. Ensemble Dimensions are the data dimensions used to select different ensemble members - often, these are the time and run dimensions. State Dimensions are the data dimensions that are organized down the state vector. These are often the spatial dimensions used to describe the dataset. In general, state dimensions will have the same metadata value at a state vector element, regardless of the ensemble member. By contrast, ensemble dimensions will have different values for different ensemble members.

Sometimes, an ensemble dimension will also have elements down the state vector (for example, successive months of the year). This is referred to as a sequence. The term coupled variables indicates that, within an ensemble member, the variables should be selected from the same points along the ensemble dimensions (for example, from the same points in time or from the same climate model run). In most cases, all the variables in an ensemble should be coupled to one another.

Outline

The following is a rough sketch for using the stateVector class.

Use the “stateVector” command to initialize the design for a state vector.
Use the “add” command to add variables to the state vector
Use the “design” command to indicate the ensemble dimensions, and to select subsets of gridfile catalogues that should be used to build the state vector ensemble.
Use the “sequence” command to implement sequences
Use the “mean”, “total”, “weightedMean”, and “weightedTotal” commands to implement means and totals in the state vector.
Use “build” to generate a state vector ensemble from the design.

The class also includes various methods that return information about the state vector. Among others, the “variables”, “length”, “members”, and “label” commands can all help facilitate workflows.

Troubleshooting Metadata

Sometimes, variables have different metadata formats along the ensemble dimensions (for example, annual and monthly time metadata). This can prevent stateVector from building an ensemble, because the class will not be able to check that the values in different ensemble members align to the same points. If this occurs, use the “metadata” command to allow comparison of the variables with different metadata formats.

Key Methods

The following methods are the most essential for users.

stateVector - Create a new, empty state vector
add - Add variables to a state vector
design - Design the dimensions of variables
sequence - Use sequences over ensemble dimensions
mean - Take means over variable dimensions
total - Take the sum total over variable dimensions
weightedMean - Take weighted means over variable dimensions
weightedTotal - Take weighted totals over variable dimensions
build - Build a state vector ensemble from a design

All User Methods

The complete list of methods for users.

Create

stateVector - Create a new, empty state vector

label - Return or specify a label for a state vector

Variables

add - Add new variables to a state vector
remove - Remove variables from a state vector
extract - Extract variables from a state vector
append - Append a second state vector to the current state vector
rename - Change the names of variables
relocate - Change the location of the gridfile associated with a variable

Design

design - Design the dimensions of variables in a state vector
sequence - Use sequences over ensemble dimensions
mean - Take the mean over variable dimensions
total - Take the sum total over variable dimensions
weightedMean - Take weighted means over variable dimensions
weightedTotal - Take weighted totals over variable dimensions

Metadata

metadata - Specify metadata options for dimensions of variables

getMetadata - Return the metadata that will be used along a dimension of a state vector variable

Overlap

overlap - Update the overlap settings of variables in a state vector

Coupling

autocouple - Specify if variables should be automatically coupled to new variables
couple - Couple indicated variables
uncouple - Uncouple indicated variables

Build

build - Build a new state vector ensemble

addMembers - Add members to an existing state vector ensemble

Size Information

length - Return the length of the state vector and its variables

members - Return the number of ensemble members associated with a state vector object

Variable Information

variable - Display a state vector variable in the console
variables - List the names of variables in a state vector
dimensions - Return the dimensions associated with variables
coupledVariables - List sets of coupled variables

General Information

disp - Display the state vector in the console

info - Return information about a state vector or its variables

Serialization

serialize - Serialize a stateVector object for fast saving/loading

deserialize - Restore a stateVector object from a serialized state

Utility Methods

Utility methods that help the class run. They are not intended for users.

General

name - Return a name for the state vector for use in error messages
assertEditable - Throw error if state vector is no longer editable
assertUnserialized - Throw error is state vector is serialized

Variables

updateLengths - Update the lengths of indicated variables
assertValidNames - Throw error if variable names are not valid
editVariables - Edit the design parameters of state vector variables

Indices

variableIndices - Parse variables and return indices in state vector

dimensionIndices - Parse dimensions and return indices in variables

Coupling

coupleDimensions - Update state and ensemble dimensions to match a template variable
coupledIndices - Return sets of coupled variable indices
couplingInfo - Return organized information about coupled variables

Build

buildEnsemble - Builds members of a state vector ensemble

Console Display

dispVariables - Display a list of state vector variables in the console

dispCoupled - Display sets of coupled variables in the console

Gridfile Interactions

parseGrids - Parse inputs that are either gridfile objects or .grid file paths
prepareGrids - Build and validate the gridfile objects for the state vector variables
buildGrids - Build unique gridfile objects
validateGrids - Check that gridfiles match recorded values

Unit Tests

tests - Implement unit tests for the stateVector class