stateVector.build

Build a state vector ensemble

Syntax



[X, metadata, obj] = obj.build(nMembers)


… = obj.build(‘all’)


… = obj.build(…, ‘sequential’, true | false)


… = obj.build(…, ‘sequential’, buildSequentially)


[ens, metadata, obj] = obj.build(…, ‘file’, filename)


… = obj.build(…, ‘file’, filename, ‘overwrite’, true | false)


… = obj.build(…, ‘file’, filename, ‘overwrite’, overwrite)


… = obj.build(…, ‘strict’, true | false)


… = obj.build(…, ‘strict’, strict)


… = obj.build(…, ‘precision’, ‘single’ | ‘double’)


… = obj.build(…, ‘precision’, precision)

Description



[X, metadata, obj] = obj.build(nMembers)

Builds a state vector ensemble with the specified number of ensemble members and returns the ensemble as output. If the state vector includes sequences or means, the method ensures that only ensemble members with complete sequences and means are built.

The built ensemble is a matrix with one column per ensemble member. As the second output, the method returns an ensembleMeatdata object, which organizes metadata along the rows and columns of the ensemble. The final output is the state vector object for the built ensemble, which can be used to add more members to the ensemble if necessary.



= obj.build(‘all’)

Builds a state vector ensemble with as many ensemble members as possible. Reports the number of ensemble members being built to the console.



= obj.build(…, ‘sequential’, true | false)


= obj.build(…, ‘sequential’, buildSequentially)

Specify whether ensemble members should be selected sequentially along the ensemble dimensions, or at random. The default behavior is random selection. Use this option if, for example, you want the ensemble members to remain ordered in time.



[ens, metadata, obj] = obj.build(…, ‘file’, filename)

Saves the state vector ensemble to a .ens file of the specified name. The saved ensemble can then be accessed at any time using the “ensemble” class. This option allows you to build ensembles that are too large to fit in active memory. When writing the ensemble to file, the first output is an ensemble object, which can be used to interact with the ensemble saved in the file.



= obj.build(…, ‘file’, filename, ‘overwrite’, true | false)


= obj.build(…, ‘file’, filename, ‘overwrite’, overwrite)

Specify whether the new .ens file can overwrite an existing file. Default is to not overwrite existing files.



= obj.build(…, ‘strict’, true | false)


= obj.build(…, ‘strict’, strict)

Specify how the method should respond if it cannot build the requested number of ensemble members. If true (default), throws an error when the requested number of ensemble members cannot be built. If false, issues a warning (but does not fail) when the requested number of ensemble members cannot be built. If this occurs, the output ensemble will have fewer columns than the requested number of ensemble members.



= obj.build(…, ‘precision’, ‘single’ | ‘double’)


= obj.build(…, ‘precision’, precision)

Specify the numerical precision of the ensemble. If no precision is specified, selects a precision based on the precision of the data used to build the ensemble.

Input Arguments

nMembers

scalar positive integer | ‘all’
The number of ensemble members (columns) that should be in the built ensemble. Use ‘all’ to use every possible ensemble member.

buildSequentially

scalar logical
True if ensemble members should be selected sequentially along ensemble dimensions. False (default) if ensemble members should be selected at random.

filename

string scalar
The name of the new “.ens” file. May be a filename, relative path, or absolute path. If not an absolute path, saves the new file relative to the current folder. Adds a “.ens” extension to the filename if it does not already have one.

overwrite

scalar logical
True if the new “.ens” file can overwrite existing files. False (default) if the method should not overwrite existing files.

precision

‘single’ | ‘double’
The desired numerical precision of the built state vector ensemble.

Output Arguments

X

numeric matrix [nState x nMembers]
The built state vector ensemble. Has one row per state vector element. Each column is an ensemble member.

ens

scalar ensemble object
An ensemble object that can be used to interact with the ensemble written to file. See >> dash.doc(‘ensemble’) for more details.

metadata

scalar ensembleMetadata object
An ensemble metadata object for the ensemble. Organizes metadata along the rows and columns of the ensemble. See >> dash.doc(‘ensembleMetadata’) for more details.

obj

scalar stateVector object
The state vector object for the built ensemble. Can be used to add additional members to the ensemble. Cannot be edited in any way.

Saves

Optionally saves a .ens file holding the state vector ensemble.