class_docstr: Applies pipelines of data augmentation.
  
  Arguments
  ---------
  parallel_augment: bool
      If False, the augmentations are applied sequentially with
      the order specified in the pipeline argument.
      When True, all the N augmentations are concatenated in the output
      on the batch axis.
  parallel_augment_fixed_bs: bool
      If False, each augmenter (performed in parallel) generates a number of
      augmented examples equal to the batch size. Thus, overall, with this
      option N*batch size artificial data are
      generated, where N is the number of augmenters.
      When True, the number of total augmented examples is kept fixed at
      the batch size, thus, for each augmenter, fixed at batch size // N examples.
      This option is useful to keep controlled the number of synthetic examples
      with respect to the original data distribution, as it keep always
      50% of original data, and 50% of augmented data.
  concat_original: bool
      if True, the original input is concatenated with the
      augmented outputs (on the batch axis).
  min_augmentations: int
      The number of augmentations applied to the input signal is randomly
      sampled between min_augmentations and max_augmentations. For instance,
      if the augmentation dict contains N=6 augmentations and we set
      select min_augmentations=1 and max_augmentations=4 we apply up to
      M=4 augmentations. The selected augmentations are applied in the order
      specified in the augmentations dict. If shuffle_augmentations = True,
      a random set of M augmentations is selected.
  max_augmentations: int
      Maximum number of augmentations to apply. See min_augmentations for
      more details.
  shuffle_augmentations:  bool
      If True, it shuffles the entries of the augmentations dictionary.
      The effect is to randomply select the order of the augmentations
      to apply.
  repeat_augment: int
      Applies the augmentation algorithm N times. This can be used to
      perform more data augmentation.
  augment_start_index: int
      The index of the first element in the input batch from which data
      augmentation should begin.
      This argument allows you to specify the starting point for applying
      data augmentation.
  augment_end_index: int
      The index of the last element in the input batch at which data
      augmentation should stop.
      You can use this argument to define the endpoint for applying data
      augmentation within the batch.
  concat_start_index: int
      If `concat_original` is set to True, you can specify a subpart of the
      original batch to concatenate in the output.
      Use this argument to select the index of the first element from the
      original input batch to start copying from.
  concat_end_index: int
      If `concat_original` is set to True, you can specify a subpart of the
      original batch to concatenate in the output. Use this argument to select
      the index of the last element from the original input batch to end the
      copying process.
  augment_prob: float
      The probability (0.0 to 1.0) of applying data augmentation. When set to 0.0,
      the original signal is returned without any augmentation. When set to 1.0,
      augmentation is always applied. Values in between determine the likelihood
      of augmentation.
  augmentations: list
      List of augmentater objects to combine to perform data augmentation.
  enable_augmentations: list
      A list of booleans used to selectively enable or disable specific augmentation
      techniques within the 'augmentations' list.
      Each boolean corresponds to an augmentation object in the 'augmentations' list
      and should be of the same length and order.
      This feature is useful for performing ablations on augmentation techniques to
      tailor them for a specific task.
  
  Example
  -------
  >>> from speechbrain.augment.time_domain import DropFreq, DropChunk
  >>> freq_dropper = DropFreq()
  >>> chunk_dropper = DropChunk(drop_start=100, drop_end=16000)
  >>> augment = Augmenter(parallel_augment=False, concat_original=False, augmentations=[freq_dropper, chunk_dropper])
  >>> signal = torch.rand([4, 16000])
  >>> output_signal, lenghts = augment(signal, lengths=torch.tensor([0.2,0.5,0.7,1.0]))
