Project Logo

Explainable AI

Installation

To install Explainable AI package:

$ pip install eazyml-xai

Available APIs

Generates explainable AI outputs for a given model based on specified inputs.

ez_init(access_key: str | None = None, usage_share_consent: bool | None = None, usage_delete: bool = False)

Initialize EazyML package by passing access_key

Args:

  • access_key (str): The access key to be set as an environment variable for EazyML.

  • usage_share_consent (bool): User’s agreement to allow their usage information to be shared. If consent is given, only OS information, Python version, and EazyML packages API call counts are collected.

Returns:

A dictionary containing the results of the initialization process with the following fields:

  • success (bool): Indicates whether the operation was successful.

  • message (str): A message describing the success or failure of the operation.

Example:
from eazyml_xai import ez_init

# Initialize the EazyML library with the access key.
# This sets the `EAZYML_ACCESS_KEY` environment variable
access_key = "your_access_key_here"  # Replace with your actual access key
_ = ez_init(access_key)
Notes:

  • Make sure to call this function before using other functionalities of the EazyML library that require a valid access key.

  • The access key will be stored in the environment, and other functions in EazyML will automatically use it when required.

ez_explain(train_data, outcome, test_data, model_info, options={})

This API generates explanations for a model’s prediction, based on provided train and test data.

Args:

  • train_data (DataFrame or str): A pandas DataFrame containing the training dataset. Alternatively, you can provide the file path of training dataset (as a string).

  • outcome (str): The target variable for the explanations.

  • test_data (DataFrame or str): A pandas DataFrame containing the test dataset. Alternatively, you can provide the file path of test dataset (as a string).

  • model_info (Bytes or object): Contains the encrypted or unencrypted details about the trained model and its environment. Alternatively, you can provide the model trained on training dataset (as a object).

  • options (dict, optional): A dictionary of options to configure the explanation process. If not provided, the function will use default settings. Supported keys include:

    • record_number (list, optional): List of test data indices for which you want explanations. If not provided, it will compute the explanation for the first test data point.

    • preprocessor (obj, optional): Preprocessor that you used on the training dataset during preprocessing.

Returns:

A dictionary containing the results of the explanations with the following fields:

  • success (bool): Indicates whether the operation was successful.

  • message (str): A message describing the success or failure of the operation.

On Success:

  • explanations (dict): The generated explanations contain the explanation string and local importance.

Example Using EazyML Predictive Models:
from eazyml_xai import ez_init, ez_explain

# Initialize the EazyML automl library.
_ = ez_init()

# Load training data (Replace with the correct data path).
train_data_path = "path_to_your_training_data.csv"
train = pd.read_csv(train_data_path)

# Load test data (Replace with the correct data path).
test_data_path = "path_to_your_test_data.csv"
test = pd.read_csv(test_data_path)

# Define the outcome (target variable)
outcome = "target"  # Replace with your target variable name

# Build EazyML predictive models
build_options = {'model_type': 'predictive'}
build_resp = ez_build_model(train, outcome=outcome, options=build_options)

# Use model_info from ez_build_model response
model_info = build_resp["model_info"]

# Customize options for fetching explanations
xai_options = {"record_number": [1, 2, 3]}

# Call the EazyML API to fetch the explanations
xai_response = ez_explain(train, outcome, test_data_path, model_info, options=xai_options)

# xai_response is a dictionary object with following keys.
# print (xai_response.keys())
# dict_keys(['success', 'message', 'explanations'])
Example Using Your Model and EazyML Preprocessor:
from eazyml_xai import ez_init, ez_explain, create_onehot_encoded_features, ez_get_data_type

# Initialize the EazyML automl library.
_ = ez_init()

# Load training data (Replace with the correct data path).
train_data_path = "path_to_your_training_data.csv"
train = pd.read_csv(train_data_path)

# Define the outcome (target variable)
outcome = "target"  # Replace with your target variable name

# Define input features (X) and target variable (y)
y = train[outcome]
X = train.drop(outcome, axis=1)

# Load test data (Replace with the correct data path).
test_data_path = "path_to_your_test_data.csv"
test = pd.read_csv(test_data_path)

# Get data type of features
type_df = ez_get_data_type(train, outcome)

# List of categorical columns
cat_list = type_df[type_df['Data Type'] == 'categorical']['Variable Name'].tolist()
cat_list = [ele for ele in cat_list if ele != outcome]

