Explaining text sentiment analysis using SageMaker Clarify

This notebook's CI test result for us-west-2 is as follows. CI test results in other regions can be found at the end of the notebook.

Runtime

This notebook takes approximately 40 minutes to run.

1. Overview
2. Prerequisites and Data
   1. Initialize SageMaker
   2. Loading the data: Women's E-commerce clothing reviews Dataset
   3. Data preparation for model training
3. Train and Deploy Hugging Face Model
   1. Train model with Hugging Face estimator
   2. Deploy Model to Endpoint
4. Model Explainability with SageMaker Clarify for text features
   1. Amazon SageMaker Clarify
   2. Model Explainability for text features
   3. Visualize local explanations
   4. Clean Up

Overview

Amazon SageMaker Clarify helps improve your machine learning models by detecting potential bias and helping explain how these models make predictions. The fairness and explainability functionality provided by SageMaker Clarify takes a step towards enabling AWS customers to build trustworthy and understandable machine learning models. The product comes with the tools to help you with the following tasks.

• Measure biases that can occur during each stage of the ML lifecycle (data collection, model training and tuning, and monitoring of ML models deployed for inference).
• Generate model governance reports targeting risk and compliance teams and external regulators.
• Provide explanations of the data, models, and monitoring used to assess predictions for input containing data of various modalities like numerical data, categorical data, text, and images.

Learn more about SageMaker Clarify here. This sample notebook walks you through:

1. Key terms and concepts needed to understand SageMaker Clarify
2. Explaining text features with Kernel SHAP
3. Visualizing the local SHAP explanations

In doing so, the notebook will first train a Hugging Face model using the Hugging Face Estimator in the SageMaker Python SDK using the training dataset, then use SageMaker Clarify to analyze a testing dataset in CSV format, and then visualize the results.

Prerequisites and Data

We require the following AWS resources to be able to successfully run this notebook.

1. Kernel: Python 3 (Data Science) kernel on SageMaker Studio or conda_python3 kernel on notebook instances
2. Instance type: Any GPU instance. Here, we use ml.g4dn.xlarge
3. SageMaker Python SDK version 2.70.0 or greater
4. Transformers >= 4.40.0
5. Datasets >= 2.18.0

Let's start by installing the required packages.

Import libraries

Initialize SageMaker

If you change the value of model_path variable above, please be sure to update the model_path in code/inference.py script as well.

Loading the data: Women's E-Commerce clothing reviews dataset

The Women’s Clothing E-Commerce dataset contains reviews written by customers. This dataset contains 23486 rows and 10 columns, where each row corresponds to a customer review.

The columns include:

• Clothing ID: Integer Categorical variable that refers to the specific piece being reviewed.
• Age: Positive Integer variable of the reviewer's age.
• Title: String variable for the title of the review.
• Review Text: String variable for the review body.
• Rating: Positive Ordinal Integer variable for the product score granted by the customer from 1 Worst, to 5 Best.
• Recommended IND: Binary variable stating where the customer recommends the product where 1 is recommended, 0 is not recommended.
• Positive Feedback Count: Positive Integer documenting the number of other customers who found this review positive.
• Division Name: Categorical name of the product high level division.
• Department Name: Categorical name of the product department name.
• Class Name: Categorical name of the product class name.

Because the dataset contains real commercial data, it has been anonymized, and any references to the company in the review text and body have been replaced with “retailer”.

Goal: To predict the sentiment of a review based on the text, and then explain the predictions using SageMaker Clarify.

Download the dataset

Data Source: https://www.kaggle.com/nicapotato/womens-ecommerce-clothing-reviews/

The Women’s E-Commerce Clothing Reviews dataset has been made available under a Creative Commons Public Domain license. A copy of the dataset has been saved in a sample data Amazon S3 bucket. Let's download the dataset.

Loading the data

Data preparation for model training

Target Variable Creation

Since the dataset does not contain a column that indicates the sentiment of the customer reviews, let's create one to specify our binary prediction task. To do this, let's assume that reviews with a Rating of 4 or higher indicate positive sentiment and reviews with a Rating of 2 or lower indicate negative sentiment. Let's also assume that a Rating of 3 indicates neutral sentiment and exclude these rows from the dataset. Additionally, to predict the sentiment of a review, we are going to use the Review Text column; therefore let's remove rows that are empty in the Review Text column of the dataset.

Train-Validation-Test splits

The most common approach for model evaluation is using the train/validation/test split. Although this approach can be very effective in general, it can result in misleading results and potentially fail when used on classification problems with a severe class imbalance. Instead, the technique must be modified to stratify the sampling by the class label as below. Stratification ensures that all classes are well represented across the train, validation and test datasets.

Upload prepared dataset to the S3

Here, we upload the prepared datasets to S3 buckets so that we can train the model with the Hugging Face Estimator.

We have split the dataset into train, test, and validation datasets. We use the train and validation datasets during training process, and run Clarify on the test dataset.

In the cell below, we convert the Pandas DataFrames into Hugging Face Datasets for downstream modeling.

Train and Deploy Hugging Face Model

In this step of the workflow, we use the Hugging Face Estimator to load the pre-trained distilbert-base-uncased model and fine-tune the model on our dataset.

Train model with Hugging Face estimator

The hyperparameters defined below are parameters that are passed to the custom PyTorch code in scripts/train.py. The only required parameter is model_name. The other parameters like epoch, train_batch_size all have default values which can be overridden by setting their values here.

