net.degreedays.api.data

Class DatedBreakdown

java.lang.Object

net.degreedays.api.data.Breakdown

net.degreedays.api.data.DatedBreakdown

Direct Known Subclasses:

CustomBreakdown, DailyBreakdown, MonthlyBreakdown, WeeklyBreakdown, YearlyBreakdown

public abstract class DatedBreakdown
extends Breakdown

Defines how a set of dated degree days should be broken down, including the period in time they should cover.

This is the abstract superclass of the types of Breakdown that can be taken by a DatedDataSpec.

To create a DatedBreakdown object you can use the static factory methods of this class. For example:

 DatedBreakdown dailyBreakdownOverLast30Days = 
     DatedBreakdown.daily(Period.latestValues(30));
 
 DatedBreakdown weeklyBreakdownFor2010WithWeeksStartingOnMonday = 
     DatedBreakdown.weekly(
         Period.dayRange(Day.of(2010, 1, 1).to(2010, 12, 31)),
         DayOfWeek.MONDAY);
 
 DatedBreakdown monthlyBreakdownOverLast12Months = 
     DatedBreakdown.monthly(Period.latestValues(12));
 
 DatedBreakdown yearlyBreakdownOverLast5Years =
     DatedBreakdown.yearly(Period.latestValues(5));
 

As you can see from the above examples, defining the Period is an important part of defining a DatedBreakdown. See that class for more information on the relevant options.

See Also:

AverageBreakdown

This abstract class is not designed to be extended by third-party code, which is why it does not have an accessible constructor.

All concrete subclasses of this abstract class are immutable. You can safely reuse them and call them from multiple threads at once.

Method Summary

Modifier and Type	Method and Description
boolean	allowPartialLatest() Returns true if the latest day range can be partially filled (i.e. incomplete); false otherwise (the default case).
static CustomBreakdown	custom(DayRanges dayRanges) Returns a non-null CustomBreakdown object that specifies degree days broken down to match the DayRanges passed in.
static DailyBreakdown	daily(Period period) Returns a non-null DailyBreakdown object that specifies daily degree days covering the specified period in time.
static MonthlyBreakdown	monthly(Period period) Returns a non-null MonthlyBreakdown object that specifies monthly degree days covering the specified period in time and broken down according to regular calendar months.
static MonthlyBreakdown	monthly(Period period, StartOfMonth startOfMonth) Returns a non-null MonthlyBreakdown object that specifies monthly degree days covering the specified period in time, with each "month" starting on the specified day of the month.
abstract MaybeEmptyDayRanges	toDayRanges(DayRange availableDataRange) Returns the breakdown in terms of the day ranges that would constitute it given source data covering availableDataRange.
static WeeklyBreakdown	weekly(Period period, DayOfWeek firstDayOfWeek) Returns a non-null WeeklyBreakdown object that specifies weekly degree days covering the specified period in time, with each "week" starting on the specified day of the week.
static YearlyBreakdown	yearly(Period period) Returns a non-null YearlyBreakdown object that specifies yearly degree days covering the specified period in time and broken down according to regular calendar years.
static YearlyBreakdown	yearly(Period period, StartOfYear startOfYear) Returns a non-null YearlyBreakdown object that specifies yearly degree days covering the specified period in time, with each "year" starting on the specified day of the year.

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

equals, getFullRangeOrNull, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

daily

public static DailyBreakdown daily(Period period)

Returns a non-null DailyBreakdown object that specifies daily degree days covering the specified period in time.

Parameters:

period - the period in time that the daily breakdown should cover. Cannot be null.

Throws:

java.lang.NullPointerException - if period is null.

weekly

public static WeeklyBreakdown weekly(Period period,
                                     DayOfWeek firstDayOfWeek)

Returns a non-null WeeklyBreakdown object that specifies weekly degree days covering the specified period in time, with each "week" starting on the specified day of the week.

To avoid the potential for confusion, you must explicitly specify the day of the week that you want each "week" to start on. For example, if a "week" should run from Monday to Sunday (inclusive), specify the firstDayOfWeek parameter as DayOfWeek.MONDAY.

Parameters:

period - the period in time that the weekly breakdown should cover. Cannot be null.

firstDayOfWeek - indicates which day should be taken as the first of each week. Cannot be null.

Throws:

java.lang.NullPointerException - if period or firstDayOfWeek is null.

monthly

public static MonthlyBreakdown monthly(Period period,
                                       StartOfMonth startOfMonth)

Returns a non-null MonthlyBreakdown object that specifies monthly degree days covering the specified period in time, with each "month" starting on the specified day of the month.

Parameters:

period - the period in time that the monthly breakdown should cover. Cannot be null.

startOfMonth - specifying which day (between 1 and 28 inclusive) should be taken as the first of each "month". Pass StartOfMonth.of(1) to specify regular calendar months. Cannot be null.

Throws:

java.lang.NullPointerException - if period or startOfMonth is null.

monthly

public static MonthlyBreakdown monthly(Period period)

