degreedays.api.regression

For using the API to run regressions against your energy-usage data.

If you are new to this module, we suggest you start by looking at RegressionApi.

Class summaries

BaseloadRegressionComponent	Contains details of the baseload component (non-weather-dependent energy usage) in a regression.
DayNormalization	Defines the day normalization used in the regression process – an important consideration when periods of energy usage cover different lengths of time.
DegreeDaysRegressionComponent	Contains details of a heating or cooling component in a regression, with the base temperature and degree days used, as well as the usual coefficient and stats.
ExpectedCorrelation	Defines how an extra predictor's figures are expected to correlate with energy usage (whether larger predictor numbers lead to larger or smaller energy usage).
ExtraPredictorSpec	Defines an extra predictor in terms of its PredictorType and ExpectedCorrelation, to help the API test and rank regressions that include data for that extra predictor.
ExtraRegressionComponent	Contains details of an extra-predictor component in a regression.
InputData	Defines the energy data (and any extra-predictor data) that the API should run regressions against.
InputPeriod	Defines a dated period with its energy usage and any extra-predictor figures.
PredictorType	Defines an extra predictor's figures as being cumulative (increasing with time and naturally larger over longer periods) or average (normalized such that the length of the period has no effect).
Regression	Contains details of a regression model that the API calculated using the InputData you provided and, typically, HDD and/or CDD as well.
RegressionApi	Provides easy, type-safe access to the API's data-related operations.
RegressionComponent	Contains details of a regression component e.g. the baseload (b*days) or the heating (h*HDD) component in a regression like E = b*days + h*HDD.
RegressionComponents	Contains all the RegressionComponent objects in a Regression.
RegressionRequest	Defines a request for the API to test regressions against the specified energy data (InputData) using degree days from the specified Location.
RegressionResponse	Contains a selection of the regressions that the API tested against your RegressionRequest, with the Regression that gave the best statistical fit listed first.
RegressionSpec	Defines a specification of a regression in terms of its HDD and/or CDD base temperature(s) and any extra predictors to be included.
RegressionTag	Tags that the API adds to Regression objects to indicate why it included them in a RegressionResponse.
RegressionTestPlan	Defines how the API should test regressions against the InputData you provide it.

degreedays.api.regression

For using the API to run regressions against your energy-usage data.

If you are new to this module, we suggest you start by looking at RegressionApi.

class degreedays.api.regression.BaseloadRegressionComponent(coefficient: float, coefficientStandardError: float, coefficientPValue: float, multiplyByNumberOfDays: bool)

Contains details of the baseload component (non-weather-dependent energy usage) in a regression.

property coefficient: float

The coefficient of this regression component e.g. the b, h, or c (depending on the component in question) in a regression with an equation like E = b*days + h*HDD + c*CDD

property coefficientPValue: float

The p-value of the coefficient. It can have values between 0 (best) and 1 (worst), and you can use it as an indication of whether there is likely to be a meaningful relationship between the component and energy consumption. People often look for p-values of 0.05 or less, but really it is a sliding scale. p-value is a common statistic (not energy specific) that you can look up online.

Note that, for a BaseloadRegressionComponent the p-value is usually high if the coefficient is small, so it’s often not as useful as the other p-values when assessing the quality of a regression.

property coefficientStandardError: float

The standard error of the coefficient. This is a measure of the precision of the regression model’s estimate of the coefficient value. It’s a common statistic (not energy specific) that you can look up online.

property multiplyByNumberOfDays: bool

True if the baseload coefficient is a per-day value that should be multiplied by the number of days covered by the period in question; or False if the coefficient is such that it will only work for periods of the same length used in the InputData.

For the baseload component this will always be True unless you ran regressions with DayNormalization.NONE.

The notes on day normalization for our online regression tool have example regression equations that should help make this clearer.

class degreedays.api.regression.DayNormalization

Defines the day normalization used in the regression process – an important consideration when periods of energy usage cover different lengths of time.

The best explanation of the day-normalization options is in the docs for our online regression tool (which itself uses the API internally).

NONE: DayNormalization

For no day normalization at all, this works fine for InputData with periods that are all the same length, but not so well for data with periods of different length.

See www.degreedays.net/regression#day-normalization

Access via: DayNormalization.NONE

UNWEIGHTED: DayNormalization

For InputData with periods of different length this is typically better than using no day normalization at all, but it’s not as good as the WEIGHTED option.

See www.degreedays.net/regression#day-normalization

Access via: DayNormalization.UNWEIGHTED

WEIGHTED: DayNormalization

The recommended option, this gives the best results for InputData with periods of different length, and the weighting makes no difference if the periods are all the same length. With this option longer periods effectively have a greater influence on the regression coefficients than shorter periods.

See www.degreedays.net/regression#day-normalization

Access via: DayNormalization.WEIGHTED

