explainabilities

Creates, updates, deletes, gets or lists an explainabilities resource.

Overview

Name	explainabilities
Type	Resource
Id	aws.forecast.explainabilities

Fields

The following fields are returned by SELECT queries:

describe_explainability

Name	Datatype	Description
creation_time	string (date-time)	When the Explainability resource was created.
data_source	object	The source of your data, an Identity and Access Management (IAM) role that allows Amazon Forecast to access the data and, optionally, an Key Management Service (KMS) key.
enable_visualization	boolean	Whether the visualization was enabled for the Explainability resource.
end_date_time	string	If TimePointGranularity is set to SPECIFIC, the last time point in the Explainability. (pattern: <code>^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$</code>)
estimated_time_remaining_in_minutes	integer (int64)	The estimated time remaining in minutes for the CreateExplainability job to complete.
explainability_arn	string	The Amazon Resource Name (ARN) of the Explainability. (pattern: <code>arn:([a-z\d-]+):forecast:.:.:.+</code>)
explainability_config	object	The configuration settings that define the granularity of time series and time points for the Explainability.
explainability_name	string	The name of the Explainability. (pattern: <code>^[a-zA-Z][a-zA-Z0-9_]*</code>)
last_modification_time	string (date-time)	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.
message	string	If an error occurred, a message about the error.
resource_arn	string	The Amazon Resource Name (ARN) of the Predictor or Forecast used to create the Explainability resource. (pattern: <code>arn:([a-z\d-]+):forecast:.:.:.+</code>)
schema	object	Defines the fields of a dataset.
start_date_time	string	If TimePointGranularity is set to SPECIFIC, the first time point in the Explainability. (pattern: <code>^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$</code>)
status	string	The status of the Explainability resource. States include: ACTIVE CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED CREATE_STOPPING, CREATE_STOPPED DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED

list_explainabilities

Name	Datatype	Description
creation_time	string (date-time)	When the Explainability was created.
explainability_arn	string	The Amazon Resource Name (ARN) of the Explainability. (pattern: <code>arn:([a-z\d-]+):forecast:.:.:.+</code>)
explainability_config	object	The configuration settings that define the granularity of time series and time points for the Explainability.
explainability_name	string	The name of the Explainability. (pattern: <code>^[a-zA-Z][a-zA-Z0-9_]*</code>)
last_modification_time	string (date-time)	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.
message	string	Information about any errors that may have occurred during the Explainability creation process.
resource_arn	string	The Amazon Resource Name (ARN) of the Predictor or Forecast used to create the Explainability. (pattern: <code>arn:([a-z\d-]+):forecast:.:.:.+</code>)
status	string	The status of the Explainability. States include: ACTIVE CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED CREATE_STOPPING, CREATE_STOPPED DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_explainability	select	region		Describes an Explainability resource created using the CreateExplainability operation.
list_explainabilities	select	region		Returns a list of Explainability resources created using the CreateExplainability operation. This operation returns a summary for each Explainability. You can filter the list using an array of Filter objects. To retrieve the complete set of properties for a particular Explainability resource, use the ARN with the DescribeExplainability operation.
create_explainability	insert	region, ExplainabilityName, ResourceArn, ExplainabilityConfig		Explainability is only available for Forecasts and Predictors generated from an AutoPredictor (CreateAutoPredictor) Creates an Amazon Forecast Explainability. Explainability helps you better understand how the attributes in your datasets impact forecast. Amazon Forecast uses a metric called Impact scores to quantify the relative impact of each attribute and determine whether they increase or decrease forecast values. To enable Forecast Explainability, your predictor must include at least one of the following: related time series, item metadata, or additional datasets like Holidays and the Weather Index. CreateExplainability accepts either a Predictor ARN or Forecast ARN. To receive aggregated Impact scores for all time series and time points in your datasets, provide a Predictor ARN. To receive Impact scores for specific time series and time points, provide a Forecast ARN. CreateExplainability with a Predictor ARN You can only have one Explainability resource per predictor. If you already enabled ExplainPredictor in CreateAutoPredictor, that predictor already has an Explainability resource. The following parameters are required when providing a Predictor ARN: ExplainabilityName - A unique name for the Explainability. ResourceArn - The Arn of the predictor. TimePointGranularity - Must be set to “ALL”. TimeSeriesGranularity - Must be set to “ALL”. Do not specify a value for the following parameters: DataSource - Only valid when TimeSeriesGranularity is “SPECIFIC”. Schema - Only valid when TimeSeriesGranularity is “SPECIFIC”. StartDateTime - Only valid when TimePointGranularity is “SPECIFIC”. EndDateTime - Only valid when TimePointGranularity is “SPECIFIC”. CreateExplainability with a Forecast ARN You can specify a maximum of 50 time series and 500 time points. The following parameters are required when providing a Predictor ARN: ExplainabilityName - A unique name for the Explainability. ResourceArn - The Arn of the forecast. TimePointGranularity - Either “ALL” or “SPECIFIC”. TimeSeriesGranularity - Either “ALL” or “SPECIFIC”. If you set TimeSeriesGranularity to “SPECIFIC”, you must also provide the following: DataSource - The S3 location of the CSV file specifying your time series. Schema - The Schema defines the attributes and attribute types listed in the Data Source. If you set TimePointGranularity to “SPECIFIC”, you must also provide the following: StartDateTime - The first timestamp in the range of time points. EndDateTime - The last timestamp in the range of time points.
delete_explainability	delete	region		Deletes an Explainability resource. You can delete only predictor that have a status of ACTIVE or CREATE_FAILED. To get the status, use the DescribeExplainability operation.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_explainability

