class_docstr: Implementation of Selectivity test by Montavon et al., 2018.
  
  At each iteration, a patch (e.g., of size 4 x 4) corresponding to the region with
  highest relevance is set to black. The plot keeps track of the function value
  as the features are being progressively removed and computes an average over
  a large number of examples.
  
  Assumptions:
      - The original metric definition relies on perturbation functionality suited only for images.
      Therefore, only apply the metric to 3-dimensional (image) data. To extend the applicablity
      to other data domains, adjustments to the current implementation might be necessary.
  
  References:
      1) Grégoire Montavon et al.:
      "Methods for interpreting and understanding deep neural networks."
      Digital Signal Processing 73 (2018): 1-15.
  
  Attributes:
      -  _name: The name of the metric.
      - _data_applicability: The data types that the metric implementation currently supports.
      - _models: The model types that this metric can work with.
      - score_direction: How to interpret the scores, whether higher/ lower values are considered better.
      - evaluation_category: What property/ explanation quality that this metric measures.
class_docstr_tok: ["Implementation","of","Selectivity","test","by","Montavon","et","al.",",","2018",".","At","each","iteration",",","a","patch","(","e.g.",",","of","size","4","x","4",")","corresponding","to","the","region","with","highest","relevance","is","set","to","black",".","The","plot","keeps","track","of","the","function","value","as","the","features","are","being","progressively","removed","and","computes","an","average","over","a","large","number","of","examples",".","Assumptions",":","-","The","original","metric","definition","relies","on","perturbation","functionality","suited","only","for","images",".","Therefore",",","only","apply","the","metric","to","3-dimensional","(","image",")","data",".","To","extend","the","applicablity","to","other","data","domains",",","adjustments","to","the","current","implementation","might","be","necessary",".","References",":","1",")","Gr\u00e9goire","Montavon","et","al",".",":","``","Methods","for","interpreting","and","understanding","deep","neural","networks",".","''","Digital","Signal","Processing","73","(","2018",")",":","1-15",".","Attributes",":","-","_name",":","The","name","of","the","metric",".","-","_data_applicability",":","The","data","types","that","the","metric","implementation","currently","supports",".","-","_models",":","The","model","types","that","this","metric","can","work","with",".","-","score_direction",":","How","to","interpret","the","scores",",","whether","higher\/","lower","values","are","considered","better",".","-","evaluation_category",":","What","property\/","explanation","quality","that","this","metric","measures","."]
docstr: This implementation represents the main logic of the metric and makes the class object callable.
  It completes instance-wise evaluation of explanations (a_batch) with respect to input data (x_batch),
  output labels (y_batch) and a torch or tensorflow model (model).
  
  Calls general_preprocess() with all relevant arguments, calls
  () on each instance, and saves results to evaluation_scores.
  Calls custom_postprocess() afterwards. Finally returns evaluation_scores.
  
  Parameters
  ----------
  model: torch.nn.Module, tf.keras.Model
      A torch or tensorflow model that is subject to explanation.
  x_batch: np.ndarray
      A np.ndarray which contains the input data that are explained.
  y_batch: np.ndarray
      A np.ndarray which contains the output labels that are explained.
  a_batch: np.ndarray, optional
      A np.ndarray which contains pre-computed attributions i.e., explanations.
  s_batch: np.ndarray, optional
      A np.ndarray which contains segmentation masks that matches the input.
  channel_first: boolean, optional
      Indicates of the image dimensions are channel first, or channel last.
      Inferred from the input shape if None.
  explain_func: callable
      Callable generating attributions.
  explain_func_kwargs: dict, optional
      Keyword arguments to be passed to explain_func on call.
  model_predict_kwargs: dict, optional
      Keyword arguments to be passed to the model's predict method.
  softmax: boolean
      Indicates whether to use softmax probabilities or logits in model prediction.
      This is used for this __call__ only and won't be saved as attribute. If None, self.softmax is used.
  device: string
      Indicated the device on which a torch.Tensor is or will be allocated: "cpu" or "gpu".
  kwargs: optional
      Keyword arguments.
  
  Returns
  -------
  evaluation_scores: list
      a list of Any with the evaluation scores of the concerned batch.
  
  Examples:
  --------
      # Minimal imports.
      >> import quantus
      >> from quantus import LeNet
      >> import torch
  
      # Enable GPU.
      >> device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
  
      # Load a pre-trained LeNet classification model (architecture at quantus/helpers/models).
      >> model = LeNet()
      >> model.load_state_dict(torch.load("tutorials/assets/pytests/mnist_model"))
  
      # Load MNIST datasets and make loaders.
      >> test_set = torchvision.datasets.MNIST(root='./sample_data', download=True)
      >> test_loader = torch.utils.data.DataLoader(test_set, batch_size=24)
  
      # Load a batch of inputs and outputs to use for XAI evaluation.
      >> x_batch, y_batch = iter(test_loader).next()
      >> x_batch, y_batch = x_batch.cpu().numpy(), y_batch.cpu().numpy()
  
      # Generate Saliency attributions of the test set batch of the test set.
      >> a_batch_saliency = Saliency(model).attribute(inputs=x_batch, target=y_batch, abs=True).sum(axis=1)
      >> a_batch_saliency = a_batch_saliency.cpu().numpy()
  
      # Initialise the metric and evaluate explanations by calling the metric instance.
      >> metric = Metric(abs=True, normalise=False)
      >> scores = metric(model=model, x_batch=x_batch, y_batch=y_batch, a_batch=a_batch_saliency)