class_docstr_tok: ["Applies","pipelines","of","data","augmentation",".","Arguments","--","--","--","--","-","parallel_augment",":","bool","If","False",",","the","augmentations","are","applied","sequentially","with","the","order","specified","in","the","pipeline","argument",".","When","True",",","all","the","N","augmentations","are","concatenated","in","the","output","on","the","batch","axis",".","parallel_augment_fixed_bs",":","bool","If","False",",","each","augmenter","(","performed","in","parallel",")","generates","a","number","of","augmented","examples","equal","to","the","batch","size",".","Thus",",","overall",",","with","this","option","N","*","batch","size","artificial","data","are","generated",",","where","N","is","the","number","of","augmenters",".","When","True",",","the","number","of","total","augmented","examples","is","kept","fixed","at","the","batch","size",",","thus",",","for","each","augmenter",",","fixed","at","batch","size","\/\/","N","examples",".","This","option","is","useful","to","keep","controlled","the","number","of","synthetic","examples","with","respect","to","the","original","data","distribution",",","as","it","keep","always","50","%","of","original","data",",","and","50","%","of","augmented","data",".","concat_original",":","bool","if","True",",","the","original","input","is","concatenated","with","the","augmented","outputs","(","on","the","batch","axis",")",".","min_augmentations",":","int","The","number","of","augmentations","applied","to","the","input","signal","is","randomly","sampled","between","min_augmentations","and","max_augmentations",".","For","instance",",","if","the","augmentation","dict","contains","N=6","augmentations","and","we","set","select","min_augmentations=1","and","max_augmentations=4","we","apply","up","to","M=4","augmentations",".","The","selected","augmentations","are","applied","in","the","order","specified","in","the","augmentations","dict",".","If","shuffle_augmentations","=","True",",","a","random","set","of","M","augmentations","is","selected",".","max_augmentations",":","int","Maximum","number","of","augmentations","to","apply",".","See","min_augmentations","for","more","details",".","shuffle_augmentations",":","bool","If","True",",","it","shuffles","the","entries","of","the","augmentations","dictionary",".","The","effect","is","to","randomply","select","the","order","of","the","augmentations","to","apply",".","repeat_augment",":","int","Applies","the","augmentation","algorithm","N","times",".","This","can","be","used","to","perform","more","data","augmentation",".","augment_start_index",":","int","The","index","of","the","first","element","in","the","input","batch","from","which","data","augmentation","should","begin",".","This","argument","allows","you","to","specify","the","starting","point","for","applying","data","augmentation",".","augment_end_index",":","int","The","index","of","the","last","element","in","the","input","batch","at","which","data","augmentation","should","stop",".","You","can","use","this","argument","to","define","the","endpoint","for","applying","data","augmentation","within","the","batch",".","concat_start_index",":","int","If","`","concat_original","`","is","set","to","True",",","you","can","specify","a","subpart","of","the","original","batch","to","concatenate","in","the","output",".","Use","this","argument","to","select","the","index","of","the","first","element","from","the","original","input","batch","to","start","copying","from",".","concat_end_index",":","int","If","`","concat_original","`","is","set","to","True",",","you","can","specify","a","subpart","of","the","original","batch","to","concatenate","in","the","output",".","Use","this","argument","to","select","the","index","of","the","last","element","from","the","original","input","batch","to","end","the","copying","process",".","augment_prob",":","float","The","probability","(","0.0","to","1.0",")","of","applying","data","augmentation",".","When","set","to","0.0",",","the","original","signal","is","returned","without","any","augmentation",".","When","set","to","1.0",",","augmentation","is","always","applied",".","Values","in","between","determine","the","likelihood","of","augmentation",".","augmentations",":","list","List","of","augmentater","objects","to","combine","to","perform","data","augmentation",".","enable_augmentations",":","list","A","list","of","booleans","used","to","selectively","enable","or","disable","specific","augmentation","techniques","within","the","'augmentations","'","list",".","Each","boolean","corresponds","to","an","augmentation","object","in","the","'augmentations","'","list","and","should","be","of","the","same","length","and","order",".","This","feature","is","useful","for","performing","ablations","on","augmentation","techniques","to","tailor","them","for","a","specific","task",".","Example","--","--","--","-",">",">",">","from","speechbrain.augment.time_domain","import","DropFreq",",","DropChunk",">",">",">","freq_dropper","=","DropFreq","(",")",">",">",">","chunk_dropper","=","DropChunk","(","drop_start=100",",","drop_end=16000",")",">",">",">","augment","=","Augmenter","(","parallel_augment=False",",","concat_original=False",",","augmentations=","[","freq_dropper",",","chunk_dropper","]",")",">",">",">","signal","=","torch.rand","(","[","4",",","16000","]",")",">",">",">","output_signal",",","lenghts","=","augment","(","signal",",","lengths=torch.tensor","(","[","0.2,0.5,0.7,1.0","]",")",")"]
code: def __init__(
      self,
      parallel_augment=False,
      parallel_augment_fixed_bs=False,
      concat_original=False,
      min_augmentations=None,
      max_augmentations=None,
      shuffle_augmentations=False,
      repeat_augment=1,
      augment_start_index=0,
      augment_end_index=None,
      concat_start_index=0,
      concat_end_index=None,
      augment_prob=1.0,
      augmentations=list(),
      enable_augmentations=None,
  ):
      super().__init__()
      self.parallel_augment = parallel_augment
      self.parallel_augment_fixed_bs = parallel_augment_fixed_bs
      self.concat_original = concat_original
      self.augmentations = augmentations
      self.min_augmentations = min_augmentations
      self.max_augmentations = max_augmentations
      self.shuffle_augmentations = shuffle_augmentations
      self.augment_start_index = augment_start_index
      self.augment_end_index = augment_end_index
      self.concat_start_index = concat_start_index
      self.concat_end_index = concat_end_index
      self.repeat_augment = repeat_augment
      self.augment_prob = augment_prob
      # Check min and max augmentations
      self.check_min_max_augmentations()
  
      # This variable represents the total number of augmentations to perform for each signal,
      # including the original signal in the count.
      self.num_augmentations = None
      self.do_augment = True
  
      # Check repeat augment arguments
      if not isinstance(self.repeat_augment, int):
          raise ValueError("repeat_augment must be an integer.")
  
      if self.repeat_augment < 0:
          raise ValueError("repeat_augment must be greater than 0.")
  
      if self.augment_end_index is not None:
          if self.augment_end_index < self.augment_start_index:
              raise ValueError(
                  "augment_end_index must be smaller or equal to augment_start_index."
              )
  
      if self.concat_end_index is not None:
          if self.concat_end_index < self.concat_start_index:
              raise ValueError(
                  "concat_end_index must be smaller or equal to concat_start_index."
              )
  
      # Managing enable augmentations
      if enable_augmentations is None:
          enable_augmentations = [True] * len(augmentations)
      elif not isinstance(enable_augmentations, list):
          raise ValueError("enable_augmentations must be a list.")
      elif len(enable_augmentations) != len(augmentations):
          raise ValueError(
              "enable_augmentations must have the same length as augmentations."
          )
      else:
          augmentations = [
              aug
              for aug, enabled in zip(
                  augmentations, enable_augmentations
              )
              if enabled
          ]
  
      # Turn augmentations into a dictionary
      self.augmentations = {
          augmentation.__class__.__name__ + str(i): augmentation
          for i, augmentation in enumerate(augmentations)
      }
  
      if len(self.augmentations) == 0:
          logger.warning(
              "No augmentation is applied because the augmentation list is empty."
          )
  
      # Check min and max augmentations
      if self.max_augmentations <= 0:
          logger.warning(
              "No augmentations applied because max_augmentations is non-positive."
          )
      if self.min_augmentations < 0:
          self.min_augmentations = 0
          logger.warning(
              "min_augmentations is negative. Modified to be non-negative."
          )
      if self.min_augmentations > self.max_augmentations:
          logger.warning(
              "min_augmentations is greater than max_augmentations. min_augmentations set to max_augmentations."
          )
          self.max_augmentations = self.min_augmentations
  
      # Check if augmentation modules need the length argument
      self.require_lengths = {}
      for aug_key, aug_fun in self.augmentations.items():
          self.require_lengths[aug_key] = lengths_arg_exists(
              aug_fun.forward
          )
  
file_path: speechbrain/speechbrain/augment/augmenter.py
imports: import random
  import logging
  import torch
  import torch.nn.functional
  from speechbrain.utils.callchains import lengths_arg_exists
label_desc: Use image node_id 1 to create a new Augmenter object from inherited base classes: torch.nn with example: obj = Augmenter(parallel_augment, parallel_augment_fixed_bs, concat_original, min_augmentations, max_augmentations, shuffle_augmentations, repeat_augment, augment_start_index, augment_end_index, concat_start_index, concat_end_index, augment_prob, augmentations, enable_augmentations)