class degreedays.api.regression.DegreeDaysRegressionComponent(coefficient: float, coefficientStandardError: float, coefficientPValue: float, baseTemperature: Temperature, sampleDegreeDaysDataSet: DatedDataSet, sampleDegreeDaysTotal: DataValue)

Contains details of a heating or cooling component in a regression, with the base temperature and degree days used, as well as the usual coefficient and stats.

property baseTemperature: Temperature

The base temperature of the degree days this regression component was calculated with.

property coefficient: float

The coefficient of this regression component e.g. the b, h, or c (depending on the component in question) in a regression with an equation like E = b*days + h*HDD + c*CDD

property coefficientPValue: float

The p-value of the coefficient. It can have values between 0 (best) and 1 (worst), and you can use it as an indication of whether there is likely to be a meaningful relationship between the component and energy consumption. People often look for p-values of 0.05 or less, but really it is a sliding scale. p-value is a common statistic (not energy specific) that you can look up online.

Note that, for a BaseloadRegressionComponent the p-value is usually high if the coefficient is small, so it’s often not as useful as the other p-values when assessing the quality of a regression.

property coefficientStandardError: float

The standard error of the coefficient. This is a measure of the precision of the regression model’s estimate of the coefficient value. It’s a common statistic (not energy specific) that you can look up online.

property sampleDegreeDaysDataSet: DatedDataSet

The DatedDataSet of the degree days this regression component was calculated with.

property sampleDegreeDaysTotal: DataValue

The DataValue representing the total number of degree days across all the periods this regression component was calculated for.

This will have a value equal to the total of all the degree-day values in sampleDegreeDaysDataSet.

class degreedays.api.regression.ExpectedCorrelation

Defines how an extra predictor’s figures are expected to correlate with energy usage (whether larger predictor numbers lead to larger or smaller energy usage). This helps the API rank the various regressions it tests, as it will downrank the regressions with extra predictors that correlate with energy usage in an unexpected way.

NEGATIVE: ExpectedCorrelation

For an extra predictor expected to have a negative correlation with energy usage i.e. larger extra-predictor figures lead to smaller energy usage.

Access via: ExpectedCorrelation.NEGATIVE

POSITIVE: ExpectedCorrelation

For an extra predictor expected to have a positive correlation with energy usage i.e. larger extra-predictor figures lead to larger energy usage.

Access via: ExpectedCorrelation.POSITIVE

POSITIVE_OR_NEGATIVE: ExpectedCorrelation

For an extra predictor that could be expected to have either a positive or negative correlation with energy usage. You could look at this as an “I don’t know what to expect” option. If possible, it’s better to figure out what each extra predictor is and what you expect from it, but this option can be useful if your system is dealing with data it doesn’t have much context on.

Access via: ExpectedCorrelation.POSITIVE_OR_NEGATIVE

class degreedays.api.regression.ExtraPredictorSpec(predictorType: PredictorType, expectedCorrelation: ExpectedCorrelation)

Defines an extra predictor in terms of its PredictorType and ExpectedCorrelation, to help the API test and rank regressions that include data for that extra predictor.

Parameters:

• predictorType (PredictorType) – defines how the extra predictor’s figures vary with the length of the periods they are measured over.

• expectedCorrelation (ExpectedCorrelation) – defines how the extra predictor is expected to correlate with energy usage.

Raises:

TypeError – if predictorType is not a PredictorType object, or expectedCorrelation is not an ExpectedCorrelation object.

ExtraPredictorSpec objects are held by the RegressionTestPlan. 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).

property expectedCorrelation: ExpectedCorrelation

The ExpectedCorrelation that defines how the extra predictor is expected to correlate with energy usage.

property predictorType: PredictorType

The PredictorType that defines how the extra predictor’s figures vary with the length of the periods they are measured over.

class degreedays.api.regression.ExtraRegressionComponent(coefficient: float, coefficientStandardError: float, coefficientPValue: float, multiplyByNumberOfDays: bool)

Contains details of an extra-predictor component in a regression.

property coefficient: float

The coefficient of this regression component e.g. the b, h, or c (depending on the component in question) in a regression with an equation like E = b*days + h*HDD + c*CDD

property coefficientPValue: float

The p-value of the coefficient. It can have values between 0 (best) and 1 (worst), and you can use it as an indication of whether there is likely to be a meaningful relationship between the component and energy consumption. People often look for p-values of 0.05 or less, but really it is a sliding scale. p-value is a common statistic (not energy specific) that you can look up online.

Note that, for a BaseloadRegressionComponent the p-value is usually high if the coefficient is small, so it’s often not as useful as the other p-values when assessing the quality of a regression.

property coefficientStandardError: float

The standard error of the coefficient. This is a measure of the precision of the regression model’s estimate of the coefficient value. It’s a common statistic (not energy specific) that you can look up online.

