Amazon Forecast
Developer Guide

This is prerelease documentation for a service in preview release. It is subject to change.

As of 6/6/19, Amazon Forecast no longer supports the following recipes: DeepAR, MDN, MLP, MQRNN, RFQR, and SQF. You can continue to use predictors created with these recipes to generate forecasts. However, you can’t use these recipes to create new predictors or to update existing predictors with new data. In addition, AutoML no longer considers these recipes. We’ve made these changes to ensure that Forecast offers the highest level of accuracy and robustness. We continue to support the ARIMA, DeepAR+, ETS, NPTS, and Prophet recipes.

CreatePredictor

Creates an Amazon Forecast predictor.

In the request, you provide a dataset group and either specify a recipe or let Amazon Forecast choose the recipe for you. The operation uses the algorithm described in the recipe to train a model using the latest version of the datasets in the specified dataset group. The result is called a predictor. In the response, the operation returns a predictor version ID. You can deploy the predictor to generate a forecast using the DeployPredictor operation.

In the CreatePredictor request, you can also do the following:

  • Override algorithm-specific hyperparameters

  • Specify a schedule for automatically retraining models

  • Specify a holiday calendar for various countries

To modify these values later, use the UpdatePredictor operation.

After creating a predictor, you can retrain the model and create a new version of the predictor with the RetrainPredictor operation.

After training a model, the CreatePredictor operation also evaluates it. To see the evaluation metrics, use the GetAccuracyMetrics operation. Always review the evaluation metrics before deciding to use the predictor to generate forecasts.

For more information about creating and deploying Amazon Forecast predictors, see Predictors.

Request Syntax

{ "DatasetGroupName": "string", "ForecastHorizon": number, "ForecastParameters": { "string" : "string" }, "HPOConfig": { "HyperParameterTuningJobObjective": { "MetricName": "string", "Type": "string" }, "ParameterRanges": { "CategoricalParameterRanges": [ { "Name": "string", "Values": [ "string" ] } ], "ContinuousParameterRanges": [ { "MaxValue": "string", "MinValue": "string", "Name": "string" } ], "IntegerParameterRanges": [ { "MaxValue": "string", "MinValue": "string", "Name": "string" } ] }, "ResourceLimits": { "MaxNumberOfTrainingJobs": number, "MaxParallelTrainingJobs": number }, "StaticHyperParameters": { "string" : "string" }, "Strategy": "string" }, "PerformAutoML": "string", "PerformHPO": "string", "PredictorName": "string", "RecipeName": "string", "RecipeParameters": { "BackTestWindowCount": number, "BackTestWindowOffset": number, "DefaultTrainingSubsampleRatio": number, "GroupByForecastKeys": [ "string" ], "HolidayCalendarName": "string", "MetricsBuckets": [ "string" ] }, "ScheduleExpression": "string", "TrainingParameters": { "string" : "string" } }

Request Parameters

The request accepts the following data in JSON format.

DatasetGroupName

The name of the dataset group to use for model training.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\_]+$

Required: Yes

ForecastHorizon

Specifies the number of forecasts to make. The forecast horizon is also called the prediction length.

For example, if you configure a dataset for daily data collection (using the DataFrequency parameter of the CreateDataset operation) and set the forecast horizon to 10, the model returns forecasts for 10 days.

Type: Integer

Required: Yes

ForecastParameters

The forecast parameters to override when running inference to generate a forecast.

If the specified recipe has multiple algorithms and you want to override a hyperparameter for a specific algorithm, specify algorithm.hyperparameter:value. If a recipe has only one algorithm or if you want to override the hyperparameter in all of the recipe's algorithms, specify hyperparameter:value.

Type: String to string map

Key Length Constraints: Maximum length of 256.

Key Pattern: ^[a-zA-Z0-9\-\_\.\/\[\]\,\\]+$

Value Length Constraints: Maximum length of 256.

