2022/08/22 - Amazon Forecast Service - 12 new api methods
Changes releasing What-If Analysis APIs and update ARN regex pattern to be more strict in accordance with security recommendation
Describes the what-if analysis created using the CreateWhatIfAnalysis operation.
In addition to listing the properties provided in the CreateWhatIfAnalysis request, this operation lists the following properties:
CreationTime
LastModificationTime
Message - If an error occurred, information about the error.
Status
See also: AWS API Documentation
Request Syntax
client.describe_what_if_analysis(
WhatIfAnalysisArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if analysis that you are interested in.
dict
Response Syntax
{
'WhatIfAnalysisName': 'string',
'WhatIfAnalysisArn': 'string',
'ForecastArn': 'string',
'EstimatedTimeRemainingInMinutes': 123,
'Status': 'string',
'Message': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastModificationTime': datetime(2015, 1, 1),
'TimeSeriesSelector': {
'TimeSeriesIdentifiers': {
'DataSource': {
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
}
},
'Schema': {
'Attributes': [
{
'AttributeName': 'string',
'AttributeType': 'string'|'integer'|'float'|'timestamp'|'geolocation'
},
]
},
'Format': 'string'
}
}
}
Response Structure
(dict) --
WhatIfAnalysisName (string) --
The name of the what-if analysis.
WhatIfAnalysisArn (string) --
The Amazon Resource Name (ARN) of the what-if analysis.
ForecastArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast.
EstimatedTimeRemainingInMinutes (integer) --
The approximate time remaining to complete the what-if analysis, in minutes.
Status (string) --
The status of the what-if analysis. States include:
ACTIVE
CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED
CREATE_STOPPING, CREATE_STOPPED
DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED
Message (string) --
If an error occurred, an informational message about the error.
CreationTime (datetime) --
When the what-if analysis was created.
LastModificationTime (datetime) --
The last time the resource was modified. The timestamp depends on the status of the job:
CREATE_PENDING - The CreationTime.
CREATE_IN_PROGRESS - The current timestamp.
CREATE_STOPPING - The current timestamp.
CREATE_STOPPED - When the job stopped.
ACTIVE or CREATE_FAILED - When the job finished or failed.
TimeSeriesSelector (dict) --
Defines the set of time series that are used to create the forecasts in a TimeSeriesIdentifiers object.
The TimeSeriesIdentifiers object needs the following information:
DataSource
Format
Schema
TimeSeriesIdentifiers (dict) --
Details about the import file that contains the time series for which you want to create forecasts.
DataSource (dict) --
The source of your data, an AWS Identity and Access Management (IAM) role that allows Amazon Forecast to access the data and, optionally, an AWS Key Management Service (KMS) key.
S3Config (dict) --
The path to the data stored in an Amazon Simple Storage Service (Amazon S3) bucket along with the credentials to access the data.
Path (string) --
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) --
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
Schema (dict) --
Defines the fields of a dataset.
Attributes (list) --
An array of attributes specifying the name and type of each field in a dataset.
(dict) --
An attribute of a schema, which defines a dataset field. A schema attribute is required for every field in a dataset. The Schema object contains an array of SchemaAttribute objects.
AttributeName (string) --
The name of the dataset field.
AttributeType (string) --
The data type of the field.
For a related time series dataset, other than date, item_id, and forecast dimensions attributes, all attributes should be of numerical type (integer/float).
Format (string) --
The format of the data, either CSV or PARQUET.
Deletes a what-if analysis created using the CreateWhatIfAnalysis operation. You can delete only what-if analyses that have a status of ACTIVE or CREATE_FAILED. To get the status, use the DescribeWhatIfAnalysis operation.
You can't delete a what-if analysis while any of its forecasts are being exported.
See also: AWS API Documentation
Request Syntax
client.delete_what_if_analysis(
WhatIfAnalysisArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if analysis that you want to delete.
None
Returns a list of what-if forecast exports created using the CreateWhatIfForecastExport operation. For each what-if forecast export, this operation returns a summary of its properties, including its Amazon Resource Name (ARN). You can retrieve the complete set of properties by using the what-if forecast export ARN with the DescribeWhatIfForecastExport operation.
See also: AWS API Documentation
Request Syntax
client.list_what_if_forecast_exports(
NextToken='string',
MaxResults=123,
Filters=[
{
'Key': 'string',
'Value': 'string',
'Condition': 'IS'|'IS_NOT'
},
]
)
string
If the result of the previous request was truncated, the response includes a NextToken. To retrieve the next set of results, use the token in the next request. Tokens expire after 24 hours.
integer
The number of items to return in the response.
list
An array of filters. For each filter, you provide a condition and a match statement. The condition is either IS or IS_NOT, which specifies whether to include or exclude the what-if forecast export jobs that match the statement from the list, respectively. The match statement consists of a key and a value.
Filter properties
Condition - The condition to apply. Valid values are IS and IS_NOT. To include the forecast export jobs that match the statement, specify IS. To exclude matching forecast export jobs, specify IS_NOT.
Key - The name of the parameter to filter on. Valid values are WhatIfForecastExportArn and Status.
Value - The value to match.
For example, to list all jobs that export a forecast named electricityWIFExport, specify the following filter:
"Filters": [ { "Condition": "IS", "Key": "WhatIfForecastExportArn", "Value": "arn:aws:forecast:us-west-2:<acct-id>:forecast/electricityWIFExport" } ]
(dict) --
Describes a filter for choosing a subset of objects. Each filter consists of a condition and a match statement. The condition is either IS or IS_NOT, which specifies whether to include or exclude the objects that match the statement, respectively. The match statement consists of a key and a value.
Key (string) -- [REQUIRED]
The name of the parameter to filter on.
Value (string) -- [REQUIRED]
The value to match.
Condition (string) -- [REQUIRED]
The condition to apply. To include the objects that match the statement, specify IS. To exclude matching objects, specify IS_NOT.
dict
Response Syntax
{
'WhatIfForecastExports': [
{
'WhatIfForecastExportArn': 'string',
'WhatIfForecastArns': [
'string',
],
'WhatIfForecastExportName': 'string',
'Destination': {
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
}
},
'Status': 'string',
'Message': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastModificationTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
WhatIfForecastExports (list) --
An array of WhatIfForecastExports objects that describe the matched forecast exports.
(dict) --
Provides a summary of the what-if forecast export properties used in the ListWhatIfForecastExports operation. To get the complete set of properties, call the DescribeWhatIfForecastExport operation, and provide the WhatIfForecastExportArn that is listed in the summary.
WhatIfForecastExportArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast export.
WhatIfForecastArns (list) --
An array of Amazon Resource Names (ARNs) that define the what-if forecasts included in the export.
(string) --
WhatIfForecastExportName (string) --
The what-if forecast export name.
Destination (dict) --
The path to the Amazon Simple Storage Service (Amazon S3) bucket where the forecast is exported.
S3Config (dict) --
The path to an Amazon Simple Storage Service (Amazon S3) bucket along with the credentials to access the bucket.
Path (string) --
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) --
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
Status (string) --
The status of the what-if forecast export. States include:
ACTIVE
CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED
CREATE_STOPPING, CREATE_STOPPED
DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED
Message (string) --
If an error occurred, an informational message about the error.
CreationTime (datetime) --
When the what-if forecast export was created.
LastModificationTime (datetime) --
The last time the resource was modified. The timestamp depends on the status of the job:
CREATE_PENDING - The CreationTime.
CREATE_IN_PROGRESS - The current timestamp.
CREATE_STOPPING - The current timestamp.
CREATE_STOPPED - When the job stopped.
ACTIVE or CREATE_FAILED - When the job finished or failed.
NextToken (string) --
If the response is truncated, Forecast returns this token. To retrieve the next set of results, use the token in the next request.
Describes the what-if forecast export created using the CreateWhatIfForecastExport operation.
In addition to listing the properties provided in the CreateWhatIfForecastExport request, this operation lists the following properties:
CreationTime
LastModificationTime
Message - If an error occurred, information about the error.
Status
See also: AWS API Documentation
Request Syntax
client.describe_what_if_forecast_export(
WhatIfForecastExportArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if forecast export that you are interested in.
dict
Response Syntax
{
'WhatIfForecastExportArn': 'string',
'WhatIfForecastExportName': 'string',
'WhatIfForecastArns': [
'string',
],
'Destination': {
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
}
},
'Message': 'string',
'Status': 'string',
'CreationTime': datetime(2015, 1, 1),
'EstimatedTimeRemainingInMinutes': 123,
'LastModificationTime': datetime(2015, 1, 1),
'Format': 'string'
}
Response Structure
(dict) --
WhatIfForecastExportArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast export.
WhatIfForecastExportName (string) --
The name of the what-if forecast export.
WhatIfForecastArns (list) --
An array of Amazon Resource Names (ARNs) that represent all of the what-if forecasts exported in this resource.
(string) --
Destination (dict) --
The destination for an export job. Provide an S3 path, an AWS Identity and Access Management (IAM) role that allows Amazon Forecast to access the location, and an AWS Key Management Service (KMS) key (optional).
S3Config (dict) --
The path to an Amazon Simple Storage Service (Amazon S3) bucket along with the credentials to access the bucket.
Path (string) --
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) --
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
Message (string) --
If an error occurred, an informational message about the error.
Status (string) --
The status of the what-if forecast. States include:
ACTIVE
CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED
CREATE_STOPPING, CREATE_STOPPED
DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED
CreationTime (datetime) --
When the what-if forecast export was created.
EstimatedTimeRemainingInMinutes (integer) --
The approximate time remaining to complete the what-if forecast export, in minutes.
LastModificationTime (datetime) --
The last time the resource was modified. The timestamp depends on the status of the job:
CREATE_PENDING - The CreationTime.
CREATE_IN_PROGRESS - The current timestamp.
CREATE_STOPPING - The current timestamp.
CREATE_STOPPED - When the job stopped.
ACTIVE or CREATE_FAILED - When the job finished or failed.
Format (string) --
The format of the exported data, CSV or PARQUET.
Deletes a what-if forecast created using the CreateWhatIfForecast operation. You can delete only what-if forecasts that have a status of ACTIVE or CREATE_FAILED. To get the status, use the DescribeWhatIfForecast operation.
You can't delete a what-if forecast while it is being exported. After a what-if forecast is deleted, you can no longer query the what-if analysis.
See also: AWS API Documentation
Request Syntax
client.delete_what_if_forecast(
WhatIfForecastArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if forecast that you want to delete.
None
Exports a forecast created by the CreateWhatIfForecast operation to your Amazon Simple Storage Service (Amazon S3) bucket. The forecast file name will match the following conventions:
≈<ForecastExportJobName>_<ExportTimestamp>_<PartNumber>
The <ExportTimestamp> component is in Java SimpleDateFormat (yyyy-MM-ddTHH-mm-ssZ).
You must specify a DataDestination object that includes an AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket. For more information, see aws-forecast-iam-roles.
For more information, see howitworks-forecast.
To get a list of all your what-if forecast export jobs, use the ListWhatIfForecastExports operation.
See also: AWS API Documentation
Request Syntax
client.create_what_if_forecast_export(
WhatIfForecastExportName='string',
WhatIfForecastArns=[
'string',
],
Destination={
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
}
},
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
Format='string'
)
string
[REQUIRED]
The name of the what-if forecast to export.
list
[REQUIRED]
The list of what-if forecast Amazon Resource Names (ARNs) to export.
(string) --
dict
[REQUIRED]
The location where you want to save the forecast and an AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the location. The forecast must be exported to an Amazon S3 bucket.
If encryption is used, Destination must include an AWS Key Management Service (KMS) key. The IAM role must allow Amazon Forecast permission to access the key.
S3Config (dict) -- [REQUIRED]
The path to an Amazon Simple Storage Service (Amazon S3) bucket along with the credentials to access the bucket.
Path (string) -- [REQUIRED]
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) -- [REQUIRED]
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
list
A list of tags to apply to the what if forecast.
(dict) --
The optional metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50.
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8.
Maximum value length - 256 Unicode characters in UTF-8.
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.
Key (string) -- [REQUIRED]
One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.
Value (string) -- [REQUIRED]
The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
string
The format of the exported data, CSV or PARQUET.
dict
Response Syntax
{
'WhatIfForecastExportArn': 'string'
}
Response Structure
(dict) --
WhatIfForecastExportArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast.
A what-if forecast is a forecast that is created from a modified version of the baseline forecast. Each what-if forecast incorporates either a replacement dataset or a set of transformations to the original dataset.
See also: AWS API Documentation
Request Syntax
client.create_what_if_forecast(
WhatIfForecastName='string',
WhatIfAnalysisArn='string',
TimeSeriesTransformations=[
{
'Action': {
'AttributeName': 'string',
'Operation': 'ADD'|'SUBTRACT'|'MULTIPLY'|'DIVIDE',
'Value': 123.0
},
'TimeSeriesConditions': [
{
'AttributeName': 'string',
'AttributeValue': 'string',
'Condition': 'EQUALS'|'NOT_EQUALS'|'LESS_THAN'|'GREATER_THAN'
},
]
},
],
TimeSeriesReplacementsDataSource={
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
},
'Schema': {
'Attributes': [
{
'AttributeName': 'string',
'AttributeType': 'string'|'integer'|'float'|'timestamp'|'geolocation'
},
]
},
'Format': 'string',
'TimestampFormat': 'string'
},
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The name of the what-if forecast. Names must be unique within each what-if analysis.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if analysis.
list
The transformations that are applied to the baseline time series. Each transformation contains an action and a set of conditions. An action is applied only when all conditions are met. If no conditions are provided, the action is applied to all items.
(dict) --
A transformation function is a pair of operations that select and modify the rows in a related time series. You select the rows that you want with a condition operation and you modify the rows with a transformation operation. All conditions are joined with an AND operation, meaning that all conditions must be true for the transformation to be applied. Transformations are applied in the order that they are listed.
Action (dict) --
An array of actions that define a time series and how it is transformed. These transformations create a new time series that is used for the what-if analysis.
AttributeName (string) -- [REQUIRED]
The related time series that you are modifying. This value is case insensitive.
Operation (string) -- [REQUIRED]
The operation that is applied to the provided attribute. Operations include:
ADD - adds Value to all rows of AttributeName.
SUBTRACT - subtracts Value from all rows of AttributeName.
MULTIPLY - multiplies all rows of AttributeName by Value.
DIVIDE - divides all rows of AttributeName by Value.
Value (float) -- [REQUIRED]
The value that is applied for the chosen Operation.
TimeSeriesConditions (list) --
An array of conditions that define which members of the related time series are transformed.
(dict) --
Creates a subset of items within an attribute that are modified. For example, you can use this operation to create a subset of items that cost $5 or less. To do this, you specify "AttributeName": "price", "AttributeValue": "5", and "Condition": "LESS_THAN". Pair this operation with the Action operation within the CreateWhatIfForecastRequest$TimeSeriesTransformations operation to define how the attribute is modified.
AttributeName (string) -- [REQUIRED]
The item_id, dimension name, IM name, or timestamp that you are modifying.
AttributeValue (string) -- [REQUIRED]
The value that is applied for the chosen Condition.
Condition (string) -- [REQUIRED]
The condition to apply. Valid values are EQUALS, NOT_EQUALS, LESS_THAN and GREATER_THAN.
dict
The replacement time series dataset, which contains the rows that you want to change in the related time series dataset. A replacement time series does not need to contain all rows that are in the baseline related time series. Include only the rows (measure-dimension combinations) that you want to include in the what-if forecast. This dataset is merged with the original time series to create a transformed dataset that is used for the what-if analysis.
This dataset should contain the items to modify (such as item_id or workforce_type), any relevant dimensions, the timestamp column, and at least one of the related time series columns. This file should not contain duplicate timestamps for the same time series.
Timestamps and item_ids not included in this dataset are not included in the what-if analysis.
S3Config (dict) -- [REQUIRED]
The path to the file(s) in an Amazon Simple Storage Service (Amazon S3) bucket, and an AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the file(s). Optionally, includes an AWS Key Management Service (KMS) key. This object is part of the DataSource object that is submitted in the CreateDatasetImportJob request, and part of the DataDestination object.
Path (string) -- [REQUIRED]
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) -- [REQUIRED]
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
Schema (dict) -- [REQUIRED]
Defines the fields of a dataset.
Attributes (list) --
An array of attributes specifying the name and type of each field in a dataset.
(dict) --
An attribute of a schema, which defines a dataset field. A schema attribute is required for every field in a dataset. The Schema object contains an array of SchemaAttribute objects.
AttributeName (string) --
The name of the dataset field.
AttributeType (string) --
The data type of the field.
For a related time series dataset, other than date, item_id, and forecast dimensions attributes, all attributes should be of numerical type (integer/float).
Format (string) --
The format of the replacement data, CSV or PARQUET.
TimestampFormat (string) --
The timestamp format of the replacement data.
list
A list of tags to apply to the what if forecast.
(dict) --
The optional metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50.
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8.
Maximum value length - 256 Unicode characters in UTF-8.
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.
Key (string) -- [REQUIRED]
One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.
Value (string) -- [REQUIRED]
The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
dict
Response Syntax
{
'WhatIfForecastArn': 'string'
}
Response Structure
(dict) --
WhatIfForecastArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast.
Describes the what-if forecast created using the CreateWhatIfForecast operation.
In addition to listing the properties provided in the CreateWhatIfForecast request, this operation lists the following properties:
CreationTime
LastModificationTime
Message - If an error occurred, information about the error.
Status
See also: AWS API Documentation
Request Syntax
client.describe_what_if_forecast(
WhatIfForecastArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if forecast that you are interested in.
dict
Response Syntax
{
'WhatIfForecastName': 'string',
'WhatIfForecastArn': 'string',
'WhatIfAnalysisArn': 'string',
'EstimatedTimeRemainingInMinutes': 123,
'Status': 'string',
'Message': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastModificationTime': datetime(2015, 1, 1),
'TimeSeriesTransformations': [
{
'Action': {
'AttributeName': 'string',
'Operation': 'ADD'|'SUBTRACT'|'MULTIPLY'|'DIVIDE',
'Value': 123.0
},
'TimeSeriesConditions': [
{
'AttributeName': 'string',
'AttributeValue': 'string',
'Condition': 'EQUALS'|'NOT_EQUALS'|'LESS_THAN'|'GREATER_THAN'
},
]
},
],
'TimeSeriesReplacementsDataSource': {
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
},
'Schema': {
'Attributes': [
{
'AttributeName': 'string',
'AttributeType': 'string'|'integer'|'float'|'timestamp'|'geolocation'
},
]
},
'Format': 'string',
'TimestampFormat': 'string'
},
'ForecastTypes': [
'string',
]
}
Response Structure
(dict) --
WhatIfForecastName (string) --
The name of the what-if forecast.
WhatIfForecastArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast.
WhatIfAnalysisArn (string) --
The Amazon Resource Name (ARN) of the what-if analysis that contains this forecast.
EstimatedTimeRemainingInMinutes (integer) --
The approximate time remaining to complete the what-if forecast, in minutes.
Status (string) --
The status of the what-if forecast. States include:
ACTIVE
CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED
CREATE_STOPPING, CREATE_STOPPED
DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED
Message (string) --
If an error occurred, an informational message about the error.
CreationTime (datetime) --
When the what-if forecast was created.
LastModificationTime (datetime) --
The last time the resource was modified. The timestamp depends on the status of the job:
CREATE_PENDING - The CreationTime.
CREATE_IN_PROGRESS - The current timestamp.
CREATE_STOPPING - The current timestamp.
CREATE_STOPPED - When the job stopped.
ACTIVE or CREATE_FAILED - When the job finished or failed.
TimeSeriesTransformations (list) --
An array of Action and TimeSeriesConditions elements that describe what transformations were applied to which time series.
(dict) --
A transformation function is a pair of operations that select and modify the rows in a related time series. You select the rows that you want with a condition operation and you modify the rows with a transformation operation. All conditions are joined with an AND operation, meaning that all conditions must be true for the transformation to be applied. Transformations are applied in the order that they are listed.
Action (dict) --
An array of actions that define a time series and how it is transformed. These transformations create a new time series that is used for the what-if analysis.
AttributeName (string) --
The related time series that you are modifying. This value is case insensitive.
Operation (string) --
The operation that is applied to the provided attribute. Operations include:
ADD - adds Value to all rows of AttributeName.
SUBTRACT - subtracts Value from all rows of AttributeName.
MULTIPLY - multiplies all rows of AttributeName by Value.
DIVIDE - divides all rows of AttributeName by Value.
Value (float) --
The value that is applied for the chosen Operation.
TimeSeriesConditions (list) --
An array of conditions that define which members of the related time series are transformed.
(dict) --
Creates a subset of items within an attribute that are modified. For example, you can use this operation to create a subset of items that cost $5 or less. To do this, you specify "AttributeName": "price", "AttributeValue": "5", and "Condition": "LESS_THAN". Pair this operation with the Action operation within the CreateWhatIfForecastRequest$TimeSeriesTransformations operation to define how the attribute is modified.
AttributeName (string) --
The item_id, dimension name, IM name, or timestamp that you are modifying.
AttributeValue (string) --
The value that is applied for the chosen Condition.
Condition (string) --
The condition to apply. Valid values are EQUALS, NOT_EQUALS, LESS_THAN and GREATER_THAN.
TimeSeriesReplacementsDataSource (dict) --
An array of S3Config, Schema, and Format elements that describe the replacement time series.
S3Config (dict) --
The path to the file(s) in an Amazon Simple Storage Service (Amazon S3) bucket, and an AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the file(s). Optionally, includes an AWS Key Management Service (KMS) key. This object is part of the DataSource object that is submitted in the CreateDatasetImportJob request, and part of the DataDestination object.
Path (string) --
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) --
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
Schema (dict) --
Defines the fields of a dataset.
Attributes (list) --
An array of attributes specifying the name and type of each field in a dataset.
(dict) --
An attribute of a schema, which defines a dataset field. A schema attribute is required for every field in a dataset. The Schema object contains an array of SchemaAttribute objects.
AttributeName (string) --
The name of the dataset field.
AttributeType (string) --
The data type of the field.
For a related time series dataset, other than date, item_id, and forecast dimensions attributes, all attributes should be of numerical type (integer/float).
Format (string) --
The format of the replacement data, CSV or PARQUET.
TimestampFormat (string) --
The timestamp format of the replacement data.
ForecastTypes (list) --
The quantiles at which probabilistic forecasts are generated. You can specify up to 5 quantiles per what-if forecast in the CreateWhatIfForecast operation. If you didn't specify quantiles, the default values are ["0.1", "0.5", "0.9"].
(string) --
What-if analysis is a scenario modeling technique where you make a hypothetical change to a time series and compare the forecasts generated by these changes against the baseline, unchanged time series. It is important to remember that the purpose of a what-if analysis is to understand how a forecast can change given different modifications to the baseline time series.
For example, imagine you are a clothing retailer who is considering an end of season sale to clear space for new styles. After creating a baseline forecast, you can use a what-if analysis to investigate how different sales tactics might affect your goals. You could create a scenario where everything is given a 25% markdown and another where everything is given a fixed dollar markdown. You can create a scenario where the sale lasts for 1 week and another where the sale lasts for 1 month. Your what-if analysis enables you to compare many different scenarios against each other.
Note that a what-if analysis is meant to display what the forecasting model has learned and how it will behave in the scenarios that you are evaluating. Do not blindly use the results of the what-if analysis to make business decisions. For instance, forecasts might not be accurate for novel scenarios where there is no reference available to determine whether a forecast is good.
The TimeSeriesSelector object defines the items that you want in the what-if analysis.
See also: AWS API Documentation
Request Syntax
client.create_what_if_analysis(
WhatIfAnalysisName='string',
ForecastArn='string',
TimeSeriesSelector={
'TimeSeriesIdentifiers': {
'DataSource': {
'S3Config': {
'Path': 'string',
'RoleArn': 'string',
'KMSKeyArn': 'string'
}
},
'Schema': {
'Attributes': [
{
'AttributeName': 'string',
'AttributeType': 'string'|'integer'|'float'|'timestamp'|'geolocation'
},
]
},
'Format': 'string'
}
},
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The name of the what-if analysis. Each name must be unique.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the baseline forecast.
dict
Defines the set of time series that are used in the what-if analysis with a TimeSeriesIdentifiers object. What-if analyses are performed only for the time series in this object.
The TimeSeriesIdentifiers object needs the following information:
DataSource
Format
Schema
TimeSeriesIdentifiers (dict) --
Details about the import file that contains the time series for which you want to create forecasts.
DataSource (dict) --
The source of your data, an AWS Identity and Access Management (IAM) role that allows Amazon Forecast to access the data and, optionally, an AWS Key Management Service (KMS) key.
S3Config (dict) -- [REQUIRED]
The path to the data stored in an Amazon Simple Storage Service (Amazon S3) bucket along with the credentials to access the data.
Path (string) -- [REQUIRED]
The path to an Amazon Simple Storage Service (Amazon S3) bucket or file(s) in an Amazon S3 bucket.
RoleArn (string) -- [REQUIRED]
The ARN of the AWS Identity and Access Management (IAM) role that Amazon Forecast can assume to access the Amazon S3 bucket or files. If you provide a value for the KMSKeyArn key, the role must allow access to the key.
Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an InvalidInputException error.
KMSKeyArn (string) --
The Amazon Resource Name (ARN) of an AWS Key Management Service (KMS) key.
Schema (dict) --
Defines the fields of a dataset.
Attributes (list) --
An array of attributes specifying the name and type of each field in a dataset.
(dict) --
An attribute of a schema, which defines a dataset field. A schema attribute is required for every field in a dataset. The Schema object contains an array of SchemaAttribute objects.
AttributeName (string) --
The name of the dataset field.
AttributeType (string) --
The data type of the field.
For a related time series dataset, other than date, item_id, and forecast dimensions attributes, all attributes should be of numerical type (integer/float).
Format (string) --
The format of the data, either CSV or PARQUET.
list
A list of tags to apply to the what if forecast.
(dict) --
The optional metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50.
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8.
Maximum value length - 256 Unicode characters in UTF-8.
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.
Key (string) -- [REQUIRED]
One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.
Value (string) -- [REQUIRED]
The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
dict
Response Syntax
{
'WhatIfAnalysisArn': 'string'
}
Response Structure
(dict) --
WhatIfAnalysisArn (string) --
The Amazon Resource Name (ARN) of the what-if analysis.
Returns a list of what-if analyses created using the CreateWhatIfAnalysis operation. For each what-if analysis, this operation returns a summary of its properties, including its Amazon Resource Name (ARN). You can retrieve the complete set of properties by using the what-if analysis ARN with the DescribeWhatIfAnalysis operation.
See also: AWS API Documentation
Request Syntax
client.list_what_if_analyses(
NextToken='string',
MaxResults=123,
Filters=[
{
'Key': 'string',
'Value': 'string',
'Condition': 'IS'|'IS_NOT'
},
]
)
string
If the result of the previous request was truncated, the response includes a NextToken. To retrieve the next set of results, use the token in the next request. Tokens expire after 24 hours.
integer
The number of items to return in the response.
list
An array of filters. For each filter, you provide a condition and a match statement. The condition is either IS or IS_NOT, which specifies whether to include or exclude the what-if analysis jobs that match the statement from the list, respectively. The match statement consists of a key and a value.
Filter properties
Condition - The condition to apply. Valid values are IS and IS_NOT. To include the what-if analysis jobs that match the statement, specify IS. To exclude matching what-if analysis jobs, specify IS_NOT.
Key - The name of the parameter to filter on. Valid values are WhatIfAnalysisArn and Status.
Value - The value to match.
For example, to list all jobs that export a forecast named electricityWhatIf, specify the following filter:
"Filters": [ { "Condition": "IS", "Key": "WhatIfAnalysisArn", "Value": "arn:aws:forecast:us-west-2:<acct-id>:forecast/electricityWhatIf" } ]
(dict) --
Describes a filter for choosing a subset of objects. Each filter consists of a condition and a match statement. The condition is either IS or IS_NOT, which specifies whether to include or exclude the objects that match the statement, respectively. The match statement consists of a key and a value.
Key (string) -- [REQUIRED]
The name of the parameter to filter on.
Value (string) -- [REQUIRED]
The value to match.
Condition (string) -- [REQUIRED]
The condition to apply. To include the objects that match the statement, specify IS. To exclude matching objects, specify IS_NOT.
dict
Response Syntax
{
'WhatIfAnalyses': [
{
'WhatIfAnalysisArn': 'string',
'WhatIfAnalysisName': 'string',
'ForecastArn': 'string',
'Status': 'string',
'Message': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastModificationTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
WhatIfAnalyses (list) --
An array of WhatIfAnalysisSummary objects that describe the matched analyses.
(dict) --
Provides a summary of the what-if analysis properties used in the ListWhatIfAnalyses operation. To get the complete set of properties, call the DescribeWhatIfAnalysis operation, and provide the WhatIfAnalysisArn that is listed in the summary.
WhatIfAnalysisArn (string) --
The Amazon Resource Name (ARN) of the what-if analysis.
WhatIfAnalysisName (string) --
The name of the what-if analysis.
ForecastArn (string) --
The Amazon Resource Name (ARN) of the baseline forecast that is being used in this what-if analysis.
Status (string) --
The status of the what-if analysis. States include:
ACTIVE
CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED
CREATE_STOPPING, CREATE_STOPPED
DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED
Message (string) --
If an error occurred, an informational message about the error.
CreationTime (datetime) --
When the what-if analysis was created.
LastModificationTime (datetime) --
The last time the resource was modified. The timestamp depends on the status of the job:
CREATE_PENDING - The CreationTime.
CREATE_IN_PROGRESS - The current timestamp.
CREATE_STOPPING - The current timestamp.
CREATE_STOPPED - When the job stopped.
ACTIVE or CREATE_FAILED - When the job finished or failed.
NextToken (string) --
If the response is truncated, Forecast returns this token. To retrieve the next set of results, use the token in the next request.
Deletes a what-if forecast export created using the CreateWhatIfForecastExport operation. You can delete only what-if forecast exports that have a status of ACTIVE or CREATE_FAILED. To get the status, use the DescribeWhatIfForecastExport operation.
See also: AWS API Documentation
Request Syntax
client.delete_what_if_forecast_export(
WhatIfForecastExportArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the what-if forecast export that you want to delete.
None
Returns a list of what-if forecasts created using the CreateWhatIfForecast operation. For each what-if forecast, this operation returns a summary of its properties, including its Amazon Resource Name (ARN). You can retrieve the complete set of properties by using the what-if forecast ARN with the DescribeWhatIfForecast operation.
See also: AWS API Documentation
Request Syntax
client.list_what_if_forecasts(
NextToken='string',
MaxResults=123,
Filters=[
{
'Key': 'string',
'Value': 'string',
'Condition': 'IS'|'IS_NOT'
},
]
)
string
If the result of the previous request was truncated, the response includes a NextToken. To retrieve the next set of results, use the token in the next request. Tokens expire after 24 hours.
integer
The number of items to return in the response.
list
An array of filters. For each filter, you provide a condition and a match statement. The condition is either IS or IS_NOT, which specifies whether to include or exclude the what-if forecast export jobs that match the statement from the list, respectively. The match statement consists of a key and a value.
Filter properties
Condition - The condition to apply. Valid values are IS and IS_NOT. To include the forecast export jobs that match the statement, specify IS. To exclude matching forecast export jobs, specify IS_NOT.
Key - The name of the parameter to filter on. Valid values are WhatIfForecastArn and Status.
Value - The value to match.
For example, to list all jobs that export a forecast named electricityWhatIfForecast, specify the following filter:
"Filters": [ { "Condition": "IS", "Key": "WhatIfForecastArn", "Value": "arn:aws:forecast:us-west-2:<acct-id>:forecast/electricityWhatIfForecast" } ]
(dict) --
Describes a filter for choosing a subset of objects. Each filter consists of a condition and a match statement. The condition is either IS or IS_NOT, which specifies whether to include or exclude the objects that match the statement, respectively. The match statement consists of a key and a value.
Key (string) -- [REQUIRED]
The name of the parameter to filter on.
Value (string) -- [REQUIRED]
The value to match.
Condition (string) -- [REQUIRED]
The condition to apply. To include the objects that match the statement, specify IS. To exclude matching objects, specify IS_NOT.
dict
Response Syntax
{
'WhatIfForecasts': [
{
'WhatIfForecastArn': 'string',
'WhatIfForecastName': 'string',
'WhatIfAnalysisArn': 'string',
'Status': 'string',
'Message': 'string',
'CreationTime': datetime(2015, 1, 1),
'LastModificationTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
WhatIfForecasts (list) --
An array of WhatIfForecasts objects that describe the matched forecasts.
(dict) --
Provides a summary of the what-if forecast properties used in the ListWhatIfForecasts operation. To get the complete set of properties, call the DescribeWhatIfForecast operation, and provide the WhatIfForecastArn that is listed in the summary.
WhatIfForecastArn (string) --
The Amazon Resource Name (ARN) of the what-if forecast.
WhatIfForecastName (string) --
The name of the what-if forecast.
WhatIfAnalysisArn (string) --
The Amazon Resource Name (ARN) of the what-if analysis that contains this what-if forecast.
Status (string) --
The status of the what-if forecast. States include:
ACTIVE
CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED
CREATE_STOPPING, CREATE_STOPPED
DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED
Message (string) --
If an error occurred, an informational message about the error.
CreationTime (datetime) --
When the what-if forecast was created.
LastModificationTime (datetime) --
The last time the resource was modified. The timestamp depends on the status of the job:
CREATE_PENDING - The CreationTime.
CREATE_IN_PROGRESS - The current timestamp.
CREATE_STOPPING - The current timestamp.
CREATE_STOPPED - When the job stopped.
ACTIVE or CREATE_FAILED - When the job finished or failed.
NextToken (string) --
If the result of the previous request was truncated, the response includes a NextToken. To retrieve the next set of results, use the token in the next request. Tokens expire after 24 hours.