property multiplyByNumberOfDays: bool

True if the coefficient is a per-day value that should be multiplied by the number of days covered by the period in question; False otherwise.

This will be True for extra predictors with PredictorType.AVERAGE, and False for extra predictors with PredictorType.CUMULATIVE.

class degreedays.api.regression.InputData(*args: InputPeriod | Iterable[InputPeriod])

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

Parameters:

*args – up to 1096 InputPeriod objects, or one or more sequences (e.g. lists or tuples) containing a total of up to 1096 InputPeriod objects.

Raises:

• TypeError – if you pass in anything that isn’t an InputPeriod object or a sequence (e.g. list or tuple) of InputPeriod objects.

• ValueError – if the InputPeriod objects passed in do not match the specified requirements.

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).

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

property extraPredictorKeys: Collection[str]

A possibly-empty Collection of extra-predictor keys that this InputData (and each InputPeriod within it) has extra-predictor figures for.

property fullRange: DayRange

A degreedays.time.DayRange indicating the total period of time covered by this InputData object (including any gaps between its input periods).

property periods: Sequence[InputPeriod]

A non-empty, chronologically-ordered Sequence of the InputPeriod objects that make up this InputData.

class degreedays.api.regression.InputPeriod(dayRange: degreedays.time.DayRange, usage: float, extraPredictorsOrNone: Mapping[str, float] | None = None)

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.

Parameters:

• dayRange (degreedays.time.DayRange) – the period of time covered.

• usage (float) – the energy usage over the specified dayRange.

• extraPredictorsOrNone (Mapping[str, float] | None) – a Mapping (e.g. a dict) of no more than 2 string extra-predictor keys to numeric extra-predictor values. Extra-predictor keys must match the regular expression [-_.a-zA-Z0-9]{1,60}, and cannot be 'baseload', 'heatingDegreeDays', or 'coolingDegreeDays'.

Raises:

• TypeError – if dayRange is not a degreedays.time.DayRange, if usage is not a float, or if extraPredictorsOrNone is not a Mapping[str, float] or None.

• ValueError – if usage or any extra-predictor values are NaN or infinity, or if there are more than 2 extra predictors, or if any extra-predictor keys do not match the specification detailed above.

See www.degreedays.net/api/regression for more information and code samples. That page has some sample code showing how to use extra predictors, and there’s also some additional practical information on specifying and using extra predictors in the docs for our website regression tool (which itself uses the API internally).

property dayRange: DayRange

The period of time covered by this InputPeriod.

property extraPredictorCount: int

The number of extra predictors that are defined for this InputPeriod.

property extraPredictorKeys: Sequence[str]

A Sequence[str] of the extra-predictor keys defined for this InputPeriod. This will be empty if no extra-predictors are defined.

getExtraPredictor(key: str) → float

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

Parameters:

key (str) – a string extra-predictor key.

Raises:

• TypeError – if key is not a str.

• KeyError – if key isn’t one of the extra-predictor keys stored in this object.

See also: extraPredictorKeys

property usage: float

The energy usage over this InputPeriod.

class degreedays.api.regression.PredictorType

Defines an extra predictor’s figures as being cumulative (increasing with time and naturally larger over longer periods) or average (normalized such that the length of the period has no effect).

AVERAGE: PredictorType

For an extra predictor that is normalized such that the length of the period has no effect e.g. an AVERAGE measure of occupancy could be the percentage of full occupancy. A building could be 50% occupied for a week, or a month, or a year – longer periods would not mean larger figures.

Access via: PredictorType.AVERAGE

CUMULATIVE: PredictorType

For an extra predictor that increases with time and is naturally larger over longer periods e.g. a CUMULATIVE measure of occupancy could be the total person-hours worked. If a typical day saw 110 person hours, a typical 5-day week might see 770 person hours (i.e. larger figures for longer periods).

Access via: PredictorType.CUMULATIVE

class degreedays.api.regression.Regression(tags: Iterable[RegressionTag], components: RegressionComponents, sampleSize: int, sampleDays: int, sampleSpan: degreedays.time.DayRange, rSquared: float, adjustedRSquared: float, crossValidatedRSquared: float, standardError: float, cvrmse: float)

Contains details of a regression model that the API calculated using the InputData you provided and, typically, HDD and/or CDD as well.

property adjustedRSquared: float

The adjusted-R-squared value for this Regression.

You can read more about this and the other statistics in the docs for our online regression tool (which uses this API internally).

property baseload: BaseloadRegressionComponent

The BaseloadRegressionComponent object representing the baseload component (b*days) of this Regression.

property coolingDegreeDaysOrNone: DegreeDaysRegressionComponent | None

The DegreeDaysRegressionComponent object representing the cooling-degree-days component (c*CDD) of this Regression, or None if no such component exists.

