textattack.search_methods package

Search Methods

Search methods explore the transformation space in an attempt to find a successful attack as determined by a Goal Functions and list of Constraints

Reimplementation of search method from Generating Natural Language Adversarial Examples

by Alzantot et. al arxiv.org/abs/1804.07998 from github.com/nesl/nlp_adversarial_examples

class textattack.search_methods.alzantot_genetic_algorithm.AlzantotGeneticAlgorithm(pop_size=60, max_iters=20, temp=0.3, give_up_if_no_improvement=False, post_crossover_check=True, max_crossover_retries=20)[source]

Bases: GeneticAlgorithm

Attacks a model with word substiutitions using a genetic algorithm.

Parameters:
  • pop_size (int) – The population size. Defaults to 60.

  • max_iters (int) – The maximum number of iterations to use. Defaults to 20.

  • temp (float) – Temperature for softmax function used to normalize probability dist when sampling parents. Higher temperature increases the sensitivity to lower probability candidates.

  • give_up_if_no_improvement (bool) – If True, stop the search early if no candidate that improves the score is found.

  • post_crossover_check (bool) – If True, check if child produced from crossover step passes the constraints.

  • max_crossover_retries (int) – Maximum number of crossover retries if resulting child fails to pass the constraints. Applied only when post_crossover_check is set to True. Setting it to 0 means we immediately take one of the parents at random as the child upon failure.

class textattack.search_methods.beam_search.BeamSearch(beam_width=8)[source]

Bases: SearchMethod

An attack that maintains a beam of the beam_width highest scoring AttackedTexts, greedily updating the beam with the highest scoring transformations from the current beam.

Parameters:
  • goal_function – A function for determining how well a perturbation is doing at achieving the attack’s goal.

  • transformation – The type of transformation.

  • beam_width (int) – the number of candidates to retain at each step

extra_repr_keys()[source]

Extra fields to be included in the representation of a class.

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

property is_black_box

Returns True if search method does not require access to victim model’s internal states.

Genetic Algorithm Word Swap

class textattack.search_methods.genetic_algorithm.GeneticAlgorithm(pop_size=60, max_iters=20, temp=0.3, give_up_if_no_improvement=False, post_crossover_check=True, max_crossover_retries=20)[source]

Bases: PopulationBasedSearch, ABC

Base class for attacking a model with word substiutitions using a genetic algorithm.

Parameters:
  • pop_size (int) – The population size. Defaults to 20.

  • max_iters (int) – The maximum number of iterations to use. Defaults to 50.

  • temp (float) – Temperature for softmax function used to normalize probability dist when sampling parents. Higher temperature increases the sensitivity to lower probability candidates.

  • give_up_if_no_improvement (bool) – If True, stop the search early if no candidate that improves the score is found.

  • post_crossover_check (bool) – If True, check if child produced from crossover step passes the constraints.

  • max_crossover_retries (int) – Maximum number of crossover retries if resulting child fails to pass the constraints. Applied only when post_crossover_check is set to True. Setting it to 0 means we immediately take one of the parents at random as the child upon failure.

check_transformation_compatibility(transformation)[source]

The genetic algorithm is specifically designed for word substitutions.

extra_repr_keys()[source]

Extra fields to be included in the representation of a class.

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

property is_black_box

Returns True if search method does not require access to victim model’s internal states.

class textattack.search_methods.greedy_search.GreedySearch[source]

Bases: BeamSearch

A search method that greedily chooses from a list of possible perturbations.

Implemented by calling BeamSearch with beam_width set to 1.

extra_repr_keys()[source]

Extra fields to be included in the representation of a class.

Greedy Word Swap with Word Importance Ranking

When WIR method is set to unk, this is a reimplementation of the search method from the paper: Is BERT Really Robust?

A Strong Baseline for Natural Language Attack on Text Classification and Entailment by Jin et. al, 2019. See https://arxiv.org/abs/1907.11932 and https://github.com/jind11/TextFooler.

class textattack.search_methods.greedy_word_swap_wir.GreedyWordSwapWIR(wir_method='unk', unk_token='[UNK]')[source]

Bases: SearchMethod

An attack that greedily chooses from a list of possible perturbations in order of index, after ranking indices by importance.

Parameters:
  • wir_method – method for ranking most important words

  • model_wrapper – model wrapper used for gradient-based ranking

