docstr: Identifies minimal perturbation based on target variable which causes
  misclassification (or other incorrect prediction) of target input.
  
  More specifically, given a perturbation parametrized by a single value
  (e.g. rotation by angle or mask percentage of top features based on
  attribution results), MinParamPerturbation helps identify the minimum value
  which leads to misclassification (or other model output change) with the
  corresponding perturbed input.
  
  Args:
      forward_func (Callable or torch.nn.Module): This can either be an instance
          of pytorch model or any modification of a model's forward
          function.
  
      attack (Perturbation or Callable): This can either be an instance
          of a Captum Perturbation / Attack
          or any other perturbation or attack function such
          as a torchvision transform.
          Perturb function must take additional argument (var_name) used for
          minimal perturbation search.
  
      arg_name (str): Name of argument / variable paramterizing attack, must be
          kwarg of attack. Examples are num_dropout or stdevs
  
      arg_min (int, float): Minimum value of target variable
  
      arg_max (int, float): Maximum value of target variable
          (not included in range)
  
      arg_step (int, float): Minimum interval for increase of target variable.
  
      mode (str, optional): Mode for search of minimum attack value;
          either ``linear`` for linear search on variable, or ``binary`` for
          binary search of variable
          Default: ``linear``
  
      num_attempts (int, optional): Number of attempts or trials with
          given variable. This should only be set to > 1 for non-deterministic
          perturbation / attack functions
          Default: ``1``
  
      preproc_fn (Callable, optional): Optional method applied to inputs. Output
          of preproc_fn is then provided as input to model, in addition to
          additional_forward_args provided to evaluate.
          Default: ``None``
  
      apply_before_preproc (bool, optional): Defines whether attack should be
          applied before or after preproc function.
          Default: ``False``
  
      correct_fn (Callable, optional): This determines whether the perturbed input
          leads to a correct or incorrect prediction. By default, this function
          is set to the standard classification test for correctness
          (comparing argmax of output with target), which requires model output to
          be a 2D tensor, returning True if all batch examples are correct and
          false otherwise. Setting this method allows
          any custom behavior defining whether the perturbation is successful
          at fooling the model. For non-classification use cases, a custom
          function must be provided which determines correctness.
  
          The first argument to this function must be the model out;
          any additional arguments should be provided through
          ``correct_fn_kwargs``.
  
          This function should have the following signature::
  
              def correct_fn(model_out: Tensor, **kwargs: Any) -> bool
  
          Method should return a boolean if correct (True) and incorrect (False).
          Default: ``None`` (applies standard correct_fn for classification)
