class_docstr: Lime is an interpretability method that trains an interpretable surrogate model
  by sampling points around a specified input example and using model evaluations
  at these points to train a simpler interpretable 'surrogate' model, such as a
  linear model.
  
  LimeBase provides a generic framework to train a surrogate interpretable model.
  This differs from most other attribution methods, since the method returns a
  representation of the interpretable model (e.g. coefficients of the linear model).
  For a similar interface to other perturbation-based attribution methods, please use
  the Lime child class, which defines specific transformations for the interpretable
  model.
  
  LimeBase allows sampling points in either the interpretable space or the original
  input space to train the surrogate model. The interpretable space is a feature
  vector used to train the surrogate interpretable model; this feature space is often
  of smaller dimensionality than the original feature space in order for the surrogate
  model to be more interpretable.
  
  If sampling in the interpretable space, a transformation function must be provided
  to define how a vector sampled in the interpretable space can be transformed into
  an example in the original input space. If sampling in the original input space, a
  transformation function must be provided to define how the input can be transformed
  into its interpretable vector representation.
  
  More details regarding LIME can be found in the original paper:
  https://arxiv.org/abs/1602.04938
docstr: Args:
  
  
      forward_func (Callable): The forward function of the model or any
              modification of it. If a batch is provided as input for
              attribution, it is expected that forward_func returns a scalar
              representing the entire batch.
      interpretable_model (Model): Model object to train interpretable model.
              A Model object provides a `fit` method to train the model,
              given a dataloader, with batches containing three tensors:
  
              - interpretable_inputs: Tensor
                [2D num_samples x num_interp_features],
              - expected_outputs: Tensor [1D num_samples],
              - weights: Tensor [1D num_samples]
  
              The model object must also provide a `representation` method to
              access the appropriate coefficients or representation of the
              interpretable model after fitting.
              Some predefined interpretable linear models are provided in
              captum._utils.models.linear_model including wrappers around
              SkLearn linear models as well as SGD-based PyTorch linear
              models.
  
              Note that calling fit multiple times should retrain the
              interpretable model, each attribution call reuses
              the same given interpretable model object.
      similarity_func (Callable): Function which takes a single sample
              along with its corresponding interpretable representation
              and returns the weight of the interpretable sample for
              training interpretable model. Weight is generally
              determined based on similarity to the original input.
              The original paper refers to this as a similarity kernel.
  
              The expected signature of this callable is:
  
              >>> similarity_func(
              >>>    original_input: Tensor or tuple[Tensor, ...],
              >>>    perturbed_input: Tensor or tuple[Tensor, ...],
              >>>    perturbed_interpretable_input:
              >>>        Tensor [2D 1 x num_interp_features],
              >>>    **kwargs: Any
              >>> ) -> float or Tensor containing float scalar
  
              perturbed_input and original_input will be the same type and
              contain tensors of the same shape (regardless of whether or not
              the sampling function returns inputs in the interpretable
              space). original_input is the same as the input provided
              when calling attribute.
  
              All kwargs passed to the attribute method are
              provided as keyword arguments (kwargs) to this callable.
      perturb_func (Callable): Function which returns a single
              sampled input, generally a perturbation of the original
              input, which is used to train the interpretable surrogate
              model. Function can return samples in either
              the original input space (matching type and tensor shapes
              of original input) or in the interpretable input space,
              which is a vector containing the intepretable features.
              Alternatively, this function can return a generator
              yielding samples to train the interpretable surrogate
              model, and n_samples perturbations will be sampled
              from this generator.
  
              The expected signature of this callable is:
  
              >>> perturb_func(
              >>>    original_input: Tensor or tuple[Tensor, ...],
              >>>    **kwargs: Any
              >>> ) -> Tensor, tuple[Tensor, ...], or
              >>>    generator yielding tensor or tuple[Tensor, ...]
  
              All kwargs passed to the attribute method are
              provided as keyword arguments (kwargs) to this callable.
  
              Returned sampled input should match the input type (Tensor
              or Tuple of Tensor and corresponding shapes) if
              perturb_interpretable_space = False. If
              perturb_interpretable_space = True, the return type should
              be a single tensor of shape 1 x num_interp_features,
              corresponding to the representation of the
              sample to train the interpretable model.
  
              All kwargs passed to the attribute method are
              provided as keyword arguments (kwargs) to this callable.
      perturb_interpretable_space (bool): Indicates whether
              perturb_func returns a sample in the interpretable space
              (tensor of shape 1 x num_interp_features) or a sample
              in the original space, matching the format of the original
              input. Once sampled, inputs can be converted to / from
              the interpretable representation with either
              to_interp_rep_transform or from_interp_rep_transform.
      from_interp_rep_transform (Callable): Function which takes a
              single sampled interpretable representation (tensor
              of shape 1 x num_interp_features) and returns
              the corresponding representation in the input space
              (matching shapes of original input to attribute).
  
              This argument is necessary if perturb_interpretable_space
              is True, otherwise None can be provided for this argument.
  
              The expected signature of this callable is:
  
              >>> from_interp_rep_transform(
              >>>    curr_sample: Tensor [2D 1 x num_interp_features]
              >>>    original_input: Tensor or Tuple of Tensors,
              >>>    **kwargs: Any
              >>> ) -> Tensor or tuple[Tensor, ...]
  
              Returned sampled input should match the type of original_input
              and corresponding tensor shapes.
  
              All kwargs passed to the attribute method are
              provided as keyword arguments (kwargs) to this callable.
  
      to_interp_rep_transform (Callable): Function which takes a
              sample in the original input space and converts to
              its interpretable representation (tensor
              of shape 1 x num_interp_features).
  
              This argument is necessary if perturb_interpretable_space
              is False, otherwise None can be provided for this argument.
  
              The expected signature of this callable is:
  
              >>> to_interp_rep_transform(
              >>>    curr_sample: Tensor or Tuple of Tensors,
              >>>    original_input: Tensor or Tuple of Tensors,
              >>>    **kwargs: Any
              >>> ) -> Tensor [2D 1 x num_interp_features]
  
              curr_sample will match the type of original_input
              and corresponding tensor shapes.
  
              All kwargs passed to the attribute method are
              provided as keyword arguments (kwargs) to this callable.
