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

Class HorizontallyDiscreteDataset<DS extends DataSource>

java.lang.Object

uk.ac.rdg.resc.edal.dataset.AbstractDataset

uk.ac.rdg.resc.edal.dataset.HorizontallyDiscreteDataset<DS>

Type Parameters:

DS - The type of DataSource which will be used to read the underlying data

All Implemented Interfaces:

Serializable, Dataset

Direct Known Subclasses:

DiscreteLayeredDataset

public abstract class HorizontallyDiscreteDataset<DS extends DataSource>
extends AbstractDataset
implements Serializable

A partial implementation of a 4-dimensional Dataset which handles the use of plugins to generate values.

Author:

Guy Griffiths, Jon Blower

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected class	HorizontallyDiscreteDataset.PointSeriesLocation
protected class	HorizontallyDiscreteDataset.ProfileLocation

Field Summary

Fields inherited from class uk.ac.rdg.resc.edal.dataset.AbstractDataset

id, plugins, vars

Constructor Summary

Constructors

Constructor	Description
HorizontallyDiscreteDataset(String id, Collection<? extends VariableMetadata> vars)

Method Summary

Modifier and Type	Method	Description
List<MapFeature>	extractMapFeatures(Set<String> varIds, MapDomain domain)	Extracts MapFeatures ready to be plotted on a map
PointCollectionFeature	extractPointCollection(Set<String> varIds, PointCollectionDomain domain)	Extracts a PointCollectionFeature containing data from the given variable IDs
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
TrajectoryFeature	extractTrajectoryFeature(Set<String> varIds, TrajectoryDomain domain)	Extracts a TrajectoryFeature containing data from the given variable IDs
Set<String>	getFeatureIds()	By default we have one feature per variable.
protected static int	getTimeIndex(org.joda.time.DateTime time, TimeAxis tAxis, String varId)
protected static int	getVerticalIndex(Double zPos, VerticalAxis zAxis, String varId)
protected abstract DS	openDataSource()
Number	readSinglePoint(String variableId, HorizontalPosition position, Double zVal, org.joda.time.DateTime time)
protected abstract Array2D<Number>	readUnderlyingHorizontalData(String varId, MapDomain domain, DS dataSource)	Reads horizontal data for a non-derived variable
protected abstract Number	readUnderlyingPointData(String variableId, HorizontalPosition position, Double zVal, org.joda.time.DateTime time, DS dataSource)	Reads a single point for a non-derived variable
protected abstract Map<HorizontallyDiscreteDataset.PointSeriesLocation,Array1D<Number>>	readUnderlyingTemporalData(String varId, TimeAxis tAxis, BoundingBox bbox, Double targetZ, Extent<Double> zExtent, DS dataSource)	Reads timeseries data for a given non-derived variable
protected abstract Map<HorizontallyDiscreteDataset.ProfileLocation,Array1D<Number>>	readUnderlyingVerticalData(String varId, VerticalAxis zAxis, BoundingBox bbox, org.joda.time.DateTime targetT, Extent<org.joda.time.DateTime> tExtent, DS dataSource)	Reads profile data for a given non-derived variable
boolean	supportsProfileFeatureExtraction(String varId)
boolean	supportsTimeseriesExtraction(String varId)

Methods inherited from class uk.ac.rdg.resc.edal.dataset.AbstractDataset

addVariablePlugin, getId, getTopLevelVariables, getVariableIds, getVariableMetadata, isDerivedVariable

Methods inherited from class java.lang.Object

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

Methods inherited from interface uk.ac.rdg.resc.edal.dataset.Dataset

getFeatureType, getMapFeatureType, readFeature

Constructor Detail

HorizontallyDiscreteDataset

public HorizontallyDiscreteDataset(String id,
                                   Collection<? extends VariableMetadata> vars)

Method Detail

getFeatureIds

public Set<String> getFeatureIds()

By default we have one feature per variable. Subclasses can override this method to implement a different scheme.

Specified by:

getFeatureIds in interface Dataset

Returns:

the IDs of features which are present in this Dataset

extractMapFeatures

public final List<MapFeature> extractMapFeatures(Set<String> varIds,
                                                 MapDomain domain)
                                          throws DataReadingException,
                                                 VariableNotFoundException

Extracts MapFeatures ready to be plotted on a map

Parameters:

varIds - The IDs of the variables to extract from the dataset

domain - The domain on which to extract the data.

Returns:

A List of MapFeatures on the supplied domain

Throws:

DataReadingException - if there is a problem reading the underlying data

VariableNotFoundException - if one or more of the supplied variable IDs does not exist in the dataset

supportsProfileFeatureExtraction

public boolean supportsProfileFeatureExtraction(String varId)

Specified by:

supportsProfileFeatureExtraction in interface Dataset

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 Dataset.extractProfileFeatures(Set, BoundingBox, Extent, Extent, HorizontalPosition, DateTime) method

extractProfileFeatures

public 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

Description copied from interface: Dataset

Extracts ProfileFeature(s) from the Dataset

Specified by:

extractProfileFeatures in interface 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

supportsTimeseriesExtraction

public boolean supportsTimeseriesExtraction(String varId)

Specified by:

supportsTimeseriesExtraction in interface Dataset

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 Dataset.extractTimeseriesFeatures(Set, BoundingBox, Extent, Extent, HorizontalPosition, Double) method

extractTimeseriesFeatures

public 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

Description copied from interface: Dataset

Extracts PointSeriesFeature(s) from the Dataset