Download the trained model files for model inference

Deploy Model

We are going to use the trained model files along with the PyTorch Inference container to deploy the model to a SageMaker endpoint.

Test the model endpoint

Let's test the model endpoint to ensure that deployment was successful.

Amazon SageMaker Clarify

With your model set up, we are ready to get explanations for text data from Clarify processing job. Please visit here for a general overview of how Clarify processing jobs work.

Model Explainability for text features

To speed up the analysis, let's take 10 samples from the testing dataset. We create a CSV file to store the testing dataset and filter out any reviews with less than 500 characters as long reviews provide better visualization.

Writing DataConfig

A DataConfig object communicates some basic information about data I/O to SageMaker Clarify. For our example here we provide the below information:

• s3_data_input_path: S3 URI of the train dataset we uploaded above
• s3_output_path: S3 URI at which our output report will be uploaded
• headers: The list of column names in the dataset
• dataset_type: specifies the format of your dataset, for this example as we are using CSV dataset this will be text/csv

Writing ModelConfig

A ModelConfig object communicates information about your trained model. To avoid additional traffic to the production models, SageMaker Clarify sets up and tears down a dedicated endpoint when processing. For our example here we provide the below information:

• model_name: name of the model trained above
• instance_type and instance_count specify your preferred instance type and instance count used to run your model on during SageMaker Clarify's processing. The example dataset is small, so a single standard instance is sufficient to run this example.
• accept_type denotes the endpoint response payload format, and content_type denotes the payload format of request to the endpoint. As per the example model we created above both of these will be text/csv.

Writing TextConfig

A TextConfig object provides information needed to compute explanations for the text features in your dataset. It includes the below parameters:

• granularity (required): To explain text features, Clarify further breaks down text into smaller text units, and considers each such text unit as a feature. The parameter granularity informs the level to which Clarify will break down the text: token, sentence, or paragraph are the allowed values for granularity.
• language (required): the language of the text features. This is required to tokenize the text to break them down to their granular form.
• max_top_tokens (optional): the number of top token attributions that will be shown in the output (we need this because the size of vocabulary can be very big). This is an optional parameter, here we use the default of 50.

Here we will set the granularity to "sentence". We will also run the explainability analysis with granularity set to "token" later and compare the outputs.

A SHAPConfig object provides information needed for the Kernel SHAP algorithm. It contains the following parameters:

• baseline: The Kernel SHAP algorithm requires a baseline (also known as background dataset). For text feature, the baseline values must be the value you want to replace the individual text feature (token, sentence or paragraph) with. For instance, in the example below, we have chosen the baseline values for review_text as <UNK>, and granularity is sentence. Every time a sentence has to replaced in the perturbed inputs, we will replace it with <UNK>. For text features, if baseline is not provided, the default replacement value will be the string <PAD>. For more details on baseline selection please refer this documentation.
• num_samples: Number of samples to be used in the Kernel SHAP algorithm. This number determines the size of the generated synthetic dataset to compute the SHAP values.
• agg_method: Aggregation method for global SHAP values. For our example here we are using mean_abs i.e. mean of absolute SHAP values for all instances.
• save_local_shap_values: Indicates whether to save the local SHAP values in the output location. Default is True.

Now we can run the explainability job with run_explainability. The below cell takes about 15 minutes to run.

Visualize local explanations

We use Captum to visualize the feature importances computed by Clarify. First, let's load the local explanations. Local text explanations can be found in the analysis results folder in a file named out.jsonl in the explanations_shap directory.

Let's take a look at the list of local explanations and examine it's output format. The local explanations file is a JSON Lines file that contains the explanation of one instance per row as seen below.

At the highest level of this JSON Line, there are two keys: explanations, join_source_value (not present here as we have not included a joinsource column in the input dataset). The key explanations contains a list of attributions for each feature in the dataset. In this case, we have a single element, because the input dataset also had a single feature. It also contains details like feature_name, data_type of the features (indicating whether Clarify inferred the column as numerical, categorical or text). Each token attribution also contains a description field that contains the token itself, and the starting index of the token in original input. This allows you to reconstruct the original sentence from the output as well.

In the following cell, we create a list of attributions and a list of tokens for use in visualizations.

Let's take a look at the first instance in the attributions_dataset and tokens_dataset. We see that they are lists of the same length, as each attribution corresponds to one sentence level token.

We obtain predictions as well so that they can be displayed alongside the feature attributions.

The below method is used to produce visualizations for the local explanations. It will visualize the attributions for the tokens with red or green colors for negative and positive attributions.

Now that we compiled the record we are ready to render the visualizations.

We see a row per review in the selected dataset. For each row we have the prediction, the label, and the highlighted text. Additionally, we show the total sum of attributions (as attribution score) and its label (as attribution label), which indicates whether it is greater than zero.

Token level explainability

So far we looked at sentence level explainability, now let's look at token level explainability by updating the TextConfig and setting granularity to "token", and updating the SHAPConfig. Let's also update the DataConfig to save the outputs to a different path.

The analysis below takes around 20 minutes to complete.

Let's visualize the local explanations as we did for the sentence level explanations.

In the visualizations below, we see how individual tokens are colored as "positive" or "negative" sentiment.

Cleanup

Finally, please remember to delete the Amazon SageMaker endpoint to avoid charges:

Notebook CI Test Results

This notebook was tested in multiple regions. The test results are as follows, except for us-west-2 which is shown at the top of the notebook.