docstr_tok: ["Args",":","forward_func","(","Callable",")",":","The","forward","function","of","the","model","or","any","modification","of","it",".","If","a","batch","is","provided","as","input","for","attribution",",","it","is","expected","that","forward_func","returns","a","scalar","representing","the","entire","batch",".","interpretable_model","(","Model",")",":","Model","object","to","train","interpretable","model",".","A","Model","object","provides","a","`","fit","`","method","to","train","the","model",",","given","a","dataloader",",","with","batches","containing","three","tensors",":","-","interpretable_inputs",":","Tensor","[","2D","num_samples","x","num_interp_features","]",",","-","expected_outputs",":","Tensor","[","1D","num_samples","]",",","-","weights",":","Tensor","[","1D","num_samples","]","The","model","object","must","also","provide","a","`","representation","`","method","to","access","the","appropriate","coefficients","or","representation","of","the","interpretable","model","after","fitting",".","Some","predefined","interpretable","linear","models","are","provided","in","captum._utils.models.linear_model","including","wrappers","around","SkLearn","linear","models","as","well","as","SGD-based","PyTorch","linear","models",".","Note","that","calling","fit","multiple","times","should","retrain","the","interpretable","model",",","each","attribution","call","reuses","the","same","given","interpretable","model","object",".","similarity_func","(","Callable",")",":","Function","which","takes","a","single","sample","along","with","its","corresponding","interpretable","representation","and","returns","the","weight","of","the","interpretable","sample","for","training","interpretable","model",".","Weight","is","generally","determined","based","on","similarity","to","the","original","input",".","The","original","paper","refers","to","this","as","a","similarity","kernel",".","The","expected","signature","of","this","callable","is",":",">",">",">","similarity_func","(",">",">",">","original_input",":","Tensor","or","tuple","[","Tensor",",","...","]",",",">",">",">","perturbed_input",":","Tensor","or","tuple","[","Tensor",",","...","]",",",">",">",">","perturbed_interpretable_input",":",">",">",">","Tensor","[","2D","1","x","num_interp_features","]",",",">",">",">","*","*","kwargs",":","Any",">",">",">",")","-",">","float","or","Tensor","containing","float","scalar","perturbed_input","and","original_input","will","be","the","same","type","and","contain","tensors","of","the","same","shape","(","regardless","of","whether","or","not","the","sampling","function","returns","inputs","in","the","interpretable","space",")",".","original_input","is","the","same","as","the","input","provided","when","calling","attribute",".","All","kwargs","passed","to","the","attribute","method","are","provided","as","keyword","arguments","(","kwargs",")","to","this","callable",".","perturb_func","(","Callable",")",":","Function","which","returns","a","single","sampled","input",",","generally","a","perturbation","of","the","original","input",",","which","is","used","to","train","the","interpretable","surrogate","model",".","Function","can","return","samples","in","either","the","original","input","space","(","matching","type","and","tensor","shapes","of","original","input",")","or","in","the","interpretable","input","space",",","which","is","a","vector","containing","the","intepretable","features",".","Alternatively",",","this","function","can","return","a","generator","yielding","samples","to","train","the","interpretable","surrogate","model",",","and","n_samples","perturbations","will","be","sampled","from","this","generator",".","The","expected","signature","of","this","callable","is",":",">",">",">","perturb_func","(",">",">",">","original_input",":","Tensor","or","tuple","[","Tensor",",","...","]",",",">",">",">","*","*","kwargs",":","Any",">",">",">",")","-",">","Tensor",",","tuple","[","Tensor",",","...","]",",","or",">",">",">","generator","yielding","tensor","or","tuple","[","Tensor",",","...","]","All","kwargs","passed","to","the","attribute","method","are","provided","as","keyword","arguments","(","kwargs",")","to","this","callable",".","Returned","sampled","input","should","match","the","input","type","(","Tensor","or","Tuple","of","Tensor","and","corresponding","shapes",")","if","perturb_interpretable_space","=","False",".","If","perturb_interpretable_space","=","True",",","the","return","type","should","be","a","single","tensor","of","shape","1","x","num_interp_features",",","corresponding","to","the","representation","of","the","sample","to","train","the","interpretable","model",".","All","kwargs","passed","to","the","attribute","method","are","provided","as","keyword","arguments","(","kwargs",")","to","this","callable",".","perturb_interpretable_space","(","bool",")",":","Indicates","whether","perturb_func","returns","a","sample","in","the","interpretable","space","(","tensor","of","shape","1","x","num_interp_features",")","or","a","sample","in","the","original","space",",","matching","the","format","of","the","original","input",".","Once","sampled",",","inputs","can","be","converted","to","\/","from","the","interpretable","representation","with","either","to_interp_rep_transform","or","from_interp_rep_transform",".","from_interp_rep_transform","(","Callable",")",":","Function","which","takes","a","single","sampled","interpretable","representation","(","tensor","of","shape","1","x","num_interp_features",")","and","returns","the","corresponding","representation","in","the","input","space","(","matching","shapes","of","original","input","to","attribute",")",".","This","argument","is","necessary","if","perturb_interpretable_space","is","True",",","otherwise","None","can","be","provided","for","this","argument",".","The","expected","signature","of","this","callable","is",":",">",">",">","from_interp_rep_transform","(",">",">",">","curr_sample",":","Tensor","[","2D","1","x","num_interp_features","]",">",">",">","original_input",":","Tensor","or","Tuple","of","Tensors",",",">",">",">","*","*","kwargs",":","Any",">",">",">",")","-",">","Tensor","or","tuple","[","Tensor",",","...","]","Returned","sampled","input","should","match","the","type","of","original_input","and","corresponding","tensor","shapes",".","All","kwargs","passed","to","the","attribute","method","are","provided","as","keyword","arguments","(","kwargs",")","to","this","callable",".","to_interp_rep_transform","(","Callable",")",":","Function","which","takes","a","sample","in","the","original","input","space","and","converts","to","its","interpretable","representation","(","tensor","of","shape","1","x","num_interp_features",")",".","This","argument","is","necessary","if","perturb_interpretable_space","is","False",",","otherwise","None","can","be","provided","for","this","argument",".","The","expected","signature","of","this","callable","is",":",">",">",">","to_interp_rep_transform","(",">",">",">","curr_sample",":","Tensor","or","Tuple","of","Tensors",",",">",">",">","original_input",":","Tensor","or","Tuple","of","Tensors",",",">",">",">","*","*","kwargs",":","Any",">",">",">",")","-",">","Tensor","[","2D","1","x","num_interp_features","]","curr_sample","will","match","the","type","of","original_input","and","corresponding","tensor","shapes",".","All","kwargs","passed","to","the","attribute","method","are","provided","as","keyword","arguments","(","kwargs",")","to","this","callable","."]
code: def __init__(
      self,
      forward_func: Callable,
      interpretable_model: Model,
      similarity_func: Callable,
      perturb_func: Callable,
      perturb_interpretable_space: bool,
      from_interp_rep_transform: Optional[Callable],
      to_interp_rep_transform: Optional[Callable],
  ) -> None:
      r"""
  
      Args:
  
  
          forward_func (Callable): The forward function of the model or any
                  modification of it. If a batch is provided as input for
                  attribution, it is expected that forward_func returns a scalar
                  representing the entire batch.
          interpretable_model (Model): Model object to train interpretable model.
                  A Model object provides a `fit` method to train the model,
                  given a dataloader, with batches containing three tensors:
  
                  - interpretable_inputs: Tensor
                    [2D num_samples x num_interp_features],
                  - expected_outputs: Tensor [1D num_samples],
                  - weights: Tensor [1D num_samples]
  
                  The model object must also provide a `representation` method to
                  access the appropriate coefficients or representation of the
                  interpretable model after fitting.
                  Some predefined interpretable linear models are provided in
                  captum._utils.models.linear_model including wrappers around
                  SkLearn linear models as well as SGD-based PyTorch linear
                  models.
  
                  Note that calling fit multiple times should retrain the
                  interpretable model, each attribution call reuses
                  the same given interpretable model object.
          similarity_func (Callable): Function which takes a single sample
                  along with its corresponding interpretable representation
                  and returns the weight of the interpretable sample for
                  training interpretable model. Weight is generally
                  determined based on similarity to the original input.
                  The original paper refers to this as a similarity kernel.
  
                  The expected signature of this callable is:
  
                  >>> similarity_func(
                  >>>    original_input: Tensor or tuple[Tensor, ...],
                  >>>    perturbed_input: Tensor or tuple[Tensor, ...],
                  >>>    perturbed_interpretable_input:
                  >>>        Tensor [2D 1 x num_interp_features],
                  >>>    **kwargs: Any
                  >>> ) -> float or Tensor containing float scalar
  
                  perturbed_input and original_input will be the same type and
                  contain tensors of the same shape (regardless of whether or not
                  the sampling function returns inputs in the interpretable
                  space). original_input is the same as the input provided
                  when calling attribute.
  
                  All kwargs passed to the attribute method are
                  provided as keyword arguments (kwargs) to this callable.
          perturb_func (Callable): Function which returns a single
                  sampled input, generally a perturbation of the original
                  input, which is used to train the interpretable surrogate
                  model. Function can return samples in either
                  the original input space (matching type and tensor shapes
                  of original input) or in the interpretable input space,
                  which is a vector containing the intepretable features.
                  Alternatively, this function can return a generator
                  yielding samples to train the interpretable surrogate
                  model, and n_samples perturbations will be sampled
                  from this generator.
  
                  The expected signature of this callable is:
  
                  >>> perturb_func(
                  >>>    original_input: Tensor or tuple[Tensor, ...],
                  >>>    **kwargs: Any
                  >>> ) -> Tensor, tuple[Tensor, ...], or
                  >>>    generator yielding tensor or tuple[Tensor, ...]
  
                  All kwargs passed to the attribute method are
                  provided as keyword arguments (kwargs) to this callable.
  
                  Returned sampled input should match the input type (Tensor
                  or Tuple of Tensor and corresponding shapes) if
                  perturb_interpretable_space = False. If
                  perturb_interpretable_space = True, the return type should
                  be a single tensor of shape 1 x num_interp_features,
                  corresponding to the representation of the
                  sample to train the interpretable model.
  
                  All kwargs passed to the attribute method are
                  provided as keyword arguments (kwargs) to this callable.
          perturb_interpretable_space (bool): Indicates whether
                  perturb_func returns a sample in the interpretable space
                  (tensor of shape 1 x num_interp_features) or a sample
                  in the original space, matching the format of the original
                  input. Once sampled, inputs can be converted to / from
                  the interpretable representation with either
                  to_interp_rep_transform or from_interp_rep_transform.
          from_interp_rep_transform (Callable): Function which takes a
                  single sampled interpretable representation (tensor
                  of shape 1 x num_interp_features) and returns
                  the corresponding representation in the input space
                  (matching shapes of original input to attribute).
  
                  This argument is necessary if perturb_interpretable_space
                  is True, otherwise None can be provided for this argument.
  
                  The expected signature of this callable is:
  
                  >>> from_interp_rep_transform(
                  >>>    curr_sample: Tensor [2D 1 x num_interp_features]
                  >>>    original_input: Tensor or Tuple of Tensors,
                  >>>    **kwargs: Any
                  >>> ) -> Tensor or tuple[Tensor, ...]
  
                  Returned sampled input should match the type of original_input
                  and corresponding tensor shapes.
  
                  All kwargs passed to the attribute method are
                  provided as keyword arguments (kwargs) to this callable.
  
          to_interp_rep_transform (Callable): Function which takes a
                  sample in the original input space and converts to
                  its interpretable representation (tensor
                  of shape 1 x num_interp_features).
  
                  This argument is necessary if perturb_interpretable_space
                  is False, otherwise None can be provided for this argument.
  
                  The expected signature of this callable is:
  
                  >>> to_interp_rep_transform(
                  >>>    curr_sample: Tensor or Tuple of Tensors,
                  >>>    original_input: Tensor or Tuple of Tensors,
                  >>>    **kwargs: Any
                  >>> ) -> Tensor [2D 1 x num_interp_features]
  
                  curr_sample will match the type of original_input
                  and corresponding tensor shapes.
  
                  All kwargs passed to the attribute method are
                  provided as keyword arguments (kwargs) to this callable.
      """
      PerturbationAttribution.__init__(self, forward_func)
      self.interpretable_model = interpretable_model
      self.similarity_func = similarity_func
      self.perturb_func = perturb_func
      self.perturb_interpretable_space = perturb_interpretable_space
      self.from_interp_rep_transform = from_interp_rep_transform
      self.to_interp_rep_transform = to_interp_rep_transform
  
      if self.perturb_interpretable_space:
          assert (
              self.from_interp_rep_transform is not None
          ), "Must provide transform from interpretable space to original input space"
          " when sampling from interpretable space."
      else:
          assert (
              self.to_interp_rep_transform is not None
          ), "Must provide transform from original input space to interpretable space"
  
imports: import inspect
  import math
  import typing
  import warnings
  from typing import Any, Callable, cast, List, Optional, Tuple, Union
  import torch
  from captum._utils.common import _expand_additional_forward_args, _expand_target, _flatten_tensor_or_tuple, _format_output, _format_tensor_into_tuples, _get_max_feature_index, _is_tuple, _reduce_list, _run_forward
  from captum._utils.models.linear_model import SkLearnLasso
  from captum._utils.models.model import Model
  from captum._utils.progress import progress
  from captum._utils.typing import BaselineType, Literal, TargetType, TensorOrTupleOfTensorsGeneric
  from captum.attr._utils.attribution import PerturbationAttribution
  from captum.attr._utils.batching import _batch_example_iterator
  from captum.attr._utils.common import _construct_default_feature_mask, _format_input_baseline
  from captum.log import log_usage
  from torch import Tensor
  from torch.nn import CosineSimilarity
  from torch.utils.data import DataLoader, TensorDataset
label_desc: Use image node_id 1 to create a new LimeBase object from inherited base classes: PerturbationAttribution with example: obj = LimeBase(forward_func, interpretable_model, similarity_func, perturb_func, perturb_interpretable_space, from_interp_rep_transform, to_interp_rep_transform)