net.degreedays.api.data

Class TimeSeriesDataSpec

java.lang.Object

net.degreedays.api.data.DataSpec

net.degreedays.api.data.TimeSeriesDataSpec

All Implemented Interfaces:

java.io.Serializable

public final class TimeSeriesDataSpec
extends DataSpec
implements java.io.Serializable

Defines a specification for a set of time-series data such as hourly temperature data covering a specific period in time.

A TimeSeriesDataSpec specifies a set of time-series data in terms of:

• the calculation process used to calculate the time-series figures (find out why time-series data is "calculated"); and
• a breakdown that determines the period in time that the time-series data should cover (more on this below).

Example TimeSeriesDataSpec code:

Here's how you could specify hourly temperature data, in Fahrenheit, covering the last 30 days:

 TimeSeriesDataSpec timeSeriesDataSpec = DataSpec.timeSeries(
     TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.FAHRENHEIT),
     DatedBreakdown.daily(Period.latestValues(30)));
 

You could then send that TimeSeriesDataSpec to the API as part of a LocationDataRequest, and get a response containing a TimeSeriesDataSet back:

 DegreeDaysApi api = new DegreeDaysApi(new AccountKey(yourStringAccountKey),
     new SecurityKey(yourStringSecurityKey));
 LocationDataRequest request = new LocationDataRequest(
     Location.postalCode("02630", "US"),
     new DataSpecs(timeSeriesDataSpec));
 LocationDataResponse response = api.dataApi().getLocationData(request);
 TimeSeriesDataSet hourlyData = 
     response.dataSets().getTimeSeries(timeSeriesDataSpec);
 for (TimeSeriesDataValue v : hourlyData.getValues()) {
     System.out.println(v.offsetDayTime() + ": " + v.value());
 }
 

To include figures for the current day (as opposed to the default behaviour of covering full days only), you can specify a DatedBreakdown with its DatedBreakdown.allowPartialLatest() property set to true. For example:

 TimeSeriesDataSpec hourlyTempsIncludingToday = DataSpec.timeSeries(
     TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.FAHRENHEIT),
     DatedBreakdown.daily(Period.latestValues(31))
         .withAllowPartialLatest(true));
 

The docs for DatedBreakdown.allowPartialLatest() explain more, including an important caution that the latest figures can be volatile, and, if stored, should be overwritten later when the weather stations have had time to send any delayed or corrected weather reports (which many weather stations send quite often).

Why does TimeSeriesDataSpec take a DatedBreakdown?

It might seem strange that TimeSeriesDataSpec takes a DatedBreakdown in the same way that DatedDataSpec (for degree days) does, because hourly data is broken down hourly, not by days, weeks, or months. However, it works this way to give you flexibility in how you specify the time-period that the time-series data should cover, and to make it easier for you to get time-series data that lines up with your degree days.

With a DatedBreakdown you can easily specify that you want hourly data covering e.g. the last 30 days, or the last 12 full calendar months, or the last 5 full calendar years, just like you do when you are using a DatedBreakdown to specify the degree days you want. You can take full advantage of widening rules if they make things more convenient for you. The data will always come back as hourly figures. Essentially a daily, weekly, monthly, or yearly breakdown in a TimeSeriesDataSpec is used only to determine the overall period of time that the time-series data should cover.

Custom breakdowns deserve a special note, however... If you create a TimeSeriesDataSpec with a custom breakdown (made up of your own custom-specified DayRanges), then your time-series data will cover only the day ranges you specify. If you specify day ranges with gaps between them, then your time-series data will have gaps too (just as your degree days would if you used the same breakdown for them). This is rather contrary to our general ethos of providing continuous data with no gaps, but it will only happen if you specifically request it (by specifying a custom breakdown with gaps between its day ranges).

Since:

1.2

See Also:

TimeSeriesDataSet, DatedDataSpec, AverageDataSpec

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.

Constructor Summary

Constructors

Constructor and Description
TimeSeriesDataSpec(TimeSeriesCalculation timeSeriesCalculation, DatedBreakdown datedBreakdown) Constructs a TimeSeriesDataSpec object with the specified TimeSeriesCalculation and DatedBreakdown.

Method Summary

Modifier and Type	Method and Description
DatedBreakdown	breakdown() Returns the non-null DatedBreakdown object that defines the period of time that the time-series data should cover (read more on how this works).
TimeSeriesCalculation	calculation() Returns the non-null TimeSeriesCalculation object that defines how the time-series data should be calculated.
java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

Methods inherited from class net.degreedays.api.data.DataSpec

average, dated, equals, hashCode, timeSeries

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TimeSeriesDataSpec

public TimeSeriesDataSpec(TimeSeriesCalculation timeSeriesCalculation,
                          DatedBreakdown datedBreakdown)

Constructs a TimeSeriesDataSpec object with the specified TimeSeriesCalculation and DatedBreakdown.

Parameters:

timeSeriesCalculation - defines how the time-series data should be calculated (e.g. specifying hourly temperature data, in Celsius). Cannot be null.

datedBreakdown - defines the period of time that the time-series data should cover (read more on how this works). Cannot be null.

Throws:

java.lang.NullPointerException - if timeSeriesCalculation or datedBreakdown is null.

Method Detail

calculation

public TimeSeriesCalculation calculation()

Returns the non-null TimeSeriesCalculation object that defines how the time-series data should be calculated. For example it could specify hourly temperature data, in Celsius.

breakdown

public DatedBreakdown breakdown()

Returns the non-null DatedBreakdown object that defines the period of time that the time-series data should cover (read more on how this works).

toString

public java.lang.String toString()

Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

The exact details of the representation are unspecified and subject to change.

Overrides:

toString in class java.lang.Object