class_docstr: Interface defining Metrics' API.
docstr: Implement this method if you need custom preprocessing of data,
  model alteration or simply for creating/initialising additional
  attributes or assertions.
  
  If this method returns a dictionary, the keys (string) will be used as
  additional arguments for evaluate_instance().
  If the key ends with `_batch`, this suffix will be removed from the
  respective argument name when passed to evaluate_instance().
  If they key corresponds to the arguments `x_batch, y_batch, a_batch, s_batch`,
  these will be overwritten for passing `x, y, a, s` to `evaluate_instance()`.
  If this method returns None, no additional keyword arguments will be
  passed to `evaluate_instance()`.
  
  Parameters
  ----------
  model: torch.nn.Module, tf.keras.Model
      A torch or tensorflow model e.g., torchvision.models 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.
  custom_batch: any
      Gives flexibility to the inheriting metric to use for evaluation, can hold any variable.
  kwargs:
      Optional, metric-specific parameters.
  
  
  Returns
  -------
  dict, optional
      A dictionary which holds (optionally additional) preprocessed data to
     be included when calling `evaluate_instance()`.
  
  
  Examples
  --------
      # Custom Metric definition with additional keyword argument used in evaluate_instance():
      >>> def custom_preprocess(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x_batch: np.ndarray,
      >>>     y_batch: Optional[np.ndarray],
      >>>     a_batch: Optional[np.ndarray],
      >>>     s_batch: np.ndarray,
      >>>     custom_batch: Optional[np.ndarray],
      >>> ) -> Dict[str, Any]:
      >>>     return {'my_new_variable': np.mean(x_batch)}
      >>>
      >>> def evaluate_instance(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x: np.ndarray,
      >>>     y: Optional[np.ndarray],
      >>>     a: Optional[np.ndarray],
      >>>     s: np.ndarray,
      >>>     my_new_variable: np.float,
      >>> ) -> float:
  
      # Custom Metric definition with additional keyword argument that ends with `_batch`
      >>> def custom_preprocess(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x_batch: np.ndarray,
      >>>     y_batch: Optional[np.ndarray],
      >>>     a_batch: Optional[np.ndarray],
      >>>     s_batch: np.ndarray,
      >>>     custom_batch: Optional[np.ndarray],
      >>> ) -> Dict[str, Any]:
      >>>     return {'my_new_variable_batch': np.arange(len(x_batch))}
      >>>
      >>> def evaluate_instance(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x: np.ndarray,
      >>>     y: Optional[np.ndarray],
      >>>     a: Optional[np.ndarray],
      >>>     s: np.ndarray,
      >>>     my_new_variable: np.int,
      >>> ) -> float:
  
      # Custom Metric definition with transformation of an existing
      # keyword argument from `evaluate_instance()`
      >>> def custom_preprocess(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x_batch: np.ndarray,
      >>>     y_batch: Optional[np.ndarray],
      >>>     a_batch: Optional[np.ndarray],
      >>>     s_batch: np.ndarray,
      >>>     custom_batch: Optional[np.ndarray],
      >>> ) -> Dict[str, Any]:
      >>>     return {'x_batch': x_batch - np.mean(x_batch, axis=0)}
      >>>
      >>> def evaluate_instance(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x: np.ndarray,
      >>>     y: Optional[np.ndarray],
      >>>     a: Optional[np.ndarray],
      >>>     s: np.ndarray,
      >>> ) -> float:
  
      # Custom Metric definition with None returned in custom_preprocess(),
      # but with inplace-preprocessing and additional assertion.
      >>> def custom_preprocess(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x_batch: np.ndarray,
      >>>     y_batch: Optional[np.ndarray],
      >>>     a_batch: Optional[np.ndarray],
      >>>     s_batch: np.ndarray,
      >>>     custom_batch: Optional[np.ndarray],
      >>> ) -> None:
      >>>     if np.any(np.all(a_batch < 0, axis=0)):
      >>>         raise ValueError("Attributions must not be all negative")
      >>>
      >>>     x_batch -= np.mean(x_batch, axis=0)
      >>>
      >>>     return None
      >>>
      >>> def evaluate_instance(
      >>>     self,
      >>>     model: ModelInterface,
      >>>     x: np.ndarray,
      >>>     y: Optional[np.ndarray],
      >>>     a: Optional[np.ndarray],
      >>>     s: np.ndarray,
      >>> ) -> float:
docstr_tok: ["Implement","this","method","if","you","need","custom","preprocessing","of","data",",","model","alteration","or","simply","for","creating\/initialising","additional","attributes","or","assertions",".","If","this","method","returns","a","dictionary",",","the","keys","(","string",")","will","be","used","as","additional","arguments","for","evaluate_instance","(",")",".","If","the","key","ends","with","`","_batch","`",",","this","suffix","will","be","removed","from","the","respective","argument","name","when","passed","to","evaluate_instance","(",")",".","If","they","key","corresponds","to","the","arguments","`","x_batch",",","y_batch",",","a_batch",",","s_batch","`",",","these","will","be","overwritten","for","passing","`","x",",","y",",","a",",","s","`","to","`","evaluate_instance","(",")","`",".","If","this","method","returns","None",",","no","additional","keyword","arguments","will","be","passed","to","`","evaluate_instance","(",")","`",".","Parameters","--","--","--","--","--","model",":","torch.nn.Module",",","tf.keras.Model","A","torch","or","tensorflow","model","e.g.",",","torchvision.models","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",".","custom_batch",":","any","Gives","flexibility","to","the","inheriting","metric","to","use","for","evaluation",",","can","hold","any","variable",".","kwargs",":","Optional",",","metric-specific","parameters",".","Returns","--","--","--","-","dict",",","optional","A","dictionary","which","holds","(","optionally","additional",")","preprocessed","data","to","be","included","when","calling","`","evaluate_instance","(",")","`",".","Examples","--","--","--","--","#","Custom","Metric","definition","with","additional","keyword","argument","used","in","evaluate_instance","(",")",":",">",">",">","def","custom_preprocess","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x_batch",":","np.ndarray",",",">",">",">","y_batch",":","Optional","[","np.ndarray","]",",",">",">",">","a_batch",":","Optional","[","np.ndarray","]",",",">",">",">","s_batch",":","np.ndarray",",",">",">",">","custom_batch",":","Optional","[","np.ndarray","]",",",">",">",">",")","-",">","Dict","[","str",",","Any","]",":",">",">",">","return","{","'my_new_variable","'",":","np.mean","(","x_batch",")","}",">",">",">",">",">",">","def","evaluate_instance","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x",":","np.ndarray",",",">",">",">","y",":","Optional","[","np.ndarray","]",",",">",">",">","a",":","Optional","[","np.ndarray","]",",",">",">",">","s",":","np.ndarray",",",">",">",">","my_new_variable",":","np.float",",",">",">",">",")","-",">","float",":","#","Custom","Metric","definition","with","additional","keyword","argument","that","ends","with","`","_batch","`",">",">",">","def","custom_preprocess","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x_batch",":","np.ndarray",",",">",">",">","y_batch",":","Optional","[","np.ndarray","]",",",">",">",">","a_batch",":","Optional","[","np.ndarray","]",",",">",">",">","s_batch",":","np.ndarray",",",">",">",">","custom_batch",":","Optional","[","np.ndarray","]",",",">",">",">",")","-",">","Dict","[","str",",","Any","]",":",">",">",">","return","{","'my_new_variable_batch","'",":","np.arange","(","len","(","x_batch",")",")","}",">",">",">",">",">",">","def","evaluate_instance","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x",":","np.ndarray",",",">",">",">","y",":","Optional","[","np.ndarray","]",",",">",">",">","a",":","Optional","[","np.ndarray","]",",",">",">",">","s",":","np.ndarray",",",">",">",">","my_new_variable",":","np.int",",",">",">",">",")","-",">","float",":","#","Custom","Metric","definition","with","transformation","of","an","existing","#","keyword","argument","from","`","evaluate_instance","(",")","`",">",">",">","def","custom_preprocess","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x_batch",":","np.ndarray",",",">",">",">","y_batch",":","Optional","[","np.ndarray","]",",",">",">",">","a_batch",":","Optional","[","np.ndarray","]",",",">",">",">","s_batch",":","np.ndarray",",",">",">",">","custom_batch",":","Optional","[","np.ndarray","]",",",">",">",">",")","-",">","Dict","[","str",",","Any","]",":",">",">",">","return","{","'x_batch","'",":","x_batch","-","np.mean","(","x_batch",",","axis=0",")","}",">",">",">",">",">",">","def","evaluate_instance","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x",":","np.ndarray",",",">",">",">","y",":","Optional","[","np.ndarray","]",",",">",">",">","a",":","Optional","[","np.ndarray","]",",",">",">",">","s",":","np.ndarray",",",">",">",">",")","-",">","float",":","#","Custom","Metric","definition","with","None","returned","in","custom_preprocess","(",")",",","#","but","with","inplace-preprocessing","and","additional","assertion",".",">",">",">","def","custom_preprocess","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x_batch",":","np.ndarray",",",">",">",">","y_batch",":","Optional","[","np.ndarray","]",",",">",">",">","a_batch",":","Optional","[","np.ndarray","]",",",">",">",">","s_batch",":","np.ndarray",",",">",">",">","custom_batch",":","Optional","[","np.ndarray","]",",",">",">",">",")","-",">","None",":",">",">",">","if","np.any","(","np.all","(","a_batch","<","0",",","axis=0",")",")",":",">",">",">","raise","ValueError","(","``","Attributions","must","not","be","all","negative","''",")",">",">",">",">",">",">","x_batch","-=","np.mean","(","x_batch",",","axis=0",")",">",">",">",">",">",">","return","None",">",">",">",">",">",">","def","evaluate_instance","(",">",">",">","self",",",">",">",">","model",":","ModelInterface",",",">",">",">","x",":","np.ndarray",",",">",">",">","y",":","Optional","[","np.ndarray","]",",",">",">",">","a",":","Optional","[","np.ndarray","]",",",">",">",">","s",":","np.ndarray",",",">",">",">",")","-",">","float",":"]
code: def custom_preprocess(
      self,
      *,
      model: ModelInterface,
      x_batch: np.ndarray,
      y_batch: np.ndarray,
      a_batch: Optional[np.ndarray],
      s_batch: Optional[np.ndarray],
      custom_batch: Any,
      **kwargs,
  ) -> Optional[Dict[str, Any]]:
      """
      Implement this method if you need custom preprocessing of data,
      model alteration or simply for creating/initialising additional
      attributes or assertions.
  
      If this method returns a dictionary, the keys (string) will be used as
      additional arguments for evaluate_instance().
      If the key ends with `_batch`, this suffix will be removed from the
      respective argument name when passed to evaluate_instance().
      If they key corresponds to the arguments `x_batch, y_batch, a_batch, s_batch`,
      these will be overwritten for passing `x, y, a, s` to `evaluate_instance()`.
      If this method returns None, no additional keyword arguments will be
      passed to `evaluate_instance()`.
  
      Parameters
      ----------
      model: torch.nn.Module, tf.keras.Model
          A torch or tensorflow model e.g., torchvision.models 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.
      custom_batch: any
          Gives flexibility to the inheriting metric to use for evaluation, can hold any variable.
      kwargs:
          Optional, metric-specific parameters.
  
  
      Returns
      -------
      dict, optional
          A dictionary which holds (optionally additional) preprocessed data to
         be included when calling `evaluate_instance()`.
  
  
      Examples
      --------
          # Custom Metric definition with additional keyword argument used in evaluate_instance():
          >>> def custom_preprocess(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x_batch: np.ndarray,
          >>>     y_batch: Optional[np.ndarray],
          >>>     a_batch: Optional[np.ndarray],
          >>>     s_batch: np.ndarray,
          >>>     custom_batch: Optional[np.ndarray],
          >>> ) -> Dict[str, Any]:
          >>>     return {'my_new_variable': np.mean(x_batch)}
          >>>
          >>> def evaluate_instance(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x: np.ndarray,
          >>>     y: Optional[np.ndarray],
          >>>     a: Optional[np.ndarray],
          >>>     s: np.ndarray,
          >>>     my_new_variable: np.float,
          >>> ) -> float:
  
          # Custom Metric definition with additional keyword argument that ends with `_batch`
          >>> def custom_preprocess(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x_batch: np.ndarray,
          >>>     y_batch: Optional[np.ndarray],
          >>>     a_batch: Optional[np.ndarray],
          >>>     s_batch: np.ndarray,
          >>>     custom_batch: Optional[np.ndarray],
          >>> ) -> Dict[str, Any]:
          >>>     return {'my_new_variable_batch': np.arange(len(x_batch))}
          >>>
          >>> def evaluate_instance(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x: np.ndarray,
          >>>     y: Optional[np.ndarray],
          >>>     a: Optional[np.ndarray],
          >>>     s: np.ndarray,
          >>>     my_new_variable: np.int,
          >>> ) -> float:
  
          # Custom Metric definition with transformation of an existing
          # keyword argument from `evaluate_instance()`
          >>> def custom_preprocess(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x_batch: np.ndarray,
          >>>     y_batch: Optional[np.ndarray],
          >>>     a_batch: Optional[np.ndarray],
          >>>     s_batch: np.ndarray,
          >>>     custom_batch: Optional[np.ndarray],
          >>> ) -> Dict[str, Any]:
          >>>     return {'x_batch': x_batch - np.mean(x_batch, axis=0)}
          >>>
          >>> def evaluate_instance(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x: np.ndarray,
          >>>     y: Optional[np.ndarray],
          >>>     a: Optional[np.ndarray],
          >>>     s: np.ndarray,
          >>> ) -> float:
  
          # Custom Metric definition with None returned in custom_preprocess(),
          # but with inplace-preprocessing and additional assertion.
          >>> def custom_preprocess(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x_batch: np.ndarray,
          >>>     y_batch: Optional[np.ndarray],
          >>>     a_batch: Optional[np.ndarray],
          >>>     s_batch: np.ndarray,
          >>>     custom_batch: Optional[np.ndarray],
          >>> ) -> None:
          >>>     if np.any(np.all(a_batch < 0, axis=0)):
          >>>         raise ValueError("Attributions must not be all negative")
          >>>
          >>>     x_batch -= np.mean(x_batch, axis=0)
          >>>
          >>>     return None
          >>>
          >>> def evaluate_instance(
          >>>     self,
          >>>     model: ModelInterface,
          >>>     x: np.ndarray,
          >>>     y: Optional[np.ndarray],
          >>>     a: Optional[np.ndarray],
          >>>     s: np.ndarray,
          >>> ) -> float:
  
      """
      pass
  
imports: from __future__ import annotations
  import functools
  import logging
  import os
  import sys
  from abc import abstractmethod
  from typing import Any, Callable, ClassVar, Dict, Generator, Generic, Sequence, Set, TypeVar, Optional, Union, TYPE_CHECKING, no_type_check
  import matplotlib.pyplot
  import numpy
  from sklearn.utils import gen_batches
  from tqdm.auto import tqdm
  from quantus.helpers import asserts, utils, warn
  from quantus.functions.normalise_func import normalise_by_max
  from quantus.helpers.enums import DataType, EvaluationCategory, ModelType, ScoreDirection
  from quantus.helpers.model.model_interface import ModelInterface
label_desc: Use image node_id 5 for calling the Metric obj's underlying member method code with example usage: obj.custom_preprocess() without return types