docstr_tok: ["This","implementation","represents","the","main","logic","of","the","metric","and","makes","the","class","object","callable",".","It","completes","instance-wise","evaluation","of","explanations","(","a_batch",")","with","respect","to","input","data","(","x_batch",")",",","output","labels","(","y_batch",")","and","a","torch","or","tensorflow","model","(","model",")",".","Calls","general_preprocess","(",")","with","all","relevant","arguments",",","calls","(",")","on","each","instance",",","and","saves","results","to","evaluation_scores",".","Calls","custom_postprocess","(",")","afterwards",".","Finally","returns","evaluation_scores",".","Parameters","--","--","--","--","--","model",":","torch.nn.Module",",","tf.keras.Model","A","torch","or","tensorflow","model","that","is","subject","to","explanation",".","x_batch",":","np.ndarray","A","np.ndarray","which","contains","the","input","data","that","are","explained",".","y_batch",":","np.ndarray","A","np.ndarray","which","contains","the","output","labels","that","are","explained",".","a_batch",":","np.ndarray",",","optional","A","np.ndarray","which","contains","pre-computed","attributions","i.e.",",","explanations",".","s_batch",":","np.ndarray",",","optional","A","np.ndarray","which","contains","segmentation","masks","that","matches","the","input",".","channel_first",":","boolean",",","optional","Indicates","of","the","image","dimensions","are","channel","first",",","or","channel","last",".","Inferred","from","the","input","shape","if","None",".","explain_func",":","callable","Callable","generating","attributions",".","explain_func_kwargs",":","dict",",","optional","Keyword","arguments","to","be","passed","to","explain_func","on","call",".","model_predict_kwargs",":","dict",",","optional","Keyword","arguments","to","be","passed","to","the","model","'s","predict","method",".","softmax",":","boolean","Indicates","whether","to","use","softmax","probabilities","or","logits","in","model","prediction",".","This","is","used","for","this","__call__","only","and","wo","n't","be","saved","as","attribute",".","If","None",",","self.softmax","is","used",".","device",":","string","Indicated","the","device","on","which","a","torch.Tensor","is","or","will","be","allocated",":","``","cpu","''","or","``","gpu","''",".","kwargs",":","optional","Keyword","arguments",".","Returns","--","--","--","-","evaluation_scores",":","list","a","list","of","Any","with","the","evaluation","scores","of","the","concerned","batch",".","Examples",":","--","--","--","--","#","Minimal","imports",".",">",">","import","quantus",">",">","from","quantus","import","LeNet",">",">","import","torch","#","Enable","GPU",".",">",">","device","=","torch.device","(","``","cuda:0","''","if","torch.cuda.is_available","(",")","else","``","cpu","''",")","#","Load","a","pre-trained","LeNet","classification","model","(","architecture","at","quantus\/helpers\/models",")",".",">",">","model","=","LeNet","(",")",">",">","model.load_state_dict","(","torch.load","(","``","tutorials\/assets\/pytests\/mnist_model","''",")",")","#","Load","MNIST","datasets","and","make","loaders",".",">",">","test_set","=","torchvision.datasets.MNIST","(","root='.\/sample_data","'",",","download=True",")",">",">","test_loader","=","torch.utils.data.DataLoader","(","test_set",",","batch_size=24",")","#","Load","a","batch","of","inputs","and","outputs","to","use","for","XAI","evaluation",".",">",">","x_batch",",","y_batch","=","iter","(","test_loader",")",".next","(",")",">",">","x_batch",",","y_batch","=","x_batch.cpu","(",")",".numpy","(",")",",","y_batch.cpu","(",")",".numpy","(",")","#","Generate","Saliency","attributions","of","the","test","set","batch","of","the","test","set",".",">",">","a_batch_saliency","=","Saliency","(","model",")",".attribute","(","inputs=x_batch",",","target=y_batch",",","abs=True",")",".sum","(","axis=1",")",">",">","a_batch_saliency","=","a_batch_saliency.cpu","(",")",".numpy","(",")","#","Initialise","the","metric","and","evaluate","explanations","by","calling","the","metric","instance",".",">",">","metric","=","Metric","(","abs=True",",","normalise=False",")",">",">","scores","=","metric","(","model=model",",","x_batch=x_batch",",","y_batch=y_batch",",","a_batch=a_batch_saliency",")"]
code: def __call__(
      self,
      model,
      x_batch: np.ndarray,
      y_batch: np.ndarray,
      a_batch: Optional[np.ndarray] = None,
      s_batch: Optional[np.ndarray] = None,
      channel_first: Optional[bool] = None,
      explain_func: Optional[Callable] = None,
      explain_func_kwargs: Optional[Dict] = None,
      model_predict_kwargs: Optional[Dict] = None,
      softmax: Optional[bool] = True,
      device: Optional[str] = None,
      batch_size: int = 64,
      **kwargs,
  ) -> List[float]:
      """
      This implementation represents the main logic of the metric and makes the class object callable.
      It completes instance-wise evaluation of explanations (a_batch) with respect to input data (x_batch),
      output labels (y_batch) and a torch or tensorflow model (model).
  
      Calls general_preprocess() with all relevant arguments, calls
      () on each instance, and saves results to evaluation_scores.
      Calls custom_postprocess() afterwards. Finally returns evaluation_scores.
  
      Parameters
      ----------
      model: torch.nn.Module, tf.keras.Model
          A torch or tensorflow model that is subject to explanation.
      x_batch: np.ndarray
          A np.ndarray which contains the input data that are explained.
      y_batch: np.ndarray
          A np.ndarray which contains the output labels that are explained.
      a_batch: np.ndarray, optional
          A np.ndarray which contains pre-computed attributions i.e., explanations.
      s_batch: np.ndarray, optional
          A np.ndarray which contains segmentation masks that matches the input.
      channel_first: boolean, optional
          Indicates of the image dimensions are channel first, or channel last.
          Inferred from the input shape if None.
      explain_func: callable
          Callable generating attributions.
      explain_func_kwargs: dict, optional
          Keyword arguments to be passed to explain_func on call.
      model_predict_kwargs: dict, optional
          Keyword arguments to be passed to the model's predict method.
      softmax: boolean
          Indicates whether to use softmax probabilities or logits in model prediction.
          This is used for this __call__ only and won't be saved as attribute. If None, self.softmax is used.
      device: string
          Indicated the device on which a torch.Tensor is or will be allocated: "cpu" or "gpu".
      kwargs: optional
          Keyword arguments.
  
      Returns
      -------
      evaluation_scores: list
          a list of Any with the evaluation scores of the concerned batch.
  
      Examples:
      --------
          # Minimal imports.
          >> import quantus
          >> from quantus import LeNet
          >> import torch
  
          # Enable GPU.
          >> device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
  
          # Load a pre-trained LeNet classification model (architecture at quantus/helpers/models).
          >> model = LeNet()
          >> model.load_state_dict(torch.load("tutorials/assets/pytests/mnist_model"))
  
          # Load MNIST datasets and make loaders.
          >> test_set = torchvision.datasets.MNIST(root='./sample_data', download=True)
          >> test_loader = torch.utils.data.DataLoader(test_set, batch_size=24)
  
          # Load a batch of inputs and outputs to use for XAI evaluation.
          >> x_batch, y_batch = iter(test_loader).next()
          >> x_batch, y_batch = x_batch.cpu().numpy(), y_batch.cpu().numpy()
  
          # Generate Saliency attributions of the test set batch of the test set.
          >> a_batch_saliency = Saliency(model).attribute(inputs=x_batch, target=y_batch, abs=True).sum(axis=1)
          >> a_batch_saliency = a_batch_saliency.cpu().numpy()
  
          # Initialise the metric and evaluate explanations by calling the metric instance.
          >> metric = Metric(abs=True, normalise=False)
          >> scores = metric(model=model, x_batch=x_batch, y_batch=y_batch, a_batch=a_batch_saliency)
      """
      return super().__call__(
          model=model,
          x_batch=x_batch,
          y_batch=y_batch,
          a_batch=a_batch,
          s_batch=s_batch,
          custom_batch=None,
          channel_first=channel_first,
          explain_func=explain_func,
          explain_func_kwargs=explain_func_kwargs,
          softmax=softmax,
          device=device,
          model_predict_kwargs=model_predict_kwargs,
          batch_size=batch_size,
          **kwargs,
      )
  
file_path: Quantus/quantus/metrics/faithfulness/selectivity.py
imports: import itertools
  import sys
  from typing import Any, Callable, Dict, List, Optional
  import numpy
  from quantus.functions.perturb_func import baseline_replacement_by_indices
  from quantus.helpers import plotting, utils, warn
  from quantus.helpers.enums import DataType, EvaluationCategory, ModelType, ScoreDirection
  from quantus.helpers.model.model_interface import ModelInterface
  from quantus.helpers.perturbation_utils import make_perturb_func
  from quantus.metrics.base import Metric
label_desc: Use image node_id 2 for calling the Selectivity obj's underlying member method code with example usage: obj.__call__(model, x_batch, y_batch, a_batch, s_batch, channel_first, explain_func, explain_func_kwargs, model_predict_kwargs, softmax, device, batch_size) and returns: super