class_docstr: Relative Output Stability leverages the stability of an explanation with respect to the change in the output logits.
  
      `ROS(x, x', ex, ex') = max \frac{||\frac{e_x - e_x'}{e_x}||_p}
      {max (||h(x) - h(x')||_p, \epsilon_{min})}`,
  
  where `h(x)` and `h(x')` are the output logits for `x` and `x'` respectively.
  
  References:
      1) Chirag Agarwal, et. al., 2022. "Rethinking stability for attribution based explanations.",
      https://arxiv.org/pdf/2203.06877.pdf
  
  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: ["Relative","Output","Stability","leverages","the","stability","of","an","explanation","with","respect","to","the","change","in","the","output","logits",".","`","ROS","(","x",",","x","'",",","ex",",","ex","'",")","=","max","\\frac","{","||\\frac","{","e_x","-","e_x","'","}","{","e_x","}","||_p","}","{","max","(","||h","(","x",")","-","h","(","x","'",")","||_p",",","\\epsilon_","{","min","}",")","}","`",",","where","`","h","(","x",")","`","and","`","h","(","x","'",")","`","are","the","output","logits","for","`","x","`","and","`","x","'","`","respectively",".","References",":","1",")","Chirag","Agarwal",",","et",".","al.",",","2022",".","``","Rethinking","stability","for","attribution","based","explanations",".","``",",","https",":","\/\/arxiv.org\/pdf\/2203.06877.pdf","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
  ----------
  nr_samples: int
      The number of samples iterated, default=200.
  abs: boolean
      Indicates whether absolute operation is applied on the attribution.
  normalise: boolean
      Flag stating if the attributions should be normalised
  normalise_func: callable
      Attribution normalisation function applied in case normalise=True.
  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=gaussian_noise.
  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.
  disable_warnings: boolean
      Indicates whether the warnings are printed, default=False.
  display_progressbar: boolean
      Indicates whether a tqdm-progress-bar is printed, default=False.
  default_plot_func: callable
      Callable that plots the metrics result.
  eps_min: float
      Small constant to prevent division by 0 in relative_stability_objective, default 1e-6.
  return_nan_when_prediction_changes: boolean
      When set to true, the metric will be evaluated to NaN if the prediction changes after the perturbation is applied, default=True.
docstr_tok: ["Parameters","--","--","--","--","--","nr_samples",":","int","The","number","of","samples","iterated",",","default=200",".","abs",":","boolean","Indicates","whether","absolute","operation","is","applied","on","the","attribution",".","normalise",":","boolean","Flag","stating","if","the","attributions","should","be","normalised","normalise_func",":","callable","Attribution","normalisation","function","applied","in","case","normalise=True",".","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=gaussian_noise",".","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",".","disable_warnings",":","boolean","Indicates","whether","the","warnings","are","printed",",","default=False",".","display_progressbar",":","boolean","Indicates","whether","a","tqdm-progress-bar","is","printed",",","default=False",".","default_plot_func",":","callable","Callable","that","plots","the","metrics","result",".","eps_min",":","float","Small","constant","to","prevent","division","by","0","in","relative_stability_objective",",","default","1e-6",".","return_nan_when_prediction_changes",":","boolean","When","set","to","true",",","the","metric","will","be","evaluated","to","NaN","if","the","prediction","changes","after","the","perturbation","is","applied",",","default=True","."]
code: def __init__(
      self,
      nr_samples: int = 200,
      abs: bool = False,
      normalise: bool = False,
      normalise_func: Optional[
          Callable[[np.ndarray], np.ndarray]
      ] = None,
      normalise_func_kwargs: Optional[Dict[str, ...]] = None,
      perturb_func: Optional[Callable] = None,
      perturb_func_kwargs: Optional[Dict[str, ...]] = None,
      return_aggregate: bool = False,
      aggregate_func: Optional[Callable[[np.ndarray], np.float]] = None,
      disable_warnings: bool = False,
      display_progressbar: bool = False,
      eps_min: float = 1e-6,
      default_plot_func: Optional[Callable] = None,
      return_nan_when_prediction_changes: bool = True,
      **kwargs,
  ):
      """
      Parameters
      ----------
      nr_samples: int
          The number of samples iterated, default=200.
      abs: boolean
          Indicates whether absolute operation is applied on the attribution.
      normalise: boolean
          Flag stating if the attributions should be normalised
      normalise_func: callable
          Attribution normalisation function applied in case normalise=True.
      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=gaussian_noise.
      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.
      disable_warnings: boolean
          Indicates whether the warnings are printed, default=False.
      display_progressbar: boolean
          Indicates whether a tqdm-progress-bar is printed, default=False.
      default_plot_func: callable
          Callable that plots the metrics result.
      eps_min: float
          Small constant to prevent division by 0 in relative_stability_objective, default 1e-6.
      return_nan_when_prediction_changes: boolean
          When set to true, the metric will be evaluated to NaN if the prediction changes after the perturbation is applied, default=True.
      """
  
      if normalise_func is None:
          normalise_func = normalise_by_average_second_moment_estimate
  
      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 = uniform_noise
  
      self._nr_samples = nr_samples
      self._eps_min = eps_min
      self.perturb_func = make_perturb_func(
          perturb_func, perturb_func_kwargs, upper_bound=0.2
      )
      self.changed_prediction_indices_func = (
          make_changed_prediction_indices_func(
              return_nan_when_prediction_changes
          )
      )
  
      if not self.disable_warnings:
          warn_parameterisation(
              metric_name=self.__class__.__name__,
              sensitive_params=(
                  "function used to generate perturbations 'perturb_func' and parameters passed to it 'perturb_func_kwargs'"
                  "number of times perturbations are sampled 'nr_samples'"
              ),
              citation='Chirag Agarwal, et. al., 2022. "Rethinking stability for attribution based explanations." https://arxiv.org/pdf/2203.06877.pdf',
          )
  
file_path: Quantus/quantus/metrics/robustness/relative_output_stability.py
imports: from __future__ import annotations
  from typing import TYPE_CHECKING, Callable, Dict, List, Optional
  import numpy
  import sys
  from quantus.functions.normalise_func import normalise_by_average_second_moment_estimate
  from quantus.functions.perturb_func import perturb_batch, uniform_noise
  from quantus.helpers.enums import DataType, EvaluationCategory, ModelType, ScoreDirection
  from quantus.helpers.model.model_interface import ModelInterface
  from quantus.helpers.perturbation_utils import make_changed_prediction_indices_func, make_perturb_func
  from quantus.helpers.warn import warn_parameterisation
  from quantus.metrics.base import Metric
label_desc: Use image node_id 1 to create a new RelativeOutputStability object from inherited base classes: Metric with example: obj = RelativeOutputStability(nr_samples, abs, normalise, normalise_func, normalise_func_kwargs, perturb_func, perturb_func_kwargs, return_aggregate, aggregate_func, disable_warnings, display_progressbar, eps_min, default_plot_func, return_nan_when_prediction_changes)