ensemble

Manipulate and load saved state vector ensembles

Description

The ensemble class implements objects that allow users to interact with a saved state vector ensemble, while minimizing the amount of data that is actually loaded into memory. To that end, the class includes methods that allow users to load select variables and ensemble members, rather than all the data stored in a .ens file. The ensemble class also implements evolving ensembles, and lets users select saved ensemble members to use in different ensembles of an evolving set.

Ensemble objects can be provided to other commands in the DASH toolbox, such as “PSM.estimate” and “kalmanFilter.prior”. This allows these methods to utilize values in a saved state vector ensemble, without requiring users to load the ensembles into memory. These other commands include various memory optimizations so that even very large ensembles can be used to estimate proxies or used for assimilation.

Outline

The following is an outline for using the ensemble class.

Use “stateVector.build” with the ‘file’ option to save a state vector ensemble in a .ens file.
Use the “ensemble” command to create an ensemble object for the .ens file.
Use the “useVariables” command to select the state vector variables required for a particular task.
Use “useMembers”, “static”, and/or “evolving” to implement static or evolving ensembles with particular members
Use “load” to load the selected variables, ensemble members, or ensembles in an evolving set. Use “loadGrid” to load a variable and regrid it from a state vector to a gridded dataset. Use “loadRows” to load specific state vector rows.

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

Key Methods

The following methods are among the most essential for users

ensemble - Create an ensemble object for a saved state vector ensemble
useVariables - Use a subset of saved variables
useMembers - Use a subset of saved ensemble members
evolving - Implement an evolving ensemble
metadata - Return the metadata for an ensemble
load - Load portions of a state vector ensemble into memory
loadGrid - Load a variable in a state vector ensemble as a gridded field

All User Methods

The complete list of methods for users.

Create

ensemble - Create an ensemble object for a saved state vector ensemble

label - Set or return a label for an ensemble object

Subset

useVariables - Use a subset of saved variables

useMembers - Use a subset of saved ensemble members

Design

static - Implement a static ensemble
evolving - Implement an evolving ensemble
evolvingLabels - Label the different ensembles in an evolving ensemble

Metadata

metadata - Return the ensembleMetadata object for an ensemble

Load

load - Loads a state vector ensemble into memory
loadGrid - Load a variable in a state vector ensemble as a gridded fields
loadRows - Loads specific rows of a state vector ensemble

Information

length - Return the state vector length of an ensemble and its variables
variables - List the variables used in an ensemble
members - List the ensemble members used in an ensemble

Sizes

nRows - Return the number of state vector rows for one or more ensemble objects
nVariables - Return the number of state vector variables for one or more ensemble objects
nMembers - Return the number of ensemble members for one or more ensemble objects
nEvolving - Return the number of ensembles implemented by static or evolving ensemble objects

Add Members

addMembers - Add more members to a saved state vector ensemble

update - Update an ensemble object to include new members added to a .ens file

Console Display

disp - Displays an ensemble object in the console

Utility Methods

Utility methods that help the class run. These do not implement error checking and are not intended for users.

Assertions

assertEvolvingMembers - Throw error if input is not a set of ensemble members for an evolving ensemble

assertStaticMembers - Throw error if input is not ensemble members for a static ensemble

Indices

variableIndices - Parse variables and return indices in state vector

evolvingIndices - Parse ensembles and return indices in the evolving set

Console Display

dispEvolving - Display the labels of evolving ensembles in the console

dispVariables - Display the names and lengths of variables in an ensemble

Misc

name - Return a name for use in error messages
parseScope - Parse scope inputs
validateMatfile - Check .ens file is valid and unaltered

Unit Tests

tests - Unit tests for the ensemble class