Value Pattern: ^[a-zA-Z0-9\-\_\.\/\[\]\,\"\\\s]+$

Required: No

HPOConfig

Provides hyperparameter override values for the algorithm in the specified recipe. If you don't provide this parameter, Amazon Forecast uses default values.

Type: HyperParameterTuningJobConfig object

Required: No

PerformAutoML

The default value is N. You are required to choose a recipe.

If you want Amazon Forecast to evaluate the recipes it provides (not custom recipes) and choose the best recipe and configuration for your training dataset, set PerformAutoML to Y. This is a good option if you aren't sure which recipe is suitable for your application.

Type: String

Valid Values: Y | N

Required: No

PerformHPO

Whether to perform hyperparameter optimization. The default value is Y.

A hyperparameter tuning job finds optimal hyperparameter values for your training data. If you specify HPOConfig, the tuning job works on the ranges that you provide. Otherwise, it works with the default hyperparameter ranges.

The following recipes support HPO:

  • DeepAR+

Type: String

Valid Values: Y | N

Required: No

PredictorName

A name for the new predictor.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\_]+$

Required: Yes

RecipeName

The name of the recipe to use for model training. If PerformAutoML is set to N, if you must specify the recipe name.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\_]+$

Required: No

RecipeParameters

Overrides recipe parameters.

BackTestWindowCount parameter - If BackTestWindowCount isn't specified, Amazon Forecast uses the value from the chosen recipe. If BackTestWindowCount isn't specified in the recipe, Amazon Forecast returns an error.

BackTestWindowOffset parameter - If BackTestWindowOffset isn't specified, Amazon Forecast uses the value from the chosen recipe. If BackTestWindowOffset isn't specified in the recipe, Amazon Forecast determines the value as follows:

  • If MinTimeseriesLength >= (2 * BackTestWindowCount * ForecastHorizon),

    then BackTestWindowOffset = ForecastHorizon.

  • If MinTimeseriesLength < (2 * BackTestWindowCount * ForecastHorizon),

    then the dataset is too small to use ForecastHorizon as an offset,

    and BackTestWindowOffset = MinTimeseriesLength / (2 * BackTestWindowCount).

MinTimeseriesLength is the minimum timeseries length in the dataset, computed during dataset import.

Type: RecipeParameters object

Required: No

ScheduleExpression

Specifies a schedule for retraining the model.

Specify this value as an Amazon CloudWatch cron expression. For more information, see Cron Expressions in the Amazon CloudWatch User Guide.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\_\*\?\,\|\^\-\/\#\s\(\)\+]+$

Required: No

TrainingParameters

The training parameters to override for model training. The parameters that you can override are listed in the individual recipes in Choosing an Amazon Forecast Recipe.

Type: String to string map

Key Length Constraints: Maximum length of 256.

Key Pattern: ^[a-zA-Z0-9\-\_\.\/\[\]\,\\]+$

Value Length Constraints: Maximum length of 256.

Value Pattern: ^[a-zA-Z0-9\-\_\.\/\[\]\,\"\\\s]+$

Required: No

Response Syntax

{ "PredictorArn": "string", "PredictorName": "string", "VersionId": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

PredictorArn

The Amazon Resource Name (ARN) of the predictor.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\-\_\.\/\:]+$

PredictorName

The name of the predictor.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\_]+$

VersionId

The version ID of the predictor.

Type: String

Length Constraints: Maximum length of 256.

Pattern: ^[a-zA-Z0-9\_]+$

Errors

InternalServiceException

Request processing has failed due to some unknown error, exception, or failure.

HTTP Status Code: 400

InvalidInputException

We can't process the request because it includes an invalid value or a value that exceeds the valid range.

HTTP Status Code: 400

InvalidStateException

Processing has reached an invalid state. Amazon Forecast returns this exception when an operation attempts to perform an action on a resource that is changing.

HTTP Status Code: 400

QuotaLimitExceededException

You have exceeded the quota limits for resources that are long-running jobs, such as import jobs, create predictors, and forecasts. You might also be creating too many resources concurrently, in which case, you might wait for resources to be created and try again.

HTTP Status Code: 400

ResourceAlreadyExistsException

There is already a resource with this name and characteristics. Try again with different settings.

HTTP Status Code: 400

ResourceNotFoundException

We can't find a resource with that name. Check the name and try again.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: