net.agmodel.physical
Interface Store

All Superinterfaces:

Sequence

All Known Implementing Classes:

StoreImpl

public interface Store

extends Sequence

Interface for a stores a time series of data collected during the partial interval (start,end] In the case of data measured over a subinterval the endpoint of the subinterval must lie in (start,end]
If interval straddles both start and end then it is also included.
Used by domain specific wrappers like net.agmodel.weatherData

interval data

   start______________end
     v                 v
 ----|=====       =====|----
  |=====|           |-----|
  |=======================|

 ---- excluded data
 ==== included data
 

point data

   start______________end
     v                 v
   . . OOOOOO         OO...
 ... excluded data
 OOO included data
 

Author:

Matthew Laurenson

Method Summary

Store	averageStore(Duration newResolution) Creates a new store with data averaged to a lower temporal resolution.
Store	averageStore(Duration newResolution, String newName) Creates a new store with data averaged to a lower temporal resolution.
Store	extendStore(Date newEnd) Creates a new store with a copy of the same data covering a longer period. The new store's resolution and starting point are the same as this one's.
Store	extendStore(Interval interval) Creates a new store at the same resolution as this one but covering a different DateRange.
JigsawQuantity	getAverage(Interval interval) Returns the average value of the time series over the interval.
float[]	getCoverage() Creates an array representing the coverage of the data returned by getData().
double[]	getData() Creates an array containing the data from the store.
JigsawQuantity	getInstant(Date time) Returns the instantaneous value of the time series at a particular point in time.
JigsawQuantity	getMaximum(Interval interval) Returns the maximum value of the time series over the interval.
JigsawQuantity	getMinimum(Interval interval) Returns the minimum value of the time series over the interval.
double	getNumberOfValues() Returns the number of data values in the store
SummaryHistory	getSummaryHistory() Returns the summary history for the data stored in the sequence
JigsawQuantity	getTotal(Interval interval) Returns the total value of the sequence over the interval.
Store	maximumStore(Duration newResolution) Creates a new store containing data summarised by finding the maximum of each subrange.
Store	maximumStore(Duration newResolution, String newName) Creates a new store containing data summarised by finding the maximum of each subrange.
Store	minimumStore(Duration newResolution) Creates a new store containing data summarised by finding the minimum of each subrange.
Store	minimumStore(Duration newResolution, String newName) Creates a new store containing data summarised by finding the minimum of each subrange.
void	putInstantValue(Date time, double value) Records the instantaneous value of the time series at a particular time
void	putValueOverInterval(Interval interval, double value) Records the value of the timeseries over some subinterval.
void	putValueOverInterval(Interval interval, JigsawQuantity value) Records the value of the timeseries over some subinterval, its coverage, and the extent to which it was interpolated.
Store	sampleStore(Duration newResolution) Creates a new store with data sampled to a lower temporal resolution.
Store	sampleStore(Duration newResolution, String newName) Creates a new store with data sampled to a lower temporal resolution.
Store	totalStore(Duration newResolution) Creates a new store with data totalled to a lower temporal resolution.
Store	totalStore(Duration newResolution, String newName) Creates a new store with data totalled to a lower temporal resolution.

Methods inherited from interface net.agmodel.physical.Sequence

clone, dumpSequence, getColumnHeading, getContentsAsString, getCurrentResolution, getDateRange, getName, getNumberOfSubComponents, getResolution, getSequenceHeading, getSubHeading, getSummaryKind, getUnitsHeading, setColumnHeading, setName

Method Detail

putInstantValue

public void putInstantValue(Date time,
                            double value)

Records the instantaneous value of the time series at a particular time

Parameters:

time - the point in time

value - the value of the time series at that time

Throws:

IllegalArgumentException - if the time is outside the interval that the period is intended to store

putValueOverInterval

public void putValueOverInterval(Interval interval,
                                 double value)

Records the value of the timeseries over some subinterval. It is assumed that the subinterval coverage is complete (ie there is no missing data in the subinterval) and that no interpolation took place.
If the store contains totalled data, and interval>currentResolution, then the data will be evenly distributed between the "cells" of the store.

Parameters:

interval - the period of time over which the measurement was taken. Interval duration must a postive integer multiple of store resolution, and the interval must align with the store "cells".

value - the value of the time series over that interval

Throws:

IllegalArgumentException - if the subinterval is outside the interval declared when the store was constructed

putValueOverInterval

public void putValueOverInterval(Interval interval,
                                 JigsawQuantity value)

Records the value of the timeseries over some subinterval, its coverage, and the extent to which it was interpolated. If the store contains totalled data, and interval>currentResolution, then the data will be evenly distributed between the "cells" of the store.

Parameters:

interval - the period of time over which the measurement was taken. Interval duration must a positive integer multiple of store resolution, and the interval must align with the store "cells".

value - the value of the time series over that interval as a JigsawQuantity

Throws:

IllegalArgumentException - if the subinterval is outside the interval declared when the store was constructed

getInstant

public JigsawQuantity getInstant(Date time)

Returns the instantaneous value of the time series at a particular point in time. If interpolation is requested, the value may be spatially and/or temporally interpolated from other data.

Returns:

the instantaneous value

getAverage

public JigsawQuantity getAverage(Interval interval)

Returns the average value of the time series over the interval. Sequence values at either end of the interval are included by weighting their values according to the proportion of their duration that lies in the period of interest.

Returns:

the average value

getMinimum