check_transformation_compatibility(transformation)[source]

Since it ranks words by their importance, GreedyWordSwapWIR is limited to word swap and deletion transformations.

extra_repr_keys()[source]

Extra fields to be included in the representation of a class.

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

property is_black_box

Returns True if search method does not require access to victim model’s internal states.

Reimplementation of search method from Xiaosen Wang, Hao Jin, Kun He (2019).

Natural Language Adversarial Attack and Defense in Word Level. http://arxiv.org/abs/1909.06723

class textattack.search_methods.improved_genetic_algorithm.ImprovedGeneticAlgorithm(pop_size=60, max_iters=20, temp=0.3, give_up_if_no_improvement=False, post_crossover_check=True, max_crossover_retries=20, max_replace_times_per_index=5)[source]

Bases: GeneticAlgorithm

Attacks a model with word substiutitions using a genetic algorithm.

Parameters:
  • pop_size (int) – The population size. Defaults to 20.

  • max_iters (int) – The maximum number of iterations to use. Defaults to 50.

  • temp (float) – Temperature for softmax function used to normalize probability dist when sampling parents. Higher temperature increases the sensitivity to lower probability candidates.

  • give_up_if_no_improvement (bool) – If True, stop the search early if no candidate that improves the score is found.

  • post_crossover_check (bool) – If True, check if child produced from crossover step passes the constraints.

  • max_crossover_retries (int) – Maximum number of crossover retries if resulting child fails to pass the constraints. Applied only when post_crossover_check is set to True. Setting it to 0 means we immediately take one of the parents at random as the child upon failure.

  • max_replace_times_per_index (int) – The maximum times words at the same index can be replaced in improved genetic algorithm.

extra_repr_keys()[source]

Extra fields to be included in the representation of a class.

Particle Swarm Optimization

Reimplementation of search method from Word-level Textual Adversarial Attacking as Combinatorial Optimization by Zang et.

al https://www.aclweb.org/anthology/2020.acl-main.540.pdf https://github.com/thunlp/SememePSO-Attack

class textattack.search_methods.particle_swarm_optimization.ParticleSwarmOptimization(pop_size=60, max_iters=20, post_turn_check=True, max_turn_retries=20)[source]

Bases: PopulationBasedSearch

Attacks a model with word substiutitions using a Particle Swarm Optimization (PSO) algorithm. Some key hyper-parameters are setup according to the original paper:

“We adjust PSO on the validation set of SST and set ω_1 as 0.8 and ω_2 as 0.2. We set the max velocity of the particles V_{max} to 3, which means the changing probability of the particles ranges from 0.047 (sigmoid(-3)) to 0.953 (sigmoid(3)).”

Parameters:
  • pop_size (int, optional) – The population size. Defaults to 60.

  • max_iters (int, optional) – The maximum number of iterations to use. Defaults to 20.

  • post_turn_check (bool, optional) – If True, check if new position reached by moving passes the constraints. Defaults to True

  • max_turn_retries (bool, optional) – Maximum number of movement retries if new position after turning fails to pass the constraints. Applied only when post_movement_check is set to True. Setting it to 0 means we immediately take the old position as the new position upon failure.

check_transformation_compatibility(transformation)[source]

The genetic algorithm is specifically designed for word substitutions.

extra_repr_keys()[source]

Extra fields to be included in the representation of a class.

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

property is_black_box

Returns True if search method does not require access to victim model’s internal states.

textattack.search_methods.particle_swarm_optimization.normalize(n)[source]

Population based Search abstract class

class textattack.search_methods.population_based_search.PopulationBasedSearch[source]

Bases: SearchMethod, ABC

Abstract base class for population-based search methods.

Examples include: genetic algorithm, particle swarm optimization

class textattack.search_methods.population_based_search.PopulationMember(attacked_text, result=None, attributes={}, **kwargs)[source]

Bases: object

Represent a single member of population.

property num_words
property score
property words

Search Method Abstract Class

class textattack.search_methods.search_method.SearchMethod[source]

Bases: ReprMixin, ABC

This is an abstract class that contains main helper functionality for search methods.

A search method is a strategy for applying transformations until the goal is met or the search is exhausted.

check_transformation_compatibility(transformation)[source]

Determines whether this search method is compatible with transformation.

get_victim_model()[source]

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

property is_black_box

Returns True if search method does not require access to victim model’s internal states.