net.degreedays.api.data

Class AverageDataSpec

java.lang.Object

net.degreedays.api.data.DataSpec

net.degreedays.api.data.AverageDataSpec

All Implemented Interfaces:

java.io.Serializable

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

Defines a specification for a set of average data such as 5-year-average degree days.

An AverageDataSpec specifies a set of average degree days in terms of:

• the calculation process used to calculate the dated figures that the averages are derived from (heating or cooling, and the base temperature); and
• its breakdown (which years of data to include in the averaged figures).

Example AverageDataSpec code:

Here's how you could specify 10-year average heating degree days with a base temperature of 70°F:

 AverageDataSpec averageDataSpec = DataSpec.average(
     Calculation.heatingDegreeDays(Temperature.fahrenheit(70)),
     AverageBreakdown.fullYears(Period.latestValues(10)));
 

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

 DegreeDaysApi api = new DegreeDaysApi(new AccountKey(yourStringAccountKey),
     new SecurityKey(yourStringSecurityKey));
 LocationDataRequest request = new LocationDataRequest(
     Location.postalCode("02630", "US"),
     new DataSpecs(averageDataSpec));
 LocationDataResponse response = api.dataApi().getLocationData(request);
 AverageDataSet averageData = response.dataSets().getAverage(averageDataSpec);
 for (int month = 1; month <= 12; month++) {
     System.out.println("Average HDD for month " + month + ": " +
         averageData.monthlyAverage(month).value());
 }
 System.out.println("Annual average HDD: " +
     averageData.annualAverage().value());
 

To request multiple sets of average data with different calculation processes (e.g. multiple different base temperatures) and/or different breakdowns, simply put multiple AverageDataSpec objects into the DataSpecs object that you pass into your LocationDataRequest.

See Also:

DatedDataSpec, TimeSeriesDataSpec

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
AverageDataSpec(Calculation calculation, AverageBreakdown averageBreakdown) Constructs an AverageDataSpec object with the specified Calculation and AverageBreakdown.

Method Summary

Modifier and Type	Method and Description
AverageBreakdown	breakdown() Returns the non-null AverageBreakdown that defines the way in which the degree days should be broken down and the period in time that they should cover.
Calculation	calculation() Returns the non-null Calculation object that defines the way in which the degree days should be calculated in terms of their base temperature and whether they should be heating degree days or cooling degree days.
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

AverageDataSpec

public AverageDataSpec(Calculation calculation,
                       AverageBreakdown averageBreakdown)

Constructs an AverageDataSpec object with the specified Calculation and AverageBreakdown.

Parameters:

calculation - defines the way in which the degree days should be calculated in terms of their base temperature and whether they should be heating degree days or cooling degree days. Cannot be null.

averageBreakdown - defines the way in which the data should be broken down and the period that it should cover. Cannot be null.

Throws:

java.lang.NullPointerException - if calculation or averageBreakdown is null.

Method Detail

calculation

public Calculation calculation()

Returns the non-null Calculation object that defines the way in which the degree days should be calculated in terms of their base temperature and whether they should be heating degree days or cooling degree days.

breakdown

public AverageBreakdown breakdown()

Returns the non-null AverageBreakdown that defines the way in which the degree days should be broken down and the period in time that they should cover.

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