Returns a non-null MonthlyBreakdown object that specifies monthly degree days covering the specified period in time and broken down according to regular calendar months.

This is a shortcut version of this method that specifies the first day of the month as the startOfMonth parameter.

Parameters:

period - the period in time that the monthly breakdown should cover. Cannot be null.

Throws:

java.lang.NullPointerException - if period is null.

yearly

public static YearlyBreakdown yearly(Period period,
                                     StartOfYear startOfYear)

Returns a non-null YearlyBreakdown object that specifies yearly degree days covering the specified period in time, with each "year" starting on the specified day of the year.

Parameters:

period - the period in time that the yearly breakdown should cover. Cannot be null.

startOfYear - specifying which day of the year (month and day of the month) should be taken as the first of each "year". Pass StartOfYear.of(1, 1) to specify regular calendar years. Cannot be null.

Throws:

java.lang.NullPointerException - if period or startOfYear is null.

yearly

public static YearlyBreakdown yearly(Period period)

Returns a non-null YearlyBreakdown object that specifies yearly degree days covering the specified period in time and broken down according to regular calendar years.

This is a shortcut version of this method that specifies January the first as the startOfYear parameter.

Parameters:

period - the period in time that the yearly breakdown should cover. Cannot be null.

Throws:

java.lang.NullPointerException - if period is null.

custom

public static CustomBreakdown custom(DayRanges dayRanges)

Returns a non-null CustomBreakdown object that specifies degree days broken down to match the DayRanges passed in.

Parameters:

dayRanges - specifying the dates that each degree-day figure should cover (typically matching the dates of your energy-usage records). Cannot be null.

Throws:

java.lang.NullPointerException - if dayRanges is null.

Since:

1.2

allowPartialLatest

public final boolean allowPartialLatest()

Returns true if the latest day range can be partially filled (i.e. incomplete); false otherwise (the default case).

When specifying time-series data (like hourly temperature data), you can specify a breakdown with this allowPartialLatest property set to true, to tell the API to include values for the current day so far. For example:

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

If you requested the above-specified hourly temperature data at, say, 11:42 on any given day, you could expect it to include values for 00:00, 01:00, 02:00 through to 11:00 on that day (bearing in mind that some stations are slower to report than others so you won't always get the absolute latest figures).

Please note that the most recent time-series data can be a little volatile, as weather stations sometimes send multiple reports for the same time, some delayed, and some marked as corrections for reports they sent earlier. Our system generates time-series data using all the relevant reports that each weather station has sent, but the generated figures may change if delayed or corrected reports come through later. If you are storing partial-latest time-series data we suggest you overwrite it later with figures generated after the day has completed and any delayed/corrected reports have had time to filter through.

This allowPartialLatest property exists mainly for time-series data, but you can also set it to true on a breakdown for degree days, to specify that the data can include a value for the latest partial week/month/year. For example:

 DatedDataSpec monthlyHddIncludingPartialLatest = DataSpec.dated(
     Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
     DatedBreakdown.monthly(Period.latestValues(12))
         .withAllowPartialLatest(true));
 

If you requested the above-specified monthly degree-day data on, say, June 22nd, you could expect the last of the 12 values returned to cover from the start of June 1st through to the end of June 21st (assuming a good weather station with frequent reporting and minimal delays). If you left allowPartialLatest with its default value of false, the last of the 12 values returned would be for the full month of May (i.e. from the start of May 1st to the end of May 31st), as the monthly figure for June wouldn't become available until June ended.

Unlike for time-series data, this property will never cause degree days to be calculated for partial days. So for degree days this property will only make a difference on weekly, monthly, yearly, and custom breakdowns with day ranges covering multiple days.

Any partial-latest day range will always start on the usual day (i.e. it will never be cut short at the start), it's only the end that can be cut short. This is true for both degree days and time-series data.

To create a DatedBreakdown with this allowPartialLatest property set to true, use the withAllowPartialLatest methods listed below under "See Also".

Since:

1.3

See Also:

DailyBreakdown.withAllowPartialLatest(boolean), WeeklyBreakdown.withAllowPartialLatest(boolean), MonthlyBreakdown.withAllowPartialLatest(boolean), YearlyBreakdown.withAllowPartialLatest(boolean), CustomBreakdown.withAllowPartialLatest(boolean)

toDayRanges

public abstract MaybeEmptyDayRanges toDayRanges(DayRange availableDataRange)

Returns the breakdown in terms of the day ranges that would constitute it given source data covering availableDataRange.

If you call fullRangeOrNull() on the return value, you'll get the same result that you'd get by calling getFullRangeOrNull(availableDataRange) on this object. Essentially this method is a more detailed version of getFullRangeOrNull that makes sense for dated breakdowns, which translate to real ranges of days on a calendar (unlike average breakdowns which are broken down into months of an "average year" rather than applying to a real calendar).

Parameters:

availableDataRange - the range of temperature data available (or the available range of daily degree-day data if summing daily degree days into a different breakdown). Cannot be null.

Throws:

java.lang.NullPointerException - if availableDataRange is null.