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

Interface Dataset

All Known Implementing Classes:

AbstractContinuousDomainDataset, AbstractDataset, DiscreteLayeredDataset, FakeTrajectoryDatasetFactory.FakeTrajectoryDataset, GriddedDataset, HorizontallyDiscreteDataset, HorizontalMesh4dDataset, HydromodelVtkGridDataset, HydromodelVtkUnstructuredDataset, PointDataset, TrajectoryDataset

public interface Dataset

Provides access to data and metadata held in underlying storage, e.g. on disk, in a database or on a remote server.

Author:

Guy Griffiths, Jon Blower

Method Summary

Modifier and Type	Method	Description
void	addVariablePlugin(VariablePlugin plugin)	Adds a VariablePlugin to this dataset to generate derived variables from existing ones in the Dataset
List<? extends ProfileFeature>	extractProfileFeatures(Set<String> varIds, BoundingBox bbox, Extent<Double> zExtent, Extent<org.joda.time.DateTime> tExtent, HorizontalPosition targetPos, org.joda.time.DateTime targetTime)	Extracts ProfileFeature(s) from the Dataset
List<? extends PointSeriesFeature>	extractTimeseriesFeatures(Set<String> varIds, BoundingBox bbox, Extent<Double> zExtent, Extent<org.joda.time.DateTime> tExtent, HorizontalPosition targetPos, Double targetZ)	Extracts PointSeriesFeature(s) from the Dataset
Set<String>	getFeatureIds()
Class<? extends DiscreteFeature<?,?>>	getFeatureType(String variableId)	Determines the type of feature returned by the readFeature(String) method for a particular variable (feature ID)
String	getId()
Class<? extends DiscreteFeature<?,?>>	getMapFeatureType(String variableId)	Determines the type of feature returned by the extractMapFeatures() methods (defined in subclasses) for a particular variable
Set<VariableMetadata>	getTopLevelVariables()
Set<String>	getVariableIds()
VariableMetadata	getVariableMetadata(String variableId)	Returns the VariableMetadata associated with a particular variable ID
Feature<?>	readFeature(String featureId)	Reads an entire feature from underlying storage
boolean	supportsProfileFeatureExtraction(String varId)
boolean	supportsTimeseriesExtraction(String varId)

Method Detail

getId

String getId()

Returns:

The ID which identifies this dataset.

getFeatureIds

Set<String> getFeatureIds()

Returns:

the IDs of features which are present in this Dataset

getFeatureType

Class<? extends DiscreteFeature<?,?>> getFeatureType(String variableId)

Determines the type of feature returned by the readFeature(String) method for a particular variable (feature ID)

Parameters:

variableId - The ID of the variable

Returns:

The class of the Features returned when calling the readFeature(java.lang.String) method for the same variable ID

readFeature

Feature<?> readFeature(String featureId)
                throws DataReadingException,
                       VariableNotFoundException

Reads an entire feature from underlying storage

Parameters:

featureId - The ID of the feature to read

Returns:

The resulting Feature

Throws:

VariableNotFoundException - If the requested feature is not found

DataReadingException

getVariableIds

Set<String> getVariableIds()

Returns:

the IDs of variables in this Dataset. Generally the term "variable" refers to a measured physical quantity

getVariableMetadata

VariableMetadata getVariableMetadata(String variableId)
                              throws VariableNotFoundException

Returns the VariableMetadata associated with a particular variable ID

Parameters:

variableId - The variable ID to search for

Returns:

The desired VariableMetadata

Throws:

VariableNotFoundException - If the requested variable is not available

getTopLevelVariables

Set<VariableMetadata> getTopLevelVariables()

Returns:

the variables at the top level of the hierarchy.

addVariablePlugin

void addVariablePlugin(VariablePlugin plugin)
                throws EdalException

Adds a VariablePlugin to this dataset to generate derived variables from existing ones in the Dataset

Parameters:

plugin - The VariablePlugin to add

Throws:

EdalException - If there is a problem adding the plugin

getMapFeatureType

Class<? extends DiscreteFeature<?,?>> getMapFeatureType(String variableId)

Determines the type of feature returned by the extractMapFeatures() methods (defined in subclasses) for a particular variable

Parameters:

variableId - The ID of the variable

Returns:

The class of the Features returned when calling the extractMapFeatures method for the given variable ID

extractProfileFeatures

List<? extends ProfileFeature> extractProfileFeatures(Set<String> varIds,
                                                      BoundingBox bbox,
                                                      Extent<Double> zExtent,
                                                      Extent<org.joda.time.DateTime> tExtent,
                                                      HorizontalPosition targetPos,
                                                      org.joda.time.DateTime targetTime)
                                               throws DataReadingException,
                                                      UnsupportedOperationException,
                                                      VariableNotFoundException

Extracts ProfileFeature(s) from the Dataset

Parameters:

varIds - The variable IDs to extract. If this is null then all variable IDs will be plotted. Any non-scalar parent variables will have all of their child variables extracted.

bbox -

• If this BoundingBox is non- null, all measurements falling within it will be returned.
• If it is null, only measurements which match the horizontal position given by targetPos will be extracted.
• If both bbox and targetPos are null no constraint is placed on horizontal positions - e.g. for a gridded field a profile will be returned for every horizontal grid point.

