text_sensitivity

Subpackages:

Submodules:

text_sensitivity.metrics module

Module for sensitivity metrics.

class text_sensitivity.metrics.FairnessMetrics(attributes, ground_truth, predictions, pos_label=None, priviliged_groups=None, unpriviliged_groups=None)

Bases: object

Calculate fairness metrics for provided attributes, ground truth values and predictions.

Parameters

  • attributes (Dict[str, LabelProvider]) – Dictionary of named attributes (e.g. sex, ethnicity, …).

  • ground_truth (LabelProvider) – Ground truth labels of instances.

  • predictions (LabelProvider) – Predicted labels of instances.

  • pos_label (Optional[LT], optional) – Positive label. Defaults to None.

  • priviliged_groups (Optional[List[Dict[str, LT]]], optional) – Dictionary with the priviliged group names for some attributes. Defaults to None.

  • unpriviliged_groups (Optional[List[Dict[str, LT]]], optional) – Dictionary with the unpriviliged group names for some attributes. Defaults to None.

Example

Calculate fairness metrics for sex (male/female) and race (Caucasian, Hispanic, African-American):

>>> attributes = {'sex': ..., 'race': ..., 'name': ...}
>>> FairnessMetric(attributes=attributes,
...                ground_truth=ground_truth,
...                predictions=predictions,
...                priviliged_groups={'sex': 'male', 'race': 'caucasian'})
property accuracy

\((TP + TN)/(P + N)\).

Type

Accuracy

property all

All indices.

property disparate_impact

Alias for statistical parity ratio.

property error_rate

\((FP + FN) / (TP + FP + FN + TN)\).

Type

Error rate

property false_discovery_rate

\(FP / (TP + FP)\).

Type

False Discovery Rate (FDR)

property false_negative_rate

\(FN / (FP + TP)\).

Type

False Negative Rate (FNR)

property false_omission_rate

\(FN / (TN + FN)\).

Type

False Omission Rate (FOR)

property false_positive_rate

\(FP / (TN + FN)\).

Type

False Positive Rate (FPR)

label_metrics(keys)

Calculate label metrics for given keys.

property mean_difference

Alias for statistical parity difference.

property negative_predictive_value

\(TN / (TN + FN)\).

Type

Negative Predictive Value (NPV)

property positive_predicted_value

\(TP / (TP + FP)\), alias for precision.

Type

Positive Predictive Value (NPV)

property precision

\(TP / (TP + FP)\).

Type

Precision

property priviliged

Indices of priviliged instances.

property recall

\(TP / (TP + FN)\)

Type

Recall

property selection_rate

\((TP + FP) / (TP + FP + TN + FN)\).

Type

Selection rate

property sensitivity

Sensitivity, alias for recall.

property specificity

\(TN / (FN + TN)\).

Type

Specificity

property statistical_parity

Statistical parity \(Pr(Y = 1) = P/(P+N)\).

property true_negative_rate

True Negative Rate (TNR), alias for specificity.

property true_positive_rate

True Positive Rate (TPR), alias for recall.

property unpriviliged

Indices of unpriviliged instances.

class text_sensitivity.metrics.Metric(name, all, priviliged, unpriviliged, abbr=None)

Bases: Readable

Named metric.

Parameters

  • name (str) – Name of metric.

  • all (float) – Score of all

  • priviliged (float) – Score of priviliged group (e.g. sex = male).

  • unpriviliged (float) – Score for unpriviliged group (e.g. sex = not male).

  • abbr (Optional[str], optional) – Abbreviation of name. Defaults to None.

property difference

Difference between unpriviliged and priviliged scores.

\[\text{metric} | A = \text{unprivileged} - \text{metric} | A = \text{privileged}\]
property ratio

Ratio between unpriviliged and priviliged scores.

\[\frac{\text{metric} | A = \text{unprivileged}}{\text{metric} | A = \text{privileged}}\]
text_sensitivity.metrics.binarize(labels, select, new_label='priviliged', other_label='unpriviliged')