docstr_tok: ["Identifies","minimal","perturbation","based","on","target","variable","which","causes","misclassification","(","or","other","incorrect","prediction",")","of","target","input",".","More","specifically",",","given","a","perturbation","parametrized","by","a","single","value","(","e.g",".","rotation","by","angle","or","mask","percentage","of","top","features","based","on","attribution","results",")",",","MinParamPerturbation","helps","identify","the","minimum","value","which","leads","to","misclassification","(","or","other","model","output","change",")","with","the","corresponding","perturbed","input",".","Args",":","forward_func","(","Callable","or","torch.nn.Module",")",":","This","can","either","be","an","instance","of","pytorch","model","or","any","modification","of","a","model","'s","forward","function",".","attack","(","Perturbation","or","Callable",")",":","This","can","either","be","an","instance","of","a","Captum","Perturbation","\/","Attack","or","any","other","perturbation","or","attack","function","such","as","a","torchvision","transform",".","Perturb","function","must","take","additional","argument","(","var_name",")","used","for","minimal","perturbation","search",".","arg_name","(","str",")",":","Name","of","argument","\/","variable","paramterizing","attack",",","must","be","kwarg","of","attack",".","Examples","are","num_dropout","or","stdevs","arg_min","(","int",",","float",")",":","Minimum","value","of","target","variable","arg_max","(","int",",","float",")",":","Maximum","value","of","target","variable","(","not","included","in","range",")","arg_step","(","int",",","float",")",":","Minimum","interval","for","increase","of","target","variable",".","mode","(","str",",","optional",")",":","Mode","for","search","of","minimum","attack","value",";","either","``","linear","``","for","linear","search","on","variable",",","or","``","binary","``","for","binary","search","of","variable","Default",":","``","linear","``","num_attempts","(","int",",","optional",")",":","Number","of","attempts","or","trials","with","given","variable",".","This","should","only","be","set","to",">","1","for","non-deterministic","perturbation","\/","attack","functions","Default",":","``","1","``","preproc_fn","(","Callable",",","optional",")",":","Optional","method","applied","to","inputs",".","Output","of","preproc_fn","is","then","provided","as","input","to","model",",","in","addition","to","additional_forward_args","provided","to","evaluate",".","Default",":","``","None","``","apply_before_preproc","(","bool",",","optional",")",":","Defines","whether","attack","should","be","applied","before","or","after","preproc","function",".","Default",":","``","False","``","correct_fn","(","Callable",",","optional",")",":","This","determines","whether","the","perturbed","input","leads","to","a","correct","or","incorrect","prediction",".","By","default",",","this","function","is","set","to","the","standard","classification","test","for","correctness","(","comparing","argmax","of","output","with","target",")",",","which","requires","model","output","to","be","a","2D","tensor",",","returning","True","if","all","batch","examples","are","correct","and","false","otherwise",".","Setting","this","method","allows","any","custom","behavior","defining","whether","the","perturbation","is","successful","at","fooling","the","model",".","For","non-classification","use","cases",",","a","custom","function","must","be","provided","which","determines","correctness",".","The","first","argument","to","this","function","must","be","the","model","out",";","any","additional","arguments","should","be","provided","through","``","correct_fn_kwargs","``",".","This","function","should","have","the","following","signature",":",":","def","correct_fn","(","model_out",":","Tensor",",","*","*","kwargs",":","Any",")","-",">","bool","Method","should","return","a","boolean","if","correct","(","True",")","and","incorrect","(","False",")",".","Default",":","``","None","``","(","applies","standard","correct_fn","for","classification",")"]
code: def __init__(
      self,
      forward_func: Callable,
      attack: Union[Callable, Perturbation],
      arg_name: str,
      arg_min: Union[int, float],
      arg_max: Union[int, float],
      arg_step: Union[int, float],
      mode: str = "linear",
      num_attempts: int = 1,
      preproc_fn: Optional[Callable] = None,
      apply_before_preproc: bool = False,
      correct_fn: Optional[Callable] = None,
  ) -> None:
      r"""
      Identifies minimal perturbation based on target variable which causes
      misclassification (or other incorrect prediction) of target input.
  
      More specifically, given a perturbation parametrized by a single value
      (e.g. rotation by angle or mask percentage of top features based on
      attribution results), MinParamPerturbation helps identify the minimum value
      which leads to misclassification (or other model output change) with the
      corresponding perturbed input.
  
      Args:
          forward_func (Callable or torch.nn.Module): This can either be an instance
              of pytorch model or any modification of a model's forward
              function.
  
          attack (Perturbation or Callable): This can either be an instance
              of a Captum Perturbation / Attack
              or any other perturbation or attack function such
              as a torchvision transform.
              Perturb function must take additional argument (var_name) used for
              minimal perturbation search.
  
          arg_name (str): Name of argument / variable paramterizing attack, must be
              kwarg of attack. Examples are num_dropout or stdevs
  
          arg_min (int, float): Minimum value of target variable
  
          arg_max (int, float): Maximum value of target variable
              (not included in range)
  
          arg_step (int, float): Minimum interval for increase of target variable.
  
          mode (str, optional): Mode for search of minimum attack value;
              either ``linear`` for linear search on variable, or ``binary`` for
              binary search of variable
              Default: ``linear``
  
          num_attempts (int, optional): Number of attempts or trials with
              given variable. This should only be set to > 1 for non-deterministic
              perturbation / attack functions
              Default: ``1``
  
          preproc_fn (Callable, optional): Optional method applied to inputs. Output
              of preproc_fn is then provided as input to model, in addition to
              additional_forward_args provided to evaluate.
              Default: ``None``
  
          apply_before_preproc (bool, optional): Defines whether attack should be
              applied before or after preproc function.
              Default: ``False``
  
          correct_fn (Callable, optional): This determines whether the perturbed input
              leads to a correct or incorrect prediction. By default, this function
              is set to the standard classification test for correctness
              (comparing argmax of output with target), which requires model output to
              be a 2D tensor, returning True if all batch examples are correct and
              false otherwise. Setting this method allows
              any custom behavior defining whether the perturbation is successful
              at fooling the model. For non-classification use cases, a custom
              function must be provided which determines correctness.
  
              The first argument to this function must be the model out;
              any additional arguments should be provided through
              ``correct_fn_kwargs``.
  
              This function should have the following signature::
  
                  def correct_fn(model_out: Tensor, **kwargs: Any) -> bool
  
              Method should return a boolean if correct (True) and incorrect (False).
              Default: ``None`` (applies standard correct_fn for classification)
      """
      self.forward_func = forward_func
      self.attack = attack
      self.arg_name = arg_name
      self.arg_min = arg_min
      self.arg_max = arg_max
      self.arg_step = arg_step
      assert self.arg_max > (
          self.arg_min + self.arg_step
      ), "Step size cannot be smaller than range between min and max"
  
      self.num_attempts = num_attempts
      self.preproc_fn = preproc_fn
      self.apply_before_preproc = apply_before_preproc
      self.correct_fn = cast(
          Callable,
          correct_fn if correct_fn is not None else default_correct_fn,
      )
  
      assert (
          mode.upper() in MinParamPerturbationMode.__members__
      ), f"Provided perturb mode {mode} is not valid - must be linear or binary"
      self.mode = MinParamPerturbationMode[mode.upper()]
  
file_path: captum/captum/robust/_core/metrics/min_param_perturbation.py
imports: import math
  from enum import Enum
  from typing import Any, Callable, cast, Dict, Generator, List, Optional, Tuple, Union
  import torch
  from captum._utils.common import _expand_additional_forward_args, _format_additional_forward_args, _reduce_list
  from captum._utils.typing import TargetType
  from captum.log import log_usage
  from captum.robust._core.perturbation import Perturbation
  from torch import Tensor
label_desc: Use image node_id 1 to create a new MinParamPerturbation object  with example: obj = MinParamPerturbation(forward_func, attack, arg_name, arg_min, arg_max, arg_step, mode, num_attempts, preproc_fn, apply_before_preproc, correct_fn)