net.degreedays.api.regression

Class RegressionTestPlan.Builder

java.lang.Object

net.degreedays.api.regression.RegressionTestPlan.Builder

Enclosing class:

RegressionTestPlan

public static final class RegressionTestPlan.Builder
extends java.lang.Object

For creating a RegressionTestPlan object that defines how the API should test regressions against the InputData you provide it.

Read the Javadoc below for details on everything you can configure, and see www.degreedays.net/api/regression for more information and code samples.

Since:

1.4

Instances of this builder class are designed for single-threaded use only. It's fine to create and use instances in multiple concurrent threads, but, in the absence of external synchronization, the use of each individual builder instance should be restricted to one thread only.

Constructor Summary

Constructors

Constructor and Description
Builder(TemperatureUnit temperatureUnit) Constructs a RegressionTestPlan.Builder with the specified TemperatureUnit (to be used for degree days) and default values for everything else.

Method Summary

Modifier and Type	Method and Description
RegressionTestPlan.Builder	addExtraPredictorSpec(java.lang.String extraPredictorKey, ExtraPredictorSpec extraPredictorSpec) Adds a specification for an extra predictor included in the InputData sent to the API, to help the API test and rank the regressions that include data for that extra predictor.
RegressionTestPlan.Builder	addRequestedRegressionSpec(RegressionSpec requestedRegressionSpec) Adds a specification for a regression that you want to receive in the response from the API.
RegressionTestPlan	build() Creates a RegressionTestPlan with the configuration currently held by this Builder.
RegressionTestPlan.Builder	setCustomTestCoolingBaseTemperatures(double... coolingBaseTemperatures) Sets custom base temperatures to be used for the CDD in regressions tested by the API, assuming the temperature unit (Celsius or Fahrenheit) this Builder was constructed with.
RegressionTestPlan.Builder	setCustomTestCoolingBaseTemperatures(java.lang.Iterable<Temperature> coolingBaseTemperatures) Sets custom base temperatures to be used for the CDD in regressions tested by the API.
RegressionTestPlan.Builder	setCustomTestCoolingBaseTemperatures(Temperature[] coolingBaseTemperatures) Sets custom base temperatures to be used for the CDD in regressions tested by the API.
RegressionTestPlan.Builder	setCustomTestHeatingBaseTemperatures(double... heatingBaseTemperatures) Sets custom base temperatures to be used for the HDD in regressions tested by the API, assuming the temperature unit (Celsius or Fahrenheit) this Builder was constructed with.
RegressionTestPlan.Builder	setCustomTestHeatingBaseTemperatures(java.lang.Iterable<Temperature> heatingBaseTemperatures) Sets custom base temperatures to be used for the HDD in regressions tested by the API.
RegressionTestPlan.Builder	setCustomTestHeatingBaseTemperatures(Temperature[] heatingBaseTemperatures) Sets custom base temperatures to be used for the HDD in regressions tested by the API.
RegressionTestPlan.Builder	setDayNormalization(DayNormalization dayNormalization) Sets the DayNormalization to be used in the regression process.
RegressionTestPlan.Builder	setExtraPredictorSpecs(java.util.Map<java.lang.String,ExtraPredictorSpec> extraPredictorSpecs) Sets the specifications for the extra predictors included in the InputData sent to the API, to help the API test and rank the regressions that include data for those extra predictors.
RegressionTestPlan.Builder	setRequestedRegressionSpecs(java.lang.Iterable<RegressionSpec> requestedRegressionSpecs) Sets specifications for up to 60 regressions that you want to receive in the response from the API.
RegressionTestPlan.Builder	setRequestedRegressionSpecs(RegressionSpec... requestedRegressionSpecs) Sets specifications for up to 60 regressions that you want to receive in the response from the API.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder(TemperatureUnit temperatureUnit)

Constructs a RegressionTestPlan.Builder with the specified TemperatureUnit (to be used for degree days) and default values for everything else.

Parameters:

temperatureUnit - specifying whether Celsius-based or Fahrenheit-based degree days should be used in regressions. Cannot be null.

Throws:

java.lang.NullPointerException - if temperatureUnit is null.

Method Detail

setDayNormalization