property crossValidatedRSquared: float

The cross-validated-R-squared value for this Regression.

You can read more about this and the other statistics in the docs for our online regression tool (which uses this API internally).

property cvrmse: float

The CVRMSE of this Regression.

You can read more about this and the other statistics in the docs for our online regression tool (which uses this API internally).

property extraPredictorKeys: Collection[str]

The possibly-empty Collection of extra-predictor keys that this Regression has extra components for.

Remember that, in the usual case, if you provide extra-predictor data to the API, it will test regressions both with and without each extra predictor, and this will be reflected in the regressions you get back in the response.

See also: getExtraComponent

getExtraComponent(extraPredictorKey: str) → ExtraRegressionComponent

Returns the ExtraRegressionComponent object with the specified extraPredictorKey, or throws a KeyError if no such component exists in this Regression (check hasExtraComponent before calling this).

Remember that, in the usual case, if you provide extra-predictor data to the API, it will test regressions both with and without each extra predictor, and this will be reflected in the regressions you get back in the response.

Parameters:

extraPredictorKey (str) – the string key that you used to identify the extra predictor in the InputData of your request.

Raises:

• TypeError – if extraPredictorKey is not a str.

• KeyError – if this Regression does not have an extra-predictor component with the specified extraPredictorKey.

See also: hasExtraComponent, extraPredictorKeys

hasExtraComponent(extraPredictorKey: str) → bool

Returns True if this Regression has an extra-predictor component with the specified extraPredictorKey; False otherwise.

Remember that, in the usual case, if you provide extra-predictor data to the API, it will test regressions both with and without each extra predictor, and this will be reflected in the regressions you get back in the response.

Parameters:

extraPredictorKey (str) – the string key that you used to identify the extra predictor in the InputData of your request.

Raises:

TypeError – if extraPredictorKey is not a str.

See also: getExtraComponent, extraPredictorKeys

hasTag(regressionTag: RegressionTag) → bool

Returns True if this Regression contains the specified regressionTag; False otherwise.

Parameters:

regressionTag (RegressionTag) – the RegressionTag that’s presence in this Regression is to be tested.

Raises:

TypeError – if regressionTag is not a RegressionTag.

See also: tags

property heatingDegreeDaysOrNone: DegreeDaysRegressionComponent | None

The DegreeDaysRegressionComponent object representing the heating-degree-days component (h*HDD) of this Regression, or None if no such component exists.

property rSquared: float

The R-squared value for this Regression.

You can read more about this and the other statistics in the docs for our online regression tool (which uses this API internally).

property sampleDays: int

The number of days covered by the sample of data used for this Regression, excluding any gaps between input periods.

property sampleSize: int

The number of energy-usage figures used for this Regression. This could be less than the number of input periods included in your request if the location could not provide enough weather data to cover all of them.

property sampleSpan: DayRange

The DayRange representing the full period covered by the sample (including any gaps) that was used for this Regression. This could be shorter than the full range of the InputData sent in your request, if the location could not provide enough weather data to cover it all.

property sampleSpanDays: int

The number of days covered by the sample (including any gaps) that was used for this Regression. This could be shorter than the number of days covered by the InputData sent in your request, if the location could not provide enough weather data to cover it all.

property spec: RegressionSpec

The RegressionSpec specifying the components that this Regression contains, such that an equivalent Regression can be requested in another API request.

See how to request specific regressions to be returned.

property standardError: float

The standard error of this Regression.

You can read more about this and the other statistics in the docs for our online regression tool (which uses this API internally).

property tags: Collection[RegressionTag]

A Collection of the tags that describe how this Regression came to be included in the response from the API.

class degreedays.api.regression.RegressionApi(requestProcessor)

Provides easy, type-safe access to the API’s data-related operations.

To get a RegressionApi object and use it, create a degreedays.api.DegreeDaysApi object, get the RegressionApi object from that, then call the method you want.

Example code for running regressions:

Please see the Python code samples in the regression API docs on our website.

runRegressions(regressionRequest: RegressionRequest) → RegressionResponse

Sends your RegressionRequest to the API servers so it can run regressions against your InputData and return a RegressionResponse containing the regressions that were statistically best and/or any that you specifically requested.

Parameters:

regressionRequest (RegressionRequest) – specifying the InputData (energy data) you want regressions to be run against, the Location for which degree days should be generated to use in those regressions, and the RegressionTestPlan defining what regressions the API should test and potentially return.

Returns:

RegressionResponse containing the regressions that the API found to give the best statistical fit with your InputData.

Raises:

• LocationError – if the request fails because of problems relating to the specified Location.

• ServiceError – if the request fails because of a problem with the API service (sorry!).

• RateLimitError – if you hit the degreedays.api.RateLimit for your account’s plan, and need to wait a little while before it’s reset.