zExtent -

• If this is non- null, all ProfileFeatures whose domains have any intersection with this vertical extent will be extracted. The domains of the extracted ProfileFeature s will be the entire available domains, not just the intersection.
• If this is null , no constraint will be placed on the vertical domain of the ProfileFeatures to extract.

tExtent -

• If this is non- null, all measurements which fall entirely within its extent will be extracted
• If it is null only profiles matching the time specified by targetT will be extracted.
• If tExtent and targetT are both null , ProfileFeatures for all available time values will be extracted.

targetPos -

• If the bbox argument is null, only measurements which match this horizontal position will be extracted. In the case of a gridded feature, this will be the profile of the grid cell which the position falls into, but for a dataset with a continuous HorizontalDomain only exact matches will be extracted
• If both bbox and targetPos are null no constraint is placed on horizontal positions - e.g. for a gridded field a profile will be returned for every horizontal grid point.
• If this is non-null, the resulting Collection will be sorted according to distance (in co-ordinate units) from the target position

targetTime -

• If tExtent is null only profiles matching the time specified by this parameter will be extracted. In the case of a gridded dataset a time is considered to match if the method TimeAxis#contains(DateTime) on its time axis returns true for the target time. For a non-gridded dataset, the feature time must exactly match the target time.
• If tExtent and targetT are both null , ProfileFeatures for all available time values will be extracted.

Returns:

A Collection of ProfileFeatures, sorted by their distance from the target horizontal position, if it exists.

Throws:

DataReadingException - if there is a problem reading the underlying data

UnsupportedOperationException - if not all of the requested variables have a vertical domain

VariableNotFoundException - if one or more of the specified variables are not present in this dataset

supportsProfileFeatureExtraction

boolean supportsProfileFeatureExtraction(String varId)

Parameters:

varId - The ID of the variable to extract

Returns:

true if this dataset supports the extraction of the given variable to ProfileFeatures via the extractProfileFeatures(Set, BoundingBox, Extent, Extent, HorizontalPosition, DateTime) method

extractTimeseriesFeatures

List<? extends PointSeriesFeature> extractTimeseriesFeatures(Set<String> varIds,
                                                             BoundingBox bbox,
                                                             Extent<Double> zExtent,
                                                             Extent<org.joda.time.DateTime> tExtent,
                                                             HorizontalPosition targetPos,
                                                             Double targetZ)
                                                      throws DataReadingException,
                                                             UnsupportedOperationException,
                                                             VariableNotFoundException

Extracts PointSeriesFeature(s) from the Dataset

Parameters:

varIds - The variable IDs to extract. If this is null then all variable IDs will be plotted. Any non-scalar parent variables will have all of their child variables extracted.

bbox -

• If this BoundingBox is non- null, all measurements falling within it will be returned.
• If it is null, only measurements which match the horizontal position given by targetPos will be extracted.
• If both bbox and targetPos are null no constraint is placed on horizontal positions - e.g. for a gridded field a profile will be returned for every horizontal grid point.

zExtent -

• If this is non- null, all measurements which fall entirely within its extent will be extracted
• If it is null only timeseries matching the depth specified by targetZ will be extracted.
• If zExtent and targetZ are both null , PointSeriesFeatures for all available depth values will be extracted.

tExtent -

• If this is non- null, all PointSeriesFeatures whose domains have any intersection with this time extent will be extracted. The domains of the extracted PointSeriesFeature s will be the entire available domains, not just the intersection.
• If this is null , no constraint will be placed on the time domain of the PointSeriesFeatures to extract.

targetPos -

• If the bbox argument is null, only measurements which match this horizontal position will be extracted. In the case of a gridded feature, this will be the profile of the grid cell which the position falls into, but for a dataset with a continuous HorizontalDomain only exact matches will be extracted
• If both bbox and targetPos are null no constraint is placed on horizontal positions - e.g. for a gridded field a profile will be returned for every horizontal grid point.
• If this is non-null, the resulting Collection will be sorted according to distance (in co-ordinate units) from the target position

targetZ -

• If zExtent is null only timeseries matching the depth specified by this parameter will be extracted. In the case of a gridded dataset a depth is considered to match if the method VerticalAxis#contains(Double) on its vertical axis returns true for the target depth. For a non-gridded dataset, the feature depth must exactly match the target depth.
• If zExtent and targetZ are both null , PointSeriesFeatures for all available time values will be extracted.

Returns:

A Collection of PointSeriesFeatures, sorted by their distance from the target horizontal position, if it exists.

Throws:

DataReadingException - if there is a problem reading the underlying data

UnsupportedOperationException - if not all of the requested variables have a time domain

VariableNotFoundException - if one or more of the specified variables are not present in this dataset

supportsTimeseriesExtraction

boolean supportsTimeseriesExtraction(String varId)

Parameters:

varId - The ID of the variable to extract

Returns:

true if this dataset supports the extraction of the given variable to PointSeriesFeatures via the extractTimeseriesFeatures(Set, BoundingBox, Extent, Extent, HorizontalPosition, Double) method