class_docstr: Implementation of Region Perturbation by Samek et al., 2015.
  
  Consider a greedy iterative procedure that consists of measuring how the class
  encoded in the image (e.g. as measured by the function f) disappears when we
  progressively remove information from the image x, a process referred to as
  region perturbation, at the specified locations.
  
  Assumptions:
      - The original metric definition relies on image-patch functionality. 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) Wojciech Samek et al.: "Evaluating the visualization of what a deep
      neural network has learned." IEEE transactions on neural networks and
      learning systems 28.11 (2016): 2660-2673.
  
  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","Region","Perturbation","by","Samek","et","al.",",","2015",".","Consider","a","greedy","iterative","procedure","that","consists","of","measuring","how","the","class","encoded","in","the","image","(","e.g",".","as","measured","by","the","function","f",")","disappears","when","we","progressively","remove","information","from","the","image","x",",","a","process","referred","to","as","region","perturbation",",","at","the","specified","locations",".","Assumptions",":","-","The","original","metric","definition","relies","on","image-patch","functionality",".","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",")","Wojciech","Samek","et","al",".",":","``","Evaluating","the","visualization","of","what","a","deep","neural","network","has","learned",".","''","IEEE","transactions","on","neural","networks","and","learning","systems","28.11","(","2016",")",":","2660-2673",".","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: Parameters
  ----------
  patch_size: integer
      The patch size for masking, default=8.
  regions_evaluation: integer
      The number of regions to evaluate, default=100.
  order: string
      Indicates whether attributions are ordered randomly ("random"),
          according to the most relevant first ("morf"), or least relevant first ("lerf"), default="morf".
  abs: boolean
      Indicates whether absolute operation is applied on the attribution, default=False.
  normalise: boolean
      Indicates whether normalise operation is applied on the attribution, default=True.
  normalise_func: callable
      Attribution normalisation function applied in case normalise=True.
      If normalise_func=None, the default value is used, default=normalise_by_max.
  normalise_func_kwargs: dict
      Keyword arguments to be passed to normalise_func on call, default={}.
  perturb_func: callable
      Input perturbation function. If None, the default value is used,
      default=baseline_replacement_by_indices.
  perturb_baseline: string
      Indicates the type of baseline: "mean", "random", "uniform", "black" or "white",
      default="black".
  perturb_func_kwargs: dict
      Keyword arguments to be passed to perturb_func, default={}.
  return_aggregate: boolean
      Indicates if an aggregated score should be computed over all instances.
  aggregate_func: callable
      Callable that aggregates the scores given an evaluation call.
  default_plot_func: callable
      Callable that plots the metrics result.
  disable_warnings: boolean
      Indicates whether the warnings are printed, default=False.
  display_progressbar: boolean
      Indicates whether a tqdm-progress-bar is printed, default=False.
  kwargs: optional
      Keyword arguments.