public RegressionTestPlan.Builder setDayNormalization(DayNormalization dayNormalization)

Sets the DayNormalization to be used in the regression process. By default this will be DayNormalization.WEIGHTED, which is the recommended option.

Parameters:

dayNormalization - the DayNormalization to be used in the regression process. Cannot be null.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if dayNormalization is null.

setCustomTestHeatingBaseTemperatures

public RegressionTestPlan.Builder setCustomTestHeatingBaseTemperatures(java.lang.Iterable<Temperature> heatingBaseTemperatures)

Sets custom base temperatures to be used for the HDD in regressions tested by the API.

By default this is not set at all (as if it had been called with null), and the API will choose the base temperatures of the HDD it tests automatically.

If an empty Iterable is passed in, no HDD will be tested unless setRequestedRegressionSpecs(RegressionSpec...) is used to specify regressions with HDD.

This method will accept up to 120 (inclusive) custom test heating base temperatures, but, if you use all 120, you will get an exception on build() unless you have set the custom test cooling base temperatures as empty. At build() time you can have up to 120 custom base temperatures in total. If you don't set any custom test cooling base temperatures (leaving the API to choose the test cooling base temperatures automatically), at build() time you will be allowed up to 60 custom test heating base temperatures.

When calling this method you may want to use Temperature.celsiusRange(double, double, double) or Temperature.fahrenheitRange(double, double, double) to create an evenly-spaced set of Temperature objects covering your desired temperature range.

The Temperature objects will be copied out of the Iterable passed in, so you are free to modify the Iterable after calling this method without such modifications affecting the state of this Builder.

See www.degreedays.net/api/regression#custom-base-temperatures for example code.

Parameters:

heatingBaseTemperatures - the base temperatures to be used for the HDD in regressions tested by the API. Cannot contain null, cannot have more than 120 temperatures, and must contain only temperatures with the same unit (Celsius or Fahrenheit) this Builder was constructed with.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if heatingBaseTemperatures contains null.

java.lang.IllegalArgumentException - if heatingBaseTemperatures contains more than 120 temperatures, or contains any temperatures with a unit that isn't the one this Builder was constructed with.

setCustomTestHeatingBaseTemperatures

public RegressionTestPlan.Builder setCustomTestHeatingBaseTemperatures(Temperature[] heatingBaseTemperatures)

Sets custom base temperatures to be used for the HDD in regressions tested by the API.

By default this is not set at all (as if it had been called with null), and the API will choose the base temperatures of the HDD it tests automatically.

If an empty array is passed in, no HDD will be tested unless setRequestedRegressionSpecs(RegressionSpec...) is used to specify regressions with HDD.

This method will accept up to 120 (inclusive) custom test heating base temperatures, but, if you use all 120, you will get an exception on build() unless you have set the custom test cooling base temperatures as empty. At build() time you can have up to 120 custom base temperatures in total. If you don't set any custom test cooling base temperatures (leaving the API to choose the test cooling base temperatures automatically), at build() time you will be allowed up to 60 custom test heating base temperatures.

The Temperature objects will be copied out of the array passed in, so you are free to modify the array after calling this method without such modifications affecting the state of this Builder.

See www.degreedays.net/api/regression#custom-base-temperatures for example code.

Parameters:

heatingBaseTemperatures - the base temperatures to be used for the HDD in regressions tested by the API. Cannot contain null, cannot have more than 120 temperatures, and must contain only temperatures with the same unit (Celsius or Fahrenheit) this Builder was constructed with.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if heatingBaseTemperatures contains null.

java.lang.IllegalArgumentException - if heatingBaseTemperatures contains more than 120 temperatures, or contains any temperatures with a unit that isn't the one this Builder was constructed with.

setCustomTestHeatingBaseTemperatures

public RegressionTestPlan.Builder setCustomTestHeatingBaseTemperatures(double... heatingBaseTemperatures)

Sets custom base temperatures to be used for the HDD in regressions tested by the API, assuming the temperature unit (Celsius or Fahrenheit) this Builder was constructed with.

By default this is not set at all (as if it had been called with null), and the API will choose the base temperatures of the HDD it tests automatically.