Convert labels in a LabelProvider to binary labels new_label and other_label.

Parameters

  • labels (LabelProvider) – LabelProvider to convert attribute labels to new_label and other_label.

  • select (Union[int, str, list, frozenset]) – Label(s) to select.

  • new_label (str, optional) – Label if attribute falls in selected values. Defaults to ‘priviliged’.

  • other_label (str, optional) – Label if attribute does not fall in selected values. Defaults to ‘unpriviliged’.

Returns

Attribute labels with either new_label or other_label.

Return type

MemoryLabelProvider

text_sensitivity.return_types module

Return types for sensitivity (tests).

class text_sensitivity.return_types.LabelMetrics(instances, label_metrics, type='sensitivity', subtype='label_metrics', callargs=None, **kwargs)

Bases: Instances

Return type for labelwise metrics.

Parameters

  • instances (_type_) – Instances.

  • label_metrics (_type_) – Metric for each label.

  • type (Optional[str], optional) – Type description. Defaults to ‘sensitivity’.

  • subtype (Optional[str], optional) – Subtype description. Defaults to ‘label_metrics’.

  • callargs (Optional[dict], optional) – Arguments used when the function was called. Defaults to None.

property content

Content as dictionary.

class text_sensitivity.return_types.MeanScore(scores, label, instances, type='sensitivity', subtype='mean_score', callargs=None, **kwargs)

Bases: Instances

Return type for text_sensitivity.mean_score().

Parameters

  • scores (List[float]) – Score for each instance.

  • label (str) – Name of label.

  • instances (_type_) – Instances.

  • type (Optional[str], optional) – Type description. Defaults to ‘sensitivity’.

  • subtype (Optional[str], optional) – Subtype description. Defaults to ‘mean_score’.

  • callargs (Optional[dict], optional) – Arguments used when the function was called. Defaults to None.

property content

Content as dictionary.

class text_sensitivity.return_types.SuccessTest(success_percentage, successes, failures, predictions=None, type='robustness', subtype='input_space', callargs=None, **kwargs)

Bases: Instances

Return type for success test.

Parameters

  • success_percentage (float) – Percentage of successful cases.

  • successes (_type_) – Instances that succeeded.

  • failures (_type_) – Instances that failed.

  • predictions (Optional[Union[LabelProvider, list, dict]], optional) – Predictions to subdivide successes/ failures into labels. Defaults to None.

  • type (str, optional) – Type description. Defaults to ‘robustness’.

  • subtype (str, optional) – Subtype description. Defaults to ‘input_space’.

  • callargs (Optional[dict], optional) – Arguments used when the function was called. Defaults to None.

property content

Content as dictionary.

text_sensitivity.sensitivity module

Sensitivity testing, for fairness and robustness.

text_sensitivity.sensitivity.apply_perturbation(dataset, perturbation)

Apply a perturbation to a dataset, getting the perturbed instances and corresponding attribute labels.

Examples

Repeat each string twice:

>>> from text_sensitivity.perturbation.sentences import repeat_k_times
>>> apply_perturbation(env, repeat_k_times(k=2))

Add the unrelated string ‘This is unrelated.’ before each instance:

>>> from text_sensitivity.perturbation import OneToOnePerturbation
>>> perturbation = OneToOnePerturbation.from_string(prefix='This is unrelated.')
>>> apply_perturbation(env, perturbation)
Parameters

  • dataset (Union[InstanceProvider, TextEnvironment]) – Dataset to apply perturbation to (e.g. all data, train set, test set, set belonging to a given label, or subset of data for a (un)protected group).

  • perturbation (Perturbation) – Perturbation to apply, one-to-one or one-to-many.

Returns

Perturbed instances and corresponding attribute labels.

Return type

Tuple[TextInstanceProvider, MemoryLabelProvider]

text_sensitivity.sensitivity.compare_accuracy(*args, **kwargs)

Compare accuracy scores for each ground-truth label and attribute.

