textflint

Unified Multilingual Robustness Evaluation Toolkit for Natural Language Processing

Project description

Textflint Logo

Unified Multilingual Robustness Evaluation Toolkit for Natural Language Processing

[TextFlint Documentation on ReadTheDocs]

About • Setup • Usage • Design

About

TextFlint is a multilingual robustness evaluation platform for natural language processing tasks, which unifies general text transformation, task-specific transformation, adversarial attack, sub-population, and their combinations to provide a comprehensive robustness analysis.

Features:

There are lots of reasons to use TextFlint:

Full coverage of transformation types, including 20 general transformations, 8 subpopulations and 60 task-specific transformations, as well as thousands of their combinations, which basically covers all aspects of text transformations to comprehensively evaluate the robustness of your model. TextFlint also supports Subpopulation and Adversarial Attack to generate model specific transformed datas.
Generate targeted augmented data, and you can use the additional data to train or fine-tune your model to improve your model's robustness.
Provide a complete analytical report automatically to accurately explain where your model's shortcomings are, such as the problems in lexical rules or syntactic rules.

Setup

Installation

Require python version >= 3.7, recommend install with pip (recommended)

pip install textflint

Usage

Workflow

The general workflow of TextFlint is displayed above. Evaluation of target models could be devided into three steps:

For input preparation, the original dataset for testing, which is to be loaded by Dataset, should be firstly formatted as a series of JSON objects. textflint configuration is specified by Config. Target model is also loaded as FlintModel.
In adversarial sample generation, multi-perspective transformations (i.e., Transformation,Subpopulation and AttackRecipe), are performed on Dataset to generate transformed samples. Besides, to ensure semantic and grammatical correctness of transformed samples, Validator calculates confidence of each sample to filter out unacceptable samples.
Lastly, Analyzer collects evaluation results and ReportGenerator automatically generates a comprehensive report of model robustness.

Quick Start

Using TextFlint to verify the robustness of a specific model is as simple as running the following command:

$ textflint --dataset input_file --config config.json

where input_file is the input file of csv or json format, config.json is a configuration file with generation and target model options. Take the configuration for TextCNN model on SA task as example:

{
  "task": "SA",
  "out_dir": "./DATA/",
  "trans_methods": [
    "Ocr",
    ["InsertAdv", "SwapNamedEnt"],   
    ...
  ],
  "trans_config": {
    "Ocr": {"trans_p": 0.3},
    ...
  },
...
}

task is the name of target task.
out_dir is the directory where each of the generated sample and its corresponding original sample are saved.
flint_model is the python file path that saves the instance of FlintModel.
trans_methods is used to specify the transformation method. For example, "Ocr" denotes the universal transformation Ocr, and ["InsertAdv", "SwapNamedEnt"] denotes a pipeline of task-specific transformations, namely InsertAdv and SwapNamedEnt.
trans_config configures the parameters for the transformation methods. The default parameter is also a good choice.

Based on the design of decoupling sample generation and model verification, TextFlint can be used inside another NLP project with just a few lines of code.

from textflint import Engine

data_path = 'input.json'
config = 'config.json'
engine = Engine()
engine.run(data_path, config)

Transformed Datasets

After transformation, here are the contents in ./DATA/:

ori_Keyboard_2.json
ori_SwapNamedEnt_1.json
trans_Keyboard_2.json
trans_SwapNamedEnt_1.json
...

where the trans_Keyboard_2.json contains 2 successfully transformed sample by transformation Keyboard and ori_Keyboard_2.json contains the corresponding original sample. The content in ori_Keyboard_2.json:

{"x": "Titanic is my favorite movie.", "y": "pos", "sample_id": 0}
{"x": "I don't like the actor Tim Hill", "y": "neg", "sample_id": 1}

The content in trans_Keyboard_2.json:

{"x": "Titanic is my favorite m0vie.", "y": "pos", "sample_id": 0}
{"x": "I don't likR the actor Tim Hill", "y": "neg", "sample_id": 1}

Design

Architecture

Input layer: receives textual datasets and models as input, represented as Dataset and FlintModel separately.

DataSet: a container for Sample, provides efficiently and handily operation interfaces for Sample. Dataset supports loading, verification, and saving data in Json or CSV format for various NLP tasks.
FlintModel: a target model used in an adversarial attack.

Generation layer: there are mainly four parts in generation layer:

Subpopulation: generates a subset of a DataSet.
Transformation: transforms each sample of Dataset if it can be transformed.
AttackRecipe: attacks the FlintModel and generate a DataSet of adversarial examples.
Validator: verifies the quality of samples generated by Transformation and AttackRecipe.