If this is called with no arguments, like builder.setCustomTestHeatingBaseTemperatures(), then no HDD will be tested unless setRequestedRegressionSpecs(RegressionSpec...) is used to specify regressions with HDD.

This method will accept up to 120 (inclusive) custom test heating base temperatures, but, if you use all 120, you will get an exception on build() unless you have set the custom test cooling base temperatures as empty. At build() time you can have up to 120 custom base temperatures in total. If you don't set any custom test cooling base temperatures (leaving the API to choose the test cooling base temperatures automatically), at build() time you will be allowed up to 60 custom test heating base temperatures.

When calling this method remember that the values passed in are converted to Temperature objects, which means they are rounded to the nearest 0.1 degrees and have maximum and minimum allowed values that depend on the temperature unit this Builder was constructed with. See Temperature.celsius(double) or Temperature.fahrenheit(double) for more.

See www.degreedays.net/api/regression#custom-base-temperatures for example code.

Parameters:

heatingBaseTemperatures - the base temperatures to be used for the HDD in regressions tested by the API. Cannot have more than 120 temperatures, and must contain only values that can be converted to Temperature objects using Temperature.celsius(double) or Temperature.fahrenheit(double) (according to the temperature unit this Builder was constructed with).

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.IllegalArgumentException - if heatingBaseTemperatures contains more than 120 temperatures, or contains any value that can't be converted into a Temperature object using Temperature.celsius(double) or Temperature.fahrenheit(double) (according to the temperature unit this Builder was constructed with).

setCustomTestCoolingBaseTemperatures

public RegressionTestPlan.Builder setCustomTestCoolingBaseTemperatures(java.lang.Iterable<Temperature> coolingBaseTemperatures)

Sets custom base temperatures to be used for the CDD in regressions tested by the API.

By default this is not set at all (as if it had been called with null), and the API will choose the base temperatures of the CDD it tests automatically.

If an empty Iterable is passed in, no CDD will be tested unless setRequestedRegressionSpecs(RegressionSpec...) is used to specify regressions with CDD.

This method will accept up to 120 (inclusive) custom test cooling base temperatures, but, if you use all 120, you will get an exception on build() unless you have set the custom test heating base temperatures as empty. At build() time you can have up to 120 custom base temperatures in total. If you don't set any custom test heating base temperatures (leaving the API to choose the test heating base temperatures automatically), at build() time you will be allowed up to 60 custom test cooling base temperatures.

When calling this method you may want to use Temperature.celsiusRange(double, double, double) or Temperature.fahrenheitRange(double, double, double) to create an evenly-spaced set of Temperature objects covering your desired temperature range.

The Temperature objects will be copied out of the Iterable passed in, so you are free to modify the Iterable after calling this method without such modifications affecting the state of this Builder.

See www.degreedays.net/api/regression#custom-base-temperatures for example code.

Parameters:

coolingBaseTemperatures - the base temperatures to be used for the CDD in regressions tested by the API. Cannot contain null, cannot have more than 120 temperatures, and must contain only temperatures with the same unit (Celsius or Fahrenheit) this Builder was constructed with.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if coolingBaseTemperatures contains null.

java.lang.IllegalArgumentException - if coolingBaseTemperatures contains more than 120 temperatures, or contains any temperatures with a unit that isn't the one this Builder was constructed with.

setCustomTestCoolingBaseTemperatures

public RegressionTestPlan.Builder setCustomTestCoolingBaseTemperatures(Temperature[] coolingBaseTemperatures)

Sets custom base temperatures to be used for the CDD in regressions tested by the API.

By default this is not set at all (as if it had been called with null), and the API will choose the base temperatures of the CDD it tests automatically.

If an empty array is passed in, no CDD will be tested unless setRequestedRegressionSpecs(RegressionSpec...) is used to specify regressions with CDD.

This method will accept up to 120 (inclusive) custom test cooling base temperatures, but, if you use all 120, you will get an exception on build() unless you have set the custom test heating base temperatures as empty. At build() time you can have up to 120 custom base temperatures in total. If you don't set any custom test heating base temperatures (leaving the API to choose the test heating base temperatures automatically), at build() time you will be allowed up to 60 custom test cooling base temperatures.

The Temperature objects will be copied out of the array passed in, so you are free to modify the array after calling this method without such modifications affecting the state of this Builder.