• InvalidRequestError – if the request that is sent to the API servers is invalid (e.g. if it is authenticated with invalid API access keys).

• TransportError – if there’s a problem sending the request to the API servers, or a problem getting the API’s response back.

• DegreeDaysApiError – the superclass of all the exceptions listed above.

• TypeError – if regressionRequest is not a RegressionRequest object.

The API’s processing will typically require it to generate degree days to match the InputData you provide in your request, so it can use those degree days in the regressions it tests. To do this it will use the Location specified in your request.

If you specify a StationIdLocation (created via Location.stationId), then the API will use data from that station. But, if you specify a GeographicLocation, the API will choose which station(s) to use automatically. The choice will depend on the dates of your InputData as well as the location you specify. Some stations have more data than others, and the quality of a station’s data can vary over time. The API will choose the station(s) that can best match the data you provide in your request.

If you specify an inactive weather station (see LocationError.isDueToLocationNotSupported for more on these), or a GeographicLocation for which no active station can be found with enough data to run regressions against your InputData, you will get a LocationError instead of a RegressionResponse.

Regressions not covering all of your input data:

If the location you specify in your request does not have sufficient weather data for the API to run regressions against your full input data, it may still be able to run regressions against part of it. You can check the Regression.sampleSpan and the Regression.sampleSize of any Regression in the response (comparing with InputData.fullRange and the len of InputData.periods) to see if this has happened.

It is unlikely to happen unless you are trying to run regressions against very old energy data, or very recent energy data e.g. that includes a day that finished in the last hour or two. If you want to be sure to prevent it from happening, you could make a LocationInfoRequest first, specifying data with a DayRangePeriod that matches your InputData and with a minimumDayRangeOrNone that specifies that same degreedays.time.DayRange. If you get a successful response back you will have a weather station ID that you know you can use in your regression request. But you will have used only 1 request unit to find that out (versus however many it might take to run a load of regressions that might only cover part of your data).

More info and code samples

Please see the regression API docs on our website for more information and Python code samples showing how to run regressions through the API.

class degreedays.api.regression.RegressionComponent(coefficient: float, coefficientStandardError: float, coefficientPValue: float)

Contains details of a regression component e.g. the baseload (b*days) or the heating (h*HDD) component in a regression like E = b*days + h*HDD

property coefficient: float

The coefficient of this regression component e.g. the b, h, or c (depending on the component in question) in a regression with an equation like E = b*days + h*HDD + c*CDD

property coefficientPValue: float

The p-value of the coefficient. It can have values between 0 (best) and 1 (worst), and you can use it as an indication of whether there is likely to be a meaningful relationship between the component and energy consumption. People often look for p-values of 0.05 or less, but really it is a sliding scale. p-value is a common statistic (not energy specific) that you can look up online.

Note that, for a BaseloadRegressionComponent the p-value is usually high if the coefficient is small, so it’s often not as useful as the other p-values when assessing the quality of a regression.

property coefficientStandardError: float

The standard error of the coefficient. This is a measure of the precision of the regression model’s estimate of the coefficient value. It’s a common statistic (not energy specific) that you can look up online.

class degreedays.api.regression.RegressionComponents(baseload: BaseloadRegressionComponent, heatingDegreeDaysOrNone: DegreeDaysRegressionComponent | None = None, coolingDegreeDaysOrNone: DegreeDaysRegressionComponent | None = None, extras: Mapping[str, ExtraRegressionComponent] = {})

Contains all the RegressionComponent objects in a Regression.

property baseload: BaseloadRegressionComponent

The BaseloadRegressionComponent object representing the baseload component (b*days) of the regression.

property coolingDegreeDaysOrNone

The DegreeDaysRegressionComponent object representing the cooling-degree-days component (c*CDD) of the regression, or None if no such component exists.

property extraPredictorKeys: Collection[str]

The possibly-empty Collection of extra-predictor keys that the regression has extra components for.

Remember that, in the usual case, if you provide extra-predictor data to the API, it will test regressions both with and without each extra predictor, and this will be reflected in the regressions you get back in the response.

See also: getExtraComponent

getExtraComponent(extraPredictorKey: str) → ExtraRegressionComponent

Returns the ExtraRegressionComponent object with the specified extraPredictorKey, or throws a KeyError if no such component exists in the regression (check hasExtraComponent before calling this).

Remember that, in the usual case, if you provide extra-predictor data to the API, it will test regressions both with and without each extra predictor, and this will be reflected in the regressions you get back in the response.

Parameters:

extraPredictorKey (str) – the string key that you used to identify the extra predictor in the InputData of your request.

Raises:

• TypeError – if extraPredictorKey is not a str.

• KeyError – if the regression does not have an extra-predictor component with the specified extraPredictorKey.

See also: hasExtraComponent, extraPredictorKeys

