class_docstr: A class for performing data augmentation using TextAttack.
  
  Returns all possible transformations for a given string. Currently only
      supports transformations which are word swaps.
  
  Args:
      transformation (textattack.Transformation): the transformation
          that suggests new texts from an input.
      constraints: (list(textattack.Constraint)): constraints
          that each transformation must meet
      pct_words_to_swap: (float): [0., 1.], percentage of words to swap per augmented example
      transformations_per_example: (int): Maximum number of augmentations
          per input
      high_yield: Whether to return a set of augmented texts that will be relatively similar, or to return only a
          single one.
      fast_augment: Stops additional transformation runs when number of successful augmentations reaches
          transformations_per_example
      advanced_metrics: return perplexity and USE Score of augmentation
  
  Example::
      >>> from textattack.transformations import WordSwapRandomCharacterDeletion, WordSwapQWERTY, CompositeTransformation
      >>> from textattack.constraints.pre_transformation import RepeatModification, StopwordModification
      >>> from textattack.augmentation import Augmenter
  
      >>> transformation = CompositeTransformation([WordSwapRandomCharacterDeletion(), WordSwapQWERTY()])
      >>> constraints = [RepeatModification(), StopwordModification()]
  
      >>> # initiate augmenter
      >>> augmenter = Augmenter(
      ...     transformation=transformation,
      ...     constraints=constraints,
      ...     pct_words_to_swap=0.5,
      ...     transformations_per_example=3
      ... )
  
      >>> # additional parameters can be modified if not during initiation
      >>> augmenter.enable_advanced_metrics = True
      >>> augmenter.fast_augment = True
      >>> augmenter.high_yield = True
  
      >>> s = 'What I cannot create, I do not understand.'
      >>> results = augmenter.augment(s)
  
      >>> augmentations = results[0]
      >>> perplexity_score = results[1]
      >>> use_score = results[2]
class_docstr_tok: ["A","class","for","performing","data","augmentation","using","TextAttack",".","Returns","all","possible","transformations","for","a","given","string",".","Currently","only","supports","transformations","which","are","word","swaps",".","Args",":","transformation","(","textattack.Transformation",")",":","the","transformation","that","suggests","new","texts","from","an","input",".","constraints",":","(","list","(","textattack.Constraint",")",")",":","constraints","that","each","transformation","must","meet","pct_words_to_swap",":","(","float",")",":","[","0.",",","1",".","]",",","percentage","of","words","to","swap","per","augmented","example","transformations_per_example",":","(","int",")",":","Maximum","number","of","augmentations","per","input","high_yield",":","Whether","to","return","a","set","of","augmented","texts","that","will","be","relatively","similar",",","or","to","return","only","a","single","one",".","fast_augment",":","Stops","additional","transformation","runs","when","number","of","successful","augmentations","reaches","transformations_per_example","advanced_metrics",":","return","perplexity","and","USE","Score","of","augmentation","Example",":",":",">",">",">","from","textattack.transformations","import","WordSwapRandomCharacterDeletion",",","WordSwapQWERTY",",","CompositeTransformation",">",">",">","from","textattack.constraints.pre_transformation","import","RepeatModification",",","StopwordModification",">",">",">","from","textattack.augmentation","import","Augmenter",">",">",">","transformation","=","CompositeTransformation","(","[","WordSwapRandomCharacterDeletion","(",")",",","WordSwapQWERTY","(",")","]",")",">",">",">","constraints","=","[","RepeatModification","(",")",",","StopwordModification","(",")","]",">",">",">","#","initiate","augmenter",">",">",">","augmenter","=","Augmenter","(","...","transformation=transformation",",","...","constraints=constraints",",","...","pct_words_to_swap=0.5",",","...","transformations_per_example=3","...",")",">",">",">","#","additional","parameters","can","be","modified","if","not","during","initiation",">",">",">","augmenter.enable_advanced_metrics","=","True",">",">",">","augmenter.fast_augment","=","True",">",">",">","augmenter.high_yield","=","True",">",">",">","s","=","'What","I","can","not","create",",","I","do","not","understand",".","'",">",">",">","results","=","augmenter.augment","(","s",")",">",">",">","augmentations","=","results","[","0","]",">",">",">","perplexity_score","=","results","[","1","]",">",">",">","use_score","=","results","[","2","]"]
docstr: Returns all possible augmentations of ``text`` according to
  ``self.transformation``.
