Amazon Forecast is no longer available to new customers. Existing customers of Amazon Forecast can continue to use the service as normal. [Learn more"](https://aws.amazon.com/blogs/machine-learning/transition-your-amazon-forecast-usage-to-amazon-sagemaker-canvas/)
# Getting Started
To get started using Amazon Forecast, you do the following.
+ Create a Forecast dataset and import training data.
+ Create a Forecast predictor, which you use generate forecasts based on your time-series data. Forecast applies the optimal combination of algorithms to each time series in your datasets.
+ Generate a forecast.
In this exercise, you use a modified version of a publicly available electricity usage dataset to train a predictor. For more information, see [ElectricityLoadDiagrams20112014 Data Set](https://archive.ics.uci.edu/ml/datasets/ElectricityLoadDiagrams20112014). The following are sample rows from the dataset:
```
2014-01-01 01:00:00, 2.53807106598985, client_0
2014-01-01 01:00:00, 23.648648648648624, client_1
2014-01-01 02:00:00, 9.648648648612345, client_0
```
For this exercise, you use the dataset to train a predictor, and then predict the hourly electricity usage by client.
You can use either the Forecast console or the AWS Command Line Interface (AWS CLI) for this exercise. Pay attention to the default regions of the Amazon Forecast console, the AWS CLI, and the Amazon Forecast SDKs, as Amazon Forecast resources are not shared across regions.
**Important**
Before you begin, make sure that you have an AWS account and have installed the AWS CLI. For more information, see [Setting Up](setup.md). We also recommend that you review [How Amazon Forecast Works](how-it-works.md).
**Topics**
+ [Prepare Input Data](#gs-upload-data-to-s3)
+ [Getting Started (Console)](gs-console.md)
+ [Getting Started (AWS CLI)](gs-cli.md)
+ [Getting Started (Python Notebooks)](getting-started-python.md)
+ [Clean Up Resources](#gs-cleanup)
## Prepare Input Data
Regardless of whether you use the Amazon Forecast console or the AWS Command Line Interface (AWS CLI) to set up a forecasting project, you need to set up your input data. To prepare your data, you do the following:
+ Download training data to your computer and upload it to an Amazon Simple Storage Service (Amazon S3) bucket in your AWS account. To import your data to an Amazon Forecast dataset, you must store it in an Amazon S3 bucket.
+ Create an AWS Identity and Access Management (IAM) role. You give Amazon Forecast permission to access your S3 bucket with the IAM role. For more information about IAM roles, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *IAM User Guide*.
**To prepare training data**
1. Download the zip file, [electricityusagedata.zip](samples/electricityusagedata.zip).
For this exercise, you use a modified version of the individual household electric power consumption dataset. (Dua, D. and Karra Taniskidou, E. (2017). UCI Machine Learning Repository [[http://archive.ics.uci.edu/ml](http://archive.ics.uci.edu/ml)]. Irvine, CA: University of California, School of Information and Computer Science.) We aggregate the usage data hourly.
1. Unzip the content and save it locally as `electricityusagedata.csv`.
1. Upload the data file to an S3 bucket.
For step-by-step instructions, see [Uploading Files and Folders by Using Drag and Drop](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html) in the *Amazon Simple Storage Service User Guide.*
1. Create an IAM role.
If you want to use the AWS CLI for the Getting Started exercise, you must create an IAM role. If you use the console, you can have it create the role for you. For step-by-step instructions, see [Set Up Permissions for Amazon Forecast](aws-forecast-iam-roles.md).
After you finish uploading the data to Amazon S3, you are ready to use the Amazon Forecast console or the AWS CLI to import training data, create a predictor, generate a forecast, and see the forecast.
+ [Getting Started (Console)](gs-console.md)
+ [Getting Started (AWS CLI)](gs-cli.md)
# Getting Started (Console)
In this exercise, you use the Amazon Forecast console to import time-series data of electricity usage, create an predictor based on the input dataset, and make predictions of future electricity usage based on the forecast horizon.
For this exercise, you use a modified version the individual household electric power consumption dataset. (Dua, D. and Karra Taniskidou, E. (2017). UCI Machine Learning Repository [[http://archive.ics.uci.edu/ml](http://archive.ics.uci.edu/ml)]. Irvine, CA: University of California, School of Information and Computer Science.) We aggregate the usage data hourly. The modified data is available as zip file, [electricityusagedata.zip](samples/electricityusagedata.zip).
**Prerequisites**
+ An AWS account. If you don't already have an AWS account, create one as described in [Sign Up for AWS](aws-forecast-set-up-aws-account.md).
+ Training data in your Amazon Simple Storage Service (Amazon S3) bucket. For more information, see [Prepare Input Data](getting-started.md#gs-upload-data-to-s3).
+ An AWS Identity and Access Management (IAM) role that allows Amazon Forecast to read and write to your S3 buckets. For more information, see [Create an IAM Role for Amazon Forecast (IAM Console)](aws-forecast-iam-roles.md#aws-forecast-create-iam-role-with-console).
Be aware that there are several steps in this exercise that require several minutes to a few hours to complete.
## Step 1: Import Training Data
To import time-series data into Amazon Forecast, create a dataset group, choose a domain for your dataset group, specify the details of your data, and point Amazon Forecast to the S3 location of your data. The target time series used in this example is [historical electricity usage](getting-started.md#gs-upload-data-to-s3) data.
**Note**
This exercise assumes that you have not created any dataset groups. If you previously created a dataset group, what you see will vary slightly from the following screenshots and instructions.
**To import time-series data for forecasting**
1. Open the Amazon Forecast console at [https://console.aws.amazon.com/forecast/](https://console.aws.amazon.com/forecast/).
1. On the Amazon Forecast home page, choose **Create dataset group**.
1. On the **Create dataset group** page, for **Dataset group details**, provide the following information:
+ **Dataset group name** – Enter a name for your dataset group.
+ **Forecasting domain** – From the drop-down menu, choose **Custom**. For more information about how to choose a forecasting domain, see [dataset domains and types](howitworks-domains-ds-types.md).
Leave the **Tags** section unchanged. Your screen should look similar to the following:
![\[Dataset group creation form with name field and forecasting domain dropdown.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step1-create-dsgroup.png)
1. Choose **Next**.
1. On the **Create target time series dataset** page, for **Dataset details**, provide the following information:
+ **Dataset name** – Enter a name for your dataset.
+ **Frequency of your data** – Keep the default value of **1**, and choose **hour** from the drop-down menu. This setting must be consistent with the input time series data. The time interval in the sample electricity-usage data is an hour.
+ **Data schema** – Choose **Schema builder** and drag the column components to match the time-series data order from top to bottom.
1. timestamp - Use the default **Timestamp Format** of **yyyy-MM-dd HH:mm:ss**.
1. target\$1value
1. item\$1id
For the electricity usage input data, the columns correspond to: a timestamp, the electricity usage at the specified time (target\$1value), and the ID of the customer charged for the electricity usage (string). The order of the columns and the timestamp format specified here must be consistent with the input time series data.
The **Dataset details** panel should look similar to the following:
![\[Dataset details form with name, frequency, and schema builder sections for data configuration.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step1-create-dataset.png)
1. For **Dataset import details**, provide the following information:
+ **Dataset import name** – Enter a name for your dataset.
+ **Select time zone** – Leave the default selected (**Do not use time zone**).
+ **Data location** – Use the following format to enter the location of your .csv file on Amazon S3:
**s3:////**
+ **IAM role** – Keep the default **Enter a custom IAM role ARN**.
Alternatively, you can have Amazon Forecast create the required IAM role for you by choosing **Create a new role** from the drop-down menu and following the on-screen instructions.
+ **Custom IAM role ARN** – Enter the Amazon Resource Name (ARN) of the IAM role that you created in [Create an IAM Role for Amazon Forecast (IAM Console)](aws-forecast-iam-roles.md#aws-forecast-create-iam-role-with-console).
The **Dataset import details** panel should look similar to the following:
![\[Dataset import details form with fields for name, time zone, data location, and IAM role.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step1-import-data.png)
1. Choose **Start**. If you are returned to the Amazon Forecast home page, choose **View dataset group**.
1. Click the name of the dataset group that you just created. The dataset group's **Dashboard** page is displayed. Your screen should look similar to the following:
![\[Dashboard overview showing steps: import data, train predictor, generate forecasts, explore insights.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step1-importing.png)
Next to **Target time series data**, you will see the status of the import job. Wait for Amazon Forecast to finish importing your time series data. The process can take several minutes or longer. When your dataset has been imported, the status transitions to **Active** and the banner at the top of the dashboard notifies you that you have successfully imported your data.
Now that your target time series dataset has been imported, you can create a predictor.
## Step 2: Create a predictor
Next you create a predictor, which you use to generate forecasts based on your time series data. Forecast applies the optimal combination of algorithms to each time series in your datasets
To create a predictor with the Forecast console, you specify a predictor name, a forecast frequency, and define a forecast horizon. For more information about the additional fields you can configure, see [Training Predictors](howitworks-predictor.md).
**To create a predictor**
1. After your target time series dataset has finished importing, your dataset group's **Dashboard** should look similar to the following:
![\[Dashboard overview showing steps: import data, train predictor, generate forecasts, explore insights.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step2-start.png)
Under **Train a predictor**, choose **Start**. The **Train predictor** page is displayed.
**Note**
The `Status` of the **Target time series data** must be `Active`, which signifies that the import successfully finished, before you can train the predictor.
1. On the **Train predictor** page, for **Predictor settings**, provide the following information:
+ **Predictor name** – Enter a name for your predictor.
+ **Forecast frequency** – Keep the default value of **1**. From the drop-down menu, choose **hour**. This setting must be consistent with the input time series data. The time interval in the sample electricity-usage data is an hour.
+ **Forecast horizon** – Choose how far into the future to make predictions. This number multiplied by the data entry frequency (`hourly`) that you specified in `Step 1: Import the Training Data` determines how far into the future to make predictions. For this exercise, set the number to `36`, to provide predictions for 36 hours.
+ **Forecast dimensions** and **Forecast quantiles** – Leave the default values for these fields.
The remaining **Input data configuration** and **Tags** sections are optional, so leave the default values. The **Predictor settings** sections should look similar to the following:
![\[Predictor settings interface showing name, forecast configuration, and quantile options.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step2-predictor-details.png)
1. Choose **Create**. Your dataset group's **Dashboard** page is displayed. Your screen should look similar to the following:
![\[Dashboard overview showing steps: import data, train predictor, generate forecasts, explore insights.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step2-predictor-dashboard.png)
1. To find the status of your predictor, choose **View predictors**.
1. On the **Predictors** page find the status of your predictor in the **Training status** column. Your screen should look similar to the following:
![\[Predictors page showing one predictor in progress with training status and other details.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step2-predictor-status.png)
Wait for Amazon Forecast to finish training the predictor. The process can take several minutes or longer. When your predictor has been trained, the status transitions to **Active** and a banner displays notifying you that you can start generating forecasts.
## Step 3: Create a Forecast
After your predictor is Active, you can create a forecast. A forecast is a group of predictions, one for every item in the target dataset. To retrieve the complete forecast, you create an export job.
**To get and view your forecast**
1. On your dataset group's **Dashboard**, under **Forecast generation**, choose **Start**. The **Create a forecast** page is displayed.
**Note**
The `Status` of **Predictor training** must be `Active` before you can generate a forecast.
1. On the **Create a forecast** page, for **Forecast details**, provide the following information:
+ **Forecast name** – Enter a name for your forecast.
+ **Predictor** – From the drop-down menu, choose the predictor that you created in `Step 2: Train a Predictor`.
The **Forecast quantiles** and **Tags** fields are optional, so leave the default value. Your screen should look similar to the following:
![\[Forecast details form with fields for name, predictor info, and optional forecast types.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step3-forecast-details.png)
Click **Start**.
1. The **Forecasts** page is displayed. Your screen should look similar to the following:
![\[Forecasts page interface showing a single forecast in progress with status and creation details.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step3-creating-forecast.png)
The **Status** column lists the status of your forecast.. Wait for Amazon Forecast to finish creating the forecast. The process can take several minutes or longer. When your forecast has been created, the status transitions to **Active**.
Now that your forecast has been created, you can export the forecast.
## Step 4: Exporting a Forecast
After the forecast has been created, you can export the complete forecast.
**To export the complete forecast**
1. On the dataset groups page, click the dataset group that you created in `Step 1: Import Training Data`.
1. Click ![\[Three horizontal lines representing a menu or navigation icon.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/menuNavPane.png) in the upper left corner of the screen to open the navigation pane. Under your dataset group, click **Forecasts**.
1. Choose the radio button next to the forecast that you created in `Step 3: Create a Forecast`.
1. Choose **Create forecast export**. The **Create forecast export** page is displayed.
1. On the **Create forecast export** page, for **Export details**, provide the following information.
+ **Export name** – Enter a name for your forecast export job.
+ **IAM role** – Keep the default **Enter a custom IAM role ARN**.
Alternatively, you can have Amazon Forecast create the required IAM role for you by choosing **Create a new role** from the drop-down menu and following the on-screen instructions.
+ **Custom IAM role ARN** – Enter the Amazon Resource Name (ARN) of the IAM role that you created in [Create an IAM Role for Amazon Forecast (IAM Console)](aws-forecast-iam-roles.md#aws-forecast-create-iam-role-with-console).
+ **S3 forecast export location** – Use the following format to enter the location of your Amazon Simple Storage Service (Amazon S3) bucket or folder in the bucket:
**s3:////**
Your screen should look similar to the following:
![\[Form for creating a forecast export with fields for export details and AWS configurations.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/createForecastExport.png)
1. Click **Start**. The **Forecasts** page is displayed.
1. Click the forecast that you created in `Step 3: Create a Forecast`. Find the **Exports** section. Your screen should look similar to the following:
![\[Exports section showing a single forecast export job in progress with location and creation date.\]](http://docs.aws.amazon.com/forecast/latest/dg/images/gs-step4-exporting.png)
You should see the status progress. Wait for Amazon Forecast to finish exporting the forecast. The process can take several minutes or longer. When your forecast has been exported, the status transitions to **Active** and you can find the forecast files in your S3 bucket.
# Getting Started (AWS CLI)
In this exercise, you use the AWS Command Line Interface (AWS CLI) to explore Amazon Forecast. You create an Amazon Forecast dataset, train an predictor, and use the resulting predictor to generate a forecast. Before you begin, make sure that you have an AWS account and that you've set up the AWS CLI. For more information, see [Setting Up](setup.md).
**Note**
The AWS CLI commands in this exercise were tested on Linux. For information about using the AWS CLI commands on Windows, see [Specifying Parameter Values for the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html) in the *AWS Command Line Interface User Guide*.
## Step 1: Import Training Data
Begin by creating a dataset and importing the electricity usage data into it.
**To create an Amazon Forecast dataset**
1. Decide which domain and dataset type is appropriate.
The training data that you will import into the dataset influences your choice of dataset domain and type. So, let's review a few sample rows of the electricity usage data.
```
2014-01-01 01:00:00, 2.53807106598985, client_0
2014-01-01 01:00:00, 23.648648648648624, client_1
2014-01-01 02:00:00, 9.648648648612345, client_0
```
The data format is CSV (comma-separated values), and it's collected hourly (as shown by the timestamps). It includes these columns:
+ Column 1 – Timestamps that show when electricity usage was recorded.
+ Column 2 – Hourly electricity usage values (note how the timestamp values increase by hour).
+ Column 3 – Client ID values that identify the customers using the electricity.
For this data, choose the following predefined dataset domain and dataset type:
+ Custom domain – None of the dataset domains, such as METRICS, RETAIL, or WEB\$1TRAFFIC, applies to this data, so choose the Custom domain.
+ Target time series type – The data is a time series because it tracks electricity usage over time. It also includes the *target* that we want to forecast (Column 2, electricity usage). Therefore, choose the target time series dataset type.
To understand why you choose this type, see [Predefined Dataset Domains and Dataset Types](howitworks-domains-ds-types.md).
1. Decide on a dataset schema.
The target time series type for the [CUSTOM Domain](custom-domain.md) requires these fields; `timestamp`, `target_value`, and `item_id`. The `target_value` field is the target. Amazon Forecast generates the forecast for this field.
To map the required fields to columns in your data, you create a schema. Each *attribute* in the schema maps to a field in the data.
**Important**
The order of attributes in the schema must match the order of fields in the training data.
```
{
"Attributes":[
{
"AttributeName": "timestamp",
"AttributeType": "timestamp"
},
{
"AttributeName": "target_value",
"AttributeType": "float"
},
{
"AttributeName": "item_id",
"AttributeType": "string"
}
]
}
```
You now have the information necessary to create a dataset and import data into it.
1. Create the dataset.
```
aws forecast create-dataset \
--dataset-name electricity_demand_ds \
--domain CUSTOM \
--dataset-type TARGET_TIME_SERIES \
--data-frequency H \
--schema '{
"Attributes": [
{
"AttributeName": "timestamp",
"AttributeType": "timestamp"
},
{
"AttributeName": "target_value",
"AttributeType": "float"
},
{
"AttributeName": "item_id",
"AttributeType": "string"
}
]
}'
```
In the request, the `data-frequency` value `H` represents a data collection frequency of hourly. The following is an example response.
```
{
"DatasetArn": "arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds"
}
```
For more information about this operation, see [CreateDataset](API_CreateDataset.md).
1. (Optional) Get the description of the dataset.
```
aws forecast describe-dataset \
--dataset-arn arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds
```
The following is an example response.
```
{
"DatasetName": "electricity_demand_ds",
"DatasetArn": "arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds",
"CreationTime": 1564533087.907,
"LastModificationTime": 1564533087.907,
"Domain": "CUSTOM",
"DatasetType": "TARGET_TIME_SERIES",
"DataFrequency": "H",
"Schema": { ... },
"EncryptionConfig": {},
"Status": "ACTIVE"
}
```
**Note**
The order of the key-value pairs in the response is arbitrary.
1. Create a dataset group and add the dataset to it. The value of the `domain` parameter must match the `domain` of the dataset.
```
aws forecast create-dataset-group \
--dataset-group-name electricity_ds_group \
--dataset-arns arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds \
--domain CUSTOM
```
The following is an example response.
```
{
"DatasetGroupArn": "arn:aws:forecast:us-west-2:acct-id:dataset-group/electricity_ds_group"
}
```
For more information about this operation, see [CreateDatasetGroup](API_CreateDatasetGroup.md).
1. (Optional) Get the description of the dataset group.
```
aws forecast describe-dataset-group \
--dataset-group-arn arn:aws:forecast:us-west-2:acct-id:dataset-group/electricity_ds_group
```
The following is an example response.
```
{
"DatasetGroupName": "electricity_ds_group",
"DatasetGroupArn": "arn:aws:forecast:us-west-2:acct-id:dataset-group/electricity_ds_group",
"DatasetArns": [
"arn:aws:forecast:us-west-2:acct-id:dataset-group/electricity_ds_group"
],
"Domain": "CUSTOM",
"CreationTime": 1564533719.852,
"LastModificationTime": 1564533719.852,
"Status": "ACTIVE"
}
```
1. Import the electricity usage training data from your Amazon S3 bucket to the dataset. The IAM role that you provide must have permission to read data from your S3 bucket. For information on how to create an IAM role, see [Create an IAM Role for Amazon Forecast (AWS CLI)](aws-forecast-iam-roles.md#aws-forecast-create-iam-role-with-cli).
```
aws forecast create-dataset-import-job \
--dataset-arn arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds \
--dataset-import-job-name electricity_ds_import_job \
--data-source '{
"S3Config": {
"Path": "s3://bucket/electricityusagedata.csv",
"RoleArn": "arn:aws:iam::acct-id:role/Role"
}
}'
```
The following is the shorthand syntax for the `data-source` parameter.
```
--data-source S3Config="{Path='s3://bucket/electricityusagedata.csv',RoleArn='arn:aws:iam::acct-id:role/Role'}"
```
The following is an example response.
```
{
"DatasetImportJobArn": "arn:aws:forecast:us-west-2:acct-id:dataset-import-job/electricity_demand_ds/electricity_ds_import_job"
}
```
For more information about this operation, see [CreateDatasetImportJob](API_CreateDatasetImportJob.md).
1. Check the import status.
```
aws forecast describe-dataset-import-job \
--dataset-import-job-arn arn:aws:forecast:us-west-2:acct-id:dataset-import-job/electricity_demand_ds/electricity_ds_import_job
```
The following is an example response.
```
{
"DatasetImportJobName": "electricity_ds_import_job",
"DatasetImportJobArn": "arn:aws:forecast:us-west-2:acct-id:dataset-import-job/electricity_demand_ds/electricity_ds_import_job",
"DatasetArn": "arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds",
"DataSource": {
"S3Config": {
"Path": "s3://bucket/electricityusagedata.csv",
"RoleArn": "arn:aws:iam::acct-id:role/ForecastRole"
}
},
"DataSize": 0.14639010466635227,
"TimeStampFormat": "yyyy-MM-dd HH:mm:ss",
"CreationTime": 1564537011.114,
"LastModificationTime": 1564537028.223,
"Status": "CREATE_IN_PROGRESS"
}
```
When all of the data has been imported, the status changes to ACTIVE and the response includes statistics for the data, as shown in the following example.
```
{
"DatasetArn": "arn:aws:forecast:us-west-2:acct-id:dataset/electricity_demand_ds",
"Status": "ACTIVE",
"FieldStatistics": {
"date": {
"Min": "2014-01-01T01:00:00Z",
"Max": "2015-01-01T00:00:00Z",
"Count": 3241200,
"CountDistinct": 8760,
"CountNull": 0
},
"target": {
"Min": "0.0",
"Max": "168200.0",
"Avg": 606.5167610461679,
"Stddev": 3518.405223972031,
"Count": 3241200,
"CountDistinct": 1196961,
"CountNull": 0,
"CountNan": 0
},
"item": {
"Count": 3241200,
"CountDistinct": 370,
"CountNull": 0
}
},
...
}
```
**Important**
You must wait until the status is ACTIVE before creating a predictor with the dataset group.
For more information about this operation, see [DescribeDatasetImportJob](API_DescribeDatasetImportJob.md).
## Step 2: Create a Predictor
To create a predictor, you use the [CreateAutoPredictor](API_CreateAutoPredictor.md) operation and provide the following information.
+ **Predictor name** – Give the predictor a name so you can distinguish it from your other predictors
+ **Dataset group** – You created the dataset group in the preceding step.
+ **Forecast frequency** – The granularity of your forecasts (hourly, daily, weekly, etc).
+ **Forecast horizon** – The number of time steps being forecasted.
After the predictor is created, you review the accuracy metrics generated by Amazon Forecast. The metrics help you decide whether to use the predictor for generating a forecast. For more information about predictors, see [Training Predictors](howitworks-predictor.md).
**To create a predictor and review the accuracy metrics**
1. Create the predictor.
```
aws forecast create-predictor \
--predictor-name electricitypredictor \
--input-data-config DatasetGroupArn="arn:aws:forecast:us-west-2:acct-id:dsgroup/electricity_ds_group" \
--forecast-horizon 36 \
--forecast-frequency D
```
The following is an example response.
```
{
"PredictorArn": "arn:aws:forecast:us-west-2:acct-id:predictor/electricitypredictor"
}
```
1. Get the predictor's status.
```
aws forecast describe-predictor \
--predictor-arn arn:aws:forecast:us-west-2:acct-id:predictor/electricitypredictor
```
The following is an example response.
```
{
"PredictorArn": "arn:aws:forecast:::predictor/electricitypredictor",
"PredictorName": "electricitypredictor",
"ForecastHorizon": 36,
"ForecastTypes": [
"0.1",
"0.5",
"0.9"
],
"ForecastFrequency": "D",
"DatasetImportJobArns": [
"arn:aws:forecast:::dataset-import-job/getting_started_dataset/gs_import"
],
"DataConfig": {
"DatasetGroupArn": "arn:aws:forecast:::dataset-group/getting_started",
"AttributeConfigs": [
{
"AttributeName": "target_value",
"Transformations": {
"aggregation": "sum",
"backfill": "zero",
"frontfill": "none",
"middlefill": "zero"
}
}
]
},
"EstimatedTimeRemainingInMinutes": 97,
"Status": "CREATE_IN_PROGRESS",
"CreationTime": "2022-02-23T09:26:24.643000-08:00",
"LastModificationTime": "2022-02-23T09:49:26.899000-08:00",
"ExplainabilityInfo": {
"Status": "NOT_AVAILABLE"
}
}
```
**Important**
Model training takes time. Don't proceed until training has completed and the status of the predictor is ACTIVE.
1. Get the accuracy metrics for the predictor.
```
aws forecast get-accuracy-metrics \
--predictor-arn arn:aws:forecast:us-west-2:acct-id:predictor/electricitypredictor
```
The following is an example response.
```
{
"PredictorEvaluationResults": [
{
"TestWindows": [
{
"EvaluationType": "SUMMARY",
"Metrics": {
"RMSE": 448.19602551622864,
"WeightedQuantileLosses": [
{
"Quantile": 0.9,
"LossValue": 0.11574311406253326
},
{
"Quantile": 0.5,
"LossValue": 0.1706269067283527
},
{
"Quantile": 0.1,
"LossValue": 0.11724164222477837
}
]
}
},
{
"EvaluationType": "COMPUTED",
"Metrics": {
"RMSE": 448.19602551622864,
"WeightedQuantileLosses": [
{
"Quantile": 0.9,
"LossValue": 0.11574311406253326
},
{
"Quantile": 0.5,
"LossValue": 0.1706269067283527
},
{
"Quantile": 0.1,
"LossValue": 0.11724164222477837
}
]
},
"TestWindowEnd": 1420070400.0,
"TestWindowStart": 1420002000.0
}
]
}
]
}
```
The metrics show the error loss for each quantile. For example, there was an 11.7% error for the first quantile. The metrics also show the root-mean-square error (`RMSE`).
The summary metrics show the average of the computed metrics over all test windows. Because there was only one test window, the summary and computed metrics are equal.
For more information about this operation, see [GetAccuracyMetrics](API_GetAccuracyMetrics.md).
## Step 3: Create a Forecast
Amazon Forecast creates a forecast for the `target_value` field (as determined by the dataset domain and type) for each unique `item_id` in the dataset. In this exercise, the `target_value` field provides electricity usage and the `item_id` provides client IDs. You get a forecast for the hourly electricity usage by customer.
After the forecast has been created, you can query for a single item or export the complete forecast.
**To create, retrieve, and export a forecast**
1. Create the forecast.
```
aws forecast create-forecast \
--forecast-name electricityforecast \
--predictor-arn arn:aws:forecast:us-west-2:acct-id:predictor/electricitypredictor
```
The operation uses the predictor to create a forecast. In the response, you get the Amazon Resource Name (ARN) of the forecast. You use this ARN to retrieve and export the forecast. The following is an example response.
```
{
"ForecastArn": "arn:aws:forecast:us-west-2:acct-id:forecast/electricityforecast"
}
```
For more information about this operation, see [CreateForecast](API_CreateForecast.md).
1. Retrieve the first two hours of the forecast for `client_1`.
**Note**
The service name, `forecastquery`, is different then the service name used elsewhere.
```
aws forecastquery query-forecast \
--forecast-arn arn:aws:forecast:us-west-2:acct-id:forecast/electricityforecast \
--start-date 2015-01-01T00:00:00 \
--end-date 2015-01-01T02:00:00 \
--filters '{"item_id":"client_1"}'
```
The operation includes the following parameters.
+ `start-date` and `end-date` – Specifies an optional date range to retrieve the forecast for. If you don't specify these parameters, the operation returns the entire forecast for `client_1`.
+ `filters` – Specifies the `item_id` filter to retrieve the electricity forecast for `client_1`.
The following is the shorthand syntax for the `filters` parameter.
```
--filters item_id="client_1"
```
The following is an example response.
```
{
"Forecast": {
"Predictions": {
"mean": [
{
"Timestamp": "2015-01-01T01:00:00",
"Value": 20.952411651611328
},
{
"Timestamp": "2015-01-01T02:00:00",
"Value": 19.11078453063965
}
],
"p90": [
{
"Timestamp": "2015-01-01T01:00:00",
"Value": 24.524038314819336
},
{
"Timestamp": "2015-01-01T02:00:00",
"Value": 22.319091796875
}
],
"p50": [
{
"Timestamp": "2015-01-01T01:00:00",
"Value": 20.7841739654541
},
{
"Timestamp": "2015-01-01T02:00:00",
"Value": 19.237524032592773
}
],
"p10": [
{
"Timestamp": "2015-01-01T01:00:00",
"Value": 18.507278442382812
},
{
"Timestamp": "2015-01-01T02:00:00",
"Value": 16.15062141418457
}
]
}
}
}
```
Because this is an hourly forecast, the response shows hourly forecast values. In the response, note the following:
+ `mean` – For the specific date and time, the mean is the predicted mean electricity usage value for the customer.
+ `p90`, `p50`, and `p10` – Specify the confidence level that the actual value will be below the listed value at the specified date and time. For example, at 2015-01-01T01:00:00, Amazon Forecast is 90% confident that the electric usage will be below 24.5. Amazon Forecast is 50% confident that usage will be below 20.8, and 10% confident that usage will be below 18.5.
For more information about this operation, see [QueryForecast](API_forecastquery_QueryForecast.md).
1. Export the complete forecast to your Amazon S3 bucket. The IAM role that you provide must have permission to write data to your S3 bucket. For information on how to create an IAM role, see [Create an IAM Role for Amazon Forecast (AWS CLI)](aws-forecast-iam-roles.md#aws-forecast-create-iam-role-with-cli).
Create a forecast export job.
```
aws forecast create-forecast-export-job \
--forecast-export-job-name electricityforecast_exportjob \
--forecast-arn arn:aws:forecast:us-west-2:acct-id:forecast/electricityforecast \
--destination S3Config="{Path='s3://bucket',RoleArn='arn:aws:iam::acct-id:role/Role'}"
```
The following is an example response.
```
{
"ForecastExportJobArn": "arn:aws:forecast::us-west-2:acct-id:forecast-export/64bbc087"
}
```
For more information about this operation, see [CreateForecastExportJob](API_CreateForecastExportJob.md).
1. Get the status of the export job.
```
aws forecast describe-forecast-export-job \
--forecast-export-job-arn arn:aws:forecast:us-west-2:acct-id:forecast/electricityforecast
```
The following is an example response.
```
{
"ForecastExportJobArn": "arn:aws:forecast::us-west-2:acct-id:forecast-export/64bbc087",
"ForecastExportJobName": "electricityforecast_exportjob",
"Status": "CREATE_IN_PROGRESS"
}
```
When the status is ACTIVE, you can find the forecast files in the specified S3 bucket.
# Getting Started (Python Notebooks)
**Note**
For a complete list of tutorials using Python notebooks, see the Amazon Forecast [Github Samples](https://github.com/aws-samples/amazon-forecast-samples/tree/master/notebooks) page.
To get started using Amazon Forecast APIs with Python notebooks, see the [Getting Started Tutorial](https://github.com/aws-samples/amazon-forecast-samples/blob/main/notebooks/basic/Getting_Started/Amazon_Forecast_Quick_Start_Guide.ipynb). The tutorial guides you through the core steps of Forecast from start to finish.
For basic tutorials for specific processes, refer to the following Python notebooks:
1. [Preparing data](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/basic/Tutorial/1.Importing_Your_Data.ipynb) - Prepare a dataset, create a dataset group, define the schema, and import the dataset group.
1. [Building your predictor](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/basic/Tutorial/2.Building_Your_Predictor.ipynb) - Train a predictor on the data you imported into your Forecast dataset.
1. [Evaluating predictors](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/basic/Tutorial/3.Evaluating_Your_Predictor.ipynb) - Obtain predictions, visualize predictions, and compare results.
1. [Retraining predictors](https://github.com/aws-samples/amazon-forecast-samples/blob/main/notebooks/advanced/Retraining_AutoPredictor/Retraining.ipynb) - Retrain an existing predictor with updated data.
1. [Upgrade to AutoPredictor](https://github.com/aws-samples/amazon-forecast-samples/blob/main/notebooks/basic/Upgrading_to_AutoPredictor/UpgradeToAutoPredictor.ipynb) - Upgrade legacy predictors to AutoPredictor.
1. [Clean Up](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/basic/Tutorial/4.Cleanup.ipynb) - Delete the dataset groups, predictors, forecasts created during the tutorials.
To repeat the Getting Started tutorial with AutoML, see [Getting Started with AutoML](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/Getting_started_with_AutoML/Getting_started_with_AutoML.ipynb).
## Advanced Tutorials
For more advanced tutorials, refer to the following Python notebooks:
+ [Item-level Explainability](https://github.com/aws-samples/amazon-forecast-samples/blob/main/notebooks/advanced/Item_Level_Explainability/Item_Level_Explanability.ipynb) - Understand how dataset attributes impact forecasts for specific time series and time points.
+ [Comparing multiple models ](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/Compare_Multiple_Models/Compare_Multiple_Models.ipynb) - Create predictors using Prophet, ETS, and DeepAR\$1, and compare their performances by visualizing the results.
+ [Cold start forecasting](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/Forecast%20with%20Cold%20Start%20Items/Forecast%20with%20Cold%20Start%20Items.ipynb) - Use item metadata and the DeepAR\$1 algorithm to forecast for cold-start scenarios (when there is little to no historical data).
+ [Incorporating related time-series datasets](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/Incorporating_Related_Time_Series_dataset_to_your_Predictor/Incorporating_Related_Time_Series_dataset_to_your_Predictor.ipynb) - Use related time-series datasets to improve the accuracy of your model.
+ [Incorporating item metadata](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/Incorporating_Item_Metadata_Dataset_to_your_Predictor/Incorporating_Item_Metadata_Dataset_to_your_Predictor.ipynb) - Use item metadata to improve the accuracy of your model.
+ [Using the Weather Index](https://github.com/aws-samples/amazon-forecast-samples/tree/master/notebooks/advanced/Weather_index) - Use the Weather Index to incorporate historical and projected weather information when training your predictors.
+ [Performing What-if analysis](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/WhatIf_Analysis/WhatIf_Analysis.ipynb) - Explore different pricing scenarios and evaluate how it impacts demand.
+ [Evaluate item-level accuracy](https://github.com/aws-samples/amazon-forecast-samples/blob/master/notebooks/advanced/Item_Level_Accuracy/Item_Level_Accuracy_Using_Bike_Example.ipynb) - Export backtest metrics and forecasts, and evaluate the item-level performance of your predictor.
## Clean Up Resources
To avoid incurring unnecessary charges, delete the resources you created after you're done with the getting started exercise. To delete the resources, use either the Amazon Forecast console or the `Delete` APIs from the SDKs or the AWS Command Line Interface (AWS CLI). For example, use the [DeleteDataset](API_DeleteDataset.md) API to delete a dataset.
To delete a resource, its status must be `ACTIVE`, `CREATE_FAILED`, or `UPDATE_FAILED`. Check the status using the `Describe` APIs, for example, [DescribeDataset](API_DescribeDataset.md).
Some resources must be deleted before others, as shown in the following table. This process can take some time.
To delete the training data you uploaded, ` electricityusagedata.csv`, see [How Do I Delete Objects from an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-objects.html).
| Resource to Delete | Delete This First | Notes |
| --- | --- | --- |
| ForecastExportJob | | |
| Forecast | | You can't delete a forecast while it is being exported. After a forecast is deleted, you can no longer query the forecast. |
| Predictor | All associated forecasts. | |
| DatasetImportJob | | Can not be deleted. |
| Dataset | | All `DatasetImportJob`s that target the dataset are also deleted. You can't delete a `Dataset` that is used by a predictor. |
| DatasetSchema | All datasets that reference the schema. | |
| DatasetGroup | All associated predictorsAll associated forecasts.All datasets in the dataset group. | You can't delete a `DatasetGroup` that contains a `Dataset` used by a predictor. |