net.degreedays.api.regression

Class InputData

java.lang.Object

net.degreedays.api.regression.InputData

All Implemented Interfaces:

java.io.Serializable

public final class InputData
extends java.lang.Object
implements java.io.Serializable

Defines the energy data (and any extra-predictor data) that the API should run regressions against.

An InputData object is essentially a chronologically-ordered set of InputPeriod objects, with each one specifying a dated period and the energy usage (and optionally any extra-predictor figures) for that period.

The regression API docs on our website have more information and code samples.

Requirements of the InputPeriod objects that make up an InputData object

Input periods must be consecutively ordered, and cannot overlap. Gaps between input periods are OK though.

If any input periods have extra-predictor figures, then all input periods must have figures for the same extra-predictor keys.

The minimum number of input periods required is:

 minimumNumberOfInputPeriods = 3 + numberOfExtraPredictors
 

Though this is just a bare minimum – you cannot hope for good regression results unless you have considerably more input periods than this. We recommend at least:

 recommendedMinimumNumberOfInputPeriods = 10 + numberOfExtraPredictors
 

InputData allows a maximum of 1096 input periods. This is enough to cover 3 years of daily data (with one of those years being a leap year).

Since:

1.4

See Also:

www.degreedays.net/api/regression for more information and code samples.

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
InputData(InputPeriod[] inputPeriods) Constructs an InputData object containing the specified InputPeriod objects.
InputData(InputPeriod firstInputPeriod, InputPeriod... additionalInputPeriods) Constructs an InputData object containing the specified InputPeriod objects.
InputData(java.lang.Iterable<InputPeriod> inputPeriods) Constructs an InputData object containing the specified InputPeriod objects.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o) Returns true if o is an InputData object containing equal InputPeriod objects (same dates, same usage values, and same extra-predictor keys and figures).
java.util.Set<java.lang.String>	extraPredictorKeys() Returns the non-null, possibly-empty, immutable set of extra-predictor keys that this InputData (and each InputPeriod within it) has extra-predictor figures for.
DayRange	fullRange() Returns a non-null DayRange indicating the total period of time covered by this InputData object (including any gaps between its input periods).
InputPeriod[]	getPeriods() Returns a non-null, non-empty, chronologically-ordered array of the InputPeriod objects that make up this InputData.
int	hashCode() Overridden to ensure consistency with equals.
boolean	isContiguous() Returns true if each contained InputPeriod starts the day after the previous InputPeriod ended (i.e. no gaps); false otherwise.
InputPeriod	periodAt(int index) Returns the InputPeriod at the specified index, which must be between 0 (inclusive) and periodCount() (exclusive).
int	periodCount() Returns the number of InputPeriod objects held by this InputData object.
java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

InputData

public InputData(InputPeriod[] inputPeriods)

Constructs an InputData object containing the specified InputPeriod objects.

Although the immutable InputPeriod objects contained within the inputPeriods array will be stored inside this InputData object, the array itself will neither be stored nor modified. So you can continue using the inputPeriods array without concern for side effects.

Parameters:

inputPeriods - the InputPeriod objects that you want this InputData to contain. Cannot contain any null values, and must satisfy the specified requirements.

Throws:

java.lang.NullPointerException - if inputPeriods is null, or if it contains a null value.

java.lang.IllegalArgumentException - if inputPeriods does not satisfy the specified requirements.

See Also:

InputData(InputPeriod, InputPeriod...), InputData(Iterable)

InputData

public InputData(InputPeriod firstInputPeriod,
                 InputPeriod... additionalInputPeriods)

Constructs an InputData object containing the specified InputPeriod objects.

Parameters:

firstInputPeriod - the first InputPeriod object that you want this InputData to contain. Cannot be null.

additionalInputPeriods - additional InputPeriod objects that you want this InputData to contain. Cannot contain any null values, and, together with firstInputPeriod, must satisfy the specified requirements.

Throws:

java.lang.NullPointerException - if firstInputPeriod or additionalInputPeriods is null, or if additionalInputPeriods contains a null value.

java.lang.IllegalArgumentException - if the input periods passed in do not satisfy the specified requirements.

See Also:

InputData(InputPeriod[]), InputData(Iterable)

InputData

public InputData(java.lang.Iterable<InputPeriod> inputPeriods)

Constructs an InputData object containing the specified InputPeriod objects.

Although the immutable InputPeriod objects contained within the inputPeriods Iterable will be stored inside this InputData object, the Iterable itself will neither be stored nor modified. So you can continue using inputPeriods without concern for side effects.

Parameters:

inputPeriods - the Iterable of InputPeriod objects that you want this InputData to contain. Cannot contain any null values, and must satisfy the specified requirements.

Throws:

java.lang.NullPointerException - if inputPeriods is null, or if it contains a null value.

java.lang.IllegalArgumentException - if inputPeriods does not satisfy the specified requirements.

See Also:

InputData(InputPeriod[]), InputData(InputPeriod, InputPeriod...)

Method Detail

periodCount

public int periodCount()

Returns the number of InputPeriod objects held by this InputData object.

See Also:

periodAt(int), getPeriods()

periodAt

public InputPeriod periodAt(int index)

Returns the InputPeriod at the specified index, which must be between 0 (inclusive) and periodCount() (exclusive).

Parameters:

index - a number, greater than or equal to zero, and less than periodCount(), indicating which InputPeriod should be returned.

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than or equal to periodCount().

getPeriods

public InputPeriod[] getPeriods()

Returns a non-null, non-empty, chronologically-ordered array of the InputPeriod objects that make up this InputData.

The returned array can be modified freely without affecting the immutability of this InputData or the arrays returned by past, concurrent, or future calls to this method. This is possible because a new array is generated with each call to this method.

See Also:

periodAt(int), periodCount()

fullRange

public DayRange fullRange()

Returns a non-null DayRange indicating the total period of time covered by this InputData object (including any gaps between its input periods).

isContiguous

public boolean isContiguous()

Returns true if each contained InputPeriod starts the day after the previous InputPeriod ended (i.e. no gaps); false otherwise.

extraPredictorKeys

public java.util.Set<java.lang.String> extraPredictorKeys()

Returns the non-null, possibly-empty, immutable set of extra-predictor keys that this InputData (and each InputPeriod within it) has extra-predictor figures for.

equals

public boolean equals(java.lang.Object o)

Returns true if o is an InputData object containing equal InputPeriod objects (same dates, same usage values, and same extra-predictor keys and figures).

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class java.lang.Object

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