Explainer API Documentation

This section provides a detailed reference of the classes, methods, and attributes available in the Explainer module.

class nlpguard.explainer.explainer.Explainer

Bases: ABC

Abstract Explainer Class.

_abc_impl = <_abc._abc_data object>
static _compute_global_scores(df, minimum_frequency=2, subtoken_separator='##') → DataFrame

Computes overall importance scores (global explanations) for each token by aggregating their importance withing individual predictions (local explanations).

Parameters:

  • df (pd.DataFrame) – Dataframe containing local explanations.

  • minimum_frequency (int, optional) – Minimum frequency of a token to be considered in the global explanations. Defaults to 2.

  • subtoken_separator (str, optional) – Subtoken separator used by the tokenizer. Defaults to “##”.

Returns:

Dataframe containing the global explanations.

Return type:

pd.DataFrame

static _load_local_explanations(dir_path) → DataFrame

Loads local explanations from a directory.

Parameters:

dir_path (str) – Path to the directory containing the local explanations.

Returns:

Dataframe containing the local explanations.

Return type:

pandas.core.frame.DataFrame

global_explanations(label_ids_to_explain, id2label, explainer_output_folder)

Computes global explanations for a set of class labels.

Parameters:

  • label_ids_to_explain (list(int)) – List of class label ids to explain.

  • id2label (dict) – Dictionary mapping class label ids to class names.

  • ( (explainer_output_folder) – obj:`str’): Path to the folder containing the local explanations.

Returns:

Dictionary containing the global explanations for each class label.

Return type:

dict

abstract local_explanations(**kwargs)

Abstract method to compute local explanations.

class nlpguard.explainer.explainer.IntegratedGradientsExplainer(model, tokenizer, device='cpu')

Bases: Explainer

Integrated Gradients implementation of the Explainer abstract class.

_abc_impl = <_abc._abc_data object>
_compute_batch_local_explanations(label_id, batch_texts, batch_pred_scores) → tuple[list[str], list[float], list[float]]

Computes local explanations for a batch of texts.

Parameters:

  • label_id (int) – Label id to explain.

  • batch_texts (list[str]) – List of texts to explain.

  • batch_pred_scores (list[float]) – List of predicted probabilities for the target label.

Returns:

Tuple containing the tokens, feature importance scores, and weighted feature importance scores.

Return type:

tuple(list(str), list(float), list(float))

static batch_iterator(list1, list2, batch_size)

Iterates two list by batch_size.

Parameters:

  • ( (batch_size) – obj:`list’): First list.

  • ( – obj:`list’): Second list.

  • ( – obj:`int’): Batch size.

Yields:

tuple – Tuple containing the current batch of list1, list2, start_index and end_index.

local_explanations(df_predictions, local_explanations_folder, label_ids_to_explain, id2label, batch_size=128)

Computes and saves local explanations for a set of predictions in the output folder.

Parameters:

  • df_predictions (pd.DataFrame) – Dataframe containing the predictions to explain.

  • local_explanations_folder (str) – Path to the folder where the local explanations will be saved.

  • label_ids_to_explain (list(int)) – List of label ids to explain.

  • id2label (dict) – Dictionary mapping label ids to label names.

  • batch_size (int, optional) – Batch size. Defaults to 128.

class nlpguard.explainer.explainer.ShapExplainer

Bases: Explainer

Shap implementation of the Explainer abstract class.

_abc_impl = <_abc._abc_data object>
global_explanations()

Computes global explanations for a set of class labels.

Parameters:

  • label_ids_to_explain (list(int)) – List of class label ids to explain.

  • id2label (dict) – Dictionary mapping class label ids to class names.

  • ( (explainer_output_folder) – obj:`str’): Path to the folder containing the local explanations.

Returns:

Dictionary containing the global explanations for each class label.

Return type:

dict

local_explanations()

Abstract method to compute local explanations.