docstr_tok: ["Returns","all","possible","augmentations","of","``","text","``","according","to","``","self.transformation","``","."]
code: def augment(self, text):
      """Returns all possible augmentations of ``text`` according to
      ``self.transformation``."""
      attacked_text = AttackedText(text)
      original_text = attacked_text
      all_transformed_texts = set()
      num_words_to_swap = max(
          int(self.pct_words_to_swap * len(attacked_text.words)), 1
      )
      augmentation_results = []
      for _ in range(self.transformations_per_example):
          current_text = attacked_text
          words_swapped = len(
              current_text.attack_attrs["modified_indices"]
          )
  
          while words_swapped < num_words_to_swap:
              transformed_texts = self.transformation(
                  current_text, self.pre_transformation_constraints
              )
  
              # Get rid of transformations we already have
              transformed_texts = [
                  t
                  for t in transformed_texts
                  if t not in all_transformed_texts
              ]
  
              # Filter out transformations that don't match the constraints.
              transformed_texts = self._filter_transformations(
                  transformed_texts, current_text, original_text
              )
  
              # if there's no more transformed texts after filter, terminate
              if not len(transformed_texts):
                  break
  
              # look for all transformed_texts that has enough words swapped
              if self.high_yield or self.fast_augment:
                  ready_texts = [
                      text
                      for text in transformed_texts
                      if len(text.attack_attrs["modified_indices"])
                      >= num_words_to_swap
                  ]
                  for text in ready_texts:
                      all_transformed_texts.add(text)
                  unfinished_texts = [
                      text
                      for text in transformed_texts
                      if text not in ready_texts
                  ]
  
                  if len(unfinished_texts):
                      current_text = random.choice(unfinished_texts)
                  else:
                      # no need for further augmentations if all of transformed_texts meet `num_words_to_swap`
                      break
              else:
                  current_text = random.choice(transformed_texts)
  
              # update words_swapped based on modified indices
              words_swapped = max(
                  len(current_text.attack_attrs["modified_indices"]),
                  words_swapped + 1,
              )
  
          all_transformed_texts.add(current_text)
  
          # when with fast_augment, terminate early if there're enough successful augmentations
          if (
              self.fast_augment
              and len(all_transformed_texts)
              >= self.transformations_per_example
          ):
              if not self.high_yield:
                  all_transformed_texts = random.sample(
                      all_transformed_texts,
                      self.transformations_per_example,
                  )
              break
  
      perturbed_texts = sorted(
          [at.printable_text() for at in all_transformed_texts]
      )
  
      if self.advanced_metrics:
          for transformed_texts in all_transformed_texts:
              augmentation_results.append(
                  AugmentationResult(original_text, transformed_texts)
              )
          perplexity_stats = Perplexity().calculate(
              augmentation_results
          )
          use_stats = USEMetric().calculate(augmentation_results)
          return perturbed_texts, perplexity_stats, use_stats
  
      return perturbed_texts
  
file_path: TextAttack/textattack/augmentation/augmenter.py
imports: import random
  import tqdm
  from textattack.constraints import PreTransformationConstraint
  from textattack.metrics.quality_metrics import Perplexity, USEMetric
  from textattack.shared import AttackedText, utils
label_desc: Use image node_id 3 for calling the Augmenter obj's underlying member method code with example usage: obj.augment(text) and returns: perturbed_texts, perturbed_texts,  perplexity_stats,  use_stats