Describes an Explainability resource created using the CreateExplainability operation.

SELECT
creation_time,
data_source,
enable_visualization,
end_date_time,
estimated_time_remaining_in_minutes,
explainability_arn,
explainability_config,
explainability_name,
last_modification_time,
message,
resource_arn,
schema,
start_date_time,
status
FROM aws.forecast.explainabilities
WHERE region = '{{ region }}' -- required
;

list_explainabilities

Returns a list of Explainability resources created using the CreateExplainability operation. This operation returns a summary for each Explainability. You can filter the list using an array of Filter objects. To retrieve the complete set of properties for a particular Explainability resource, use the ARN with the DescribeExplainability operation.

SELECT
creation_time,
explainability_arn,
explainability_config,
explainability_name,
last_modification_time,
message,
resource_arn,
status
FROM aws.forecast.explainabilities
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_explainability

Explainability is only available for Forecasts and Predictors generated from an AutoPredictor (CreateAutoPredictor) Creates an Amazon Forecast Explainability. Explainability helps you better understand how the attributes in your datasets impact forecast. Amazon Forecast uses a metric called Impact scores to quantify the relative impact of each attribute and determine whether they increase or decrease forecast values. To enable Forecast Explainability, your predictor must include at least one of the following: related time series, item metadata, or additional datasets like Holidays and the Weather Index. CreateExplainability accepts either a Predictor ARN or Forecast ARN. To receive aggregated Impact scores for all time series and time points in your datasets, provide a Predictor ARN. To receive Impact scores for specific time series and time points, provide a Forecast ARN. CreateExplainability with a Predictor ARN You can only have one Explainability resource per predictor. If you already enabled ExplainPredictor in CreateAutoPredictor, that predictor already has an Explainability resource. The following parameters are required when providing a Predictor ARN: ExplainabilityName - A unique name for the Explainability. ResourceArn - The Arn of the predictor. TimePointGranularity - Must be set to “ALL”. TimeSeriesGranularity - Must be set to “ALL”. Do not specify a value for the following parameters: DataSource - Only valid when TimeSeriesGranularity is “SPECIFIC”. Schema - Only valid when TimeSeriesGranularity is “SPECIFIC”. StartDateTime - Only valid when TimePointGranularity is “SPECIFIC”. EndDateTime - Only valid when TimePointGranularity is “SPECIFIC”. CreateExplainability with a Forecast ARN You can specify a maximum of 50 time series and 500 time points. The following parameters are required when providing a Predictor ARN: ExplainabilityName - A unique name for the Explainability. ResourceArn - The Arn of the forecast. TimePointGranularity - Either “ALL” or “SPECIFIC”. TimeSeriesGranularity - Either “ALL” or “SPECIFIC”. If you set TimeSeriesGranularity to “SPECIFIC”, you must also provide the following: DataSource - The S3 location of the CSV file specifying your time series. Schema - The Schema defines the attributes and attribute types listed in the Data Source. If you set TimePointGranularity to “SPECIFIC”, you must also provide the following: StartDateTime - The first timestamp in the range of time points. EndDateTime - The last timestamp in the range of time points.

