Click or drag to resize

TimeSeriesDataSpec Class

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

Namespace:  DegreeDays.Api.Data
Assembly:  DegreeDays (in DegreeDays.dll) Version: 1.3
Syntax
public sealed class TimeSeriesDataSpec : DataSpec

The TimeSeriesDataSpec type exposes the following members.

Constructors
  NameDescription
Public methodTimeSeriesDataSpec(TimeSeriesCalculation, DatedBreakdown)
Constructs a TimeSeriesDataSpec object with the specified TimeSeriesCalculation and DatedBreakdown.
Top
Properties
  NameDescription
Public propertyBreakdown
Gets the non-null DatedBreakdown object that defines the period of time that the time-series data should cover (read more about how this works in the remarks for TimeSeriesDataSpec).
Public propertyCalculation
Gets 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.
Top
Methods
  NameDescription
Public methodEquals(Object)
Two DataSpec objects are equal if they have the same class and the same configuration.
(Inherited from DataSpec.)
Public methodGetHashCode
Overridden to ensure consistency with Equals.
(Inherited from DataSpec.)
Public methodToString
Returns a non-null, non-empty string representation of this instance for logging and debugging purposes.
(Overrides ObjectToString.)
Top
Remarks

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

  • the calculation process used to calculate the time-series figures (see the remarks for TimeSeriesCalculation to 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);
foreach (TimeSeriesDataValue v in hourlyData.Values) {
    Console.WriteLine(v.DateTimeOffset + ": " + 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 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 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).

Thread Safety
Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.
Version History
VersionDescription
1.2 This was added in version 1.2.
See Also