Specified by:

extractTimeseriesFeatures in interface 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

extractPointCollection

public PointCollectionFeature extractPointCollection(Set<String> varIds,
                                                     PointCollectionDomain domain)
                                              throws DataReadingException,
                                                     VariableNotFoundException

Extracts a PointCollectionFeature containing data from the given variable IDs

Parameters:

varIds - The variables to extract data from. If null, all available variables will be present in the returned PointCollectionFeature

domain - The PointCollectionDomain over which to extract data

Returns:

A PointCollectionFeature containing the extracted data

Throws:

DataReadingException - If there is a problem reading the underlying data

VariableNotFoundException - If one or more of the supplied variable IDs is not present in this HorizontallyDiscreteDataset

extractTrajectoryFeature

public TrajectoryFeature extractTrajectoryFeature(Set<String> varIds,
                                                  TrajectoryDomain domain)
                                           throws DataReadingException,
                                                  VariableNotFoundException

Extracts a TrajectoryFeature containing data from the given variable IDs

Parameters:

varIds - The variables to extract data from. If null, all available variables will be present in the returned TrajectoryFeature

domain - The TrajectoryDomain over which to extract data

Returns:

A TrajectoryFeature containing the extracted data

Throws:

DataReadingException - If there is a problem reading the underlying data

VariableNotFoundException - If one or more of the supplied variable IDs is not present in this HorizontallyDiscreteDataset

readSinglePoint

public final Number readSinglePoint(String variableId,
                                    HorizontalPosition position,
                                    Double zVal,
                                    org.joda.time.DateTime time)
                             throws DataReadingException,
                                    VariableNotFoundException

Throws:

DataReadingException

VariableNotFoundException

getTimeIndex

protected static int getTimeIndex(org.joda.time.DateTime time,
                                  TimeAxis tAxis,
                                  String varId)

getVerticalIndex

protected static int getVerticalIndex(Double zPos,
                                      VerticalAxis zAxis,
                                      String varId)

readUnderlyingPointData

protected abstract Number readUnderlyingPointData(String variableId,
                                                  HorizontalPosition position,
                                                  Double zVal,
                                                  org.joda.time.DateTime time,
                                                  DS dataSource)
                                           throws DataReadingException,
                                                  VariableNotFoundException

Reads a single point for a non-derived variable

Parameters:

variableId - The ID of the variable to read

position - The HorizontalPosition at which to read the data

zVal - The z-position to read at

time - The time to read at

dataSource - The DataSource to read from

Returns:

The value of the data, or null if there is no data there

Throws:

DataReadingException - If there is a problem reading the data

VariableNotFoundException - If the requested variable is not present in the Dataset

readUnderlyingHorizontalData

protected abstract Array2D<Number> readUnderlyingHorizontalData(String varId,
                                                                MapDomain domain,
                                                                DS dataSource)
                                                         throws DataReadingException,
                                                                VariableNotFoundException

Reads horizontal data for a non-derived variable

Parameters:

varId - The ID of the variable to read

domain - The MapDomain on which to read data

dataSource - The HorizontallyDiscreteDataset to read data from

Returns:

An Array2D containing the data corresponding to the supplied MapDomain

Throws:

DataReadingException - If there is a problem reading the data

VariableNotFoundException - If the requested variable is not present in the Dataset

readUnderlyingVerticalData

protected abstract Map<HorizontallyDiscreteDataset.ProfileLocation,Array1D<Number>> readUnderlyingVerticalData(String varId,
                                                                                                                     VerticalAxis zAxis,
                                                                                                                     BoundingBox bbox,
                                                                                                                     org.joda.time.DateTime targetT,
                                                                                                                     Extent<org.joda.time.DateTime> tExtent,
                                                                                                                     DS dataSource)
                                                                                                              throws DataReadingException,
                                                                                                                     VariableNotFoundException

Reads profile data for a given non-derived variable

Parameters:

varId - The of the variable to read data for

zAxis - The desired vertical axis of the data

bbox - The BoundingBox within which to read profiles

targetT - The target time at which to read profiles

tExtent - The time Extent within which to read profiles

dataSource - The DataSource to read from

Returns:

A Map of unique profile locations to data for each

Throws:

DataReadingException - If there was a problem reading data from the DataSource

VariableNotFoundException - If the requested variable is not present in the Dataset

readUnderlyingTemporalData

protected abstract Map<HorizontallyDiscreteDataset.PointSeriesLocation,Array1D<Number>> readUnderlyingTemporalData(String varId,
                                                                                                                         TimeAxis tAxis,
                                                                                                                         BoundingBox bbox,
                                                                                                                         Double targetZ,
                                                                                                                         Extent<Double> zExtent,
                                                                                                                         DS dataSource)
                                                                                                                  throws DataReadingException,
                                                                                                                         VariableNotFoundException

Reads timeseries data for a given non-derived variable

Parameters:

varId - The of the variable to read data for

tAxis - The desired time axis of the data

bbox - The BoundingBox within which to read timeseries

targetZ - The target depth to read timeseries at

zExtent - The vertical Extent within which to read timeseries

dataSource - The DataSource to read from

Returns:

A Map of unique profile locations to data for each

Throws:

DataReadingException - If there was a problem reading data from the DataSource

VariableNotFoundException - If the requested variable is not present in the Dataset

openDataSource

protected abstract DS openDataSource()
                              throws DataReadingException

Returns:

The DataSource from which to read data

Throws:

DataReadingException - if there is a problem opening the DataSource