public JigsawQuantity getMinimum(Interval interval)

Returns the minimum value of the time series over the interval. Sequence values at either end of the interval are included in the comparison if more than 50% of their duration lies within the interval of interest. If exactly 50% of their duration lies within the interval, then the first measurement is omitted and the last measurement is included

Returns:

the minimum value

getMaximum

public JigsawQuantity getMaximum(Interval interval)

Returns the maximum value of the time series over the interval. Sequence values at either end of the interval are included in the comparison if more than 50% of their duration lies within the interval of interest. If exactly 50% of their duration lies within the interval, then the first measurement is omitted and the last measurement is included

Returns:

the maximum value

getTotal

public JigsawQuantity getTotal(Interval interval)

Returns the total value of the sequence over the interval. Weighted contributions from sequence values at either end of the interval are included based on the extent to which they "fall into" the interval. Point measurements are interpreted as if they represented an interval ending at the sample time. If data is missing, the total returned is just the total of the available data; the returned value not scaled up in any way. This ensures that, for example, rainfall for the current day is not overestimated.

Returns:

the total value

totalStore

public Store totalStore(Duration newResolution)

Creates a new store with data totalled to a lower temporal resolution. eg total hourly data into daily data.
The new store's default name is provided by SummaryKind.TOTAL.getName().

Parameters:

newResolution - the resolution of the resulting sequence

Returns:

a new sequence of totals at the requested resolution

totalStore

public Store totalStore(Duration newResolution,
                        String newName)

Creates a new store with data totalled to a lower temporal resolution. eg total hourly data into daily data.

Parameters:

newResolution - the resolution of the resulting sequence

newName - the new name for the store

Returns:

a new sequence of totals at the requested resolution

averageStore

public Store averageStore(Duration newResolution)

Creates a new store with data averaged to a lower temporal resolution. eg average hourly data into daily data. The new store's default name is provided by SummaryKind.AVERAGE.getName(). See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

Returns:

a new sequence of averages at the requested resolution

averageStore

public Store averageStore(Duration newResolution,
                          String newName)

Creates a new store with data averaged to a lower temporal resolution. eg average hourly data into daily data. See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

newName - the new name for the store

Returns:

a new sequence of averages at the requested resolution

minimumStore

public Store minimumStore(Duration newResolution)

Creates a new store containing data summarised by finding the minimum of each subrange. The new store's default name is provided by SummaryKind.MINIMUM.getName(). See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

Returns:

a new sequence of minimums at the requested resolution

minimumStore

public Store minimumStore(Duration newResolution,
                          String newName)

Creates a new store containing data summarised by finding the minimum of each subrange. See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

newName - the new name for the store

Returns:

a new sequence of minimums at the requested resolution

maximumStore

public Store maximumStore(Duration newResolution)

Creates a new store containing data summarised by finding the maximum of each subrange. See totalStore(Duration) for information on how the first data value is handled. The new store's default name is provided by SummaryKind.MAXIMUM.getName().

Parameters:

newResolution - the resolution of the resulting sequence

Returns:

a new sequence of maximums at the requested resolution

maximumStore

public Store maximumStore(Duration newResolution,
                          String newName)

Creates a new store containing data summarised by finding the maximum of each subrange. See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

newName - the new name for the store

Returns:

a new sequence of maximums at the requested resolution

sampleStore

public Store sampleStore(Duration newResolution)

Creates a new store with data sampled to a lower temporal resolution. eg sample hourly data into daily data. Data is sampled at the end of subintervals. The new store's default name is provided by SummaryKind.SAMPLE.getName(). See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

Returns:

a new sequence of samples at the requested resolution

sampleStore

public Store sampleStore(Duration newResolution,
                         String newName)

Creates a new store with data sampled to a lower temporal resolution. eg sample hourly data into daily data. Data is sampled at the end of subintervals. See totalStore(Duration) for information on how the first data value is handled.

Parameters:

newResolution - the resolution of the resulting sequence

newName - the new name for the store

Returns:

a new sequence of samples at the requested resolution

extendStore

public Store extendStore(Interval interval)

Creates a new store at the same resolution as this one but covering a different DateRange.
If the period covered by the two stores overlaps, the new store contains a copy of the data in the overlap. Data is transferred using getInstant() and putInstant().

Parameters:

interval - the interval that the new store covers.

Returns:

the new store.

extendStore

public Store extendStore(Date newEnd)

Creates a new store with a copy of the same data covering a longer period.
The new store's resolution and starting point are the same as this one's. Data is transferred using getInstant() and putInstant().

Parameters:

newEnd - the new end date, later than the current end date;

Returns:

the new store.

Throws:

IllegalArgumentException - if newEnd is earlier or the same as the current end.

getSummaryHistory

public SummaryHistory getSummaryHistory()

Returns the summary history for the data stored in the sequence

Returns:

the composition

getData

public double[] getData()

Creates an array containing the data from the store. You should use getCoverage() to test for the coverage. (Missing values are returned as Double.NaN at present, but this might change.)
Note that the first element of the array corresponds to getStart() and is therefore empty in most cases.

Returns:

the data in a timeseries array

getCoverage

public float[] getCoverage()

Creates an array representing the coverage of the data returned by getData().

Returns:

an array of values ranging from JigsawQuantity.COMPLETE to JigsawQuantity.DEVOID.

getNumberOfValues

public double getNumberOfValues()

Returns the number of data values in the store

Returns:

the number of data values stored. If the data is summarised, this may be fractional