hasExtraComponent(extraPredictorKey: str) → bool

Returns True if the regression has an extra-predictor component with the specified extraPredictorKey; False otherwise.

Remember that, in the usual case, if you provide extra-predictor data to the API, it will test regressions both with and without each extra predictor, and this will be reflected in the regressions you get back in the response.

Parameters:

extraPredictorKey (str) – the string key that you used to identify the extra predictor in the InputData of your request.

Raises:

TypeError – if extraPredictorKey is not a str.

See also: getExtraComponent, extraPredictorKeys

property heatingDegreeDaysOrNone

The DegreeDaysRegressionComponent object representing the heating-degree-days component (h*HDD) of the regression, or None if no such component exists.

property spec: RegressionSpec

The RegressionSpec specifying the components that this object contains, such that a Regression with equivalent components can be requested in another API request.

See how to request specific regressions to be returned.

class degreedays.api.regression.RegressionRequest(location: Location, inputData: InputData, testPlan: RegressionTestPlan)

Defines a request for the API to test regressions against the specified energy data (InputData) using degree days from the specified Location.

Parameters:

• location (Location) – the location for which the API should generate degree days to use in the regressions it tests against the InputData.

• inputData (InputData) – the dated records of energy usage and any extra-predictor data to be used in the regressions tested by the API.

• testPlan (RegressionTestPlan) – defining how the API should test regressions against the InputData. Must have an ExtraPredictorSpec for any extra-predictor keys used in inputData, and, if it has any RegressionTestPlan.requestedRegressionSpecs, they must not contain any extra-predictor keys that do not have data in inputData.

Raises:

• TypeError – if location is not a subclass of Location, or if inputData is not an InputData object, or if testPlan is not a RegressionTestPlan object.

• ValueError – if inputData contains extra-predictor data but testPlan does not contain an ExtraPredictorSpec for each extra-predictor key included, or if testPlan contains any RegressionSpec in RegressionTestPlan.requestedRegressionSpecs with an extra-predictor key that does not have data in inputData.

A successfully-processed RegressionRequest, sent to the API via RegressionApi.runRegressions(regressionRequest), will result in a RegressionResponse containing a list of the regressions with the best statistical fit.

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

property inputData: InputData

The InputData containing the dated records of energy usage and any extra-predictor data to be used in the regressions tested by the API.

property location: Location

The Location for which the API should generate degree days to use in the regressions it tests against the inputData.

property testPlan: RegressionTestPlan

The RegressionTestPlan that defines how the API should test regressions against the inputData.

class degreedays.api.regression.RegressionResponse(metadata: degreedays.api.ResponseMetadata, stationId: str, targetLongLat: degreedays.geo.LongLat, sources: Iterable[Source], regressionsOrFailure: Iterable[Regression] | degreedays.api.Failure)

Contains a selection of the regressions that the API tested against your RegressionRequest, with the Regression that gave the best statistical fit listed first.

To get a RegressionResponse, you would send a RegressionRequest to the API via RegressionApi.runRegressions(regressionRequest). See www.degreedays.net/api/regression for more information and code samples.

getRegressions() → Sequence[Regression]

Returns a non-empty best-first ordered Sequence of Regression objects, or throws a SourceDataError if the API could not generate regressions because there was not enough good weather data for the Location specified in your RegressionRequest.

Raises:

SourceDataError – if the API could not generate any regressions because there wasn’t enough good weather data available for the Location specified in your RegressionRequest.

property metadata: ResponseMetadata

An object containing metadata sent back with every response from the API servers, including details of the account’s current rate limit.

property sources: Sequence[Source]

The non-empty Sequence of source(s) (essentially weather stations) that were used to generate the degree days used for the regressions in this response. If this response does not actually contain any regressions, this will return the source(s) that would have been used if they had had enough data to run regressions against the InputData provided in the request.

At the time of writing there will only be one source for any given response (so sources[0]) is the way to get it)… But at some point we might start combining data from multiple sources to satisfy requests for data from GeographicLocation types. If we do add this feature, it will be optional, and disabled by default, so the behaviour of your system won’t change unless you want it to.

property stationId: str

The non-empty canonical ID of the weather station or combination of weather stations that supplied the temperature data used to calculate the degree days used for the regressions in this response. If this response does not actually contain any regressions, this will be the ID of the weather station that would have been used if it had had enough data to run regressions against the InputData provided in the request.

If the Location in the RegressionRequest was a StationIdLocation (created via Location.stationId), this method will simply return the canonical form of that weather station’s ID. We say “canonical” because it’s possible for a station ID to be expressed in more than one way, like upper case or lower case. The canonical form of the station ID is the form that you should display in a UI or store in a database if appropriate.

If the Location in the RegressionRequest was a GeographicLocation, then:

