sagemaker_model_monitor/fairness_and_explainability/SageMaker-Model-Monitor-Fairness-and-Explainability.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Amazon SageMaker Clarify Model Monitors\n",
    "This notebook shows how to:\n",
    "* Host a machine learning model in Amazon SageMaker and capture inference requests, results, and metadata \n",
    "* Schedule Clarify bias monitor to monitor predictions for bias drift on a regular basis.\n",
    "* Schedule Clarify explainability monitor to monitor predictions for feature attribution drift on a regular basis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Background\n",
    "\n",
    "Amazon SageMaker Model Monitor continuously monitors the quality of Amazon SageMaker machine learning models in production. It enables developers to set alerts for when there are deviations in the model quality. Early and pro-active detection of these deviations enables corrective actions, such as retraining models, auditing upstream systems, or fixing data quality issues without having to monitor models manually or build additional tooling. \n",
    "\n",
    "Amazon SageMaker Clarify bias monitoring helps data scientists and ML engineers monitor predictions for bias on a regular basis. One way bias can be introduced in deployed ML models is when the data used in training differs from the data used to generate predictions. This is especially pronounced if the data used for training changes over time (e.g. fluctuating mortgage rates), and the model prediction will not be accurate unless the model is retrained with updated data. For example, model for predicting home prices can be biased if the mortgage rates used to train the model differ from the most current real-world mortgage rate.\n",
    "\n",
    "Aamazon SageMaker Clarify explainability monitoring offers tools to provide global explanations of models and to explain the predictions of a deployed model producing inferences. Such model explanation tools can help ML modelers and developers and other internal stakeholders understand model characteristics as a whole prior to deployment and to debug predictions provided by the model once deployed. The current offering includes a scalable and efficient implementation of [SHAP](https://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions), based on the concept of the [Shapley value](https://en.wikipedia.org/wiki/Shapley_value) from the field of cooperative game theory that assigns each feature an importance value for a particular prediction.\n",
    "\n",
    "As the model is monitored, customers can view exportable reports and graphs detailing bias and feature attributions in SageMaker Studio and configure alerts in Amazon CloudWatch to receive notifications if violations are detected."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## General Setup\n",
    "\n",
    "To get started, make sure these prerequisites completed.\n",
    "\n",
    "* Specify an AWS Region to host the model.\n",
    "* An IAM role ARN exists that is used to give Amazon SageMaker access to data in Amazon Simple Storage Service (Amazon S3). See the documentation for how to fine tune the permissions needed. \n",
    "* Create an S3 bucket used to store the test dataset, any additional model data, data captured from model invocations and ground truth data. For demonstration purposes, this notebook uses the same bucket for these. In reality, they could be separated with different security policies."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Imports\n",
    "\n",
    "Import APIs to be used by the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import copy\n",
    "import json\n",
    "import random\n",
    "import time\n",
    "import pandas as pd\n",
    "\n",
    "from datetime import datetime, timedelta\n",
    "\n",
    "from sagemaker import get_execution_role, image_uris, Session\n",
    "from sagemaker.clarify import (\n",
    "    BiasConfig,\n",
    "    DataConfig,\n",
    "    ModelConfig,\n",
    "    ModelPredictedLabelConfig,\n",
    "    SHAPConfig,\n",
    ")\n",
    "from sagemaker.model import Model\n",
    "from sagemaker.model_monitor import (\n",
    "    BiasAnalysisConfig,\n",
    "    CronExpressionGenerator,\n",
    "    DataCaptureConfig,\n",
    "    EndpointInput,\n",
    "    ExplainabilityAnalysisConfig,\n",
    "    ModelBiasMonitor,\n",
    "    ModelExplainabilityMonitor,\n",
    ")\n",
    "from sagemaker.s3 import S3Downloader, S3Uploader"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Handful of configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "role = get_execution_role()\n",
    "print(f\"RoleArn: {role}\")\n",
    "\n",
    "sagemaker_session = Session()\n",
    "sagemaker_client = sagemaker_session.sagemaker_client\n",
    "sagemaker_runtime_client = sagemaker_session.sagemaker_runtime_client\n",
    "\n",
    "region = sagemaker_session.boto_region_name\n",
    "print(f\"AWS region: {region}\")\n",
    "\n",
    "# A different bucket can be used, but make sure the role for this notebook has\n",
    "# the s3:PutObject permissions. This is the bucket into which the data is captured\n",
    "bucket = Session().default_bucket()\n",
    "print(f\"Demo Bucket: {bucket}\")\n",
    "prefix = \"sagemaker/DEMO-ClarifyModelMonitor-20200901\"\n",
    "s3_key = f\"s3://{bucket}/{prefix}\"\n",
    "print(f\"S3 key: {s3_key}\")\n",
    "\n",
    "s3_capture_upload_path = f\"{s3_key}/datacapture\"\n",
    "ground_truth_upload_path = f\"{s3_key}/ground_truth_data/{datetime.now():%Y-%m-%d-%H-%M-%S}\"\n",
    "s3_report_path = f\"{s3_key}/reports\"\n",
    "\n",
    "print(f\"Capture path: {s3_capture_upload_path}\")\n",
    "print(f\"Ground truth path: {ground_truth_upload_path}\")\n",
    "print(f\"Report path: {s3_report_path}\")\n",
    "\n",
    "baseline_results_uri = f\"{s3_key}/baselining\"\n",
    "print(f\"Baseline results uri: {baseline_results_uri}\")\n",
    "\n",
    "endpoint_instance_count = 1\n",
    "endpoint_instance_type = \"ml.m5.large\"\n",
    "schedule_expression = CronExpressionGenerator.hourly()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Model files and data files\n",
    "\n",
    "The prebuilt model, and a couple of dataset files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_file = \"model/xgb-churn-prediction-model.tar.gz\"\n",
    "test_file = \"test_data/upload-test-file.txt\"\n",
    "test_dataset = \"test_data/test-dataset-input-cols.csv\"\n",
    "validation_dataset = \"test_data/validation-dataset-with-header.csv\"\n",
    "dataset_type = \"text/csv\"\n",
    "\n",
    "with open(validation_dataset) as f:\n",
    "    headers_line = f.readline().rstrip()\n",
    "all_headers = headers_line.split(\",\")\n",
    "label_header = all_headers[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To verify that the execution role for this notebook has the necessary permissions to proceed. Put a simple test object into the S3 bucket speciﬁed above. If this command fails, update the role to have `s3:PutObject` permission on the bucket and try again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Upload a test file\n",
    "S3Uploader.upload(test_file, f\"s3://{bucket}/test_upload\")\n",
    "print(\"Success! We are all set to proceed.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PART A: Capturing real-time inference data from Amazon SageMaker endpoints\n",
    "Create an endpoint to showcase the data capture capability in action. (In next parts, model monitors will be created to process the data.)\n",
    "\n",
    "## Upload the pre-trained model to Amazon S3\n",
    "As an example, this code uploads a pre-trained XGBoost model that is ready for to be deployed. This model was trained using the [XGBoost Churn Prediction Notebook](https://github.com/aws/amazon-sagemaker-examples/blob/master/introduction_to_applying_machine_learning/xgboost_customer_churn/xgboost_customer_churn.ipynb) in SageMaker."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_url = S3Uploader.upload(model_file, s3_key)\n",
    "print(f\"Model file has been uploaded to {model_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deploy the model to Amazon SageMaker\n",
    "Start with deploying a pre-trained churn prediction model. Here, create the SageMaker `Model` object with the image and model data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_name = f\"DEMO-xgb-churn-pred-model-monitor-{datetime.utcnow():%Y-%m-%d-%H%M}\"\n",
    "print(\"Model name: \", model_name)\n",
    "endpoint_name = f\"DEMO-xgb-churn-model-monitor-{datetime.utcnow():%Y-%m-%d-%H%M}\"\n",
    "print(\"Endpoint name: \", endpoint_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To enable data capture for monitoring jobs, here specify the new capture option called `DataCaptureConfig`, it enables capturing the request payload and the response payload of the endpoint. The capture config applies to all variants. Go ahead with the deployment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image_uri = image_uris.retrieve(\"xgboost\", region, \"0.90-1\")\n",
    "print(f\"XGBoost image uri: {image_uri}\")\n",
    "model = Model(\n",
    "    role=role,\n",
    "    name=model_name,\n",
    "    image_uri=image_uri,\n",
    "    model_data=model_url,\n",
    "    sagemaker_session=sagemaker_session,\n",
    ")\n",
    "\n",
    "data_capture_config = DataCaptureConfig(\n",
    "    enable_capture=True,\n",
    "    sampling_percentage=100,\n",
    "    destination_s3_uri=s3_capture_upload_path,\n",
    ")\n",
    "print(f\"Deploying model {model_name} to endpoint {endpoint_name}\")\n",
    "model.deploy(\n",
    "    initial_instance_count=endpoint_instance_count,\n",
    "    instance_type=endpoint_instance_type,\n",
    "    endpoint_name=endpoint_name,\n",
    "    data_capture_config=data_capture_config,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Invoke the deployed model\n",
    "\n",
    "Now send data to this endpoint to get inferences in real time. Because data capture is enabled in the previous steps, the request and response payload, along with some additional metadata, is saved in the Amazon S3 location specified in the DataCaptureConfig."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"Sending test traffic to the endpoint {endpoint_name}. \\nPlease wait\", end=\"\")\n",
    "test_dataset_size = 0  # record the number of rows in data we're sending for inference\n",
    "with open(test_dataset, \"r\") as f:\n",
    "    for row in f:\n",
    "        if test_dataset_size < 120:\n",
    "            payload = row.rstrip(\"\\n\")\n",
    "            response = sagemaker_runtime_client.invoke_endpoint(\n",
    "                EndpointName=endpoint_name,\n",
    "                Body=payload,\n",
    "                ContentType=dataset_type,\n",
    "            )\n",
    "            prediction = response[\"Body\"].read()\n",
    "            print(\".\", end=\"\", flush=True)\n",
    "            time.sleep(0.5)\n",
    "        test_dataset_size += 1\n",
    "\n",
    "print()\n",
    "print(\"Done!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## View captured data\n",
    "\n",
    "Now list the data capture files stored in Amazon S3. There should be different files from different time periods organized based on the hour in which the invocation occurred. The format of the Amazon S3 path is:\n",
    "\n",
    "`s3://{destination-bucket-prefix}/{endpoint-name}/{variant-name}/yyyy/mm/dd/hh/filename.jsonl`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Waiting 30 seconds for captures to show up\", end=\"\")\n",
    "for _ in range(30):\n",
    "    capture_files = sorted(S3Downloader.list(f\"{s3_capture_upload_path}/{endpoint_name}\"))\n",
    "    if capture_files:\n",
    "        break\n",
    "    print(\".\", end=\"\", flush=True)\n",
    "    time.sleep(1)\n",
    "print()\n",
    "print(\"Found Capture Files:\")\n",
    "print(\"\\n \".join(capture_files[-5:]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, view the content of a single capture file. Take a quick peek at the first few lines in the captured file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "capture_file = S3Downloader.read_file(capture_files[-1]).split(\"\\n\")[-10:-1]\n",
    "print(capture_file[-1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, the contents of a single line is present below in a formatted JSON file to observe a little better."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(json.dumps(json.loads(capture_file[-1]), indent=2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start generating some artificial traffic\n",
    "The cell below starts a thread to send some traffic to the endpoint. If there is no traffic, the monitoring jobs are marked as `Failed` since there is no data to process."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import threading\n",
    "\n",
    "\n",
    "class WorkerThread(threading.Thread):\n",
    "    def __init__(self, do_run, *args, **kwargs):\n",
    "        super(WorkerThread, self).__init__(*args, **kwargs)\n",
    "        self.__do_run = do_run\n",
    "        self.__terminate_event = threading.Event()\n",
    "\n",
    "    def terminate(self):\n",
    "        self.__terminate_event.set()\n",
    "\n",
    "    def run(self):\n",
    "        while not self.__terminate_event.is_set():\n",
    "            self.__do_run(self.__terminate_event)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def invoke_endpoint(terminate_event):\n",
    "    with open(test_dataset, \"r\") as f:\n",
    "        i = 0\n",
    "        for row in f:\n",
    "            payload = row.rstrip(\"\\n\")\n",
    "            response = sagemaker_runtime_client.invoke_endpoint(\n",
    "                EndpointName=endpoint_name,\n",
    "                ContentType=\"text/csv\",\n",
    "                Body=payload,\n",
    "                InferenceId=str(i),  # unique ID per row\n",
    "            )\n",
    "            i += 1\n",
    "            response[\"Body\"].read()\n",
    "            time.sleep(1)\n",
    "            if terminate_event.is_set():\n",
    "                break\n",
    "\n",
    "\n",
    "# Keep invoking the endpoint with test data\n",
    "invoke_endpoint_thread = WorkerThread(do_run=invoke_endpoint)\n",
    "invoke_endpoint_thread.start()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice the `inferenceId` attribute used above to invoke. If this is present, it will be used to join with ground truth data (otherwise `eventId` will be used):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start generating some fake ground truth\n",
    "\n",
    "Besides captures, model bias monitoring execution also requires ground truth data. In real use cases, ground truth data should be regularly collected and uploaded to designated S3 location. In this example notebook, below code snippet is used to generate fake ground truth data. The first-party merge container will combine captures and ground truth data, and the merged data will be passed to model bias monitoring job for analysis. Similar to captures, the model bias monitoring execution will fail if there's no data to merge."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "\n",
    "def ground_truth_with_id(inference_id):\n",
    "    random.seed(inference_id)  # to get consistent results\n",
    "    rand = random.random()\n",
    "    # format required by the merge container\n",
    "    return {\n",
    "        \"groundTruthData\": {\n",
    "            \"data\": \"1\" if rand < 0.7 else \"0\",  # randomly generate positive labels 70% of the time\n",
    "            \"encoding\": \"CSV\",\n",
    "        },\n",
    "        \"eventMetadata\": {\n",
    "            \"eventId\": str(inference_id),\n",
    "        },\n",
    "        \"eventVersion\": \"0\",\n",
    "    }\n",
    "\n",
    "\n",
    "def upload_ground_truth(upload_time):\n",
    "    records = [ground_truth_with_id(i) for i in range(test_dataset_size)]\n",
    "    fake_records = [json.dumps(r) for r in records]\n",
    "    data_to_upload = \"\\n\".join(fake_records)\n",
    "    target_s3_uri = f\"{ground_truth_upload_path}/{upload_time:%Y/%m/%d/%H/%M%S}.jsonl\"\n",
    "    print(f\"Uploading {len(fake_records)} records to\", target_s3_uri)\n",
    "    S3Uploader.upload_string_as_file_body(data_to_upload, target_s3_uri)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Generate data for the last hour\n",
    "upload_ground_truth(datetime.utcnow() - timedelta(hours=1))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Generate data once a hour\n",
    "def generate_fake_ground_truth(terminate_event):\n",
    "    upload_ground_truth(datetime.utcnow())\n",
    "    for _ in range(0, 60):\n",
    "        time.sleep(60)\n",
    "        if terminate_event.is_set():\n",
    "            break\n",
    "\n",
    "\n",
    "ground_truth_thread = WorkerThread(do_run=generate_fake_ground_truth)\n",
    "ground_truth_thread.start()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PART B: Model Bias Monitor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Model bias monitor can detect bias drift of Machine Learning models in a regular basis. Similar to the other monitoring types, the standard procedure of creating a model bias monitor is first baselining and then monitoring schedule."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_monitor = ModelBiasMonitor(\n",
    "    role=role,\n",
    "    sagemaker_session=sagemaker_session,\n",
    "    max_runtime_in_seconds=1800,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Create a baselining job\n",
    "\n",
    "A baselining job runs predictions on training dataset and suggests constraints. `suggest_baseline()` method starts a `SageMakerClarifyProcessor` processing job using SageMaker Clarify container to generate the constraints.\n",
    "\n",
    "The step is not mandatory, but providing constraints file to the monitor can enable violations file generation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configurations\n",
    "\n",
    "Information about the input data need to be provided to the processor."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`DataConfig` stores information about the dataset to be analyzed, for example the dataset file, its format (CSV or JSONLines), headers (if any) and label."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_baselining_job_result_uri = f\"{baseline_results_uri}/model_bias\"\n",
    "model_bias_data_config = DataConfig(\n",
    "    s3_data_input_path=validation_dataset,\n",
    "    s3_output_path=model_bias_baselining_job_result_uri,\n",
    "    label=label_header,\n",
    "    headers=all_headers,\n",
    "    dataset_type=dataset_type,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`BiasConfig` is the configuration of the sensitive groups in the dataset. Typically, bias is measured by computing a metric and comparing it across groups. The group of interest is specified using the \"facet.\" For post-training bias, the possitive label should also be taken into account."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_config = BiasConfig(\n",
    "    label_values_or_threshold=[1],\n",
    "    facet_name=\"Account Length\",\n",
    "    facet_values_or_threshold=[100],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`ModelPredictedLabelConfig` specifies how to extract a predicted label from the model output. This model returns probability that user will churn. Here choose an arbitrary 0.8 cutoff to consider that a customer will churn. For more complicated outputs, there are a few more options, like \"label\" is the index, name or JSONpath to locate predicted label in endpoint response payload."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_predicted_label_config = ModelPredictedLabelConfig(\n",
    "    probability_threshold=0.8,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`ModelConfig` is configuration related to model to be used for inferencing. In order to compute post-training bias metrics, the computation needs to get inferences for the model name provided. To accomplish this, the processing job will use the model to create an ephemeral endpoint (also known as \"shadow endpoint\"). The processing job will delete the shadow endpoint after the computations are completed. The configuration is also used by explainability monitor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_config = ModelConfig(\n",
    "    model_name=model_name,\n",
    "    instance_count=endpoint_instance_count,\n",
    "    instance_type=endpoint_instance_type,\n",
    "    content_type=dataset_type,\n",
    "    accept_type=dataset_type,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Kick off baselining job"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_monitor.suggest_baseline(\n",
    "    model_config=model_config,\n",
    "    data_config=model_bias_data_config,\n",
    "    bias_config=model_bias_config,\n",
    "    model_predicted_label_config=model_predicted_label_config,\n",
    ")\n",
    "print(f\"ModelBiasMonitor baselining job: {model_bias_monitor.latest_baselining_job_name}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below cell waits until the baselining job is completed and then inspects the suggested constraints. This step can be skipped, because the monitor to be scheduled will automatically pick up baselining job name and wait for it before monitoring execution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_monitor.latest_baselining_job.wait(logs=False)\n",
    "model_bias_constraints = model_bias_monitor.suggested_constraints()\n",
    "print()\n",
    "print(f\"ModelBiasMonitor suggested constraints: {model_bias_constraints.file_s3_uri}\")\n",
    "print(S3Downloader.read_file(model_bias_constraints.file_s3_uri))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Schedule model bias monitor\n",
    "\n",
    "With above constraints collected, now call `create_monitoring_schedule()` method to schedule a hourly monitor, to analyze the data with monitoring schedule. If a baselining job has been submitted, then the monitor will automatically pick up analysis configuration from the baselining job. But if the baselining step is skipped, or the capture dataset has different nature than the training dataset, then analysis configuration has to be provided.\n",
    "\n",
    "`BiasAnalysisConfig` is a subset of the configuration of the baselining job, many options are not needed because,\n",
    "* Model bias monitor will merge captures and ground truth data and use merged data as dataset. (~~DataConfig~~)\n",
    "* Captures already include predictions, so there is no need to create shadow endpoint. (~~ModelConfig~~)\n",
    "* Attributes like probability threshold are provided as part of EndpointInput. (~~ModelPredictedLabelConfig~~)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_analysis_config = None\n",
    "if not model_bias_monitor.latest_baselining_job:\n",
    "    model_bias_analysis_config = BiasAnalysisConfig(\n",
    "        model_bias_config,\n",
    "        headers=all_headers,\n",
    "        label=label_header,\n",
    "    )\n",
    "model_bias_monitor.create_monitoring_schedule(\n",
    "    analysis_config=model_bias_analysis_config,\n",
    "    output_s3_uri=s3_report_path,\n",
    "    endpoint_input=EndpointInput(\n",
    "        endpoint_name=endpoint_name,\n",
    "        destination=\"/opt/ml/processing/input/endpoint\",\n",
    "        start_time_offset=\"-PT1H\",\n",
    "        end_time_offset=\"-PT0H\",\n",
    "        probability_threshold_attribute=0.8,\n",
    "    ),\n",
    "    ground_truth_input=ground_truth_upload_path,\n",
    "    schedule_cron_expression=schedule_expression,\n",
    ")\n",
    "print(f\"Model bias monitoring schedule: {model_bias_monitor.monitoring_schedule_name}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Wait for the first execution\n",
    "\n",
    "The schedule starts jobs at the previously specified intervals. Code below wait util time crosses the hour boundary (in UTC) to see executions kick off.\n",
    "\n",
    "Note: Even for an hourly schedule, Amazon SageMaker has a buffer period of 20 minutes to schedule executions. The execution might start in anywhere from zero to ~20 minutes from the hour boundary. This is expected and done for load balancing in the backend."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def wait_for_execution_to_start(model_monitor):\n",
    "    print(\n",
    "        \"A hourly schedule was created above and it will kick off executions ON the hour (plus 0 - 20 min buffer).\"\n",
    "    )\n",
    "\n",
    "    print(\"Waiting for the first execution to happen\", end=\"\")\n",
    "    schedule_desc = model_monitor.describe_schedule()\n",
    "    while \"LastMonitoringExecutionSummary\" not in schedule_desc:\n",
    "        schedule_desc = model_monitor.describe_schedule()\n",
    "        print(\".\", end=\"\", flush=True)\n",
    "        time.sleep(60)\n",
    "    print()\n",
    "    print(\"Done! Execution has been created\")\n",
    "\n",
    "    print(\"Now waiting for execution to start\", end=\"\")\n",
    "    while schedule_desc[\"LastMonitoringExecutionSummary\"][\"MonitoringExecutionStatus\"] in \"Pending\":\n",
    "        schedule_desc = model_monitor.describe_schedule()\n",
    "        print(\".\", end=\"\", flush=True)\n",
    "        time.sleep(10)\n",
    "\n",
    "    print()\n",
    "    print(\"Done! Execution has started\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wait_for_execution_to_start(model_bias_monitor)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In real world, a monitoring schedule is supposed to be active all the time. But in this example, it can be stopped to avoid incurring extra charges. A stopped schedule will not trigger further executions, but the ongoing execution will continue. And if needed, the schedule can be restarted by `start_monitoring_schedule()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_bias_monitor.stop_monitoring_schedule()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Wait for the execution to finish\n",
    "\n",
    "In the previous cell, the first execution has started. This section waits for the execution to finish so that its analysis results are available. Here are the possible terminal states and what each of them mean:\n",
    "\n",
    "* Completed - This means the monitoring execution completed and no issues were found in the violations report.\n",
    "* CompletedWithViolations - This means the execution completed, but constraint violations were detected.\n",
    "* Failed - The monitoring execution failed, maybe due to client error (perhaps incorrect role permissions) or infrastructure issues. Further examination of FailureReason and ExitMessage is necessary to identify what exactly happened.\n",
    "* Stopped - job exceeded max runtime or was manually stopped."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Waits for the schedule to have last execution in a terminal status.\n",
    "def wait_for_execution_to_finish(model_monitor):\n",
    "    schedule_desc = model_monitor.describe_schedule()\n",
    "    execution_summary = schedule_desc.get(\"LastMonitoringExecutionSummary\")\n",
    "    if execution_summary is not None:\n",
    "        print(\"Waiting for execution to finish\", end=\"\")\n",
    "        while execution_summary[\"MonitoringExecutionStatus\"] not in [\n",
    "            \"Completed\",\n",
    "            \"CompletedWithViolations\",\n",
    "            \"Failed\",\n",
    "            \"Stopped\",\n",
    "        ]:\n",
    "            print(\".\", end=\"\", flush=True)\n",
    "            time.sleep(60)\n",
    "            schedule_desc = model_monitor.describe_schedule()\n",
    "            execution_summary = schedule_desc[\"LastMonitoringExecutionSummary\"]\n",
    "        print()\n",
    "        print(\"Done! Execution has finished\")\n",
    "    else:\n",
    "        print(\"Last execution not found\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wait_for_execution_to_finish(model_bias_monitor)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inspect execution results\n",
    "\n",
    "List the generated reports,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "schedule_desc = model_bias_monitor.describe_schedule()\n",
    "execution_summary = schedule_desc.get(\"LastMonitoringExecutionSummary\")\n",
    "if execution_summary and execution_summary[\"MonitoringExecutionStatus\"] in [\n",
    "    \"Completed\",\n",
    "    \"CompletedWithViolations\",\n",
    "]:\n",
    "    last_model_bias_monitor_execution = model_bias_monitor.list_executions()[-1]\n",
    "    last_model_bias_monitor_execution_report_uri = (\n",
    "        last_model_bias_monitor_execution.output.destination\n",
    "    )\n",
    "    print(f\"Report URI: {last_model_bias_monitor_execution_report_uri}\")\n",
    "    last_model_bias_monitor_execution_report_files = sorted(\n",
    "        S3Downloader.list(last_model_bias_monitor_execution_report_uri)\n",
    "    )\n",
    "    print(\"Found Report Files:\")\n",
    "    print(\"\\n \".join(last_model_bias_monitor_execution_report_files))\n",
    "else:\n",
    "    last_model_bias_monitor_execution = None\n",
    "    print(\n",
    "        \"====STOP==== \\n No completed executions to inspect further. Please wait till an execution completes or investigate previously reported failures.\"\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If there are violations compared to the baseline, they will be listed here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if last_model_bias_monitor_execution:\n",
    "    model_bias_violations = last_model_bias_monitor_execution.constraint_violations()\n",
    "    if model_bias_violations:\n",
    "        print(model_bias_violations.body_dict)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The analysis results and CloudWatch metrics are visualized in SageMaker Studio. Select the Endpoints tab, then double click the endpoint to show the UI."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PART C: Model Explainability Monitor\n",
    "\n",
    "Model explainability monitor can explain the predictions of a deployed model producing inferences and detect feature attribution drift on a regular basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_explainability_monitor = ModelExplainabilityMonitor(\n",
    "    role=role,\n",
    "    sagemaker_session=sagemaker_session,\n",
    "    max_runtime_in_seconds=1800,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a baselining job\n",
    "\n",
    "Similary, a baselining job can be scheduled to suggest constraints for model explainability monitor."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, the explainability baselining job shares the test dataset with the bias baselining job, so here it uses the same `DataConfig`, the only difference is the job output URI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_explainability_baselining_job_result_uri = f\"{baseline_results_uri}/model_explainability\"\n",
    "model_explainability_data_config = DataConfig(\n",
    "    s3_data_input_path=validation_dataset,\n",
    "    s3_output_path=model_explainability_baselining_job_result_uri,\n",
    "    label=label_header,\n",
    "    headers=all_headers,\n",
    "    dataset_type=dataset_type,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Currently the Clarify explainer offers a scalable and efficient implementation of SHAP, so the explainability config is `SHAPConfig`, including\n",
    "* baseline: A list of rows (at least one) or S3 object URI to be used as the baseline dataset in the Kernel SHAP algorithm. The format should be the same as the dataset format. Each row should contain only the feature columns/values and omit the label column/values.\n",
    "* 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.\n",
    "* agg_method: Aggregation method for global SHAP values. Valid values are\n",
    "  * \"mean_abs\" (mean of absolute SHAP values for all instances),\n",
    "  * \"median\" (median of SHAP values for all instances) and\n",
    "  * \"mean_sq\" (mean of squared SHAP values for all instances).\n",
    "* use_logit: Indicator of whether the logit function is to be applied to the model predictions. Default is False. If \"use_logit\" is true then the SHAP values will have log-odds units.\n",
    "* save_local_shap_values (bool): Indicator of whether to save the local SHAP values in the output location. Default is True."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Here use the mean value of test dataset as SHAP baseline\n",
    "test_dataframe = pd.read_csv(test_dataset, header=None)\n",
    "shap_baseline = [list(test_dataframe.mean())]\n",
    "\n",
    "shap_config = SHAPConfig(\n",
    "    baseline=shap_baseline,\n",
    "    num_samples=100,\n",
    "    agg_method=\"mean_abs\",\n",
    "    save_local_shap_values=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Kick off baselining job\n",
    "\n",
    "The same model_config is required, because the explainability baselining job needs to create shadow endpoint to get predictions for generated synthetic dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_explainability_monitor.suggest_baseline(\n",
    "    data_config=model_explainability_data_config,\n",
    "    model_config=model_config,\n",
    "    explainability_config=shap_config,\n",
    ")\n",
    "print(\n",
    "    f\"ModelExplainabilityMonitor baselining job: {model_explainability_monitor.latest_baselining_job_name}\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wait for baselining job to finish (or skip this cell because the monitor to be scheduled will wait for it anyway)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_explainability_monitor.latest_baselining_job.wait(logs=False)\n",
    "model_explainability_constraints = model_explainability_monitor.suggested_constraints()\n",
    "print()\n",
    "print(\n",
    "    f\"ModelExplainabilityMonitor suggested constraints: {model_explainability_constraints.file_s3_uri}\"\n",
    ")\n",
    "print(S3Downloader.read_file(model_explainability_constraints.file_s3_uri))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Schedule model explainability monitor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Call `create_monitoring_schedule()` method to schedule a hourly monitor, to analyze the data with monitoring schedule. If a baselining job has been submitted, then the monitor will automatically pick up analysis configuration from the baselining job. But if the baselining step is skipped, or the capture dataset has different nature than the training dataset, then analysis configuration has to be provided.\n",
    "\n",
    "`ModelConfig` is required by `ExplainabilityAnalysisConfig` for the same reason as it is required by the baselining job. Note that only features are required for computing feature attribution, so ground truth label should be excluded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_explainability_analysis_config = None\n",
    "if not model_explainability_monitor.latest_baselining_job:\n",
    "    # Remove label because only features are required for the analysis\n",
    "    headers_without_label_header = copy.deepcopy(all_headers)\n",
    "    headers_without_label_header.remove(label_header)\n",
    "    model_explainability_analysis_config = ExplainabilityAnalysisConfig(\n",
    "        explainability_config=shap_config,\n",
    "        model_config=model_config,\n",
    "        headers=headers_without_label_header,\n",
    "    )\n",
    "model_explainability_monitor.create_monitoring_schedule(\n",
    "    output_s3_uri=s3_report_path,\n",
    "    endpoint_input=endpoint_name,\n",
    "    schedule_cron_expression=schedule_expression,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Wait for execution and inspect analysis results\n",
    "\n",
    "Once created the schedule is started by default, here wait for the its first execution to start, then stop the schedule to avoid incurring charges."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wait_for_execution_to_start(model_explainability_monitor)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_explainability_monitor.stop_monitoring_schedule()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wait further for the execution to finish, then inspect its analysis results,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wait_for_execution_to_finish(model_explainability_monitor)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "schedule_desc = model_explainability_monitor.describe_schedule()\n",
    "execution_summary = schedule_desc.get(\"LastMonitoringExecutionSummary\")\n",
    "if execution_summary and execution_summary[\"MonitoringExecutionStatus\"] in [\n",
    "    \"Completed\",\n",
    "    \"CompletedWithViolations\",\n",
    "]:\n",
    "    last_model_explainability_monitor_execution = model_explainability_monitor.list_executions()[-1]\n",
    "    last_model_explainability_monitor_execution_report_uri = (\n",
    "        last_model_explainability_monitor_execution.output.destination\n",
    "    )\n",
    "    print(f\"Report URI: {last_model_explainability_monitor_execution_report_uri}\")\n",
    "    last_model_explainability_monitor_execution_report_files = sorted(\n",
    "        S3Downloader.list(last_model_explainability_monitor_execution_report_uri)\n",
    "    )\n",
    "    print(\"Found Report Files:\")\n",
    "    print(\"\\n \".join(last_model_explainability_monitor_execution_report_files))\n",
    "else:\n",
    "    last_model_explainability_monitor_execution = None\n",
    "    print(\n",
    "        \"====STOP==== \\n No completed executions to inspect further. Please wait till an execution completes or investigate previously reported failures.\"\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If there are any violations compared to the baseline, they will be listed here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if last_model_explainability_monitor_execution:\n",
    "    model_explainability_violations = (\n",
    "        last_model_explainability_monitor_execution.constraint_violations()\n",
    "    )\n",
    "    if model_explainability_violations:\n",
    "        print(model_explainability_violations.body_dict)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The analysis results and CloudWatch metrics are visualized in SageMaker Studio. Select the Endpoints tab, then double click the endpoint to show the UI."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PART D: Cleanup\n",
    "\n",
    "The endpoint can keep running and capturing data, but if there is no plan to collect more data or use this endpoint further, it should be deleted to avoid incurring additional charges. Note that deleting endpoint does not delete the data that was captured during the model invocations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First stop the worker threads,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "invoke_endpoint_thread.terminate()\n",
    "ground_truth_thread.terminate()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then stop all monitors scheduled for the endpoint"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sagemaker.predictor import Predictor\n",
    "\n",
    "predictor = Predictor(endpoint_name, sagemaker_session=sagemaker_session)\n",
    "model_monitors = predictor.list_monitors()\n",
    "for model_monitor in model_monitors:\n",
    "    model_monitor.stop_monitoring_schedule()\n",
    "    wait_for_execution_to_finish(model_monitor)\n",
    "    model_monitor.delete_monitoring_schedule()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally delete the endpoint"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predictor.delete_endpoint()\n",
    "predictor.delete_model()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "instance_type": "ml.t3.medium",
  "kernelspec": {
   "display_name": "Python 3 (Data Science)",
   "language": "python",
   "name": "python3__SAGEMAKER_INTERNAL__arn:aws:sagemaker:us-east-2:429704687514:image/datascience-1.0"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}