docstr_tok: ["Parameters","--","--","--","--","--","patch_size",":","integer","The","patch","size","for","masking",",","default=8",".","regions_evaluation",":","integer","The","number","of","regions","to","evaluate",",","default=100",".","order",":","string","Indicates","whether","attributions","are","ordered","randomly","(","``","random","''",")",",","according","to","the","most","relevant","first","(","``","morf","''",")",",","or","least","relevant","first","(","``","lerf","''",")",",","default=","''","morf","''",".","abs",":","boolean","Indicates","whether","absolute","operation","is","applied","on","the","attribution",",","default=False",".","normalise",":","boolean","Indicates","whether","normalise","operation","is","applied","on","the","attribution",",","default=True",".","normalise_func",":","callable","Attribution","normalisation","function","applied","in","case","normalise=True",".","If","normalise_func=None",",","the","default","value","is","used",",","default=normalise_by_max",".","normalise_func_kwargs",":","dict","Keyword","arguments","to","be","passed","to","normalise_func","on","call",",","default=","{","}",".","perturb_func",":","callable","Input","perturbation","function",".","If","None",",","the","default","value","is","used",",","default=baseline_replacement_by_indices",".","perturb_baseline",":","string","Indicates","the","type","of","baseline",":","``","mean","''",",","``","random","''",",","``","uniform","''",",","``","black","''","or","``","white","''",",","default=","''","black","''",".","perturb_func_kwargs",":","dict","Keyword","arguments","to","be","passed","to","perturb_func",",","default=","{","}",".","return_aggregate",":","boolean","Indicates","if","an","aggregated","score","should","be","computed","over","all","instances",".","aggregate_func",":","callable","Callable","that","aggregates","the","scores","given","an","evaluation","call",".","default_plot_func",":","callable","Callable","that","plots","the","metrics","result",".","disable_warnings",":","boolean","Indicates","whether","the","warnings","are","printed",",","default=False",".","display_progressbar",":","boolean","Indicates","whether","a","tqdm-progress-bar","is","printed",",","default=False",".","kwargs",":","optional","Keyword","arguments","."]
code: def __init__(
      self,
      patch_size: int = 8,
      order: str = "morf",
      regions_evaluation: int = 100,
      abs: bool = False,
      normalise: bool = True,
      normalise_func: Optional[
          Callable[[np.ndarray], np.ndarray]
      ] = None,
      normalise_func_kwargs: Optional[Dict[str, Any]] = None,
      perturb_func: Optional[Callable] = None,
      perturb_baseline: str = "black",
      perturb_func_kwargs: Optional[Dict[str, Any]] = None,
      return_aggregate: bool = False,
      aggregate_func: Optional[Callable] = None,
      default_plot_func: Optional[Callable] = None,
      disable_warnings: bool = False,
      display_progressbar: bool = False,
      **kwargs,
  ):
      """
      Parameters
      ----------
      patch_size: integer
          The patch size for masking, default=8.
      regions_evaluation: integer
          The number of regions to evaluate, default=100.
      order: string
          Indicates whether attributions are ordered randomly ("random"),
              according to the most relevant first ("morf"), or least relevant first ("lerf"), default="morf".
      abs: boolean
          Indicates whether absolute operation is applied on the attribution, default=False.
      normalise: boolean
          Indicates whether normalise operation is applied on the attribution, default=True.
      normalise_func: callable
          Attribution normalisation function applied in case normalise=True.
          If normalise_func=None, the default value is used, default=normalise_by_max.
      normalise_func_kwargs: dict
          Keyword arguments to be passed to normalise_func on call, default={}.
      perturb_func: callable
          Input perturbation function. If None, the default value is used,
          default=baseline_replacement_by_indices.
      perturb_baseline: string
          Indicates the type of baseline: "mean", "random", "uniform", "black" or "white",
          default="black".
      perturb_func_kwargs: dict
          Keyword arguments to be passed to perturb_func, default={}.
      return_aggregate: boolean
          Indicates if an aggregated score should be computed over all instances.
      aggregate_func: callable
          Callable that aggregates the scores given an evaluation call.
      default_plot_func: callable
          Callable that plots the metrics result.
      disable_warnings: boolean
          Indicates whether the warnings are printed, default=False.
      display_progressbar: boolean
          Indicates whether a tqdm-progress-bar is printed, default=False.
      kwargs: optional
          Keyword arguments.
      """
      if default_plot_func is None:
          default_plot_func = (
              plotting.plot_region_perturbation_experiment
          )
  
      super().__init__(
          abs=abs,
          normalise=normalise,
          normalise_func=normalise_func,
          normalise_func_kwargs=normalise_func_kwargs,
          return_aggregate=return_aggregate,
          aggregate_func=aggregate_func,
          default_plot_func=default_plot_func,
          display_progressbar=display_progressbar,
          disable_warnings=disable_warnings,
          **kwargs,
      )
  
      if perturb_func is None:
          perturb_func = baseline_replacement_by_indices
  
      # Save metric-specific attributes.
      self.patch_size = patch_size
      self.order = order.lower()
      self.regions_evaluation = regions_evaluation
      self.perturb_func = make_perturb_func(
          perturb_func,
          perturb_func_kwargs,
          perturb_baseline=perturb_baseline,
      )
  
      # Asserts and warnings.
      asserts.assert_attributions_order(order=self.order)
      if not self.disable_warnings:
          warn.warn_parameterisation(
              metric_name=self.__class__.__name__,
              sensitive_params=(
                  "baseline value 'perturb_baseline'"
                  ", the patch size for masking 'patch_size'"
                  " and number of regions to evaluate 'regions_evaluation'"
              ),
              data_domain_applicability=(
                  f"Also, the current implementation only works for 3-dimensional (image) data."
              ),
              citation=(
                  "Samek, Wojciech, et al. 'Evaluating the visualization of what a deep"
                  " neural network has learned.' IEEE transactions on neural networks and"
                  " learning systems 28.11 (2016): 2660-2673"
              ),
          )
  
file_path: Quantus/quantus/metrics/faithfulness/region_perturbation.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 asserts, 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 1 to create a new RegionPerturbation object from inherited base classes: Metric with example: obj = RegionPerturbation(patch_size, order, regions_evaluation, abs, normalise, normalise_func, normalise_func_kwargs, perturb_func, perturb_baseline, perturb_func_kwargs, return_aggregate, aggregate_func, default_plot_func, disable_warnings, display_progressbar)