{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Amazon Fraud Detector from End to End for Account Takeover Insights \n",
"### Un-supervised fraud detection \n",
"-------\n",
"- [Introduction](#Introduction)\n",
"- [Data preparation](#Data_preparation)\n",
"- [Set up AWS credentials & permissions](#Set_up_AWS_credentials_permissions)\n",
"- [Plan](#Plan)\n",
"\n",
"\n",
"## Introduction\n",
"-------\n",
"\n",
"Amazon Fraud Detector (AFD) is a fully managed service that makes it easy to identify potentially fraudulent online activities such as online payment fraud, creation of fake accounts, and account takeovers. Fraud Detector capitalizes on the latest advances in machine learning (ML) and 20 years of fraud detection expertise from AWS and Amazon.com to automatically identify potentially fraudulent activities so you can catch more fraud faster. \n",
"\n",
"In this notebook, we'll use the Amazon Fraud Detector API to define an entity and an event of interest and send events to AFD from a CSV file stored in S3. Next, we'll train a model with Account Takeover Insight template using the events we have sent. After that, we'll derive some rules and create a \"detector\" by combining our entity, event, model, and rules into a single endpoint. Finally, we'll apply the detector to a sample of our data to identify potentially fraudulent events.\n",
"\n",
"After running this notebook you should be able to: \n",
"\n",
"- Define an Entity and an Event\n",
"- Send Events to AFD\n",
"- Train a Machine Learning (ML) Model\n",
"- Author Rules to identify potential fraud based on the model's score\n",
"- Create a Fraud Detector\n",
"- Apply the Detector's \"predict\" function, to generate a model score and rule outcomes on data \n",
"\n",
"If you would like to know more, please check out [Fraud Detector's Documentation](https://docs.aws.amazon.com/frauddetector/). \n",
"\n",
"\n",
"## Data preparation \n",
"------\n",
"\n",
"Before you train a Transaction Fraud Insights model, ensure that you have stored at least 10,000 records in your training dataset within Amazon Fraud Detector. We recommend that you collect at least 3-6 weeks of historic data with at least 1,500 unique entities. The Transaction Fraud Insights model will calculate aggregates likes account’s age, transaction counts based on the account’s history. Therefore, providing the full history of the accounts will help the model to calculate the aggregates correctly to capture the fraud patterns.\n",
"\n",
"In addition to the event variables, the training dataset must contain the following headers:\n",
"* ENTITY_TYPE - Who is performing the activity, e.g. customer. Currently, AFD only support one ENTITY_TYPE per EVENT_TYPE. That column should contain a single value. \n",
"* ENTITY_ID - An identifier for who is performing the activity, e.g. customer id\n",
"* EVENT_ID - An identifier for the event, e.g. order id\n",
"* EVENT_TIMESTAMP - The timestamp of when the event occurred. The timestamp must be in ISO 8601 standard in UTC.\n",
"* EVENT_LABEL - Classifies the event as fraudulent or legitimate. The values in the column must correspond to the values defined in the event type.\n",
"* LABEL_TIMESTAMP - Timestamp of when the label is updated. LABEL_TIMESTAMP is required if EVENT_LABEL is included. If you do not have that data, you can duplicate the EVENT_TIMESTAMP column and rename it as LABEL_TIMESTAMP.\n",
"\n",
"\n",
"\n",
"## Set up AWS credentials & permissions \n",
"----\n",
"\n",
"https://docs.aws.amazon.com/frauddetector/latest/ug/set-up.html\n",
"\n",
"To use Amazon Fraud Detector, you have to set up permissions that allow access to the Amazon Fraud Detector console and API operations. You also have to allow Amazon Fraud Detector to perform tasks on your behalf and to access resources that you own. We recommend creating an AWS Identify and Access Management (IAM) user with access restricted to Amazon Fraud Detector operations and required permissions. You can add other permissions as needed.\n",
"\n",
"The following policies provide the required permission to use Amazon Fraud Detector. If you are using SageMaker Notebook Instance, add the following two policies to the Instance's IAM role and restart your kernel:\n",
"\n",
"- *AmazonFraudDetectorFullAccessPolicy* \n",
" Allows you to perform the following actions: \n",
" - Access all Amazon Fraud Detector resources \n",
" - List and describe all model endpoints in Amazon SageMaker \n",
" - List all IAM roles in the account \n",
" - List all Amazon S3 buckets \n",
" - Allow IAM Pass Role to pass a role to Amazon Fraud Detector \n",
"\n",
"- *AmazonS3FullAccess* \n",
" Allows full access to Amazon S3. This is required to upload training files to S3.\n",
" \n",
" \n",
" \n",
"## Plan\n",
"------\n",
"A *Detector* contains the event, model(s) and rule(s) for a particular type of fraud that you want to detect. We'll use the following 8 steps to plan a Fraud Detector:\n",
"\n",
"1. [Setup notebook](#setup_notebook) \n",
" a. Name the major components: Event, Entity, Model, Detector \n",
" b. Specify the MODEL_TYPE you want to train \n",
" c. Plug in your S3 Bucket and CSV File\n",
" \n",
"2. [Load and profile your dataset](#load_and_profile_your_data) \n",
" a. This will give you an idea of what your dataset contains \n",
" b. This will also identify the variables and labels that will need to be created to define your event\n",
"\n",
"3. [Create event variables and labels](#create_event_variables_and_labels) \n",
" a. This will create the variables and labels in fraud detector \n",
"\n",
"4. [Define your Entity and Event Type](#define_your_entity_and_event_type) \n",
" a. What is activity that you are detecting? That's likely your Event Type (e.g. transaction) \n",
" b. Who is performing this activity? That's likely your Entity (e.g. customer)\n",
"\n",
"5. [Send events](#send_events) \n",
" a. This will ingest your events to AFD \n",
" \n",
"6. [Create and train your model](#create_and_train_your_model)\t\n",
" a. Model training takes anywhere from 45-60 minutes. Once complete you need to promote your endpoint \n",
" b. Promote your model\n",
"\n",
"7. [Create a Fraud Detector, generate Rules and assemble your Detector](#create_detector) \n",
" a. Create your detector \n",
" b. Define outcomes, e.g. fraud, investigate and approve \n",
" c. Create rules based on your model scores \n",
" d. Assemble your detector: combine your rule(s) and model into a \"detector\"\n",
"\n",
"8. [Make predictions](#make_predictions) \n",
" a. Interactively call predict API on a handful of records "
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Current boto3 version: 1.24.36\n"
]
}
],
"source": [
"# -- check boto3 version, if it is lower than 1.18.59, update it and restart the kernel --\n",
"import boto3\n",
"import os\n",
"\n",
"current_boto3_version = boto3.__version__\n",
"print('Current boto3 version:', current_boto3_version)\n",
"\n",
"if current_boto3_version < '1.24.36':\n",
" print('update boto3...')\n",
" %pip install 'boto3>=1.24.36'\n",
" os._exit(00) "
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"# -- import packages --\n",
"import boto3\n",
"import time\n",
"import logging\n",
"import numpy as np\n",
"import pandas as pd\n",
"import matplotlib.pyplot as plt\n",
"from multiprocessing import Pool\n",
"from datetime import datetime, date\n",
"from dateutil.relativedelta import relativedelta\n",
"import csv, codecs\n",
"from sklearn.metrics import roc_curve, roc_auc_score, auc, roc_auc_score\n",
"\n",
"# -- for display --\n",
"from IPython.core.display import display, HTML\n",
"from IPython.display import clear_output\n",
"display(HTML(\"\"))\n",
"pd.set_option('display.max_rows', 500)\n",
"pd.set_option('display.max_columns', 500)\n",
"pd.set_option('display.width', 1000)\n",
"%matplotlib inline "
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [],
"source": [
"# -- initialize the AFD client --\n",
"client = boto3.client('frauddetector')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 1. Setup notebook \n",
"-----\n",
"\n",
"***To get started***\n",
"\n",
"1. Name the major components of Fraud Detector\n",
"2. Specify the MODEL_TYPE you want to train: ACCOUNT_TAKEOVER_INSIGHTS. \n",
"2. Plug in your S3 Bucket and CSV file path\n",
"\n",
"Then you can interactively exeucte the code cells in the notebook, no need to change anything unless you want to. \n",
"\n",
"\n",
"
Major Fraud Detector Components \n",
" \n",
"- **EVENT_TYPE** is a business activity that you want evaluated for fraud risk \n",
"- **ENTITY_TYPE** represents the \"what or who\" that is performing the event you want to evaluate\n",
"- **MODEL_NAME** is the name of your supervised machine learning model that Fraud Detector trains on your behalf\n",
"- **DETECTOR_NAME** is the name of the detector that contains the detection logic (model and rules) that you apply to events that you want to evaluate for fraud\n",
"\n",
"
\n",
"\n",
"\n",
"Identify the following assets:\n",
"\n",
"
Bucket, File and ARN Role\n",
"\n",
"- **S3_BUCKET** is the name of the bucket where your file lives\n",
"- **S3_FILE** is the URL to your s3 file\n",
"- **ARN_ROLE** is the role Fraud Detector use to access your data in s3 bucket\n",
"\n",
"
\n",
"\n",
"\n",
"_**Note**: To use Amazon Fraud Detector, you have to set up permissions that allow access to the Amazon Fraud Detector console and API operations. You also have to allow Amazon Fraud Detector to perform tasks on your behalf and to access resources that you own. We recommend creating an AWS Identify and Access Management (IAM) user with access restricted to. Amazon Fraud Detector operations and required permissions. You can add other permissions as needed. See \"Create an IAM User and Assign Required Permissions\" in the user's guide: https://docs.aws.amazon.com/frauddetector/latest/ug/set-up.html_"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"
\n",
"Update following section: Define event, model, detector names, and data location\n",
"
"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"# -- this is all you need to fill out, once complete simply interactively run each code cell -- \n",
"EVENT_TYPE = \"your_event_name\"\n",
"EVENT_DESC = \"your event description\"\n",
"\n",
"MODEL_NAME = \"your_model_name\"\n",
"MODEL_DESC = \"your model description\"\n",
"\n",
"DETECTOR_NAME = \"your_detector_name\" \n",
"DETECTOR_DESC = \"your detector description\"\n",
"\n",
"MODEL_TYPE = \"ACCOUNT_TAKEOVER_INSIGHTS\" \n",
"\n",
"S3_BUCKET = \"your-s3-bucket-with-data\" \n",
"S3_FILE = \"path-to-your-data-file\" \n",
"ARN_ROLE = \"your-arn-role\"\n",
"\n",
"# -- percentage of data used in model training (by default: 80%). \n",
"TRAINING_PERC = 0.8 "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Header names in your CSV files"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"EVENT_ID\n",
"ENTITY_ID\n",
"ENTITY_TYPE\n",
"EVENT_TIMESTAMP\n",
"EVENT_LABEL\n",
"LABEL_TIMESTAMP\n",
"ip\n",
"useragent\n",
"fp\n",
"session_id\n",
"are_credentials_valid\n"
]
}
],
"source": [
"s3 = boto3.resource('s3')\n",
"obj = s3.Object(S3_BUCKET, S3_FILE)\n",
"body = obj.get()['Body']\n",
"reader = csv.DictReader(codecs.getreader(\"utf-8\")(body))\n",
"header_names = reader.fieldnames\n",
"for item in header_names:\n",
" print(item)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Map header names to mandatory/optional variable types"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"
\n",
"Update following section: Fill the mapping with CSV header names printed above. \n",
"
"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# -- map your data to the variable types --\n",
"# Except the fixed-naming columns (EVENT_ID, ENTITY_ID, ENTITY_TYPE, EVENT_TIMESTAMP), use the VARIABLES_MAP dictionary \n",
"# to map the variable type to the column names in your data.\n",
"# Mandatory variable types include: IP_ADDRESS, USERAGENT, ARE_CREDENTIALS_VALID\n",
"# Optional variable types: FINGERPRINT, SESSION_ID\n",
"\n",
"VARIABLES_MAP = {\n",
" # Mandatory variables\n",
" \"IP_ADDRESS\": \"ip\", # e.g. ip\n",
" \"USERAGENT\": \"useragent\", # e.g. user_agent\n",
" \"ARE_CREDENTIALS_VALID\": \"are_credentials_valid\", # e.g. are_credentials_valid\n",
" \n",
" # Optional variables\n",
" \"FINGERPRINT\": \"fp\", # e.g. fingerprint\n",
" \"SESSION_ID\": \"session_id\" # e.g. session_id\n",
"}\n",
"\n",
"for c in VARIABLES_MAP.keys():\n",
" if VARIABLES_MAP[c]!=\"\" and VARIABLES_MAP[c] not in header_names:\n",
" raise ValueError(f'Variable {VARIABLES_MAP[c]} (type {c}) not in CSV header!')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 2. Load and profile your dataset \n",
"-----\n",
"\n",
"The functions below will: 1) profile your data, creating descriptive statististics, 2) perform basic data quality checks (nulls, unique variables, etc.), and 3) return summary statistics and the EVENT and MODEL schemas used to define your EVENT_TYPE and train your model. \n",
"\n",
"\n",
"_**Important Note**: The functions below provides a layman guess for the fraud/legit labels and variable mapping. Please review the summary stats, event variables, event labels and training data schema and make sure they are aligned with how you want to use the data. You can always manually modify them if needed._\n",
"\n",
"
💡 summary stats, event variables, event labels and training data schema \n",
"\n",
"- summary stats: data quality and summary statistics of the data; used to create variables of the specific feature types\n",
"- event variables: variables associated with the specific event type; used when creating event type and sending events\n",
"- event labels: labels associated with the event type; used when creating event type\n",
"- training data schema: define the variables to build the model, labels to be used as fraud/legit, and how to treat the unlabeled events; By default, we identify the rare event as fraud, and the rest as not-fraud. If you have more than 2 labels in the data or want to map them in a different way, you can manually modify the training data schema \n",
"\n",
"
\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {},
"outputs": [],
"source": [
"# --- no changes; just run this code block ---\n",
"def summary_stats(df, variables_map):\n",
" \"\"\"\n",
" Generate summary statistics for a pandas data frame \n",
" \"\"\"\n",
" rowcnt = len(df)\n",
" \n",
" # -- calculating data statistics and data types -- \n",
" df_s1 = df.agg(['count', 'nunique']).transpose().reset_index().rename(columns={\"index\":\"feature_name\"})\n",
" df_s1[\"null\"] = (rowcnt - df_s1[\"count\"]).astype('int64')\n",
" df_s1[\"not_null\"] = rowcnt - df_s1[\"null\"]\n",
" df_s1[\"null_pct\"] = df_s1[\"null\"] / rowcnt\n",
" df_s1[\"nunique_pct\"] = df_s1['nunique']/ rowcnt\n",
"\n",
" dt = pd.DataFrame(df.dtypes).reset_index().rename(columns={\"index\":\"feature_name\", 0:\"dtype\"})\n",
" df_stats = pd.merge(dt, df_s1, on='feature_name', how='inner').round(4)\n",
" df_stats['nunique'] = df_stats['nunique'].astype('int64')\n",
" df_stats['count'] = df_stats['count'].astype('int64')\n",
" \n",
" \n",
" # -- variable type mapper: map mandatory variables and variables_map -- \n",
" flatten_var_maps = []\n",
" for vartype in variables_map.keys():\n",
" if isinstance(variables_map[vartype], list):\n",
" for var in variables_map[vartype]:\n",
" flatten_var_maps.append([vartype, var])\n",
" else:\n",
" flatten_var_maps.append([vartype, variables_map[vartype]])\n",
" \n",
" for vartype in ['ENTITY_TYPE','ENTITY_ID','EVENT_ID','EVENT_TIMESTAMP']:\n",
" flatten_var_maps.append([vartype, vartype])\n",
" for vartype in ['EVENT_LABEL','LABEL_TIMESTAMP']:\n",
" if vartype in df.columns:\n",
" flatten_var_maps.append([vartype, vartype])\n",
"\n",
" df_schema = pd.DataFrame(flatten_var_maps, columns = ['feature_type', 'feature_name'])\n",
" df_stats = pd.merge(df_stats, df_schema, how = 'left', on = 'feature_name')\n",
" \n",
" # -- variable type mapper: map the rest types based on data type -- \n",
" df_stats.loc[(df_stats['feature_type'].isna())&(df_stats[\"dtype\"] == object), 'feature_type'] = \"CATEGORICAL\"\n",
" df_stats.loc[(df_stats['feature_type'].isna())&((df_stats[\"dtype\"] == \"int64\") | (df_stats[\"dtype\"] == \"float64\")), 'feature_type'] = \"NUMERIC\"\n",
" \n",
" # -- variable validation -- \n",
" df_stats['feature_warning'] = \"NO WARNING\"\n",
" df_stats.loc[(df_stats[\"nunique\"] != 2) & (df_stats[\"feature_name\"] == \"EVENT_LABEL\"),'feature_warning' ] = \"LABEL WARNING, NON-BINARY EVENT LABEL\"\n",
" df_stats.loc[(df_stats[\"nunique_pct\"] > 0.9) & (df_stats['feature_type'] == \"CATEGORICAL\") ,'feature_warning' ] = \"EXCLUDE, GT 90% UNIQUE\"\n",
" df_stats.loc[(df_stats[\"null_pct\"] > 0.2) & (df_stats[\"null_pct\"] <= 0.75), 'feature_warning' ] = \"NULL WARNING, GT 20% MISSING\"\n",
" df_stats.loc[df_stats[\"null_pct\"] > 0.75,'feature_warning' ] = \"EXCLUDE, GT 75% MISSING\"\n",
" df_stats.loc[((df_stats['dtype'] == \"int64\" ) | (df_stats['dtype'] == \"float64\" ) ) & (df_stats['nunique'] < 0.2), 'feature_warning' ] = \"LIKELY CATEGORICAL, NUMERIC w. LOW CARDINALITY\"\n",
" return df_stats[['feature_name', 'feature_type', 'dtype', 'count', 'null', 'null_pct', 'nunique', 'nunique_pct', 'feature_warning']]\n",
"\n",
"\n",
"def prepare_schema(df, df_stats, variables_map):\n",
" \"\"\"\n",
" Prepare schema for following steps\n",
" \"\"\"\n",
" # -- prepare event variables --\n",
" exclude_list = ['ENTITY_TYPE','ENTITY_ID','EVENT_ID','EVENT_TIMESTAMP','EVENT_LABEL','LABEL_TIMESTAMP','UNKNOWN']\n",
" event_variables = df_stats.loc[(~df_stats['feature_type'].isin(exclude_list))]['feature_name'].to_list()\n",
" \n",
" # -- define training_data_schema, Stored events need to specify unlabeledEventsTreatment --\n",
" training_data_schema = {\n",
" 'modelVariables' : df_stats.loc[~(df_stats['feature_type'].isin(exclude_list))]['feature_name'].to_list(),\n",
" }\n",
" \n",
" if 'EVENT_LABEL' in df.columns:\n",
" # -- target -- \n",
" label_value_count = df['EVENT_LABEL'].dropna().astype('str', errors='ignore').value_counts()\n",
" event_labels = label_value_count.index.unique().tolist() \n",
" training_data_schema['labelSchema'] = {\n",
" # we assume the rare event as fraud, and the rest as not-fraud. \n",
" # if you have more than 2 labels in the data or want to map them in a different way, you can manually modify the training data schema\n",
" 'labelMapper' : {\n",
" 'FRAUD' : [str(label_value_count.idxmin())],\n",
" 'LEGIT' : [i for i in event_labels if i not in [str(label_value_count.idxmin())]]\n",
" },\n",
" # there are there options for unlabeledEventsTreatment: \n",
" 'unlabeledEventsTreatment': 'LEGIT'\n",
" }\n",
" else:\n",
" event_labels = None\n",
" \n",
" return training_data_schema, event_variables, event_labels\n",
"\n",
"\n",
"def profiling(df, variables_map):\n",
" \"\"\"\n",
" profiling the input pandas data frame and prepare schema for following steps \n",
" \n",
" Arguments:\n",
" df (DataFrame) - panda's dataframe to create summary statistics for\n",
" variables_map (dictionary) - variables map dictionary - key is the variable type and value is the list of variable name\n",
" \n",
" Returns:\n",
" DataFrame of summary statistics, training data schema, event variables and event labels \n",
" \"\"\"\n",
" df = df.copy()\n",
" \n",
" # -- check required variables --\n",
" required_var_type = ['ENTITY_TYPE','ENTITY_ID','EVENT_ID','EVENT_TIMESTAMP', 'IP_ADDRESS', 'USERAGENT', 'ARE_CREDENTIALS_VALID']\n",
" required_var_name = []\n",
" for item in required_var_type:\n",
" if VARIABLES_MAP.get(item):\n",
" required_var_name.append(VARIABLES_MAP.get(item))\n",
" else:\n",
" required_var_name.append(item)\n",
"\n",
" missing_required_vars = [i for i in required_var_name if i not in set(df.columns)]\n",
" if len(missing_required_vars) != 0:\n",
" raise ValueError(f'Required columns {missing_required_vars} are not included in the training data.')\n",
" \n",
" # -- check if entity types only contains one value --\n",
" entity_types = list(df['ENTITY_TYPE'].unique())\n",
" if len(entity_types)> 1:\n",
" raise ValueError('Currently, Amazon Fraud Detector only support one ENTITY_TYPE per EVENT_TYPE.')\n",
" \n",
" # -- get data summary --\n",
" df_stats = summary_stats(df, variables_map)\n",
" \n",
" # -- prepare schema for following steps -- \n",
" training_data_schema, event_variables, event_labels = prepare_schema(df, df_stats, variables_map)\n",
" \n",
" print(\"--- summary stats ---\")\n",
" print(df_stats)\n",
" print(\"\\n\")\n",
" print(\"--- event variables ---\")\n",
" print(event_variables)\n",
" print(\"\\n\")\n",
" print(\"--- event labels ---\")\n",
" print(event_labels)\n",
" print(\"\\n\")\n",
" print(\"--- training data schema ---\")\n",
" print(training_data_schema)\n",
" \n",
" return df_stats, training_data_schema, event_variables, event_labels\n"
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {
"scrolled": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"--- event timestamp ---\n",
"earliest event: 2022-01-01T00:00:31Z , latest event: 2022-06-30T23:59:49Z\n",
"split training and test set at: 2022-05-27T21:56:51Z\n",
"\n",
"\n",
"--- summary stats ---\n",
" feature_name feature_type dtype count null null_pct nunique nunique_pct feature_warning\n",
"0 EVENT_ID EVENT_ID object 735683 0 0.0000 735683 1.0000 NO WARNING\n",
"1 ENTITY_ID ENTITY_ID object 735683 0 0.0000 100000 0.1359 NO WARNING\n",
"2 ENTITY_TYPE ENTITY_TYPE object 735683 0 0.0000 1 0.0000 NO WARNING\n",
"3 EVENT_TIMESTAMP EVENT_TIMESTAMP object 735683 0 0.0000 718441 0.9766 NO WARNING\n",
"4 EVENT_LABEL EVENT_LABEL object 529 735154 0.9993 2 0.0000 EXCLUDE, GT 75% MISSING\n",
"5 LABEL_TIMESTAMP LABEL_TIMESTAMP object 529 735154 0.9993 529 0.0007 EXCLUDE, GT 75% MISSING\n",
"6 ip IP_ADDRESS object 735683 0 0.0000 190546 0.2590 NO WARNING\n",
"7 useragent USERAGENT object 735683 0 0.0000 15715 0.0214 NO WARNING\n",
"8 fp FINGERPRINT object 735683 0 0.0000 270396 0.3675 NO WARNING\n",
"9 session_id SESSION_ID object 735683 0 0.0000 426005 0.5791 NO WARNING\n",
"10 are_credentials_valid ARE_CREDENTIALS_VALID bool 735683 0 0.0000 2 0.0000 NO WARNING\n",
"\n",
"\n",
"--- event variables ---\n",
"['ip', 'useragent', 'fp', 'session_id', 'are_credentials_valid']\n",
"\n",
"\n",
"--- event labels ---\n",
"['0', '1']\n",
"\n",
"\n",
"--- training data schema ---\n",
"{'modelVariables': ['ip', 'useragent', 'fp', 'session_id', 'are_credentials_valid'], 'labelSchema': {'labelMapper': {'FRAUD': ['1'], 'LEGIT': ['0']}, 'unlabeledEventsTreatment': 'LEGIT'}}\n"
]
}
],
"source": [
"# -- connect to S3, snag file, and convert to a panda's dataframe --\n",
"s3 = boto3.resource('s3')\n",
"obj = s3.Object(S3_BUCKET, S3_FILE)\n",
"body = obj.get()['Body']\n",
"df = pd.read_csv(body, dtype={'EVENT_LABEL': object})\n",
" \n",
"# -- by default, we split the data into training (80%) and test set (20%) --\n",
"earliest_event = df['EVENT_TIMESTAMP'].min()\n",
"latest_event = df['EVENT_TIMESTAMP'].max()\n",
"if TRAINING_PERC > 1 or TRAINING_PERC <= 0:\n",
" raise ValueError(\"TRAINING_PERC should be in (0,1]\")\n",
"else:\n",
" test_split_row = int(df.shape[0]*TRAINING_PERC)\n",
" test_split_time = df.sort_values(by = 'EVENT_TIMESTAMP').iloc[test_split_row]['EVENT_TIMESTAMP']\n",
" test_split_time = pd.to_datetime(test_split_time).strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n",
"\n",
"print(\"--- event timestamp ---\")\n",
"print(\"earliest event:\", earliest_event, \", latest event:\", latest_event) \n",
"print(\"split training and test set at:\", test_split_time) \n",
"print(\"\\n\")\n",
"\n",
"# -- call profiling function -- \n",
"df_stats, training_data_schema, event_variables, event_labels = profiling(df, VARIABLES_MAP)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 3. Create event variables and labels \n",
"-----\n",
"\n",
"The following section will automatically create your modeling input variables for you. \n",
"\n",
"\n",
"\n",
"
💡 APIs for Creating/Deleting Variables and Labels \n",
" \n",
"- **create_variable**: Creates a variable in Fraud Detector\n",
"- **get_variables**: Gets all of the variables or a specific label if name is provided\n",
"- **delete_variables**: Delete a variable; If you have events, models or detectors created using the variable, you need to delect the associated resource first\n",
"- **put_label**: Creates a label\n",
"- **get_labels**: Gets all labels or a specific label if name is provided\n",
"- **delete_label**: Delete a label \n",
"
"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"scrolled": true
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
" --- model variable dict --\n",
"ip has been defined, data type: STRING\n",
"useragent has been defined, data type: STRING\n",
"fp has been defined, data type: STRING\n",
"session_id has been defined, data type: STRING\n",
"Creating variable: are_credentials_valid\n",
"\n",
"\n",
"{'ip': 'STRING', 'useragent': 'STRING', 'fp': 'STRING', 'session_id': 'STRING', 'are_credentials_valid': 'ARE_CREDENTIALS_VALID'}\n"
]
}
],
"source": [
"# -- function to create all your variables --- \n",
"def create_variables(features_dict):\n",
" \"\"\"\n",
" Check if variables exist, if not, adds the variable to Fraud Detector \n",
" \n",
" Arguments: \n",
" features_dict - a dictionary maps your variables to variable type\n",
" \"\"\"\n",
" for feature in features_dict.keys(): \n",
" if features_dict[feature] in ['NUMERIC','PRICE']:\n",
" DATA_TYPE = 'FLOAT'\n",
" DEFAULT_VALUE = '0.0'\n",
" elif features_dict[feature]=='ARE_CREDENTIALS_VALID':\n",
" DATA_TYPE = 'BOOLEAN'\n",
" DEFAULT_VALUE = 'false'\n",
" else:\n",
" DATA_TYPE = 'STRING'\n",
" DEFAULT_VALUE = ''\n",
" \n",
" try:\n",
" resp = client.get_variables(name = feature)\n",
" features_dict[feature] = resp['variables'][0]['dataType']\n",
" print(\"{0} has been defined, data type: {1}\".format(feature, features_dict[feature]))\n",
" except:\n",
" print(\"Creating variable: {0}\".format(feature))\n",
" resp = client.create_variable(\n",
" name = feature,\n",
" dataType = DATA_TYPE,\n",
" dataSource ='EVENT',\n",
" defaultValue = DEFAULT_VALUE, \n",
" description = feature,\n",
" variableType = features_dict[feature])\n",
" return features_dict\n",
"\n",
"exclude_list = ['ENTITY_TYPE','ENTITY_ID','EVENT_ID','EVENT_TIMESTAMP','EVENT_LABEL','LABEL_TIMESTAMP','UNKNOWN']\n",
"features_dict = df_stats.loc[(~df_stats['feature_type'].isin(exclude_list))].set_index('feature_name')['feature_type'].to_dict()\n",
"print(\"\\n --- model variable dict --\")\n",
"features_dict = create_variables(features_dict)\n",
"print(\"\\n\")\n",
"print(features_dict)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### 2. Create labels (Optional)"
]
},
{
"cell_type": "code",
"execution_count": 25,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
" --- model label schema dict --\n",
"{'FRAUD': ['1'], 'LEGIT': ['0']}\n"
]
}
],
"source": [
"# -- function to create all your labels --- \n",
"def create_label(label_mapper):\n",
" \"\"\"\n",
" Add labels to Fraud Detector\n",
" \n",
" Arguments:\n",
" label_mapper - a dictionary maps Fraud/Legit to your labels in data\n",
" \"\"\"\n",
" for label in label_mapper['FRAUD']:\n",
" response = client.put_label(\n",
" name = label,\n",
" description = \"FRAUD\")\n",
" \n",
" for label in label_mapper['LEGIT']:\n",
" response = client.put_label(\n",
" name = label,\n",
" description = \"LEGIT\")\n",
"\n",
"if 'labelSchema' in training_data_schema:\n",
" label_mapper = training_data_schema['labelSchema']['labelMapper']\n",
" print(\"\\n --- model label schema dict --\")\n",
" print(label_mapper)\n",
" create_label(label_mapper)\n",
"else:\n",
" print('Labels not defined, skip.')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 4. Define your Entity and Event Types \n",
"-----\n",
" \n",
"The following code block will automatically create your entity and event types for you.\n",
"\n",
"
💡 APIs for Entity and Event Types \n",
"\n",
"- **put_entity_type**: Creates or updates an entity type. An entity represents who is performing the event. An entity type classifies the entity. Example classifications include customer, merchant, or account\n",
"- **get_entity_type**: Gets all entity types or a specific entity type if a name is specified\n",
"- **delete_entity_type**: Deletes an entity type. If you have an event type associated with the entity type, you need to delete that event type first \n",
"- **put_event_type**: Creates or updates an event type. An event is a business activity that is evaluated for fraud risk. Example event types include online payment transactions, account registrations, and authentications\n",
"- **get_event_type**: Gets all event types or a specific event type if name is provided\n",
"- **delete_event_typ**e: Delete one event type \n",
"\n",
"
"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# --- no changes just run this code block ---\n",
"\n",
"# -- create entity types if not exist --\n",
"entity_type = list(df['ENTITY_TYPE'].unique())[0]\n",
"\n",
"try:\n",
" response = client.get_entity_types(name = entity_type)\n",
" print(\"-- entity type exists --\")\n",
" print(response)\n",
"except:\n",
" response = client.put_entity_type(\n",
" name = entity_type,\n",
" description = entity_type\n",
" )\n",
" print(\"-- create entity type --\")\n",
" print(response)\n",
" \n",
"\n",
"# -- create event type --\n",
"try:\n",
" response = client.get_event_types(name = EVENT_TYPE)\n",
" print(\"\\n-- event type exists --\")\n",
" print(response)\n",
"except:\n",
" response = client.put_event_type (\n",
" name = EVENT_TYPE,\n",
" eventVariables = event_variables,\n",
" labels = event_labels,\n",
" eventIngestion = 'ENABLED',\n",
" entityTypes = [entity_type])\n",
" print(\"\\n-- create event type --\")\n",
" print(response)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 5. Send Events \n",
"\n",
"***Send Events use Batch Import***\n",
"\n",
"The following section will automatically stream in data from S3 bucket to AFD using the Batch Import function. After sending all your events, you can also go to the console, click \"Refresh events data\" to check the number of events, the earliest and the latest event timestamp, etc.\n",
"\n",
"
💡 APIs for Sending, Getting and Deleting Events \n",
"\n",
"- **send_event**: Send one event to AFD\n",
"- **get_event**: Get the specified event by its eventId\n",
"- **delete_events_by_event_type**: Delete all events associated with the event type\n",
"- **delete_event**: Deletes the specified event\n",
"- **create_batch_import_job**: Batch import all event in a csv file on S3 bucket to AFD\n",
"- **get_batch_import_jobs**: Check the status of batch import job \n",
"\n",
"
\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"## -- create batch import job --\n",
"client.create_batch_import_job(\n",
" jobId = f'batch_import_{EVENT_TYPE}_v2',\n",
" inputPath = f's3://{S3_BUCKET}/{S3_FILE}',\n",
" outputPath = f's3://{S3_BUCKET}',\n",
" eventTypeName = EVENT_TYPE,\n",
" iamRoleArn = ARN_ROLE\n",
")"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# -- takes sometime to import all data into AFD -- \n",
"print(\"-- wait for model training to complete --\") \n",
"stime = time.time()\n",
"while True:\n",
" clear_output(wait = True)\n",
" response = client.get_batch_import_jobs(jobId = f'batch_import_{EVENT_TYPE}_v2')\n",
" status = response['batchImports'][0]['status']\n",
" if status in ['IN_PROGRESS', 'IN_PROGRESS_INITIALIZING']:\n",
" print(f\"current progress: {(time.time() - stime)/60:{3}.{3}} minutes\")\n",
" time.sleep(60) # -- sleep for 60 seconds \n",
" else:\n",
" print(f\"Model status : {status}\")\n",
" break\n",
"etime = time.time()\n",
"\n",
"# -- summarize --\n",
"print(\"\\n --- batch import complete --\")\n",
"print(\"Elapsed time : %s\" % (etime - stime) + \" seconds \\n\" )\n",
"print(response)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"-----\n",
"***(Optional) Update Label***\n",
"\n",
"After streaming in events, you can always update their event labels after investigation.\n",
"\n",
"
💡 API for Updating Event Labels \n",
"\n",
"- **update_event_label**: Update one event's label\n",
"\n",
"
\n",
"\n",
"For example, we can update the label of the event we just sent from '0' to '1' by running:\n",
"\n",
"```python\n",
"client.update_event_label(\n",
" eventId = '3200002a7ee5e7d0dc80ad7906d792373b',\n",
" eventTypeName = EVENT_TYPE,\n",
" assignedLabel = '1',\n",
" labelTimestamp = '2021-05-01T17:01:00Z'\n",
")\n",
"```\n",
"\n",
"Check the updated event:\n",
"```python\n",
"client.get_event(eventId = '3200002a7ee5e7d0dc80ad7906d792373b', eventTypeName = EVENT_TYPE)\n",
"```\n",
"\n",
"You will see the `currentLabel` has been updated to '1':\n",
"\n",
"```python\n",
"{\n",
" 'event': {\n",
" 'eventId': '3200002a7ee5e7d0dc80ad7906d792373b',\n",
" 'eventTypeName': 'accounttakeover',\n",
" 'eventTimestamp': '2020-11-28T14:59:50Z',\n",
" 'eventVariables': {\n",
" 'ip': '1.1.1.1',\n",
" 'user_agent': 'Mozilla/5.0 (compatible; MSIE 9.0; Windows 95; Trident/3.0)'\n",
" },\n",
" 'currentLabel': '1',\n",
" 'labelTimestamp': '2021-05-01T17:01:00Z',\n",
" 'entities': [{'entityType': 'user', 'entityId': '153-04-1621'}]\n",
" },\n",
" 'ResponseMetadata': ...\n",
"}\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 6. Create and train your model \n",
"-----\n",
"\n",
"After sending all your events, we recommend waiting 10-20 minutes to ensure that they are fully ingested by the system. Then, you can start to create and train your model. The following section will automatically train and activate your model for you. By default, we use all features available, if you want to exclude features from training, you can review and modify the `training_data_schema`.\n",
" \n",
"
💡 APIs for Creating and Training Model \n",
"\n",
"- **create_model**: Creates a model using the specified model type. Available model types include: ONLINE_FRAUD_INSIGHTS, TRANSACTION_FRAUD_INSIGHTS\n",
"- **update_model**: Updates a model. You can update the description attribute using this action\n",
"- **get_models**: Gets one or more models. Gets all models for the AWS account if no model type and no model id provided\n",
"- **create_model_version**: Creates a version of the model using the specified model type and model id\n",
"- **update_model_version**: Updates a model version. Updating a model version retrains an existing model version using updated training data and produces a new minor version of the model. This action creates and trains a new minor version of the model, for example version 1.01, 1.02, 1.03\n",
"- **describe_model_versions**: Gets all of the model versions for the specified model type or for the specified model type and model ID. You can also get details for a single, specified model version\n",
"- **get_model_version**: Gets the details of the specified model version\n",
"- **put_external_model**: Creates or updates an Amazon SageMaker model endpoint. You can also use this action to update the configuration of the model endpoint, including the IAM role and/or the mapped variables\n",
"- **get_external_models**: Gets the details for one or more Amazon SageMaker models that have been imported into the service\n",
"- **update_model_version_status**: Updates the status of a model version. You can 1) Change the TRAINING_COMPLETE status to ACTIVE, 2) Change ACTIVE to INACTIVE\n",
"\n",
"
"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# --- no changes; just run this code block ---\n",
"# -- create our model --\n",
"try:\n",
" response = client.create_model(\n",
" description = MODEL_DESC,\n",
" eventTypeName = EVENT_TYPE,\n",
" modelId = MODEL_NAME,\n",
" modelType = MODEL_TYPE)\n",
" print(\"-- initalize model --\")\n",
" print(response)\n",
"except Exception:\n",
" pass"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# --- no changes; just run this code block ---\n",
"# -- initalizes the model, it's now ready to train --\n",
"response = client.create_model_version(\n",
" modelId = MODEL_NAME,\n",
" modelType = MODEL_TYPE,\n",
" trainingDataSource = 'INGESTED_EVENTS',\n",
" trainingDataSchema = training_data_schema,\n",
" ingestedEventsDetail={\n",
" 'ingestedEventsTimeWindow': {\n",
" 'startTime': df['EVENT_TIMESTAMP'].min(),\n",
" 'endTime': test_split_time\n",
" }\n",
" }\n",
")\n",
"model_version = response['modelVersionNumber']\n",
"print(\"-- model training --\")\n",
"print(response)\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# -- model training can take a long time, we'll loop until it's complete -- \n",
"print(\"-- wait for model training to complete --\") \n",
"stime = time.time()\n",
"while True:\n",
" clear_output(wait = True)\n",
" response = client.get_model_version(modelId = MODEL_NAME, modelType = MODEL_TYPE, modelVersionNumber = model_version)\n",
" if response['status'] == 'TRAINING_IN_PROGRESS':\n",
" print(f\"current progress: {(time.time() - stime)/60:{3}.{3}} minutes\")\n",
" time.sleep(60) # -- sleep for 60 seconds \n",
" if response['status'] != 'TRAINING_IN_PROGRESS':\n",
" print(\"Model status : \" + response['status'])\n",
" break\n",
"etime = time.time()\n",
"\n",
"# -- summarize --\n",
"print(\"\\n --- model training complete --\")\n",
"print(f\"Elapsed time: {(etime - stime)/60:{3}.{3}} minutes \\n\" )\n",
"print(response)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# -- activate the model version --\n",
"response = client.update_model_version_status (\n",
" modelId = MODEL_NAME,\n",
" modelType = MODEL_TYPE,\n",
" modelVersionNumber = model_version,\n",
" status = 'ACTIVE'\n",
")\n",
"print(\"-- activating model --\")\n",
"print(response)\n",
"\n",
"# -- wait until model is active --\n",
"print(\"--- waiting until model status is active \")\n",
"stime = time.time()\n",
"while True:\n",
" clear_output(wait=True)\n",
" response = client.get_model_version(modelId=MODEL_NAME, modelType = MODEL_TYPE, modelVersionNumber = model_version)\n",
" if response['status'] != 'ACTIVE':\n",
" print(f\"current progress: {(time.time() - stime)/60:{3}.{3}} minutes\")\n",
" time.sleep(60) # sleep for 1 minute \n",
" if response['status'] == 'ACTIVE':\n",
" print(\"Model status : \" + response['status'])\n",
" break\n",
" \n",
"etime = time.time()\n",
"print(f\"Elapsed time: {(etime - stime)/60:{3}.{3}} minutes \\n\" )\n",
"print(response)"
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {},
"outputs": [],
"source": [
"trainingMetrics = client.describe_model_versions(\n",
" modelId = MODEL_NAME,\n",
" modelVersionNumber = model_version,\n",
" modelType = MODEL_TYPE,\n",
" maxResults = 10\n",
")"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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NGpUnfnzR9O6dT2vyxIRkePg8xDPA/x1THzDhn0sX76dpk1rsGDBaFq1qut1SSIicpz8HeJ5uYC/Qvz00+vz/vujqFOnCiedVNvrckREpAx8PTsd548Q37HjAG+/vargeceOjRXgIiIVgK9D3OVlBx5YvLeFhNHPP6fTvfsEBg589YggFxGR2Ofv4fTg5PSKOrFty5Y0evSYwPff76JNm3p07tzU65JERKQc+TzE8ye2eVxIGGzcuI8ePSayevVuzjyzAfPmjaJevWpelyUiIuXI3yEe/FzReuJr1+6hR4+JrFu3l7PPbsTcuSOpW7eq12WJiEg583eIu4p37XTnHFdd9Rrr1u3l3HObMGfOSGrVqux1WSIiEga+ntiWryLNTjcznn/+ci699BTef3+UAlxEpALzdYhXpMuuFr55ydlnN+Kdd4bpWugiIhWcv0O8ggynL136M61a/YcJE5Z4XYqIiESQv0Oc2L8V6VdfbaF79wls336AN95YWfCPiYiIVHz+DvEYvwHKZ59tomfPiezZc4gBA07ljTeujul/SERE5Nj4O8QLeuIeF3IcFi3aQO/eL7N/fyaDBrXh9devplIlX59sICLiO74O8Xyx1hNPTV3HxRdPIj09i2HD2vLKK1eRmFhxLx0rIiLF83XXLVaPH9euXZnKlRO4+uo2vPDC5cTH638xERE/8neIBz/HWk+8XbuGfPXVDZxwQi3i4mKrdhERKT++7sLF0rXT3357FS+88HXB8xNPrK0AFxHxOX/3xPPvYhblKf766ysYPvxNcnPzOPPMBpxzThOvSxIRkSjg75440X+xl8mTlzF06DRycvK4++4udOzY2OuSREQkSvg6xPNF6zHx8eOXMGrUW+TlOf761648/HDPqB81EBGRyPH3cHoUXzt93LjF/OpXMwF46KEe3HPPhR5XJCIi0cbfIe6i82Ive/ce4r77FgLw+OO9+f3vz/e4IhERiUY+D/HA52gbTq9VqzJz547k0083cdNNHb0uR0REopS/Q5zgKWZREuJLlvxM+/YNgcC54O3aNfS4IhERiWa+ntgWLaeYOed44IFUzjrrWV588RtPaxERkdjh6554Pi8j3DnHn/+8gP/930XExRlJSboGuoiIhMbXIe71tdOdc/z+93P55z8/Iz7emDx5IEOGtPW0JhERiR3+DvGCW5FGvi+el+f43e/e48knvyQxMY5XXx3ElVe2jngdIiISuxTieDOcfs8983nyyS9JSopn2rTBXHrpKR5UISIisUwT2/CmJz5y5Jk0a1aDGTOGKsBFROS4+LonTkFPPDIh7pwr+Iehbdv6/PjjrVSq5PNvgYiIHDdfJ0gkJ7ZlZ+cyYsSb9Op1Ejfe2AFAAS4iMSEvL49NmzZx4MABr0uJCTVr1mTlypXH9JrExETq169PjRo1jul1vk6R/AgP93B6ZmYOQ4a8wfTp3zNv3k8MGtSGOnWqhPU9RUTKy86dOzEzTj31VOLifH0UNiRpaWkkJyeHvL1zjoyMDDZv3gxwTEHu6+9GwbXTw/gehw7lMHDga0yf/j21a1dm7txRCnARiSl79+6lQYMGCvAwMTOqVq1KkyZN2L59+zG91uc98fCeYnbwYDYDBkxl3ryfSEmpyvvvjyq4rKqISKzIzc0lMTHR6zIqvCpVqpCdnX1Mr1GIE56eeHp6Fpdd9gqpqeto0KAa8+aNpm3b+mF4JxGR8PP68tR+cDxt7OsQzxeOH86tW9P47rsdNGpUnQULruG001LK/T1ERMTffH2AI5yT01u1qsv8+aP58MOxCnARkTDr1q0btWvXJjMzs2DZmDFjSEpKIjk5meTkZNq2bcuf/vQn9u3bV7DN+PHjiY+Pp3r16tSoUYN27doxc+ZML76E4+LzEC/f88R37TrIq69+W/C8bdv6nHxynXLZt4iIFG/dunV89NFHmBkzZsw4Yt1dd91FWloaO3bs4KWXXuKzzz6jS5cuR5wud95555Gens7evXv59a9/zdChQ9m7d2+Ev4rj4+8QL8eJbdu3H6BHj4kMHTqNKVOWl3l/IiISmokTJ9K5c2fGjBnDhAkTit2mcuXKnHPOOcyYMYNdu3bx0ksv/WKbuLg4Ro0axYEDB/jxxx/DXXa5UIhT9oltP/+cTvfuE1i2bBunnlqXrl1PKHtxIiISkokTJzJixAhGjBjBnDlz2LZtW4nbJicn07t3bz766KNfrMvNzeWll14iMTGRE06Ijb/jvp7YVnDt9DLE+ObN++nRYyI//LCLNm3qMX/+aBo2rF5OFYqIRKF/RGim+p1Hn7i0aNEi1q9fz+DBg0lJSaFly5ZMmTKF22+/vcTXNG7cmMWLFxc8/+yzz6hVqxYHDhwgISGBSZMmUb9+bJxN5OueeL7jHU7fsGEfXbuO54cfdnHmmQ1ITb1GAS4iEkETJkygT58+pKQEJhAPHz68xCH1fJs3b6ZOncPzlTp37szevXvZs2cPl19+ebG99Gjl8554Xhle6xg69A3WrNnD2Wc3Yu7ckdStW7UcqxMRiVIh9JAjISMjg9dee43c3FwaNgxcSCszM5O9e/eydOnSYl+Tnp7OvHnz+POf//yLddWrV+fpp5+mZcuWXHvttZx11llhrb88+LonXpZrp5sZL7xwOZdddgrz549WgIuIRNjbb79NfHw83333HUuWLGHJkiWsXLmSCy+8kIkTJx6xbWZmJosXL+aKK66gdu3ajB07tth91q1bl+uvv56//e1vkfgSyszfIX4c107fu/dQwePWresxY8YwatWqXM6ViYjI0UyYMIGxY8fSvHlzGjZsWPBxyy23MHnyZHJycnjsscdITk6mTp06jB49mg4dOvDJJ59QrVq1Evd72223MWvWLJYtWxbBr+b4+Hs4/RjvJ/7tt9vp1Wsi9913Eb/5zbnhLE1ERI5i9uzZxS4fPHgwgwcPBmDSpEml7mPMmDGMGTPmiGVNmzY94qIx0Uw9cSCU0fQlS36mW7fxbNt2gHfe+YG8vOg4JiQiIv7l6xDPd7Se+FdfbaFHjwns2pXBJZe04u23hxIXp5sBiIiIt3wd4qH0pT/9dCM9e05kz55DXHHFabz55hAqV/b1UQgREYkS/g5xV/plVxct2kCfPpPYvz+Tq69uw2uvDSIpKT6SJYqIiJTI113Ko01sq1+/GtWrJzFgwKmMH38FCQm+/p9HRESijL9D/CgT2045pS6ff349TZokEx+vABcRkeji62QquNhLoZ74zJk/8J//fF7wvHnzmgpwERGJSr7uiefLPyb+1lsrGTLkDbKz82jfviEXXhgbd7ERERF/CmsX08z6mtn3ZrbazP5YzHozsyeC65eZ2dnhrKeo/OF0gFdf/Zarr36d7Ow87rzzPC64oHkkSxERETlmYQtxM4sHngL6AW2AYWbWpshm/YBWwY8bgf+Gq57i5E9sW/ZFQ4YPf5PcXMc991zA44/3Pu47m4mIiERKOHvi5wKrnXM/OeeygKnAgCLbDAAmuoDPgFpm1iiMNR3B4eD7s3j75dPIy3M88EA3/ud/eijARURiTLdu3ahduzaZmZncdNNNVK9enerVq5OUlERiYmLB8379+gGBG6L86U9/onnz5lSpUoVWrVrx+OOPHzFCW9p7Va5cmeTkZGrUqEGHDh145JFHjrhU6/3331/wvrVq1eL888/n008/LfevO5wh3gTYWOj5puCyY90mbDIPxcHX3cAZDz/cg7/8pasCXEQkxqxbt46PPvoIM2PGjBk888wzpKenk56ezj333MOQIUMKnr/33nsAXH311cyfP59Zs2aRlpbGyy+/zLhx4/jd734X0ns++eSTpKWlsXXrVv7xj38wdepU+vfvf8Q/Afnvu3PnTrp3787VV19d7l97OCe2FZeGRf/FCWUbzOxGAsPtNGjQgNTU1DIXB3Dw0B7oN5EemRdx3nldy22/fpSenq72KyO1YdmpDcuuuDasWbMmaWlp3hQUgueee45zzjmHjh078sILL9C3b9+CdZmZmWRnZx9Rf2pqKnPnzuWbb76hadOmZGRkcPrpp/Pss8/Su3dvrr32Wlq2bFni++Xm5nLo0KGCfXbo0IEpU6bQsWNHXn/9dfr06fOL973iiit4+OGHWbt2LSkpKSXu+9ChQ8f0MxzOEN8ENCv0vCmw5Ti2wTk3DhgH0LFjR9etW7dyKbDL+Z9x+QcL6Na1B4lJuh94WaSmplJe3xe/UhuWndqw7Iprw5UrV5KcnFzw3G6IzIiley60G029+uqr3HHHHXTq1InOnTtz8OBBGjRoAEClSpVITEw8ov6PP/6YTp060bp16yP206NHD5o2bcrnn39O+/btS3y/+Pj4guH0fG3atKFjx44sXryYfv36HfG+WVlZTJs2jbp169KsWTMSEkqO3sqVK3PWWWeF9HVDeIfTvwRamdmJZpYEDAVmFNlmBjA6OEu9M7DPObc1jDUdITGpKomJ1RXgIiIxatGiRaxfv57BgwfToUMHWrZsyZQpU0p9zc6dO2nUqPjpV40aNWLnzp3HVUvjxo3ZvXt3wfPXXnuNWrVqUaVKFZ577jneeOONUgP8eIStJ+6cyzGzW4A5QDzwonNuhZndFFz/DDAL6A+sBg4CY8NVj4iIlI9Qe8iRMGHCBPr06VMwRD18+HAmTJjA7bffXuJrUlJS+PHHH4tdt3Xr1lKHu0uzefNmzj///ILngwcPZtKkSezcuZOrrrqKxYsXl/tIUVgv9uKcm0UgqAsve6bQYwf8Jpw1iIhIxZSRkcFrr71Gbm4uDRs2BALHwPfu3cvSpUtp165dsa/r1asX//rXv9i4cSPNmh0+ovvFF1+wceNGevToccy1bNy4kcWLF3P33Xf/Yl1KSgrPPvss55xzDsOHDy9xFOB46HqiIiISk95++23i4+P57rvvWLJkCUuWLGHlypVceOGFTJw4scTX9erVi549e3LVVVexYsUKcnNz+eyzzxgxYgQ333wzrVq1CrmGgwcP8sEHHzBgwADOPfdc+vfvX+x2p512GhdffDGPPfbYMX+dpVGIi4hITJowYQJjx46lefPmNGzYsODjlltuYfLkyeTk5JT42mnTptG9e3f69u1L9erVGTlyJNdddx3/+c9/QnrvW265heTkZBo0aMBtt93GVVddxezZs4mLKzlW//CHPzBu3Di2b99+zF9rSXTtdBERiUmzZ88udvngwYMZPHgwELjoSnEqV67Mo48+yqOPPnrM7xvKKWDFvW+nTp04cODAMb9fadQTFxERiVEKcRERkSLyL9Na9OOjjz7yurQjaDhdRESkiPT0dK9LCIl64iIiclSh3BhEyuZ42lghLiIipYqPjyc7O9vrMiq8jIwMEhMTj+k1CnERESlVrVq12LZtG3l5eV6XUiE55zh48CCbN2+mfv36x/RaHRMXEZFSpaSksGnTJr7//nuvS4kJhw4donLlysf0msTERBo0aECNGjWO6XUKcRERKVVcXBzNmzf3uoyYkZqaekx3IisLDaeLiIjEKIW4iIhIjFKIi4iIxCiFuIiISIyyWDuB38x2AOvLcZcpwM5y3J9fqR3LTm1YdmrDslMbll042vAE51y9ogtjLsTLm5l95Zzr6HUdsU7tWHZqw7JTG5ad2rDsItmGGk4XERGJUQpxERGRGKUQh3FeF1BBqB3LTm1YdmrDslMbll3E2tD3x8RFRERilXriIiIiMco3IW5mfc3sezNbbWZ/LGa9mdkTwfXLzOxsL+qMZiG04Yhg2y0zs0/MrJ0XdUazo7Vhoe3OMbNcMxsUyfpiRSjtaGbdzGyJma0wsw8iXWO0C+H3uaaZvWNmS4NtONaLOqOVmb1oZtvN7NsS1kcmU5xzFf4DiAfWACcBScBSoE2RbfoD7wEGdAY+97ruaPoIsQ3PB2oHH/dTGx57GxbabgEwCxjkdd3R9hHiz2It4DugefB5fa/rjqaPENvwHuDR4ON6wG4gyevao+UDuAg4G/i2hPURyRS/9MTPBVY7535yzmUBU4EBRbYZAEx0AZ8BtcysUaQLjWJHbUPn3CfOuT3Bp58BTSNcY7QL5ecQ4FZgGrA9ksXFkFDacTjwpnNuA4BzTm15pFDa0AHJZmZAdQIhnhPZMqOXc+5DAm1Skohkil9CvAmwsdDzTcFlx7qNnx1r+1xH4L9QOeyobWhmTYArgWciWFesCeVn8RSgtpmlmtliMxsdsepiQyht+CTQGtgCLAd+55zLi0x5FUJEMsUv9xO3YpYVnZYfyjZ+FnL7mFl3AiF+QVgrij2htOG/gLudc7mBDpAUI5R2TAA6AD2BKsCnZvaZc+6HcBcXI0Jpw4uBJUAPoCXwvpl95JzbH+baKoqIZIpfQnwT0KzQ86YE/rs81m38LKT2MbMzgeeBfs65XRGqLVaE0oYdganBAE8B+ptZjnPu7YhUGBtC/X3e6Zw7ABwwsw+BdoBCPCCUNhwLPOICB3hXm9la4DTgi8iUGPMikil+GU7/EmhlZieaWRIwFJhRZJsZwOjgjMLOwD7n3NZIFxrFjtqGZtYceBMYpR5PsY7ahs65E51zLZxzLYA3gF8rwH8hlN/n6cCFZpZgZlWBTsDKCNcZzUJpww0ERjIwswbAqcBPEa0ytkUkU3zRE3fO5ZjZLcAcArMyX3TOrTCzm4LrnyEwE7g/sBo4SOC/UAkKsQ3/AtQFng72JHOcbqRQIMQ2lKMIpR2dcyvNbDawDMgDnnfOFXsqkB+F+LP4IDDezJYTGBq+2zmnu5sFmdkrQDcgxcw2AX8FEiGymaIrtomIiMQovwyni4iIVDgKcRERkRilEBcREYlRCnEREZEYpRAXERGJUQpxkShkZg3NbKqZrTGz78xslpmdErwz18xj3Nf4/LuhBS9D6slpf8H3/j54V6wvzaz9UbavZWa/jlB5IjFJIS4SZYI3nHgLSHXOtXTOtSFwR6kG3lZWLkY459oBTwOPH2XbWoBCXKQUCnGR6NMdyC588Rfn3BLn3EfBp9XN7A0zW2Vmk4Ohj5n9JdjD/dbMxuUvL4mZ9TGzT83sazN73cyqB5evM7MHgsuXm9lpweX1zOz94PJnzWy9maUE1400sy8scP/uZ80s/ihf46cEbwZhZtXNbH6h98u/m9YjQMvgPh8PbvuH4Ne4zMweOJZGFamIFOIi0actsLiU9WcBtwFtCNwPuktw+ZPOuXOcc20J3PTj0pJ2EAzfe4Fezrmzga+AOwptsjO4/L/A74PL/gosCC5/C2ge3FdrYAjQxTnXHsgFRhzla+wLvB18fAi4Mrjf7sA/gv+A/BFY45xr75z7g5n1AVoRuI1me6CDmV10lPcRqdB8cdlVkQrmC+fcJgAzWwK0ABYB3c3sLqAqUAdYAbxTwj46E/gn4ONghz2JQO8435vBz4uBgcHHFxC4TSrOudlmln/v+J4E7hj2ZXBfVSj5XuiTzawagUt9nh1cZsDDwUDOI9BDL+7QQZ/gxzfB59UJhPqHJbyXSIWnEBeJPiuAQaWszyz0OBdIMLPKBI4zd3TObTSz+4HKpezDgPedc8OO8h65HP47UdLwvAETnHN/KuX98o0AlhIYKn+KwD8II4B6QAfnXLaZrSuhdgP+1zn3bAjvI+ILGk4XiT4LgEpmdkP+AjM7x8y6lvKa/NDbGTy2Xdo/AQCfAV3M7OTg/qua2SlHec0iYHBw+z5A7eDy+cAgM6sfXFfHzE4oaSfOuWwCQ/mdg0PxNYHtwQDvDuS/Ng1ILvTSOcC1hY7dN8l/TxG/UoiLRJng/ZuvBHoHTzFbAdxPKfcids7tBZ4DlhM41vzlUd5jBzAGeMXMlhEI9dOOUtoDQB8z+xroB2wF0pxz3xEI5bnBfb0PNDrK+2cA/yBwvH0y0NHMviLQK18V3GYXgeH+b83scefcXGAK8GnwzlpvcGTIi/iO7mImIiExs0pAbvA2lucB/w1OZBMRj+iYuIiEqjnwmpnFAVnADUfZXkTCTD1xERGRGKVj4iIiIjFKIS4iIhKjFOIiIiIxSiEuIiISoxTiIiIiMUohLiIiEqP+HzuQwkIbronRAAAAAElFTkSuQmCC",
"text/plain": [
"
"
]
},
"metadata": {
"needs_background": "light"
},
"output_type": "display_data"
}
],
"source": [
"# -- variable importance summary -- \n",
"varImpMetrics = client.describe_model_versions(\n",
" modelId = MODEL_NAME,\n",
" modelVersionNumber = model_version,\n",
" modelType = MODEL_TYPE,\n",
" maxResults = 10\n",
")['modelVersionDetails'][0]['trainingResultV2']['aggregatedVariablesImportanceMetrics'] \n",
"\n",
"df_var_imp = pd.DataFrame(varImpMetrics['logOddsMetrics']).sort_values(by='aggregatedVariablesImportance')\n",
"\n",
"# -- Variable importance Chart -- \n",
"df_var_imp.plot.barh(x='variableNames',y='aggregatedVariablesImportance',figsize=(10,int(df_var_imp.shape[0])))\n",
"plt.xlabel('Variable Importance (logOdds)')\n",
"plt.grid()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 7. Create a Fraud Detector, generate Rules and assemble your Detector \n",
"-----\n",
"The following section will automatically generate a number of fraud, investigate and approve rules based on the false positive rate and score thresholds of your model. These are just example rules that you could create, it is recommended that you fine tune your rules specifically to your business use case. \n",
" \n",
"
💡 Key APIs for Generating Rules, Creating and Publishing a Detector \n",
" \n",
"- **put_detector**: Creates or updates a detector\n",
"- **put_outcome**: Creates or updates an outcome\n",
"- **create_rule**: Creates a rule for use with the specified detector\n",
"- **update_rule_version**: Updates a rule version resulting in a new rule version (version 1, 2, 3 ...)\n",
"- **create_detector_version**: Creates a detector version. The detector version starts in a DRAFT status\n",
"- **update_detector_version**: Updates a detector version. The detector version attributes that you can update include models, external model endpoints, rules, rule execution mode, and description. You can only update a DRAFT detector version\n",
"- **update_detector_version_status**: Updates the detector version’s status. You can perform the following promotions or demotions using UpdateDetectorVersionStatus: DRAFT to ACTIVE, ACTIVE to INACTIVE, and INACTIVE to ACTIVE\n",
"- **describe_detector**: Gets all versions for a specified detector\n",
"
"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [],
"source": [
"# -- put detector, initalizes your detector -- \n",
"response = client.put_detector(\n",
" detectorId = DETECTOR_NAME, \n",
" description = DETECTOR_DESC,\n",
" eventTypeName = EVENT_TYPE )"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" --- score thresholds 1% to 6% --- \n",
" cr adr atodr threshold\n",
"0 0.01 0.86 0.84 750.0\n",
"1 0.02 0.90 0.92 670.0\n",
"2 0.03 0.92 0.92 620.0\n",
"3 0.04 0.95 0.92 575.0\n",
"4 0.05 0.96 0.97 540.0\n",
"5 0.06 0.96 0.97 515.0\n"
]
}
],
"source": [
"# -- check the score thresholds with FPR from 1% to 6% --\n",
"model_stat = df_model.sort_values(by='cr')\n",
"model_stat['cr_bin']=np.ceil(model_stat['cr']*100)*0.01\n",
"m = model_stat.loc[model_stat.groupby([\"cr_bin\"])[\"threshold\"].idxmin()] \n",
"m = m.round(decimals=2)[['cr','adr','atodr','threshold']]\n",
"print (\" --- score thresholds 1% to 6% --- \")\n",
"print(m.loc[(m['cr'] > 0.0 ) & (m['cr'] <= 0.06)].reset_index(drop=True))"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# -- decide what threshold and corresponding outcome you want to add -- \n",
"# here, we create three simple rules by cutting the score at [950,750], \n",
"# and create three outcome ['investigate', 'challenge', 'approve'] \n",
"# it will create 3 rules:\n",
"# score > 950: investigate\n",
"# score > 750: challenge \n",
"# score <= 750: approve\n",
"\n",
"score_cuts = [950,750] # Note: recommend to fine tune this based on your business use case\n",
"outcomes = ['investigate', 'challenge', 'approve'] # Note: recommend to define this based on your business use case\n",
"\n",
"def create_outcomes(outcomes):\n",
" \"\"\" \n",
" Create Fraud Detector Outcomes \n",
" \"\"\" \n",
" for outcome in outcomes:\n",
" print(\"creating outcome variable: {0} \".format(outcome))\n",
" response = client.put_outcome(name = outcome, description = outcome)\n",
"\n",
"def create_rules(score_cuts, outcomes):\n",
" \"\"\"\n",
" Creating rules \n",
" \n",
" Arguments:\n",
" score_cuts - list of score cuts to create rules\n",
" outcomes - list of outcomes associated with the rules\n",
" \n",
" Returns:\n",
" a rule list to used when creating detector\n",
" \"\"\"\n",
" \n",
" if len(score_cuts)+1 != len(outcomes):\n",
" logging.error('Your socre cuts and outcomes are not matched.')\n",
" \n",
" rule_list = []\n",
" for i in range(len(outcomes)):\n",
" # rule expression\n",
" if i < (len(outcomes)-1):\n",
" rule = \"${0}_insightscore > {1}\".format(MODEL_NAME,score_cuts[i])\n",
" else:\n",
" rule = \"${0}_insightscore <= {1}\".format(MODEL_NAME,score_cuts[i-1])\n",
" \n",
" # append to rule_list (used when create detector)\n",
" rule_id = \"rules{0}_{1}\".format(i, MODEL_NAME)\n",
" \n",
" rule_list.append({\n",
" \"ruleId\": rule_id, \n",
" \"ruleVersion\" : '1',\n",
" \"detectorId\" : DETECTOR_NAME\n",
" })\n",
" \n",
" # create rules\n",
" print(\"creating rule: {0}: IF {1} THEN {2}\".format(rule_id, rule, outcomes[i]))\n",
" try:\n",
" response = client.create_rule(\n",
" ruleId = rule_id,\n",
" detectorId = DETECTOR_NAME,\n",
" expression = rule,\n",
" language = 'DETECTORPL',\n",
" outcomes = [outcomes[i]]\n",
" )\n",
" except:\n",
" print(\"this rule already exists in this detector\")\n",
" \n",
" return rule_list\n",
" \n",
"# -- create outcomes -- \n",
"print(\" -- create outcomes --\")\n",
"create_outcomes(outcomes)\n",
"\n",
"# -- create rules --\n",
"print(\" -- create rules --\")\n",
"rule_list = create_rules(score_cuts, outcomes)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# -- create detector version --\n",
"client.create_detector_version(\n",
" detectorId = DETECTOR_NAME,\n",
" rules = rule_list,\n",
" modelVersions = [{\"modelId\": MODEL_NAME, \n",
" \"modelType\": MODEL_TYPE,\n",
" \"modelVersionNumber\": model_version}],\n",
" # there are 2 options for ruleExecutionMode:\n",
" # 'ALL_MATCHED' - return all matched rules' outcome\n",
" # 'FIRST_MATCHED' - return first matched rule's outcome\n",
" ruleExecutionMode = 'FIRST_MATCHED'\n",
")\n",
"\n",
"print(\"\\n -- detector created -- \")\n",
"print(response) "
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Latest Detector Version: 1\n",
"\n",
" -- detector activated -- \n",
"{'ResponseMetadata': {'RequestId': 'a1df5bee-a034-4459-886a-91d1c2c5d9da', 'HTTPStatusCode': 200, 'HTTPHeaders': {'date': 'Fri, 22 Jul 2022 23:21:28 GMT', 'content-type': 'application/x-amz-json-1.1', 'content-length': '2', 'connection': 'keep-alive', 'x-amzn-requestid': 'a1df5bee-a034-4459-886a-91d1c2c5d9da'}, 'RetryAttempts': 0}}\n"
]
}
],
"source": [
"# -- activate the latest detector version --\n",
"detector_version_summaries = client.describe_detector(detectorId=DETECTOR_NAME)['detectorVersionSummaries']\n",
"latest_detector_version = max([det['detectorVersionId'] for det in detector_version_summaries])\n",
"print('Latest Detector Version:', latest_detector_version)\n",
"\n",
"response = client.update_detector_version_status(\n",
" detectorId = DETECTOR_NAME,\n",
" detectorVersionId = latest_detector_version,\n",
" status = 'ACTIVE'\n",
")\n",
"print(\"\\n -- detector activated -- \")\n",
"print(response)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 8. Make predictions \n",
"-----\n",
"\n",
"The following section will apply your detector to the latest 20% of your data to check the model performance. \n",
"\n",
"
💡 API for Making Predictions \n",
"\n",
"- **get_event_prediction**: Evaluates an event against a detector version. If a version ID is not provided, the detector’s (ACTIVE) version is used. \n",
"\n",
"\n",
"
💡 Write Predictions \n",
"\n",
"- You can write your prediction dataset to a CSV to manually review predictions\n",
"- Simply add a cell below and copy the code below\n",
"\n",
"