Package uk.ac.rdg.resc.edal.dataset.plugins

Class VariablePlugin

java.lang.Object

uk.ac.rdg.resc.edal.dataset.plugins.VariablePlugin

Direct Known Subclasses:

ArbitraryGroupPlugin, DifferencePlugin, NormalisedDifferencePlugin, ValueErrorPlugin, VectorPlugin

public abstract class VariablePlugin
extends Object

This class specifies a way of generating new variables on-the-fly from existing ones. It works by supplying to the constructor a list of variable IDs which the plugin uses, and a list of suffixes which it provides. The full variable IDs which the plugin provides are obtained by combining the input IDs and adding each of the suffixes. The plugin must then override the two abstract methods doProcessVariableMetadata(VariableMetadata...) and generateValue(String, HorizontalPosition, Number...) to generate appropriate metadata and values respectively. For an example of usage, see VectorPlugin, which groups vector components and generates magnitude and direction variables.

Author:

Guy Griffiths

Field Summary

Fields

Modifier and Type	Field	Description
protected int	prefixLength
protected String[]	uses

Constructor Summary

Constructors

Constructor	Description
VariablePlugin(String[] usesVariables, String[] providesSuffixes)	Instantiate a plugin

Method Summary

Modifier and Type	Method	Description
protected String	combineIds(String... partsToUse)	Provides a convenience method for mangling several IDs into one new one.
protected abstract VariableMetadata[]	doProcessVariableMetadata(VariableMetadata... metadata)	Subclasses should override this method to modify the VariableMetadata tree, and return any new objects added to it.
Array1D<Number>	generateArray1D(String varId, Array1D<HorizontalPosition> positions, Array1D<Number>... sourceArrays)	Convenience method for generating an Array1D from source
Array2D<Number>	generateArray2D(String varId, Array2D<HorizontalPosition> positions, Array2D<Number>... sourceArrays)	Convenience method for generating an Array2D from source
protected abstract Number	generateValue(String varSuffix, HorizontalPosition pos, Number... sourceValues)	Subclasses should override this method to generate values based on source variable values
protected String	getFullId(String suffix)	Returns an ID based on the combined ID of all used variables and the suffix of a provided variable.
Number	getValue(String varId, HorizontalPosition pos, Number... values)	Generates a value for the desired ID
protected VariableMetadata	newVariableMetadataFromDomains(Parameter parameter, boolean scalar, HorizontalDomain[] hDomains, VerticalDomain[] zDomains, TemporalDomain[] tDomains)	Generates VariableMetadata from the given arguments and domains.
protected VariableMetadata	newVariableMetadataFromMetadata(Parameter parameter, boolean scalar, VariableMetadata... metadata)	Generates VariableMetadata from the given arguments and metadata.
VariableMetadata[]	processVariableMetadata(VariableMetadata... metadata)	Modifies the current VariableMetadata tree to reflect the changes this plugin implements.
String[]	providesVariables()
String[]	usesVariables()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uses

protected String[] uses

prefixLength

protected int prefixLength

Constructor Detail

VariablePlugin

public VariablePlugin(String[] usesVariables,
                      String[] providesSuffixes)

Instantiate a plugin

Parameters:

usesVariables - The IDs of the variables used to generate new values

providesSuffixes - The suffixes of the generated variables. These will not form the actual variable IDs.

Method Detail

usesVariables

public String[] usesVariables()

Returns:

The IDs of the variables which this plugin uses, in the order it needs them

providesVariables

public String[] providesVariables()

Returns:

The IDs of the variables which this plugin provides

generateArray1D

public Array1D<Number> generateArray1D(String varId,
                                       Array1D<HorizontalPosition> positions,
                                       Array1D<Number>... sourceArrays)

Convenience method for generating an Array1D from source

Parameters:

varId - The ID of the variable to generate

positions - An Array1D of the positions of each value

sourceArrays - An Array1D containing the source values

Returns:

An Array1D containing the generated values

generateArray2D

public Array2D<Number> generateArray2D(String varId,
                                       Array2D<HorizontalPosition> positions,
                                       Array2D<Number>... sourceArrays)

Convenience method for generating an Array2D from source

Parameters:

varId - The ID of the variable to generate

positions - An Array2D of the positions of each value

sourceArrays - An Array2D containing the source values

Returns:

An Array2D containing the generated values

processVariableMetadata

public VariableMetadata[] processVariableMetadata(VariableMetadata... metadata)
                                           throws EdalException

Modifies the current VariableMetadata tree to reflect the changes this plugin implements.

Parameters:

metadata - An array of VariableMetadata of the source variables