• If the degree days used in the regressions were calculated using temperature data from a single station (the usual case), this method will return the canonical form of that station’s ID.

• If the degree days used in the regressions were calculated using temperature data combined from multiple stations (something that the API might optionally start doing at some point in the future), this method will return the ID of a “virtual station” that represents the specific combination of weather stations used.

Either way, the station ID returned by this method can be used to run more regressions or fetch more data from the same station(s) that were used to generate the degree days used for the regressions in this response. For example, you might want to start off using a GeographicLocation initially, and then use the returned station ID to fetch more data or run more regressions using the same station.

property targetLongLat: LongLat

The degreedays.geo.LongLat object that specifies the geographic position of the Location from the RegressionRequest that led to this response.

If the Location from the request was a PostalCodeLocation (created via Location.postalCode), this will be the LongLat that the API determined to be the central point of that postal code.

If the Location from the request was a StationIdLocation (created via Location.stationId), this will be the LongLat of that station (also accessible through sources).

If the Location from the request was a LongLatLocation (created via Location.longLat), this will simply be the LongLat that was originally specified. (Bear in mind that the longitude and latitude may have been rounded slightly between the request and the response. Such rounding would only introduce very small differences that would be insignificant as far as the real-world position is concerned, but it’s worth bearing this in mind in case you are comparing for equality the returned LongLat with the LongLat from the request. The two positions will be close, but they might not be equal.)

class degreedays.api.regression.RegressionSpec(heatingBaseTemperatureOrNone: Temperature | None = None, coolingBaseTemperatureOrNone: Temperature | None = None, extraPredictorKeys: Iterable[str] | str = ())

Defines a specification of a regression in terms of its HDD and/or CDD base temperature(s) and any extra predictors to be included.

Parameters:

• heatingBaseTemperatureOrNone (Temperature | None) – the base temperature of the heating degree days to be included in the specified regression, or the default value of None if heating degree days should not be included.

• coolingBaseTemperatureOrNone (Temperature | None) – the base temperature of the cooling degree days to be included in the specified regression, or the default value of None if cooling degree days should not be included.

• extraPredictorKeys (Iterable[str] | str) – an Iterable (e.g. tuple or list) of string extra-predictor keys that identify the extra predictors to be included in the regression, or the default empty tuple to indicate that no extra predictors should be included. There can be a maximum of 2 keys. Each key must match the regular expression [-_.a-zA-Z0-9]{1,60}, with 'baseload', 'heatingDegreeDays', and 'coolingDegreeDays' specifically disallowed. If you want to pass in just one key, for convenience you can optionally pass in just that one string instead of an Iterable[str].

Raises:

• TypeError – if heatingBaseTemperatureOrNone is not a Temperature or None, or if coolingBaseTemperatureOrNone is not a Temperature or None, or if extraPredictorKeys is not an Iterable of string keys, or a single string key.

• ValueError – if extraPredictorKeys does not match the specification detailed above.

See www.degreedays.net/api/regression for more information and code samples showing how to create RegressionSpec items and set them in your RegressionTestPlan to ensure that the API will test and return those regressions.

property coolingBaseTemperatureOrNone: Temperature | None

The base temperature to be used for the cooling degree days in the specified regression, or None if cooling degree days should not be included.

property extraPredictorKeys: Collection[str]

The keys of the extra predictors to be included in the specified regression.

property heatingBaseTemperatureOrNone: Temperature | None

The base temperature to be used for the heating degree days in the specified regression, or None if heating degree days should not be included.

class degreedays.api.regression.RegressionTag

Tags that the API adds to Regression objects to indicate why it included them in a RegressionResponse.

IN_SHORTLIST_RANGE: RegressionTag

Indicates a regression that was explicitly specified in the request, and that has strong enough statistics to appear in the SHORTLIST even though it wasn’t auto-selected to be in the shortlist (if it was it would have the SHORTLIST tag instead).

It is possible for none of the REQUESTED regressions to have this tag if none of them have statistics as good as the auto-selected SHORTLIST regressions.

Note that you can set requested regressions when you create the RegressionTestPlan.

Access via: RegressionTag.IN_SHORTLIST_RANGE

NOTABLE_OTHER: RegressionTag

Indicates a regression that didn’t make the SHORTLIST, but was considered notable. This might, for example, apply to the best CDD-only regression for a set of data that correlates better with HDD than CDD, or to a regression with shortlist-worthy stats but unexpected negative coefficients.

Access via: RegressionTag.NOTABLE_OTHER

REQUESTED: RegressionTag

Indicates a regression that was explicitly specified in the request as one that should be returned.

You can set requested regressions when you create the RegressionTestPlan.

Access via: RegressionTag.REQUESTED

SHORTLIST: RegressionTag

Indicates a regression that was automatically selected by the API as a shortlist regression – one that looks likely to describe the usage data better than the others tested.

