net.degreedays.api.regression

Class RegressionApi

java.lang.Object

net.degreedays.api.regression.RegressionApi

public final class RegressionApi
extends java.lang.Object

Provides easy, type-safe access to the API's regression-related operations.

Creating a RegressionApi object

Instead of creating a RegressionApi instance directly, you would typically create a DegreeDaysApi object and get a RegressionApi from that with DegreeDaysApi.regressionApi(). Although the only state of a RegressionApi object is the RequestProcessor passed into its constructor, so, if you have a RequestProcessor, there's no reason not to create a RegressionApi object directly if doing it that way makes sense for your app.

Example code for running regressions

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

Since:

1.4

See Also:

runRegressions(RegressionRequest)

This class is designed to be safe for use from multiple concurrent threads. However, if you create a customized instance of this class (using a RequestProcessor that you have written or customized), then the thread-safety of its operation will depend on the thread-safety of that RequestProcessor.

Constructor Summary

Constructors

Constructor and Description
RegressionApi(RequestProcessor requestProcessor) Constructs a RegressionApi object that uses the specified RequestProcessor internally.

Method Summary

Modifier and Type	Method and Description
RegressionResponse	runRegressions(RegressionRequest request) Sends your RegressionRequest to the API servers so it can run regressions against your InputData and return a non-null RegressionResponse containing the regressions that were statistically best and/or any that you specifically requested.

Methods inherited from class java.lang.Object

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

Constructor Detail

RegressionApi

public RegressionApi(RequestProcessor requestProcessor)

Constructs a RegressionApi object that uses the specified RequestProcessor internally.

Parameters:

requestProcessor - the non-null RequestProcessor that the new RegressionApi object should use internally for its processing.

Throws:

java.lang.NullPointerException - if requestProcessor is null.

Method Detail

runRegressions

public RegressionResponse runRegressions(RegressionRequest request)

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

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 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 (more on these here), or a GeographicLocation for which no active station can be found with enough data to run regressions against your InputData, you will get a LocationException 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.sampleSize() and the Regression.sampleSpan() of any Regression in the response (comparing with InputData.periodCount() and InputData.fullRange()) 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, with a minimum DayRange that also specifies that same 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).

Parameters:

request - a 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. Cannot be null.

Returns:

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

Throws:

LocationException - if the request fails because of problems relating to the specified Location.

ServiceException - if the request fails because of a problem with the API service (sorry!).

RateLimitException - if you hit the RateLimit for your account's plan, and need to wait a little while before it's reset.

InvalidRequestException - if the request that is sent to the API servers is invalid (e.g. if it is authenticated with invalid API access keys or because regression is not available on the current API account plan).

TransportException - if there's a problem sending the request to the API servers, or a problem getting the API's response back.

DegreeDaysApiException - the superclass of all the exceptions listed above.

java.lang.NullPointerException - if request is null.

See Also:

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