# Create one-hot encoded features
train = create_onehot_encoded_features(train, cat_list)

# Define your model object (replace with any model of your choice)
model_info = <YourModelClass>(<parameters>)  # e.g., RandomForestClassifier(), LogisticRegression(), etc.

# Train your model object
model_info.fit(X, y)

# Customize options for fetching explanations
xai_options = {"record_number": [1, 2, 3]}

# Call the EazyML API to fetch the explanations
xai_response = ez_explain(train, outcome, test_data_path, model_info, options=xai_options)

# xai_response is a dictionary object with following keys.
# print (xai_response.keys())
Example Using Your Model and Preprocessor:
from eazyml_xai import ez_init, ez_explain

# Initialize the EazyML automl library.
_ = ez_init()

# Load training data (Replace with the correct data path).
train_data_path = "path_to_your_training_data.csv"
train = pd.read_csv(train_data_path)

# Define the outcome (target variable)
outcome = "target"  # Replace with your target variable name

# Define input features (X) and target variable (y)
y = train[outcome]
X = train.drop(outcome, axis=1)

# Load test data (Replace with the correct data path).
test_data_path = "path_to_your_test_data.csv"
test = pd.read_csv(test_data_path)

# Implement your preprocessing steps within a custom preprocessor class and define it
# (Replace <YourPreprocessorClass> with the specific preprocessor class you're using)
preprocessor = <YourPreprocessorClass>(<parameters>)  # Example: StandardScaler(), CustomPreprocessor()

# Fit the preprocessor on your dataset
preprocessor.fit(X, y)

# Define your model object (replace with any model of your choice)
model_info = <YourModelClass>(<parameters>)  # e.g., RandomForestClassifier(), LogisticRegression(), etc.

# Train your model object
model_info.fit(X, y)

# Customize options for fetching explanations
xai_options = {"record_number": [1, 2, 3], "preprocessor", preprocessor}

# Call the EazyML API to fetch the explanations
xai_response = ez_explain(train_data_path, outcome, test_data_path, model_info, options=xai_options)

# xai_response is a dictionary object with following keys.
# print (xai_response.keys())
# dict_keys(['success', 'message', 'explanations'])
create_onehot_encoded_features(df, cols)

Convert categorical variables into dummy/one-hot encoded variables.

This function takes a DataFrame and a list of column names, and returns a new DataFrame where the specified columns are transformed into one-hot encoded (dummy) variables.

Args:

  • df (pd.DataFrame): pandas dataframe for which dummy features are to be created

  • cols (‘list’): List of categorical columns to be encoded

Returns:

A DataFrame with the specified columns replaced by their corresponding one-hot encoded dummy variables.

Example:
from eazyml_xai import ez_init, ez_get_data_type, create_onehot_encoded_features

# Initialize the EazyML automl library.
_ = ez_init()

# Load data (Replace with the correct data path).
data_path = "path_to_your_data.csv"
data = pd.read_csv(data_path)

# Define the outcome (target variable)
outcome = "target"  # Replace with your target variable name

# Get data type of features
type_df = ez_get_data_type(data, outcome)

# List of categorical columns
cat_list = type_df[type_df['Data Type'] == 'categorical']['Variable Name'].tolist()
cat_list = [ele for ele in cat_list if ele != outcome]

# Create one-hot encoded features
onehot_encoded_df = create_onehot_encoded_features(data, cat_list)

# The onehot_encoded_df is a one-hot encoded DataFrame.
ez_get_data_type(df, outcome)

Identifies if the columns are categorical or numeric and produces a DataFrame containing data types

Args:

  • df (pd.DataFrame): pandas dataframe for which data types are to be identified.

  • outcome (‘str’): Outcome variable name from the df

Returns:

A DataFrame with Variable Name and corresponding Data Type

Example:
from eazyml_xai import ez_init, ez_get_data_type

# Initialize the EazyML automl library.
_ = ez_init()

# Load data (Replace with the correct data path).
data_path = "path_to_your_data.csv"
data = pd.read_csv(data_path)

# Define the outcome (target variable)
outcome = "target"  # Replace with your target variable name

# Get data type of features
type_df = ez_get_data_type(data, outcome)

# type_df is a dataframe with following columns.
# print (type_df.columns)
# Index(['Variable Name', 'Data Type'], dtype='object')