Access via: RegressionTag.SHORTLIST

class degreedays.api.regression.RegressionTestPlan(temperatureUnit: TemperatureUnit, dayNormalization: DayNormalization = DayNormalization.WEIGHTED, customTestHeatingBaseTemperaturesOrNone: Iterable[Temperature | float] | None = None, customTestCoolingBaseTemperaturesOrNone: Iterable[Temperature | float] | None = None, extraPredictorSpecs: Mapping[str, ExtraPredictorSpec] = {}, requestedRegressionSpecs: Iterable[RegressionSpec] = ())

Defines how the API should test regressions against the InputData you provide it.

Parameters:

• temperatureUnit (TemperatureUnit) – specifies whether Celsius-based or Fahrenheit-based degree days should be used in regressions.

• dayNormalization (DayNormalization) – specifies the DayNormalization to be used in the regression process. By default this will be DayNormalization.WEIGHTED, which is the recommended option.

• customTestHeatingBaseTemperaturesOrNone (Iterable[Temperature | float]) – the base temperatures to be used for the HDD in regressions tested by the API. By default this is None so the API will test a wide range of HDD base temperatures automatically. See examples of how to use custom base temperatures.

• customTestCoolingBaseTemperaturesOrNone (Iterable[Temperature | float]) – the base temperatures to be used for the CDD in regressions tested by the API. By default this is None so the API will test a wide range of CDD base temperatures automatically. See examples of how to use custom base temperatures.

• extraPredictorSpecs (Mapping[str, ExtraPredictorSpec]) – a Mapping (e.g. a dict) with string extra-predictor keys as keys (these should match the extra-predictor keys used in each InputPeriod of your InputData), and the corresponding ExtraPredictorSpec objects as values. 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. By default this is empty for the simple case of no extra predictors being used. See more info and examples on using extra predictors from Python.

• requestedRegressionSpecs (Iterable[RegressionSpec]) – specifications for up to 60 regressions that you want to receive in the response from the API. By default this is empty so the only regressions returned will be the ones chosen automatically by the API. See more info and examples on requesting specific regressions.

Raises:

• TypeError – if any of the arguments do not match the specifications detailed above.

• ValueError – if any custom base Temperature objects have units that don’t match temperatureUnit; if any float temperatures cannot be used to create a valid Temperature with temperatureUnit (e.g. because they’re out of the allowed range, or NaN); if requestedRegressionSpecs contains any RegressionSpec items with extra-predictor keys not covered by extraPredictorSpecs; or if any of customTestHeatingBaseTemperaturesOrNone, customTestCoolingBaseTemperaturesOrNone, extraPredictorSpecs, or requestedRegressionSpecs contain more than the maximum number of items allowed. Note that the maximum number of customTestHeatingBaseTemperaturesOrNone depends on the maximum number of customTestCoolingBaseTemperaturesOrNone and vice versa, as explained here.

You can create a RegressionTestPlan with default options like:

testPlan = RegressionTestPlan(TemperatureUnit.CELSIUS)

or:

testPlan = RegressionTestPlan(TemperatureUnit.FAHRENHEIT)

But there are lots of ways to configure a test plan further by specifiying optional parameters. See www.degreedays.net/api/regression for more information and code samples.

property customTestCoolingBaseTemperaturesOrNone: Sequence[Temperature] | None

The custom set of base temperatures to be used for the CDD in regressions tested by the API, or None if no such base temperatures are specified.

If this is an empty Sequence, the API will not include CDD in any of its test regressions (unless requestedRegressionSpecs specifies any regressions with CDD in them).

property customTestHeatingBaseTemperaturesOrNone: Sequence[Temperature] | None

The custom set of base temperatures to be used for the HDD in regressions tested by the API, or None if no such base temperatures are specified.

If this is an empty Sequence, the API will not include HDD in any of its test regressions (unless requestedRegressionSpecs specifies any regressions with HDD in them).

property dayNormalization: DayNormalization

The DayNormalization to be used in the regression process.

property extraPredictorKeys: Collection[str]

The possibly-empty Collection of extra-predictor keys that this RegressionTestPlan has ExtraPredictorSpec objects for.

getExtraPredictorSpec(key: str) → ExtraPredictorSpec

Returns the ExtraPredictorSpec associated with the specified string key.

Parameters:

key (str) – a string extra-predictor key.

Raises:

• TypeError – if key is not a str.

• KeyError – if key isn’t associated with an ExtraPredictorSpec in this object.

property requestedRegressionSpecs: Collection[RegressionSpec]

A possibly-empty Collection of specifications for regressions that the API is specifically instructed to test and return (on top of any others that it will test and potentially return anyway).

property temperatureUnit: TemperatureUnit

The TemperatureUnit that specifies whether Celsius-based or Fahrenheit-based degree days should be used in regressions.