See www.degreedays.net/api/regression#custom-base-temperatures for example code.

Parameters:

coolingBaseTemperatures - the base temperatures to be used for the CDD in regressions tested by the API. Cannot contain null, cannot have more than 120 temperatures, and must contain only temperatures with the same unit (Celsius or Fahrenheit) this Builder was constructed with.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if coolingBaseTemperatures contains null.

java.lang.IllegalArgumentException - if coolingBaseTemperatures contains more than 120 temperatures, or contains any temperatures with a unit that isn't the one this Builder was constructed with.

setCustomTestCoolingBaseTemperatures

public RegressionTestPlan.Builder setCustomTestCoolingBaseTemperatures(double... coolingBaseTemperatures)

Sets custom base temperatures to be used for the CDD in regressions tested by the API, assuming the temperature unit (Celsius or Fahrenheit) this Builder was constructed with.

By default this is not set at all (as if it had been called with null), and the API will choose the base temperatures of the CDD it tests automatically.

If this is called with no arguments, like builder.setCustomTestCoolingBaseTemperatures(), then no CDD will be tested unless setRequestedRegressionSpecs(RegressionSpec...) is used to specify regressions with CDD.

This method will accept up to 120 (inclusive) custom test cooling base temperatures, but, if you use all 120, you will get an exception on build() unless you have set the custom test heating base temperatures as empty. At build() time you can have up to 120 custom base temperatures in total. If you don't set any custom test heating base temperatures (leaving the API to choose the test heating base temperatures automatically), at build() time you will be allowed up to 60 custom test cooling base temperatures.

When calling this method remember that the values passed in are converted to Temperature objects, which means they are rounded to the nearest 0.1 degrees and have maximum and minimum allowed values that depend on the temperature unit this Builder was constructed with. See Temperature.celsius(double) or Temperature.fahrenheit(double) for more.

See www.degreedays.net/api/regression#custom-base-temperatures for example code.

Parameters:

coolingBaseTemperatures - the base temperatures to be used for the CDD in regressions tested by the API. Cannot have more than 120 temperatures, and must contain only values that can be converted to Temperature objects using Temperature.celsius(double) or Temperature.fahrenheit(double) (according to the temperature unit this Builder was constructed with).

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.IllegalArgumentException - if coolingBaseTemperatures contains more than 120 temperatures, or contains any value that can't be converted into a Temperature object using Temperature.celsius(double) or Temperature.fahrenheit(double) (according to the temperature unit this Builder was constructed with).

addExtraPredictorSpec

public RegressionTestPlan.Builder addExtraPredictorSpec(java.lang.String extraPredictorKey,
                                                        ExtraPredictorSpec extraPredictorSpec)

Adds a specification for an extra predictor included in the InputData sent to the API, to help the API test and rank the regressions that include data for that extra predictor.

There's some sample code 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).

If you have 2 extra predictors (the maximum allowed, though this is not checked until you call build()), you can call this method twice, or do all the extra-predictor specification in one call to setExtraPredictorSpecs(java.util.Map<java.lang.String, net.degreedays.api.regression.ExtraPredictorSpec>).

Parameters:

extraPredictorKey - the String key used to identify the extra predictor in each InputPeriod of your InputData. Cannot be null, must match the regular expression [-_.a-zA-Z0-9]{1,60}, and cannot be "baseload", "heatingDegreeDays", or "coolingDegreeDays".

extraPredictorSpec - the specification for the extra predictor identified by extraPredictorKey. Cannot be null.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if extraPredictorKey or extraPredictorSpec is null.

java.lang.IllegalArgumentException - if extraPredictorKey does not match the specification detailed above.

See Also:

setExtraPredictorSpecs(java.util.Map<java.lang.String, net.degreedays.api.regression.ExtraPredictorSpec>)

setExtraPredictorSpecs

public RegressionTestPlan.Builder setExtraPredictorSpecs(java.util.Map<java.lang.String,ExtraPredictorSpec> extraPredictorSpecs)

Sets the specifications for the extra predictors included in the InputData sent to the API, to help the API test and rank the regressions that include data for those extra predictors.

There's some sample code 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).