text_sensitivity.sensitivity.compare_metric(env, model, perturbation, **kwargs)

Get metrics for each ground-truth label and attribute.

Examples

Compare metric of model performance (e.g. accuracy, precision) before and after mapping each instance in a dataset to uppercase.

>>> from text_sensitivity.perturbation.sentences import to_upper
>>> compare_metric(env, model, to_upper)

Compare metric when randomly adding 10 perturbed instances with typos to each instance in a dataset.

>>> from text_sensitivity.perturbation.characters import add_typos
>>> compare_metric(env, model, add_typos(n=10))
Parameters

  • env (TextEnvironment) – Environment containing original instances (.dataset) and ground-truth labels (.labels).

  • model (AbstractClassifier) – Black-box model to compare metrics on.

  • perturbation (Perturbation) – Peturbation to apply.

Returns

Original label (before perturbation), perturbed label (after perturbation) and metrics for label-attribute pair.

Return type

LabelMetrics

text_sensitivity.sensitivity.compare_precision(*args, **kwargs)

Compare precision scores for each ground-truth label and attribute.

text_sensitivity.sensitivity.compare_recall(*args, **kwargs)

Compare recall scores for each ground-truth label and attribute.

text_sensitivity.sensitivity.equal_ground_truth(ground_truth, instances)

When you expect the ground-truth label will remain equal after the perturbation is applied.

Parameters

  • ground_truth (MemoryLabelProvider) – Labelprovider.

  • instances (InstanceProvider) – Instanceprovider.

Yields

Iterator[Tuple[KT, LT]] – Keys and corresponding labels.

Return type

Iterator[Tuple[TypeVar(KT), TypeVar(LT)]]

text_sensitivity.sensitivity.input_space_robustness(model, generators, n_samples=100, min_length=0, max_length=100, seed=0, **kwargs)

Test the robustness of a machine learning model to different input types.

Example

Test a pretrained black-box model for its robustness to 1000 random strings (length 0 to 500), containing whitespace characters, ASCII (upper, lower and numbers), emojis and Russian Cyrillic characters:

>>> from text_sensitivity.data.random.string import RandomAscii, RandomCyrillic, RandomEmojis, RandomWhitespace
>>> input_space_robustness(model,
>>>                        [RandomWhitespace(), RandomAscii(), RandomEmojis(base=True), RandomCyrillic('ru')],
>>>                        n_samples=1000,
>>>                        min_length=0,
>>>                        max_length=500)
Parameters

  • model (AbstractClassifier) – Machine learning model to test.

  • generators (List[RandomString]) – Random character generators.

  • n_samples (int, optional) – Number of test samples. Defaults to 100.

  • min_length (int, optional) – Input minimum length. Defaults to 0.

  • max_length (int, optional) – Input maximum length. Defaults to 100.

  • seed (Optional[int], optional) – Seed for reproducibility purposes. Defaults to 0.

Returns

Percentage of success cases, list of succeeded/failed instances

Return type

SuccessTest

text_sensitivity.sensitivity.invariance(pattern, model, expectation=None, **kwargs)

Test for the failure rate under invariance.

Parameters

  • pattern (str) – String pattern to generate examples from.

  • model (AbstractClassifier) – Model to test.

  • expectation (Optional[LT], optional) – Expected outcome values. Defaults to None.

  • **kwargs – Optional arguments passed onto the data.generate.from_pattern() function.

Returns

Percentage of success cases, list of succeeded (invariant)/failed (variant) instances

Return type

SuccessTest

text_sensitivity.sensitivity.mean_score(pattern, model, selected_label=None, **kwargs)

Calculate mean (probability) score for a given label, for data generated from a pattern.

Parameters

  • pattern (str) –

  • model (AbstractClassifier) – Model to generate scores from.

  • selected_label (Optional[LT], optional) – Label name to select. If None is replaced by the first label. Defaults to None.

Returns

Mean score for the selected label, generated instances and label scores.

Return type

MeanScore