class_docstr: Create Model Explainer
  
  Black-box models may have very different structures. This class creates a unified
  representation of a model, which can be further processed by various explanations.
  Methods of this class produce explanation objects, that contain the main result
  attribute, and can be visualised using the plot method.
  
  The `model` is the only required parameter, but most of the explanations require
  that other parameters are provided (See `data`, `y`, `predict_function`, `model_type`).
  
  Parameters
  ----------
  model : object
      Model to be explained.
  data : pd.DataFrame or np.ndarray (2d)
      Data which will be used to calculate the explanations. It shouldn't contain
      the target column (See `y`).
      NOTE: If target variable is present in the data, some of the functionalities may
      not work properly.
  y : pd.Series or pd.DataFrame or np.ndarray (1d)
      Target variable with outputs / scores. It shall have the same length as `data`.
  predict_function : function, optional
      Function that takes two parameters (model, data) and returns a np.ndarray (1d)
      with model predictions (default is predict method extracted from the model).
      NOTE: This function needs to work with `data` as pd.DataFrame.
  residual_function : function, optional
      Function that takes three parameters (model, data, y) and returns a np.ndarray (1d)
      with model residuals (default is a function constructed from `predict_function`).
  weights : pd.Series or np.ndarray (1d), optional
      Sampling weights for observations in `data`. It shall have the same length as
      `data` (default is `None`).
  label : str, optional
      Model name to appear in result and plots
      (default is last element of the class attribute extracted from the model).
  model_class : str, optional
      Class of the model that is used e.g. to choose the `predict_function`
      (default is the class attribute extracted from the model).
      NOTE: Use if your model is wrapped with Pipeline.
  verbose : bool
      Print diagnostic messages during the Explainer initialization (default is `True`).
  precalculate : bool
      Calculate y_hat (predicted values) and residuals during the Explainer
      initialization (default is `True`).
  model_type : {'regression', 'classification', None}
      Model task type that is used e.g. in `model_performance()` and `model_parts()`
      (default is try to extract the information from the model, else `None`).
  model_info: dict, optional
      Dict `{'model_package', 'model_package_version', ...}` containing additional
      information to be stored.
  
  Attributes
  --------
  model : object
      A model to be explained.
  data : pd.DataFrame
      Data which will be used to calculate the explanations.
  y : np.ndarray (1d)
      Target variable with outputs / scores.
  predict_function : function
      Function that takes two arguments (model, data) and returns np.ndarray (1d)
      with model predictions.
  y_hat : np.ndarray (1d)
      Model predictions for `data`.
  residual_function : function
      Function that takes three arguments (model, data, y) and returns np.ndarray (1d)
      with model residuals.
  residuals : np.ndarray (1d)
      Model residuals for `data`.
  weights : np.ndarray (1d)
      Sampling weights for observations in `data`.
  label : str
      Name to appear in result and plots.
  model_class : str
      Class of the model.
  model_type : {'regression', 'classification', `None`}
      Model task type.
  model_info: dict
      Dict `{'model_package', 'model_package_version', ...}` containing additional
      information.
  
  Notes
  --------
  - https://pbiecek.github.io/ema/dataSetsIntro.html#ExplainersTitanicPythonCode
