net.degreedays.api.regression

Class InputPeriod

java.lang.Object

net.degreedays.api.regression.InputPeriod

All Implemented Interfaces:

java.io.Serializable

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

Defines a dated period with its energy usage and any extra-predictor figures. A set of InputPeriod items together forms the InputData required for every RegressionRequest.

To create a simple InputPeriod just use the InputPeriod(DayRange, double) constructor. If, then, you also wish to add extra-predictor figures, use the withExtraPredictor(java.lang.String, double) method.

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

Since:

1.4

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
InputPeriod(DayRange dayRange, double usage) Constructs an InputPeriod covering the specified DayRange and with the specified energy usage.

Method Summary

Modifier and Type	Method and Description
DayRange	dayRange() Returns the non-null period of time covered by this InputPeriod.
boolean	equals(java.lang.Object o) Returns true if o is an InputPeriod with the same dayRange and usage as this, and with the same extra-predictor keys and values (the order of the keys is not important for this).
java.util.Set<java.lang.String>	extraPredictorKeys() Returns the non-null, possibly-empty, immutable set of extra-predictor keys that this InputPeriod has extra-predictor figures for.
double	getExtraPredictor(java.lang.String key) Returns the double value of the extra predictor with the specified string key.
int	hashCode() Overridden to ensure consistency with equals.
java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
double	usage() Returns the energy usage over this InputPeriod.
InputPeriod	withExtraPredictor(java.lang.String key, double value) Returns a new InputPeriod based on this but also including an extra predictor with the specified key and value.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

InputPeriod

public InputPeriod(DayRange dayRange,
                   double usage)

Constructs an InputPeriod covering the specified DayRange and with the specified energy usage.

Parameters:

dayRange - the non-null period of time covered.

usage - the energy usage over the specified dayRange.

Throws:

java.lang.NullPointerException - if dayRange is null.

java.lang.IllegalArgumentException - if usage is NaN or infinity.

Method Detail

dayRange

public DayRange dayRange()

Returns the non-null period of time covered by this InputPeriod.

usage

public double usage()

Returns the energy usage over this InputPeriod.

extraPredictorKeys

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

Returns the non-null, possibly-empty, immutable set of extra-predictor keys that this InputPeriod has extra-predictor figures for.

See Also:

getExtraPredictor(java.lang.String), withExtraPredictor(java.lang.String, double)

getExtraPredictor

public double getExtraPredictor(java.lang.String key)

Returns the double value of the extra predictor with the specified string key.

Parameters:

key - a non-null, non-empty string key.

Throws:

java.lang.NullPointerException - if key is null.

java.lang.IllegalArgumentException - if key isn't one of the extra-predictor keys stored in this object.

See Also:

extraPredictorKeys(), withExtraPredictor(java.lang.String, double)

withExtraPredictor

public InputPeriod withExtraPredictor(java.lang.String key,
                                      double value)

Returns a new InputPeriod based on this but also including an extra predictor with the specified key and value.

Every InputPeriod in a set of InputData must have values for the same extra-predictor keys. So, for example, if you include an "occupancy" extra-predictor figure in one InputPeriod in your InputData, you must include an "occupancy" figure in all of them.

There's some sample code showing how to use this method in the regression API docs on our website, and also there's some additional practical information on specifying and using extra predictors in the docs for our website regression tool (which itself uses the API internally).

Parameters:

key - the extra-predictor key used to identify this extra predictor. Cannot be null, must match the regular expression [-_.a-zA-Z0-9]{1,60}, and cannot be "baseload", "heatingDegreeDays", or "coolingDegreeDays".

value - the value of the extra predictor over the time period covered by this InputPeriod's dayRange().

Throws:

java.lang.NullPointerException - if key is null.

java.lang.IllegalArgumentException - if key does not match the specification detailed above, or if value is NaN or infinite.

java.lang.IllegalStateException - if this InputPeriod already has 2 extra predictors (the maximum allowed).

equals

public boolean equals(java.lang.Object o)

Returns true if o is an InputPeriod with the same dayRange and usage as this, and with the same extra-predictor keys and values (the order of the keys is not important for this).

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