Report layer: analyzes model testing results and provides robustness report for users.

Transformation

In order to verify the robustness comprehensively, TextFlint offers 20 universal transformations and 60 task-specific transformations, covering 12 NLP tasks. The following table summarizes the Transformation currently supported and the examples for each transformation can be found in our web site.

Task	Transformation	Description	Reference
UT (Universal Transformation)	`AppendIrr`	_{Extend sentences by irrelevant sentences}	-
	`BackTrans`	_{BackTrans (Trans short for translation) replaces test data with paraphrases by leveraging back translation, which is able to figure out whether or not the target models merely capture the literal features instead of semantic meaning.}	-
	`Contraction`	_{Contraction replaces phrases like `will not` and `he has` with contracted forms, namely, `won’t` and `he’s`}	-
	`InsertAdv`	_{Transforms an input by add adverb word before verb}	-
	`Keyboard`	_{Keyboard turn to the way how people type words and change tokens into mistaken ones with errors caused by the use of keyboard, like `word → worf` and `ambiguous → amviguius`.}	-
	`MLMSuggestion`	_{MLMSuggestion (MLM short for masked language model) generates new sentences where one syntactic category element of the original sentence is replaced by what is predicted by masked language models.}	-
	`Ocr`	_{Transformation that simulate ocr error by random values.}	-
	`Prejudice`	_{Transforms an input by Reverse gender or place names in sentences.}	-
	`Punctuation`	_{Transforms input by add punctuation at the end of sentence.}	-
	`ReverseNeg`	_{Transforms an affirmative sentence into a negative sentence, or vice versa.}	-
	`SpellingError`	_{Transformation that leverage pre-defined spelling mistake dictionary to simulate spelling mistake.}	_{Text Data Augmentation Made Simple By Leveraging NLP Cloud APIs (https://arxiv.org/ftp/arxiv/papers/1812/1812.04718.pdf)}
	`SwapAntWordNet`	_{Transforms an input by replacing its words with antonym provided by WordNet.}	-
	`SwapNamedEnt`	_{Swap entities with other entities of the same category.}	-
	`SwapNum`	_{Transforms an input by replacing the numbers in it.}	-
	`SwapSynWordEmbedding`	_{Transforms an input by replacing its words by Glove.}	-
	`SwapSynWordNet`	_{Transforms an input by replacing its words with synonyms provided by WordNet.}	-
	`Tense`	_{Transforms all verb tenses in sentence.}	-
	`TwitterType`	_{Transforms input by common abbreviations in TwitterType.}	-
	`Typos`	_{Randomly inserts, deletes, swaps or replaces a single letter within one word (Ireland → Irland).}	_{Synthetic and noise both break neural machine translation (https://arxiv.org/pdf/1711.02173.pdf)}
	`WordCase`	_{Transform an input to upper and lower case or capitalize case.}	-
RE (Relation Extraction)	`InsertClause`	_{InsertClause is a transformation method which inserts entity description for head and tail entity}	-
	`SwapEnt-LowFreq`	_{SwapEnt-LowFreq is a sub-transformation method from EntitySwap which replace entities in text with random same typed entities with low frequency.}	-
	`SwapTriplePos-Birth`	_{SwapTriplePos-Birth is a transformation method specially designed for birth relation. It paraphrases the sentence and keeps the original birth relation between the entity pairs.}	-
	`SwapTriplePos-Employee`	_{SwapTriplePos-Employee is a transformation method specially designed for employee relation. It deletes the TITLE description of each employee and keeps the original employee relation between the entity pairs.}	-
	`SwapEnt-SamEtype`	_{SwapEnt-SamEtype is a sub-transformation method from EntitySwap which replace entities in text with random entities with the same type.}	-
	`SwapTriplePos-Age`	_{SwapTriplePos-Age is a transformation method specially designed for age relation. It paraphrases the sentence and keeps the original age relation between the entity pairs.}	-
	`SwapEnt-MultiType`	_{SwapEnt-MultiType is a sub-transformation method from EntitySwap which replace entities in text with random same-typed entities with multiple possible types.}	-
NER (Named Entity Recognition)	`EntTypos`	_{Swap/delete/add random character for entities}	-
	`ConcatSent`	_{Concatenate sentences to a longer one.}	-
	`SwapLonger`	_{Substitute short entities to longer ones}	-
	`CrossCategory`	_{Entity Swap by swaping entities with ones that can be labeled by different labels.}	-
	`OOV`	_{Entity Swap by OOV entities.}	-
POS (Part-of-Speech Tagging)	`SwapMultiPOSRB`	_{It is implied by the phenomenon of conversion that some words hold multiple parts of speech. That is to say, these multi-part-of-speech words might confuse the language models in terms of POS tagging. Accordingly, we replace adverbs with words holding multiple parts of speech.}	-
	`SwapPrefix`	_{Swapping the prefix of one word and keeping its part of speech tag.}	-
	`SwapMultiPOSVB`	_{It is implied by the phenomenon of conversion that some words hold multiple parts of speech. That is to say, these multi-part-of-speech words might confuse the language models in terms of POS tagging. Accordingly, we replace verbs with words holding multiple parts of speech.}	-
	`SwapMultiPOSNN`	_{It is implied by the phenomenon of conversion that some words hold multiple parts of speech. That is to say, these multi-part-of-speech words might confuse the language models in terms of POS tagging. Accordingly, we replace nouns with words holding multiple parts of speech.}	-
	`SwapMultiPOSJJ`	_{It is implied by the phenomenon of conversion that some words hold multiple parts of speech. That is to say, these multi-part-of-speech words might confuse the language models in terms of POS tagging. Accordingly, we replace adjectives with words holding multiple parts of speech.}	-
COREF (Coreference Resolution)	`RndConcat`	_{RndConcat is a task-specific transformation of coreference resolution, this transformation will randomly retrieve an irrelevant paragraph from the corpus, and concatenate it after the original document}	-
	`RndDelete`	_{RndDelete is a task-specific transformation of coreference resolution, through this transformation, there is a possibility (20% by default) for each sentence in the original document to be deleted, and at least one sentence will be deleted; related coreference labels will also be deleted}	-
	`RndReplace`	_{RndInsert is a task-specific transformation of coreference resolution, this transformation will randomly retrieve irrelevant sentences from the corpus, and replace sentences from the original document with them （the proportion of replaced sentences and original sentences is 20% by default）}	-
	`RndShuffle`	_{RndShuffle is a task-specific transformation of coreference resolution, during this transformation, a certain number of swapping will be processed, which swap the order of two adjacent sentences of the original document （the number of swapping is 20% of the number of original sentences by default）}	-
	`RndInsert`	_{RndInsert is a task-specific transformation of coreference resolution, this transformation will randomly retrieve irrelevant sentences from the corpus, and insert them into the original document （the proportion of inserted sentences and original sentences is 20% by default）}	-
	`RndRepeat`	_{RndRepeat is a task-specific transformation of coreference resolution, this transformation will randomly pick sentences from the original document, and insert them somewhere else in the document （the proportion of inserted sentences and original sentences is 20% by default）}	-
ABSA (Aspect-based Sentiment Analysis)	`RevTgt`	_{RevTgt: reverse the sentiment of the target aspect.}	_{Tasty Burgers, Soggy Fries: Probing Aspect Robustness in Aspect-Based Sentiment Analysis (https://www.aclweb.org/anthology/2020.emnlp-main.292.pdf)}
	`AddDiff`	_{RevNon: Reverse the sentiment of the non-target aspects with originally the same sentiment as target.}
	`RevNon`	_{AddDiff: Add aspects with the opposite sentiment from the target aspect.}
CWS (Chinese Word Segmentation)	`SwapContraction`	_{SwapContriction is a task-specific transformation of Chinese Word Segmentation, this transformation will replace some common abbreviations in the sentence with complete words with the same meaning}	-
	`SwapNum`	_{SwapNum is a task-specific transformation of Chinese Word Segmentation, this transformation will replace the numerals in the sentence with other numerals of similar size}	-
	`SwapSyn`	_{SwapSyn is a task-specific transformation of Chinese Word Segmentation, this transformation will replace some words in the sentence with some very similar words}	-
	`SwapName`	_{SwapName is a task-specific transformation of Chinese Word Segmentation, this transformation will replace the last name or first name of the person in the sentence to produce some local ambiguity that has nothing to do with the sentence}	-
	`SwapVerb`	_{SwapName is a task-specific transformation of Chinese Word Segmentation, this transformation will transform some of the verbs in the sentence to other forms in Chinese}	-
SM (Semantic Matching)	`SwapWord`	_{This transformation will add some meaningless sentence to premise, which do not change the semantics.}	-
	`SwapNum`	_{This transformation will find some num words in sentences and replace them with different num word.}	-
	`Overlap`	_{This method generate some data by some template, whose hypotheis and sentence1 have many overlap but different meaning.}	-
SA (Sentiment Analysis)	`SwapSpecialEnt-Person`	_{SpecialEntityReplace-Person is a task-specific transformation of sentiment analysis, this transformation will identify some special person name in the sentence, randomly replace it with other entity names of the same kind}	-
	`SwapSpecialEnt-Movie`	_{SpecialEntityReplace is a task-specific transformation of sentiment analysis, this transformation will identify some special movie name in the sentence, randomly replace it with other movie name.}	-
	`AddSum-Movie`	_{AddSummary-Movie is a task-specific transformation of sentiment analysis, this transformation will identify some special movie name in the sentence, and insert the summary of these entities after them (the summary content is from wikipedia).}	-
	`AddSum-Person`	_{AddSummary-Person is a task-specific transformation of sentiment analysis, this transformation will identify some special person name in the sentence, and insert the summary of these entities after them (the summary content is from wikipedia).}	-
	`DoubleDenial`	_{SpecialWordDoubleDenial is a task-specific transformation of sentiment analysis, this transformation will find some special words in the sentence and replace them with double negation}	-
NLI (Natural Language Inference)	`NumWord`	_{This transformation will find some num words in sentences and replace them with different num word.}	_{Stress Test Evaluation for Natural Language Inference (https://www.aclweb.org/anthology/C18-1198/)}
	`SwapAnt`	_{This transformation will find some keywords in sentences and replace them with their antonym.}
	`AddSent`	_{This transformation will add some meaningless sentence to premise, which do not change the semantics.}
	`Overlap`	_{This method generate some data by some template, whose hypotheis and premise have many overlap but different meaning.}	_{Right for the Wrong Reasons: Diagnosing Syntactic Heuristics in Natural Language Inference (https://www.aclweb.org/anthology/P19-1334/)}
MRC (Machine Reading Comprehension)	`PerturbQuestion-MLM`	_{PerturbQuestion is a task-specific transformation of machine reading comprehension, this transformation paraphrases the question.}	-
	`PerturbQuestion-BackTrans`	_{PerturbQuestion is a task-specific transformation of machine reading comprehension, this transformation paraphrases the question.}	-
	`AddSentDiverse`	_{AddSentenceDiverse is a task-specific transformation of machine reading comprehension, this transformation generates a distractor with altered question and fake answer.}	_{Adversarial Augmentation Policy Search for Domain and Cross-LingualGeneralization in Reading Comprehension (https://arxiv.org/pdf/2004.06076)}
	`PerturbAnswer`	_{PerturbAnswer is a task-specific transformation of machine reading comprehension, this transformation transforms the sentence with golden answer based on specific rules.}
	`ModifyPos`	_{ModifyPosition is a task-specific transformation of machine reading comprehension, this transformation rotates the sentences of context.}	-
DP (Dependency Parsing)	`AddSubtree`	_{AddSubtree is a task-specific transformation of dependency parsing, this transformation will transform the input sentence by adding a subordinate clause from WikiData.}	-
DP (Dependency Parsing)	`RemoveSubtree`	_{RemoveSubtree is a task-specific transformation of dependency parsing, this transformation will transform the input sentence by removing a subordinate clause.}	-

Subpopulation

Subpopulation is to identify the specific part of dataset on which the target model performs poorly. To retrieve a subset that meets the configuration, Subpopulation divides the dataset through sorting samples by certain attributes. We also support the following Subpopulation:

Subpopulation	Description	Reference
`LMSubPopulation_0%-20%`	_{Filter samples based on the text perplexity from a language model (i.e., GPT-2), 0-20% is the lower part of the scores.}	_{Robustness Gym: Unifying the NLP Evaluation Landscape (https://arxiv.org/pdf/2101.04840)}
`LMSubPopulation_80%-100%`	_{Filter samples based on the text perplexity from a language model (i.e., GPT-2), 80-100% is the higher part of the scores.}
`LengthSubPopulation_0%-20%`	_{Filter samples based on text length, 0-20% is the lower part of the length.}
`LengthSubPopulation_80%-100%`	_{Filter samples based on text length, 80-100% is the higher part of the length.}
`PhraseSubPopulation-negation`	_{Filter samples based on a group of phrases, the remaining samples contain negation words (e.g., not, don't, aren't, no).}
`PhraseSubPopulation-question`	_{Filter samples based on a group of phrases, the remaining samples contain question words (e.g., what, which, how, when).}
`PrejudiceSubpopulation-man`	_{Filter samples based on gender bias, the chosen samples only contain words related to male (e.g., he, his, father, boy).}
`PrejudiceSubpopulation-woman`	_{Filter samples based on gender bias, the chosen samples only contain words related to female (e.g., she, her, mother, girl)}

AttackRecipe

AttackRecipe aims to find a perturbation of an input text satisfies the attack's goal to fool the given FlintModel. In contrast to Transformation, AttackRecipe requires the prediction scores of the target model. textflint provides an interface to integrate the easy-to-use adversarial attack recipes implemented based on textattack. Users can refer to textattack for more information about the supported AttackRecipe.

Validator

It is crucial to verify the quality of samples generated by Transformation and AttackRecipe. TextFlint provides several metrics to calculate confidence:

Validator	Description	Reference
`MaxWordsPerturbed`	_{Word replacement ratio in the generated text compared with the original text based on LCS.}	-
`LevenshteinDistance`	_{The edit distance between original text and generated text}	-
`DeCLUTREncoder`	_{Semantic similarity calculated based on Universal Sentence Encoder}	_{Universal sentence encoder (https://arxiv.org/pdf/1803.11175.pdf)}
`GPT2Perplexity`	_{Language model perplexity calculated based on the GPT2 model}	_{Language models are unsupervised multitask learners (http://www.persagen.com/files/misc/radford2019language.pdf)}
`TranslateScore`	_{BLEU/METEOR/chrF score}	_{Bleu: a method for automatic evaluation of machine translation (https://www.aclweb.org/anthology/P02-1040.pdf) METEOR: An automatic metric for MT evaluation with improved correlation with human judgments (https://www.aclweb.org/anthology/W05-0909.pdf) chrF: character n-gram F-score for automatic MT evaluation (https://www.aclweb.org/anthology/W15-3049.pdf)}

Report

In Generation Layer, TextFlint can generate three types of adversarial samples and verify the robustness of the target model. Based on the results from Generation Layer, Report Layer aims to provide users with a standard analysis report from lexics, syntax, and semantic levels. For example, on the Sentiment Analysis (SA) task, this is a statistical chart of the performance ofXLNET with different types of Transformation/Subpopulation/AttackRecipe on the IMDB dataset. We can find that the model performance is lower than the original results in all the transformed dataset.

Citation

If you are using TextFlint for your work, please cite:

@article{gui2021textflint,
  title={TextFlint: Unified Multilingual Robustness Evaluation Toolkit for Natural Language Processing},
  author={Gui, Tao and Wang, Xiao and Zhang, Qi and Liu, Qin and Zou, Yicheng and Zhou, Xin and Zheng, Rui and Zhang, Chong and Wu, Qinzhuo and Ye, Jiacheng and others},
  journal={arXiv preprint arXiv:2103.11441},
  year={2021}
}

Project details

Release history Release notifications | RSS feed

0.1.0

Mar 15, 2022

0.0.5

Aug 30, 2021

This version

0.0.4

Jul 9, 2021

0.0.3

Apr 21, 2021

0.0.2

Apr 8, 2021

0.0.1

Apr 6, 2021

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

textflint-0.0.4.tar.gz (207.3 kB view details)

Uploaded Jul 9, 2021 Source

Built Distribution

textflint-0.0.4-py3-none-any.whl (280.4 kB view details)

Uploaded Jul 9, 2021 Python 3

File details

Details for the file textflint-0.0.4.tar.gz.

File metadata

Download URL: textflint-0.0.4.tar.gz
Upload date: Jul 9, 2021
Size: 207.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.1 importlib_metadata/4.6.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.5

File hashes

Hashes for textflint-0.0.4.tar.gz
Algorithm	Hash digest
SHA256	`7dbf7767abe6d76ba34198d3e3f36b29b63fc7a4511dd14793ea60b70392d6cb`
MD5	`646e625fba893e3c04aafcf77c8618db`
BLAKE2b-256	`02b7ccc17de7c945df9b30b427b45d58c243362011f788ee76db6d96e7a98dd8`

See more details on using hashes here.

Provenance

File details

Details for the file textflint-0.0.4-py3-none-any.whl.

File metadata

Download URL: textflint-0.0.4-py3-none-any.whl
Upload date: Jul 9, 2021
Size: 280.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.1 importlib_metadata/4.6.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.5

File hashes

Hashes for textflint-0.0.4-py3-none-any.whl
Algorithm	Hash digest
SHA256	`eef50ccbe0595ee73410d3d9eeb7e62ad004b705b5da5c580f645338bb0b73b8`
MD5	`15457af697d556bc0ffcbd5f0b5aa786`
BLAKE2b-256	`8e57ba2252555d6cf8d45e0257479a0cb7149224c5b02af7ad0e9239b1d22aac`