class_docstr_tok: ["Create","Model","Explainer","Black-box","models","may","have","very","different","structures",".","This","class","creates","a","unified","representation","of","a","model",",","which","can","be","further","processed","by","various","explanations",".","Methods","of","this","class","produce","explanation","objects",",","that","contain","the","main","result","attribute",",","and","can","be","visualised","using","the","plot","method",".","The","`","model","`","is","the","only","required","parameter",",","but","most","of","the","explanations","require","that","other","parameters","are","provided","(","See","`","data","`",",","`","y","`",",","`","predict_function","`",",","`","model_type","`",")",".","Parameters","--","--","--","--","--","model",":","object","Model","to","be","explained",".","data",":","pd.DataFrame","or","np.ndarray","(","2d",")","Data","which","will","be","used","to","calculate","the","explanations",".","It","should","n't","contain","the","target","column","(","See","`","y","`",")",".","NOTE",":","If","target","variable","is","present","in","the","data",",","some","of","the","functionalities","may","not","work","properly",".","y",":","pd.Series","or","pd.DataFrame","or","np.ndarray","(","1d",")","Target","variable","with","outputs","\/","scores",".","It","shall","have","the","same","length","as","`","data","`",".","predict_function",":","function",",","optional","Function","that","takes","two","parameters","(","model",",","data",")","and","returns","a","np.ndarray","(","1d",")","with","model","predictions","(","default","is","predict","method","extracted","from","the","model",")",".","NOTE",":","This","function","needs","to","work","with","`","data","`","as","pd.DataFrame",".","residual_function",":","function",",","optional","Function","that","takes","three","parameters","(","model",",","data",",","y",")","and","returns","a","np.ndarray","(","1d",")","with","model","residuals","(","default","is","a","function","constructed","from","`","predict_function","`",")",".","weights",":","pd.Series","or","np.ndarray","(","1d",")",",","optional","Sampling","weights","for","observations","in","`","data","`",".","It","shall","have","the","same","length","as","`","data","`","(","default","is","`","None","`",")",".","label",":","str",",","optional","Model","name","to","appear","in","result","and","plots","(","default","is","last","element","of","the","class","attribute","extracted","from","the","model",")",".","model_class",":","str",",","optional","Class","of","the","model","that","is","used","e.g",".","to","choose","the","`","predict_function","`","(","default","is","the","class","attribute","extracted","from","the","model",")",".","NOTE",":","Use","if","your","model","is","wrapped","with","Pipeline",".","verbose",":","bool","Print","diagnostic","messages","during","the","Explainer","initialization","(","default","is","`","True","`",")",".","precalculate",":","bool","Calculate","y_hat","(","predicted","values",")","and","residuals","during","the","Explainer","initialization","(","default","is","`","True","`",")",".","model_type",":","{","'regression","'",",","'classification","'",",","None","}","Model","task","type","that","is","used","e.g",".","in","`","model_performance","(",")","`","and","`","model_parts","(",")","`","(","default","is","try","to","extract","the","information","from","the","model",",","else","`","None","`",")",".","model_info",":","dict",",","optional","Dict","`","{","'model_package","'",",","'model_package_version","'",",","...","}","`","containing","additional","information","to","be","stored",".","Attributes","--","--","--","--","model",":","object","A","model","to","be","explained",".","data",":","pd.DataFrame","Data","which","will","be","used","to","calculate","the","explanations",".","y",":","np.ndarray","(","1d",")","Target","variable","with","outputs","\/","scores",".","predict_function",":","function","Function","that","takes","two","arguments","(","model",",","data",")","and","returns","np.ndarray","(","1d",")","with","model","predictions",".","y_hat",":","np.ndarray","(","1d",")","Model","predictions","for","`","data","`",".","residual_function",":","function","Function","that","takes","three","arguments","(","model",",","data",",","y",")","and","returns","np.ndarray","(","1d",")","with","model","residuals",".","residuals",":","np.ndarray","(","1d",")","Model","residuals","for","`","data","`",".","weights",":","np.ndarray","(","1d",")","Sampling","weights","for","observations","in","`","data","`",".","label",":","str","Name","to","appear","in","result","and","plots",".","model_class",":","str","Class","of","the","model",".","model_type",":","{","'regression","'",",","'classification","'",",","`","None","`","}","Model","task","type",".","model_info",":","dict","Dict","`","{","'model_package","'",",","'model_package_version","'",",","...","}","`","containing","additional","information",".","Notes","--","--","--","--","-","https",":","\/\/pbiecek.github.io\/ema\/dataSetsIntro.html","#","ExplainersTitanicPythonCode"]
docstr: Creates a model-level fairness explanation that enables bias detection
  
  This method returns a GroupFairnessClassification or a GroupFairnessRegression
  object depending of the type of predictor. They work as a wrapper of the
  protected attribute and the Explainer from which `y` and `y_hat`
  attributes were extracted. Along with an information about
  privileged subgroup (value in the `protected` parameter), those 3 vectors
  create triplet `(y, y_hat, protected)` which is a base for all further
  fairness calculations and visualizations.
  
  The GroupFairnessRegression should be treated as experimental tool.
  It was implemented according to Fairness Measures for Regression via
  Probabilistic Classification - Steinberg et al. (2020).
  
  Parameters
  -----------
  protected : np.ndarray (1d)
      Vector, preferably 1-dimensional np.ndarray containing strings,
      which denotes the membership to a subgroup. It doesn't have to be binary.
      It doesn't need to be in data. It is sometimes suggested not to use
      sensitive attributes in modelling, but still check model bias for them.
      NOTE: List and pd.Series are also supported; however, if provided,
      they will be transformed into a np.ndarray (1d) with dtype 'U'.
  privileged : str
      Subgroup that is suspected to have the most privilege.
      It needs to be a string present in `protected`.
  cutoff : float or dict, optional
      Only for classification models.
      Threshold for probabilistic output of a classifier.
      It might be: a `float` - same for all subgroups from `protected`,
      or a `dict` - individually adjusted for each subgroup;
      must have values from `protected` as keys.
  epsilon : float
      Parameter defines acceptable fairness scores. The closer to `1` the
      more strict the verdict is. If the ratio of certain unprivileged
      and privileged subgroup is within the `(epsilon, 1/epsilon)` range,
      then there is no discrimination in this metric and for this subgroups
      (default is `0.8`).
  label : str, optional
      Name to appear in result and plots. Overrides default.
  kwargs : dict
      Keyword arguments. It supports `verbose`, which is a boolean
      value telling if additional output should be printed
      (`True`) or not (`False`, default).
  
  Returns
  -----------
  GroupFairnessClassification class object (a subclass of _FairnessObject)
      Explanation object containing the main result attribute and the plot method.
      
  It has the following main attributes:
      - result : `pd.DataFrame`
          Scaled `metric_scores`. The scaling is performed by
          dividing all metric scores by scores of the privileged subgroup.
      - metric_scores : `pd.DataFrame`
          Raw metric scores for each subgroup.
      - parity_loss : `pd.Series`
          It is a summarised `result`. From each metric (column) a logarithm
          is calculated, then the absolute value is taken and summarised.
          Therefore, for metric M:
              `parity_loss` is a `sum(abs(log(M_i / M_privileged)))`
                  where `M_i` is the metric score for subgroup `i`.
      - label : `str`
          `label` attribute from the Explainer object.
              Labels must be unique when plotting.
      - cutoff : `dict`
          A float value for each subgroup (key in dict).
  
  Notes
  -----------
  - Verma, S. & Rubin, J. (2018) https://fairware.cs.umass.edu/papers/Verma.pdf
  - Zafar, M.B., et al. (2017) https://arxiv.org/pdf/1610.08452.pdf
  - Hardt, M., et al. (2016) https://arxiv.org/pdf/1610.02413.pdf
  - Steinberg, D., et al. (2020) https://arxiv.org/pdf/2001.06089.pdf