INSERT INTO aws.forecast.explainabilities (
ExplainabilityName,
ResourceArn,
ExplainabilityConfig,
DataSource,
Schema,
EnableVisualization,
StartDateTime,
EndDateTime,
Tags,
region
)
SELECT 
'{{ ExplainabilityName }}' /* required */,
'{{ ResourceArn }}' /* required */,
'{{ ExplainabilityConfig }}' /* required */,
'{{ DataSource }}',
'{{ Schema }}',
{{ EnableVisualization }},
'{{ StartDateTime }}',
'{{ EndDateTime }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
explainability_arn
;

Manifest

# Description fields are for documentation purposes
- name: explainabilities
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the explainabilities resource.
  - name: ExplainabilityName
    value: "{{ ExplainabilityName }}"
    description: |
      A unique name for the Explainability.
  - name: ResourceArn
    value: "{{ ResourceArn }}"
    description: |
      The Amazon Resource Name (ARN) of the Predictor or Forecast used to create the Explainability.
  - name: ExplainabilityConfig
    description: |
      The configuration settings that define the granularity of time series and time points for the Explainability.
    value:
      TimeSeriesGranularity: "{{ TimeSeriesGranularity }}"
      TimePointGranularity: "{{ TimePointGranularity }}"
  - name: DataSource
    description: |
      The source of your data, an Identity and Access Management (IAM) role that allows Amazon Forecast to access the data and, optionally, an Key Management Service (KMS) key.
    value:
      S3Config:
        Path: "{{ Path }}"
        RoleArn: "{{ RoleArn }}"
        KMSKeyArn: "{{ KMSKeyArn }}"
  - name: Schema
    description: |
      Defines the fields of a dataset.
    value:
      Attributes:
        - AttributeName: "{{ AttributeName }}"
          AttributeType: "{{ AttributeType }}"
  - name: EnableVisualization
    value: {{ EnableVisualization }}
    description: |
      Create an Explainability visualization that is viewable within the Amazon Web Services console.
  - name: StartDateTime
    value: "{{ StartDateTime }}"
    description: |
      If TimePointGranularity is set to SPECIFIC, define the first point for the Explainability. Use the following timestamp format: yyyy-MM-ddTHH:mm:ss (example: 2015-01-01T20:00:00)
  - name: EndDateTime
    value: "{{ EndDateTime }}"
    description: |
      If TimePointGranularity is set to SPECIFIC, define the last time point for the Explainability. Use the following timestamp format: yyyy-MM-ddTHH:mm:ss (example: 2015-01-01T20:00:00)
  - name: Tags
    description: |
      Optional metadata to help you categorize and organize your resources. Each tag consists of a key and an optional value, both of which you define. Tag keys and values are case sensitive. The following restrictions apply to tags: For each resource, each tag key must be unique and each tag key must have one value. Maximum number of tags per resource: 50. Maximum key length: 128 Unicode characters in UTF-8. Maximum value length: 256 Unicode characters in UTF-8. Accepted characters: all letters and numbers, spaces representable in UTF-8, and + - = . _ : / @. If your tagging schema is used across other services and resources, the character restrictions of those services also apply. Key prefixes cannot include any upper or lowercase combination of aws: or AWS:. Values can have this prefix. If a tag value has aws as its prefix but the key does not, 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. You cannot edit or delete tag keys with this prefix.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

DELETE examples

delete_explainability

Deletes an Explainability resource. You can delete only predictor that have a status of ACTIVE or CREATE_FAILED. To get the status, use the DescribeExplainability operation.

DELETE FROM aws.forecast.explainabilities
WHERE region = '{{ region }}' --required
;