Returns:

An array of any new VariableMetadata objects inserted into the tree

Throws:

EdalException - If there is a problem processing the metadata

getValue

public Number getValue(String varId,
                       HorizontalPosition pos,
                       Number... values)

Generates a value for the desired ID

Parameters:

varId - The ID of the variable to generate a value for

pos - The HorizontalPosition at which the data is being generated. This may be relevant to how the plugin processes the values

values - An array of Numbers representing the source values

Returns:

The derived value

doProcessVariableMetadata

protected abstract VariableMetadata[] doProcessVariableMetadata(VariableMetadata... metadata)
                                                         throws EdalException

Subclasses should override this method to modify the VariableMetadata tree, and return any new objects added to it. This allows subclasses to arbitrarily restructure the metadata tree by calling the VariableMetadata.setParent(VariableMetadata, String) methods. Note that the IDs in the newly-created VariableMetadata objects should be generated by calling getFullId(String) with the variable's suffix. If the plugin is designed to group several child variables, the first child will be used to automatically estimate the scale range of the parent. This is guaranteed to only be called once.

Parameters:

metadata - An array of VariableMetadata of the source variables in the order they were supplied to the constructor

Returns:

The derived VariableMetadata

Throws:

EdalException - If there is a problem generating new metadata

generateValue

protected abstract Number generateValue(String varSuffix,
                                        HorizontalPosition pos,
                                        Number... sourceValues)

Subclasses should override this method to generate values based on source variable values

Parameters:

varSuffix - The suffix ID of the variable to generate VariableMetadata for. This will be one of the provided suffixes in the constructor, but not the actual variable ID (which subclasses do not need to worry about)

pos - The HorizontalPosition at which the value is generated. This may affect the returned value

sourceValues - An array of Numbers representing the source values in the order they were supplied to the constructor

Returns:

The derived value

combineIds

protected String combineIds(String... partsToUse)

Provides a convenience method for mangling several IDs into one new one. This just concatenates them, but subclasses may wish to override this if they require a specific format for IDs. This is guaranteed to be called once upon construction.

Parameters:

partsToUse - The IDs to base this name on

getFullId

protected final String getFullId(String suffix)

Returns an ID based on the combined ID of all used variables and the suffix of a provided variable. This should be used by subclasses to generate new VariableMetadata objects in doProcessVariableMetadata(VariableMetadata...) if required

Parameters:

suffix - The suffix used to identify the generated variable.

Returns:

The full ID

newVariableMetadataFromMetadata

protected VariableMetadata newVariableMetadataFromMetadata(Parameter parameter,
                                                           boolean scalar,
                                                           VariableMetadata... metadata)
                                                    throws IncorrectDomainException

Generates VariableMetadata from the given arguments and metadata. If all VariableMetadata arguments are of the same type (e.g. GridVariableMetadata or HorizontalMesh4dVariableMetadata ), then the return type is guaranteed to be of that type. If that is not possible, an exception will be thrown. This should be used by subclasses when generating VariableMetadata from several other VariableMetadata objects.

Parameters:

parameter - The Parameter describing the variable

scalar - Whether the resulting variable is a scalar (if not, it is a grouping variable)

metadata - An array of VariableMetadata objects for the source data

Returns:

A VariableMetadata object with the specified parameters, and domains which encompass the intersection of all of the supplied domains. If appropriate, this will be a GridVariableMetadata object.

Throws:

IncorrectDomainException - If a common domain of the same type as the domains of the supplied VariableMetadata objects cannot be found.

newVariableMetadataFromDomains

protected VariableMetadata newVariableMetadataFromDomains(Parameter parameter,
                                                          boolean scalar,
                                                          HorizontalDomain[] hDomains,
                                                          VerticalDomain[] zDomains,
                                                          TemporalDomain[] tDomains)
                                                   throws IncorrectDomainException

Generates VariableMetadata from the given arguments and domains. If all of the domains are HorizontalGrids, then the resulting VariableMetadata will also be GridVariableMetadata and can be cast as such. This should be used by subclasses when generating VariableMetadata from several other VariableMetadata objects.

Parameters:

parameter - The Parameter describing the variable

scalar - Whether the resulting variable is a scalar (if not, it is a grouping variable)

hDomains - An array of HorizontalDomains for the source data

zDomains - An array of VerticalDomains for the source data

tDomains - An array of TemporalDomains for the source data

Returns:

A VariableMetadata object with the specified parameters, and domains which encompass the intersection of all of the supplied domains. If appropriate, this will be a GridVariableMetadata object.

Throws:

IncorrectDomainException