docstr_tok: ["Creates","a","model-level","fairness","explanation","that","enables","bias","detection","This","method","returns","a","GroupFairnessClassification","or","a","GroupFairnessRegression","object","depending","of","the","type","of","predictor",".","They","work","as","a","wrapper","of","the","protected","attribute","and","the","Explainer","from","which","`","y","`","and","`","y_hat","`","attributes","were","extracted",".","Along","with","an","information","about","privileged","subgroup","(","value","in","the","`","protected","`","parameter",")",",","those","3","vectors","create","triplet","`","(","y",",","y_hat",",","protected",")","`","which","is","a","base","for","all","further","fairness","calculations","and","visualizations",".","The","GroupFairnessRegression","should","be","treated","as","experimental","tool",".","It","was","implemented","according","to","Fairness","Measures","for","Regression","via","Probabilistic","Classification","-","Steinberg","et","al",".","(","2020",")",".","Parameters","--","--","--","--","--","-","protected",":","np.ndarray","(","1d",")","Vector",",","preferably","1-dimensional","np.ndarray","containing","strings",",","which","denotes","the","membership","to","a","subgroup",".","It","does","n't","have","to","be","binary",".","It","does","n't","need","to","be","in","data",".","It","is","sometimes","suggested","not","to","use","sensitive","attributes","in","modelling",",","but","still","check","model","bias","for","them",".","NOTE",":","List","and","pd.Series","are","also","supported",";","however",",","if","provided",",","they","will","be","transformed","into","a","np.ndarray","(","1d",")","with","dtype","'","U","'",".","privileged",":","str","Subgroup","that","is","suspected","to","have","the","most","privilege",".","It","needs","to","be","a","string","present","in","`","protected","`",".","cutoff",":","float","or","dict",",","optional","Only","for","classification","models",".","Threshold","for","probabilistic","output","of","a","classifier",".","It","might","be",":","a","`","float","`","-","same","for","all","subgroups","from","`","protected","`",",","or","a","`","dict","`","-","individually","adjusted","for","each","subgroup",";","must","have","values","from","`","protected","`","as","keys",".","epsilon",":","float","Parameter","defines","acceptable","fairness","scores",".","The","closer","to","`","1","`","the","more","strict","the","verdict","is",".","If","the","ratio","of","certain","unprivileged","and","privileged","subgroup","is","within","the","`","(","epsilon",",","1\/epsilon",")","`","range",",","then","there","is","no","discrimination","in","this","metric","and","for","this","subgroups","(","default","is","`","0.8","`",")",".","label",":","str",",","optional","Name","to","appear","in","result","and","plots",".","Overrides","default",".","kwargs",":","dict","Keyword","arguments",".","It","supports","`","verbose","`",",","which","is","a","boolean","value","telling","if","additional","output","should","be","printed","(","`","True","`",")","or","not","(","`","False","`",",","default",")",".","Returns","--","--","--","--","--","-","GroupFairnessClassification","class","object","(","a","subclass","of","_FairnessObject",")","Explanation","object","containing","the","main","result","attribute","and","the","plot","method",".","It","has","the","following","main","attributes",":","-","result",":","`","pd.DataFrame","`","Scaled","`","metric_scores","`",".","The","scaling","is","performed","by","dividing","all","metric","scores","by","scores","of","the","privileged","subgroup",".","-","metric_scores",":","`","pd.DataFrame","`","Raw","metric","scores","for","each","subgroup",".","-","parity_loss",":","`","pd.Series","`","It","is","a","summarised","`","result","`",".","From","each","metric","(","column",")","a","logarithm","is","calculated",",","then","the","absolute","value","is","taken","and","summarised",".","Therefore",",","for","metric","M",":","`","parity_loss","`","is","a","`","sum","(","abs","(","log","(","M_i","\/","M_privileged",")",")",")","`","where","`","M_i","`","is","the","metric","score","for","subgroup","`","i","`",".","-","label",":","`","str","`","`","label","`","attribute","from","the","Explainer","object",".","Labels","must","be","unique","when","plotting",".","-","cutoff",":","`","dict","`","A","float","value","for","each","subgroup","(","key","in","dict",")",".","Notes","--","--","--","--","--","-","-","Verma",",","S.","&","Rubin",",","J",".","(","2018",")","https",":","\/\/fairware.cs.umass.edu\/papers\/Verma.pdf","-","Zafar",",","M.B.",",","et","al",".","(","2017",")","https",":","\/\/arxiv.org\/pdf\/1610.08452.pdf","-","Hardt",",","M.",",","et","al",".","(","2016",")","https",":","\/\/arxiv.org\/pdf\/1610.02413.pdf","-","Steinberg",",","D.",",","et","al",".","(","2020",")","https",":","\/\/arxiv.org\/pdf\/2001.06089.pdf"]
code: def model_fairness(
      self,
      protected,
      privileged,
      cutoff=0.5,
      epsilon=0.8,
      label=None,
      **kwargs,
  ):
      """Creates a model-level fairness explanation that enables bias detection
  
      This method returns a GroupFairnessClassification or a GroupFairnessRegression
      object depending of the type of predictor. They work as a wrapper of the
      protected attribute and the Explainer from which `y` and `y_hat`
      attributes were extracted. Along with an information about
      privileged subgroup (value in the `protected` parameter), those 3 vectors
      create triplet `(y, y_hat, protected)` which is a base for all further
      fairness calculations and visualizations.
  
      The GroupFairnessRegression should be treated as experimental tool.
      It was implemented according to Fairness Measures for Regression via
      Probabilistic Classification - Steinberg et al. (2020).
  
      Parameters
      -----------
      protected : np.ndarray (1d)
          Vector, preferably 1-dimensional np.ndarray containing strings,
          which denotes the membership to a subgroup. It doesn't have to be binary.
          It doesn't need to be in data. It is sometimes suggested not to use
          sensitive attributes in modelling, but still check model bias for them.
          NOTE: List and pd.Series are also supported; however, if provided,
          they will be transformed into a np.ndarray (1d) with dtype 'U'.
      privileged : str
          Subgroup that is suspected to have the most privilege.
          It needs to be a string present in `protected`.
      cutoff : float or dict, optional
          Only for classification models.
          Threshold for probabilistic output of a classifier.
          It might be: a `float` - same for all subgroups from `protected`,
          or a `dict` - individually adjusted for each subgroup;
          must have values from `protected` as keys.
      epsilon : float
          Parameter defines acceptable fairness scores. The closer to `1` the
          more strict the verdict is. If the ratio of certain unprivileged
          and privileged subgroup is within the `(epsilon, 1/epsilon)` range,
          then there is no discrimination in this metric and for this subgroups
          (default is `0.8`).
      label : str, optional
          Name to appear in result and plots. Overrides default.
      kwargs : dict
          Keyword arguments. It supports `verbose`, which is a boolean
          value telling if additional output should be printed
          (`True`) or not (`False`, default).
  
      Returns
      -----------
      GroupFairnessClassification class object (a subclass of _FairnessObject)
          Explanation object containing the main result attribute and the plot method.
  
      It has the following main attributes:
          - result : `pd.DataFrame`
              Scaled `metric_scores`. The scaling is performed by
              dividing all metric scores by scores of the privileged subgroup.
          - metric_scores : `pd.DataFrame`
              Raw metric scores for each subgroup.
          - parity_loss : `pd.Series`
              It is a summarised `result`. From each metric (column) a logarithm
              is calculated, then the absolute value is taken and summarised.
              Therefore, for metric M:
                  `parity_loss` is a `sum(abs(log(M_i / M_privileged)))`
                      where `M_i` is the metric score for subgroup `i`.
          - label : `str`
              `label` attribute from the Explainer object.
                  Labels must be unique when plotting.
          - cutoff : `dict`
              A float value for each subgroup (key in dict).
  
      Notes
      -----------
      - Verma, S. & Rubin, J. (2018) https://fairware.cs.umass.edu/papers/Verma.pdf
      - Zafar, M.B., et al. (2017) https://arxiv.org/pdf/1610.08452.pdf
      - Hardt, M., et al. (2016) https://arxiv.org/pdf/1610.02413.pdf
      - Steinberg, D., et al. (2020) https://arxiv.org/pdf/2001.06089.pdf
      """
  
      if self.model_type == "classification":
          fobject = GroupFairnessClassification(
              y=self.y,
              y_hat=self.y_hat,
              protected=protected,
              privileged=privileged,
              cutoff=cutoff,
              epsilon=epsilon,
              label=self.label,
              **kwargs,
          )
  
      elif self.model_type == "regression":
          fobject = GroupFairnessRegression(
              y=self.y,
              y_hat=self.y_hat,
              protected=protected,
              privileged=privileged,
              epsilon=epsilon,
              label=self.label,
              **kwargs,
          )
  
      else:
          raise ValueError(
              "'model_type' must be either 'classification' or 'regression'"
          )
  
      if label:
          fobject.label = label
  
      return fobject
  
imports: import numpy
  from dalex.model_explanations import ModelPerformance, VariableImportance, AggregatedProfiles, ResidualDiagnostics
  from dalex.predict_explanations import BreakDown, Shap, CeterisParibus
  from dalex.wrappers import ShapWrapper
  from dalex.fairness import GroupFairnessClassification, GroupFairnessRegression
  from .None import checks
  from .None import utils
  from .None import helper
  from ..None import _global_checks
label_desc: Use image node_id 12 for calling the Explainer obj's underlying member method code with example usage: obj.model_fairness(protected, privileged, cutoff, epsilon, label) and returns: fobject