Data will be copied from the Map passed in (rather than this Builder storing the Map internally), so you can continue to use the Map however you like after calling this method.

Parameters:

extraPredictorSpecs - a Map with extra-predictor keys as Map keys (these should match the extra-predictor keys used in each InputPeriod of your InputData), and the corresponding ExtraPredictorSpec objects as values. Cannot be null or contain null, cannot have more than 2 mappings, and must have valid keys matching the regular expression [-_.a-zA-Z0-9]{1,60}, with "baseload", "heatingDegreeDays", and "coolingDegreeDays" specifically disallowed.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if extraPredictorSpecs is null or contains null.

java.lang.IllegalArgumentException - if there are more than 2 mappings, or if any of the keys do not match the specification detailed above.

See Also:

addExtraPredictorSpec(java.lang.String, net.degreedays.api.regression.ExtraPredictorSpec)

addRequestedRegressionSpec

public RegressionTestPlan.Builder addRequestedRegressionSpec(RegressionSpec requestedRegressionSpec)

Adds a specification for a regression that you want to receive in the response from the API.

You will be able to identify your requested regression(s) by looping over the returned regressions and calling Regression.hasTag(net.degreedays.api.regression.RegressionTag) with RegressionTag.REQUESTED.

There's some sample code in the regression API docs on our website.

Parameters:

requestedRegressionSpec - the specification for the regression that you want to be returned in the API response. Cannot be null.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if requestedRegressionSpec is null.

See Also:

setRequestedRegressionSpecs(RegressionSpec...)

setRequestedRegressionSpecs

public RegressionTestPlan.Builder setRequestedRegressionSpecs(java.lang.Iterable<RegressionSpec> requestedRegressionSpecs)

Sets specifications for up to 60 regressions that you want to receive in the response from the API.

You will be able to identify your requested regression(s) by looping over the returned regressions and calling Regression.hasTag(net.degreedays.api.regression.RegressionTag) with RegressionTag.REQUESTED.

There's some sample code in the regression API docs on our website.

Data will be copied from the Iterable passed in (rather than this Builder storing the Iterable internally), so you can continue to use the Iterable however you like after calling this method.

Parameters:

requestedRegressionSpecs - the specifications for the regressions that you want to be returned in the API response. Cannot be null, and cannot contain null.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if requestedRegressionSpecs is null or contains null.

java.lang.IllegalArgumentException - if requestedRegressionSpecs contains more than 60 RegressionSpec objects.

setRequestedRegressionSpecs

public RegressionTestPlan.Builder setRequestedRegressionSpecs(RegressionSpec... requestedRegressionSpecs)

Sets specifications for up to 60 regressions that you want to receive in the response from the API.

You will be able to identify your requested regression(s) by looping over the returned regressions and calling Regression.hasTag(net.degreedays.api.regression.RegressionTag) with RegressionTag.REQUESTED.

There's some sample code in the regression API docs on our website.

Data will be copied from the array passed in (rather than this Builder storing the array internally), so you can continue to use the array however you like after calling this method.

Parameters:

requestedRegressionSpecs - the specifications for the regressions that you want to be returned in the API response. Cannot be null, and cannot contain null.

Returns:

this Builder, for easy method chaining.

Throws:

java.lang.NullPointerException - if requestedRegressionSpecs is null or contains null.

java.lang.IllegalArgumentException - if requestedRegressionSpecs contains more than 60 RegressionSpec objects.

build

public RegressionTestPlan build()

Creates a RegressionTestPlan with the configuration currently held by this Builder.

This does a lot of checking to ensure that only a valid RegressionTestPlan can be created. The rules are as follows:

• There cannot be more than 120 custom test base temperatures in total. If either heating or cooling custom test base temperatures are left as default, that counts as 60, meaning there cannot be more than 60 of the other. If both are set as empty then at least one requested regression spec must have been set.
• There cannot be more than 2 extra-predictor specs.
• There cannot be more than 60 requested regression specs.
• If any of the requested regression specs include extra-predictor keys, this Builder must have an ExtraPredictorSpec for each of those extra-predictor keys.

Throws:

java.lang.IllegalStateException - if anything in the configuration of this Builder would make for an invalid RegressionTestPlan according to the rules detailed above.