shaprpy 0.3.0__py3-none-any.whl

shaprpy/__init__.py

@@ -0,0 +1,51 @@
+from importlib.metadata import version, PackageNotFoundError
+from importlib import import_module
+
+# Lightweight public re-export (no R dependency)
+from . import datasets  # noqa: F401
+
+__all__ = ["explain", "datasets", "ensure_r_ready"]
+
+try:
+    __version__ = version("shaprpy")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+_r_ready = False
+_explain_impl = None
+
+
+def ensure_r_ready() -> bool:
+    """Ensure rpy2 and the R package 'shapr' are available, then bind the real explain() (idempotent)."""
+    global _r_ready, _explain_impl
+    if _r_ready:
+        return True
+
+    try:
+        import rpy2.robjects as _ro  # noqa: F401
+        from rpy2.robjects.packages import importr
+    except Exception as e:
+        raise ImportError(
+            "shaprpy requires rpy2 and a working R installation.\n"
+            "Install R and rpy2, and ensure R is on PATH/R_HOME. See README."
+        ) from e
+
+    try:
+        importr("shapr")
+    except Exception as e:
+        raise ImportError(
+            "The R package 'shapr' is not installed or not found.\n"
+            "In an R session, run: install.packages('shapr')"
+        ) from e
+
+    # Import the implementation from a private module to avoid name collision
+    _explain_mod = import_module(__name__ + "._explain")
+    _explain_impl = _explain_mod.explain
+    _r_ready = True
+    return True
+
+
+def explain(*args, **kwargs):
+    """Lazily initialize R/shapr then call the real explain()."""
+    ensure_r_ready()
+    return _explain_impl(*args, **kwargs)

shaprpy/_explain.py

@@ -0,0 +1,630 @@
+import warnings
+import numpy as np
+import pandas as pd
+from typing import Callable
+from datetime import datetime
+import rpy2.robjects as ro
+from rpy2.robjects.packages import importr
+from rpy2.rinterface import NULL, NA
+from shaprpy.utils import r2py, py2r, recurse_r_tree
+from rpy2.robjects.vectors import StrVector, ListVector
+
+data_table = importr('data.table')
+shapr = importr('shapr')
+utils = importr('utils')
+base = importr('base')
+stats = importr('stats')
+
+def maybe_null(val):
+  return val if val is not None else NULL
+
+def explain(
+    model,
+    x_explain: pd.DataFrame,
+    x_train: pd.DataFrame,
+    approach: str | list[str],
+    phi0: float,
+    iterative: bool | None = None,
+    max_n_coalitions: int | None = None,
+    group: dict | None = None,
+    n_MC_samples: int = 1000,
+    seed: int | None = None,
+    verbose: str | list[str] | None = "basic",
+    predict_model: Callable | None = None,
+    get_model_specs: Callable | None = None,
+    asymmetric: bool = False,
+    causal_ordering: dict | None = None,
+    confounding: bool | None = None,
+    extra_computation_args: dict | None = None,
+    iterative_args: dict | None = None,
+    output_args: dict | None = None,
+    **kwargs,
+  ):
+    """
+    Explain the output of machine learning models with more accurately estimated Shapley values.
+
+    Computes dependence-aware Shapley values for observations in `x_explain` from the specified
+    `model` by using the method specified in `approach` to estimate the conditional expectation.
+
+    Parameters
+    ----------
+    model: The model whose predictions we want to explain.
+      `shaprpy` natively supports `sklearn`, `xgboost` and `keras` models.
+      Unsupported models can still be explained by passing `predict_model` and (optionally) `get_model_specs`.
+    x_explain: pd.DataFrame
+      Contains the features whose predictions ought to be explained.
+    x_train: pd.DataFrame
+      Contains the data used to estimate the (conditional) distributions for the features
+      needed to properly estimate the conditional expectations in the Shapley formula.
+    approach: str or list[str]
+      The method(s) to estimate the conditional expectation. All elements should,
+      either be `"gaussian"`, `"copula"`, `"empirical"`, `"ctree"`, `"categorical"`, `"timeseries"`, `"independence"`,
+      `"regression_separate"`, or `"regression_surrogate"`.
+    phi0: float
+      The prediction value for unseen data, i.e. an estimate of the expected prediction without conditioning on any
+      features. Typically we set this value equal to the mean of the response variable in our training data, but other
+      choices such as the mean of the predictions in the training data are also reasonable.
+    iterative: bool or None, optional
+      If `None` (default), the argument is set to `True` if there are more than 5 features/groups, and `False` otherwise.
+      If `True`, the Shapley values are estimated iteratively in an iterative manner.
+    max_n_coalitions: int or None, optional
+      The upper limit on the number of unique feature/group coalitions to use in the iterative procedure
+      (if `iterative = True`). If `iterative = False` it represents the number of feature/group coalitions to use directly.
+      `max_n_coalitions = None` corresponds to `max_n_coalitions=2^n_features`.
+    group: dict or None, optional
+      If `None` regular feature wise Shapley values are computed.
+      If provided, group wise Shapley values are computed. `group` then contains lists of unique feature names with the
+      features included in each of the different groups.
+    n_MC_samples: int, optional
+      Indicating the maximum number of samples to use in the Monte Carlo integration for every conditional expectation.
+    seed: int or None, optional
+      Specifies the seed before any randomness based code is being run.
+      If `None` (default) the seed will be inherited from the calling environment.
+    verbose: str or list[str] or None, optional
+      Specifies the verbosity (printout detail level) through one or more of the strings `"basic"`, `"progress"`,
+      `"convergence"`, `"shapley"`  and `"vS_details"`. `None` means no printout.
+    predict_model: Callable, optional
+      The prediction function used when `model` is not natively supported. The function must have two arguments, `model` and `newdata`
+      which specify, respectively, the model and a pandas.DataFrame to compute predictions for. The function must give the prediction as a numpy.Array.
+    get_model_specs: Callable, optional
+      An optional function for checking model/data consistency when `model` is not natively supported. The function takes `model` as argument
+      and provides a `dict` with 3 elements: `labels`, `classes`, and `factor_levels`.
+    asymmetric: bool, optional
+      If `False` (default), `explain` computes regular symmetric Shapley values. If `True`, then `explain` computes asymmetric Shapley values
+      based on the (partial) causal ordering given by `causal_ordering`.
+    causal_ordering: dict or None, optional
+      An unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect.
+    confounding: bool or None, optional
+      A vector of logicals specifying whether confounding is assumed or not for each component in the `causal_ordering`.
+    extra_computation_args: dict or None, optional
+      Specifies extra arguments related to the computation of the Shapley values.
+    iterative_args: dict or None, optional
+      Specifies the arguments for the iterative procedure.
+    output_args: dict or None, optional
+      Specifies certain arguments related to the output of the function.
+    **kwargs: Further arguments passed to specific approaches.
+
+    Returns
+    -------
+    dict
+      A dictionary containing the following items:
+      - "shapley_values_est": pd.DataFrame with the estimated Shapley values.
+      - "shapley_values_sd": pd.DataFrame with the standard deviation of the Shapley values.
+      - "pred_explain": numpy.Array with the predictions for the explained observations.
+      - "MSEv": dict with the values of the MSEv evaluation criterion.
+      - "iterative_results": dict with the results of the iterative estimation.
+      - "saving_path": str with the path where intermediate results are stored.
+      - "internal": dict with the different parameters, data, functions and other output used internally.
+      - "timing": dict containing timing information for the different parts of the computation.
+    """
+
+    init_time = base.Sys_time() # datetime.now()
+
+
+    if seed is not None:
+      base.set_seed(seed)
+
+    # Gets and check feature specs from the model
+    rfeature_specs = get_feature_specs(get_model_specs, model)
+
+    # Fixes the conversion from dict to a named list of vectors in R
+    r_group = NULL if group is None else ListVector({key: StrVector(value) for key, value in group.items()})
+
+    # Fixes the conversion from dict to a named list of vectors in R
+    r_causal_ordering = NULL if causal_ordering is None else ListVector({key: StrVector(value) for key, value in causal_ordering.items()})
+
+
+    # Fixes method specific argument names by replacing first occurrence of "_" with "."
+    if len(kwargs) > 0:
+      kwargs = change_first_underscore_to_dot(kwargs)
+
+      # Convert from dict to a named list of vectors in R if `regression.vfold_cv_para` is provided by the user
+      if 'regression.vfold_cv_para' in kwargs:
+        kwargs['regression.vfold_cv_para'] = ListVector(kwargs['regression.vfold_cv_para'])
+
+    # Convert from None or dict to a named list in R
+    if iterative_args is None:
+      iterative_args = ro.ListVector({})
+    else:
+      iterative_args = ListVector(iterative_args)
+
+    if output_args is None:
+      output_args = ro.ListVector({})
+    else:
+      output_args = ListVector(output_args)
+
+    if extra_computation_args is None:
+      extra_computation_args = ro.ListVector({})
+    else:
+      extra_computation_args = ListVector(extra_computation_args)
+
+    model_class = f"{type(model).__module__}.{type(model).__name__}"
+
+    # Sets up and organizes input parameters
+    # Checks the input parameters and their compatability
+    # Checks data/model compatability
+
+    if isinstance(approach, str):
+      approach = [approach]
+
+    if isinstance(verbose, str):
+      verbose = [verbose]
+    if isinstance(verbose, list):
+      verbose = StrVector(verbose)
+    else:
+      verbose = maybe_null(verbose)
+
+
+    rinternal = shapr.setup(
+      x_train = py2r(x_train),
+      x_explain = py2r(x_explain),
+      approach = StrVector(approach),
+      phi0 = phi0,
+      max_n_coalitions = maybe_null(max_n_coalitions),
+      group = r_group,
+      n_MC_samples = n_MC_samples,
+      seed = maybe_null(seed),
+      feature_specs = rfeature_specs,
+      verbose = verbose,
+      iterative = maybe_null(iterative),
+      iterative_args = iterative_args,
+      asymmetric = asymmetric,
+      causal_ordering = r_causal_ordering,
+      confounding = maybe_null(confounding),
+      output_args = output_args,
+      extra_computation_args = extra_computation_args,
+      init_time = init_time,
+      is_python = True,
+      model_class = model_class,
+      **kwargs
+    )
+
+    # Gets predict_model (if not passed to explain) and checks that predict_model gives correct format
+    predict_model = get_predict_model(x_test=x_train.head(2), predict_model=predict_model, model=model)
+
+    rinternal.rx2['timing_list'].rx2['test_prediction'] = base.Sys_time()
+
+    rinternal = additional_regression_setup(
+      rinternal,
+      model,
+      predict_model,
+      x_train,
+      x_explain)
+
+    # Not called for approach %in% c("regression_surrogate","vaeac")
+    rinternal = shapr.setup_approach(internal = rinternal) # model and predict_model are not supported in Python
+
+    rinternal.rx2['main_timing_list'] = rinternal.rx2['timing_list']
+
+    converged = False
+    iter = len(rinternal.rx2('iter_list'))
+
+    if seed is not None:
+      base.set_seed(seed)
+
+    shapr.cli_startup(rinternal, verbose)
+
+    rinternal.rx2['iter_timing_list'] = ro.ListVector({})
+
+    while not converged:
+      shapr.cli_iter(verbose, rinternal, iter)
+
+      rinternal.rx2['timing_list'] = ro.ListVector({'init': base.Sys_time()})
+
+      # Setup the Shapley framework
+      rinternal = shapr.shapley_setup(rinternal)
+
+      # Only actually called for approach in ["regression_surrogate", "vaeac"]
+      rinternal = shapr.setup_approach(rinternal)
+
+      # Compute the vS
+      vS_list = compute_vS(rinternal, model, predict_model)
+
+      # Compute Shapley value estimates and bootstrapped standard deviations
+      rinternal = shapr.compute_estimates(rinternal, vS_list)
+
+      # Check convergence based on estimates and standard deviations (and thresholds)
+      rinternal = shapr.check_convergence(rinternal)
+
+      # Save intermediate results
+      shapr.save_results(rinternal)
+
+      # Preparing parameters for next iteration (does not do anything if already converged)
+      rinternal = shapr.prepare_next_iteration(rinternal)
+
+      # Printing iteration information
+      shapr.print_iter(rinternal)
+
+      # Setting globals to simplify the loop
+      converged = rinternal.rx2('iter_list')[iter-1].rx2('converged')[0]
+
+      rinternal.rx2['timing_list'] = ro.ListVector({**dict(rinternal.rx2['timing_list'].items()), 'postprocess_res': base.Sys_time()})
+
+      # Add the current timing_list to the iter_timing_list
+      rinternal.rx2['iter_timing_list'] = ro.ListVector({**dict(rinternal.rx2['iter_timing_list'].items()), f'element_{iter}': rinternal.rx2['timing_list']})
+
+      iter += 1
+
+    rinternal.rx2['main_timing_list'] = ro.ListVector({**dict(rinternal.rx2['main_timing_list'].items()), 'main_computation': base.Sys_time()})
+
+    # Rerun after convergence to get the same output format as for the non-iterative approach
+    routput = shapr.finalize_explanation(rinternal)
+
+    rinternal.rx2['main_timing_list'] = ro.ListVector({**dict(rinternal.rx2['main_timing_list'].items()), 'finalize_explanation': base.Sys_time()})
+
+
+    routput.rx2['timing'] = shapr.compute_time(rinternal)
+
+    # Some cleanup when doing testing
+    testing = rinternal.rx2('parameters').rx2('testing')[0]
+    if testing:
+      routput = shapr.testing_cleanup(routput)
+
+    # Convert R objects to Python objects
+    shapley_values_est = recurse_r_tree(routput.rx2('shapley_values_est'))
+    shapley_values_sd = recurse_r_tree(routput.rx2('shapley_values_sd'))
+    pred_explain = recurse_r_tree(routput.rx2('pred_explain'))
+    MSEv = recurse_r_tree(routput.rx2('MSEv'))
+    iterative_results = recurse_r_tree(routput.rx2('iterative_results'))
+    saving_path = recurse_r_tree(routput.rx2('saving_path'))
+    internal = recurse_r_tree(routput.rx2('internal'))
+    timing = recurse_r_tree(routput.rx2('timing'))
+
+    return {
+      "shapley_values_est": shapley_values_est,
+      "shapley_values_sd": shapley_values_sd,
+      "pred_explain": pred_explain,
+      "MSEv": MSEv,
+      "iterative_results": iterative_results,
+      "saving_path": saving_path,
+      "internal": internal,
+      "timing": timing,
+    }
+
+
+def compute_vS(rinternal, model, predict_model):
+
+  iter = len(rinternal.rx2('iter_list'))
+
+  S_batch = rinternal.rx2('iter_list')[iter-1].rx2('S_batch')
+
+  # verbose
+  shapr.cli_compute_vS(rinternal)
+
+  stats.rnorm(1) # Perform a single sample to forward the RNG state one step. This is done to ensurie consistency with
+                # future.apply::future_lapply in R which does this to to guarantee consistency for parallellization.
+                # See ?future.apply::future_lapply for details
+
+  vS_list = ro.ListVector({})
+  for i, S in enumerate(S_batch):
+    vS_list.rx2[i+1] = batch_compute_vS(S=S, rinternal=rinternal, model=model, predict_model=predict_model)
+
+  #### Adds v_S output above to any vS_list already computed ####
+  vS_list = shapr.append_vS_list(vS_list,rinternal)
+
+  return vS_list
+
+
+def batch_compute_vS(S, rinternal, model, predict_model):
+  regression = rinternal.rx2('parameters').rx2('regression')[0]
+
+  # Check if we are to use regression or Monte Carlo integration to compute the contribution function values
+  if regression:
+    dt_vS = shapr.batch_prepare_vS_regression(S=S, internal=rinternal)
+  else:
+    # dt_vS is either only dt_vS or a list containing dt_vS and dt if internal$parameters$output_args$keep_samp_for_vS = TRUE
+    dt_vS = batch_prepare_vS_MC(S=S, rinternal=rinternal, model=model, predict_model=predict_model)
+
+  return dt_vS
+
+
+def batch_prepare_vS_MC_old(S, rinternal, model, predict_model):
+  keep_samp_for_vS = rinternal.rx2('parameters').rx2('keep_samp_for_vS')[0]
+  feature_names = list(rinternal.rx2('parameters').rx2('feature_names'))
+
+  dt = shapr.batch_prepare_vS_MC_auxiliary(S=S, internal=rinternal)
+
+  dt = compute_preds(dt=dt, feature_names=feature_names, predict_model=predict_model, model=model)
+
+  dt_vS = shapr.compute_MCint(dt)
+
+  if keep_samp_for_vS:
+    return ro.ListVector({'dt_vS':dt_vS, 'dt_samp_for_vS':dt})
+  else:
+    return dt_vS
+
+def batch_prepare_vS_MC(S, rinternal, model, predict_model):
+  feature_names = list(rinternal.rx2('parameters').rx2('feature_names'))
+  keep_samp_for_vS = rinternal.rx2('parameters').rx2('output_args').rx2('keep_samp_for_vS')[0]
+  causal_sampling = rinternal.rx2('parameters').rx2('causal_sampling')[0]
+  output_size = int(rinternal.rx2('parameters').rx2('output_size')[0])
+
+  dt = shapr.batch_prepare_vS_MC_auxiliary(S=S, internal=rinternal, causal_sampling=causal_sampling)
+
+  pred_cols = [f"p_hat{i+1}" for i in range(output_size)]
+  type_ = rinternal.rx2('parameters').rx2('type')[0]
+
+  if type_ == "forecast":
+    horizon = rinternal.rx2('parameters').rx2('horizon')[0]
+    n_endo = rinternal.rx2('data').rx2('n_endo')[0]
+    explain_idx = rinternal.rx2('parameters').rx2('explain_idx')[0]
+    explain_lags = rinternal.rx2('parameters').rx2('explain_lags')[0]
+    y = rinternal.rx2('data').rx2('y')
+    xreg = rinternal.rx2('data').rx2('xreg')
+    dt = compute_preds(
+      dt=dt,
+      feature_names=feature_names,
+      predict_model=predict_model,
+      model=model,
+      type_=type_,
+      horizon=horizon,
+      n_endo=n_endo,
+      explain_idx=explain_idx,
+      explain_lags=explain_lags,
+      y=y,
+      xreg=xreg
+      )
+  else:
+    dt = compute_preds(
+      dt=dt,
+      feature_names=feature_names,
+      predict_model=predict_model,
+      model=model,
+      type_=type_
+      )
+
+  dt_vS = shapr.compute_MCint(dt)
+
+  if keep_samp_for_vS:
+    return ro.ListVector({'dt_vS': dt_vS, 'dt_samp_for_vS': dt})
+  else:
+    return dt_vS
+
+def compute_preds(
+  dt,
+  feature_names,
+  predict_model,
+  model,
+  type_,
+  horizon=None,
+  n_endo=None,
+  explain_idx=None,
+  explain_lags=None,
+  y=None,
+  xreg=None
+):
+  # Predictions
+  if type_ == "forecast":
+    preds = predict_model(
+      model,
+      r2py(dt).loc[:,:n_endo],
+      r2py(dt).loc[:,n_endo:],
+      horizon,
+      explain_idx,
+      explain_lags,
+      y,
+      xreg
+      )
+
+  else:
+    preds = predict_model(
+      model,
+      r2py(dt).loc[:,feature_names]
+      )
+
+  return ro.r.cbind(dt, p_hat=ro.FloatVector(preds.tolist()))
+
+
+
+def compute_preds_old(dt, feature_names, predict_model, model):
+  preds = predict_model(model, r2py(dt).loc[:,feature_names])
+  return ro.r.cbind(dt, p_hat=ro.FloatVector(preds.tolist()))
+
+
+
+def get_feature_specs(get_model_specs, model):
+  model_class0 = type(model)
+
+  if (get_model_specs is not None) and (not callable(get_model_specs)):
+    raise ValueError('`get_model_specs` must be None or callable.')
+
+  if get_model_specs is None:
+    get_model_specs = prebuilt_get_model_specs(model)
+    if get_model_specs is None:
+      warnings.warn(f'No pre-built get_model_specs for model of type {type(model)}, disabling checks.')
+      return NULL
+
+  if callable(get_model_specs):
+    try:
+      feature_specs = get_model_specs(model)
+    except Exception as e:
+      raise RuntimeError(f'The get_model_specs function of class `{model_class0}` is invalid.\nA basic function test threw the following error:\n{e}')
+
+  if not isinstance(feature_specs, dict):
+    raise ValueError(f'`get_model_specs` returned an object of type `{type(feature_specs)}`, but it should be of type `dict`')
+  if set(feature_specs.keys()) != set(["labels","classes","factor_levels"]):
+    raise ValueError(f'`get_model_specs` should return a `dict` with keys ["labels","classes","factor_levels"], but found keys {list(feature_specs.keys())}')
+
+  if feature_specs is None:
+    rfeature_specs = NULL
+  else:
+    py2r_or_na = lambda v: py2r(v) if v is not None else NA
+    def strvec_or_na(v):
+      if v is None: return NA
+      strvec = StrVector(list(v.values()))
+      strvec.names = list(v.keys())
+      return strvec
+    def listvec_or_na(v):
+      if v is None: return NA
+      return ro.ListVector({k:list(val) for k,val in v.items()})
+
+    rfeature_specs = ro.ListVector({
+      'labels': py2r_or_na(feature_specs['labels']),
+      'classes': strvec_or_na(feature_specs['classes']),
+      'factor_levels': listvec_or_na(feature_specs['factor_levels']),
+    })
+  return rfeature_specs
+
+
+def get_predict_model(x_test, predict_model, model):
+
+  model_class0 = type(model)
+
+  if (predict_model is not None) and (not callable(predict_model)):
+    raise RuntimeError(f'The predict_model function of class `{model}` is invalid.\nA basic function test threw the following error:\n{e}')
+
+  if predict_model is None:
+    predict_model = prebuilt_predict_model(model)
+    if predict_model is None:
+      raise ValueError(f'No pre-built predict_model for model of type {type(model)}. Please pass a custom predict_model to shaprpy.explain(...).')
+
+  try:
+    tmp = py2r(predict_model(model, x_test))
+  except Exception as e:
+      raise RuntimeError(f'The predict_model function of class `{model_class0}` is invalid.\nA basic function test threw the following error:\n{e}')
+  if not all(base.is_numeric(tmp)):
+    raise RuntimeError('The output of predict_model is expected to be numeric.')
+  if not (len(tmp) == 2):
+    raise RuntimeError('The output of predict_model does not match the length of the input.')
+  return predict_model
+
+
+def prebuilt_get_model_specs(model):
+
+  # Look for sklearn
+  try:
+    from sklearn.base import BaseEstimator
+    if isinstance(model, BaseEstimator):
+      return lambda m: {
+        'labels': m.feature_names_in_,
+        'classes': None, # Not available from model object
+        'factor_levels': None, # Not available from model object
+      }
+  except:
+    pass
+
+  # Look for xgboost.core.Booster
+  try:
+    import xgboost as xgb
+    if isinstance(model, xgb.core.Booster):
+      return lambda m: {
+        'labels': np.array(m.feature_names),
+        'classes': None, # Not available from model object
+        'factor_levels': None, # Not available from model object
+      }
+  except:
+    pass
+
+  return None
+
+
+def prebuilt_predict_model(model):
+
+  # Look for sklearn
+  try:
+    from sklearn.base import is_classifier, is_regressor
+    if is_classifier(model): return lambda m, x: m.predict_proba(x)[:,1]
+    if is_regressor(model): return lambda m, x: m.predict(x).flatten()
+  except:
+    pass
+
+  # Look for xgboost.core.Booster
+  try:
+    import xgboost as xgb
+    if isinstance(model, xgb.core.Booster):
+      return lambda m, x: m.predict(xgb.DMatrix(x))
+  except:
+    pass
+
+  # Look for keras
+  try:
+    from keras.models import Model
+    if isinstance(model, Model):
+      def predict_fn(m,x):
+        pred = m.predict(x)
+        return pred.reshape(pred.shape[0],)
+      return predict_fn
+  except:
+    pass
+
+  return None
+
+
+def compute_time(timing_list):
+
+  timing_secs = {
+      f'{key}': (timing_list[key] - timing_list[prev_key]).total_seconds()
+      for key, prev_key in zip(list(timing_list.keys())[1:], list(timing_list.keys())[:-1])
+  }
+  timing_output = {
+      'init_time': timing_list['init_time'].strftime("%Y-%m-%d %H:%M:%S"),
+      'total_time_secs': sum(timing_secs.values()),
+      'timing_secs': timing_secs
+  }
+
+  return timing_output
+
+
+def additional_regression_setup(rinternal, model, predict_model, x_train, x_explain):
+  # Add the predicted response of the training and explain data to the internal list for regression-based methods
+  regression = rinternal.rx2("parameters").rx2("regression")[0]
+  if regression:
+    rinternal = regression_get_y_hat(rinternal, model, predict_model, x_train, x_explain)
+
+  return rinternal
+
+
+def regression_get_y_hat(rinternal, model, predict_model, x_train, x_explain):
+  x_train_y_hat = predict_model(model, x_train)
+  x_explain_y_hat = predict_model(model, x_explain)
+
+  # Extract data list, add the predicted responses, and then updated rinternal (direct assignment did not work)
+  data = rinternal.rx2['data']
+  data.rx2['x_train_y_hat'] = ro.FloatVector(x_train_y_hat.tolist())
+  data.rx2['x_explain_y_hat'] = ro.FloatVector(x_explain_y_hat.tolist())
+  rinternal.rx2['data'] = data
+
+  return rinternal
+
+
+def regression_remove_objects(routput):
+  tmp_internal = routput.rx2("internal")
+  tmp_parameters = tmp_internal.rx2("parameters")
+  objects = StrVector(("regression", "regression.model", "regression.tune_values", "regression.vfold_cv_para",
+                           "regression.recipe_func", "regression.tune", "regression.surrogate_n_comb"))
+  tmp_parameters.rx[objects] = NULL
+  tmp_internal.rx2["parameters"] = tmp_parameters
+  if tmp_parameters.rx2("approach")[0] == "regression_surrogate":
+      tmp_objects = tmp_internal.rx2("objects")
+      tmp_objects.rx["regression.surrogate_model"] = NULL
+      tmp_internal.rx2["objects"] = tmp_objects
+  routput.rx2["internal"] = tmp_internal
+  return routput
+
+
+def change_first_underscore_to_dot(kwargs):
+  kwargs_tmp = {}
+  for k, v in kwargs.items():
+    kwargs_tmp[k.replace('_', '.', 1)] = v
+  return kwargs_tmp
+

shaprpy/datasets.py

@@ -0,0 +1,27 @@
+import pandas as pd
+from sklearn.datasets import fetch_openml, fetch_california_housing, load_iris
+from sklearn.model_selection import train_test_split
+
+
+def load_california_housing():
+  housing = fetch_california_housing()
+  dfx = pd.DataFrame(housing.data, columns=housing.feature_names)
+  dfy = pd.DataFrame({'target': housing.target})
+  dfx_train, dfx_test, dfy_train, dfy_test = train_test_split(dfx, dfy, test_size=0.99, random_state=42)
+  dfx_test, dfy_test = dfx_test[:5], dfy_test[:5] # To reduce computational load
+  return dfx_train, dfx_test, dfy_train, dfy_test
+
+
+def load_binary_iris():
+  bcancer = load_iris()
+  dfx = pd.DataFrame(bcancer.data, columns=bcancer.feature_names).iloc[bcancer.target<2] # Turning it into a binary classification problem
+  dfy = pd.DataFrame({'target': bcancer.target}).iloc[bcancer.target<2] # Turning it into a binary classification problem
+  dfx_train, dfx_test, dfy_train, dfy_test = train_test_split(dfx, dfy, test_size=5, random_state=42)
+  return dfx_train, dfx_test, dfy_train, dfy_test
+
+
+def load_adult():
+  dfx, y = fetch_openml(data_id=1590, return_X_y=True)
+  dfx = dfx.dropna(axis=1) # Drop columns with NAs for simplicity
+  dfy = pd.DataFrame({'target': y.factorize()[0]})
+  return train_test_split(dfx, dfy, test_size=5, random_state=42)

shaprpy/utils.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pandas as pd
+from rpy2.robjects.conversion import localconverter
+from rpy2.robjects import default_converter, Formula
+from rpy2.robjects.functions import SignatureTranslatedFunction
+from rpy2.robjects.numpy2ri import converter as np_converter
+from rpy2.robjects.pandas2ri import converter as pd_converter
+from rpy2.robjects.pandas2ri import _to_pandas_factor
+from rpy2.rinterface import NULL, NA
+from rpy2.robjects.vectors import DataFrame, FloatVector, IntVector, BoolVector, StrVector, ListVector, FactorVector, FloatMatrix, Matrix, POSIXct
+import warnings
+
+
+@pd_converter.rpy2py.register(FactorVector)
+def rpt2py_factorvector(obj):
+    return _to_pandas_factor(obj)
+
+
+def py2r(obj):
+  with localconverter(default_converter + np_converter + pd_converter) as converter:
+    robj = converter.py2rpy(obj)
+  return robj
+
+
+def r2py(robj):
+  converter = default_converter + np_converter + pd_converter
+  obj = converter.rpy2py(robj)
+  return obj
+
+
+def recurse_r_tree(data):
+  if data == NULL:
+      return None
+  elif type(data) == DataFrame:
+      try:
+          return r2py(data)
+      except Exception as e:
+          # The column "features" in internal$objects$X is known to cause problems
+          d = {}
+          for col in data.names:
+              try:
+                  d[col] = r2py(data.rx2(col))
+              except:
+                  # We manually convert the elements of the column "features" in internal$objects$X
+                  d[col] = [r2py(d) for d in data.rx2(col)]
+          return pd.DataFrame(d, index=data.rownames)
+  elif type(data) in [FloatVector, IntVector, BoolVector, FloatMatrix, Matrix]:
+      return np.array(data)
+  elif type(data) == FactorVector:
+      return _to_pandas_factor(data)
+  elif type(data) == POSIXct:
+      with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        tmp = r2py(data).strftime("%Y-%m-%d %H:%M:%S")[0]
+      return tmp
+  elif type(data) == SignatureTranslatedFunction:
+      return str(data)
+  elif type(data) == Formula:
+      return str(data)  
+  elif type(data) == ListVector:
+      if type(data.names) == type(NULL):
+          data.names = [f"element_{i+1}" for i in range(len(data))]
+      return dict(zip(data.names, [recurse_r_tree(d) for d in data]))
+  elif type(data) == StrVector:
+      return [recurse_r_tree(d) for d in data]
+  else:
+      return data  # We reached the end of recursion (if not converted below, return the object as is)

shaprpy-0.3.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: shaprpy
+Version: 0.3.0
+Summary: Python wrapper for the R package shapr (via rpy2)
+Author: Martin Jullum, Lars Henry Berge Olsen, Didrik Nielsen
+License: YEAR: 2019
+        COPYRIGHT HOLDER: Norsk Regnesentral
+        
+Project-URL: Homepage, https://github.com/NorskRegnesentral/shapr
+Project-URL: Documentation, https://norskregnesentral.github.io/shapr/shaprpy.html
+Project-URL: Issues, https://github.com/NorskRegnesentral/shapr/issues
+Project-URL: Changelog, https://github.com/NorskRegnesentral/shapr/blob/main/python/CHANGELOG.md
+Keywords: explainable-ai,shapley-values,machine-learning,model-interpretability
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE.md
+Requires-Dist: rpy2>=3.5.1
+Requires-Dist: numpy>=1.22.3
+Requires-Dist: pandas>=1.4.2
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: tabulate>=0.8.10
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: syrupy>=4.0.0; extra == "test"
+Requires-Dist: xgboost>=1.5.0; extra == "test"
+Dynamic: license-file
+
+# shaprpy
+
+Python wrapper for the R package [shapr](https://github.com/NorskRegnesentral/shapr).
+
+NOTE: This wrapper is not as comprehensively tested as the `R`-package.
+
+`shaprpy` relies heavily on the `rpy2` Python library for accessing R from within Python.
+`rpy2` has limited support on Windows. `shaprpy` has only been tested on Linux.
+The below instructions assumes a Linux environment.
+
+# shaprpy
+
+`shaprpy` is a Python wrapper for the R package [shapr](https://github.com/NorskRegnesentral/shapr),
+using the [`rpy2`](https://rpy2.github.io/) Python library to access R from within Python.
+
+> **Note:** This wrapper is **not** as comprehensively tested as the R package.
+> `rpy2` has limited support on Windows, and the same therefore applies to `shaprpy`.
+> `shaprpy` has only been tested on Linux (and WSL - Windows Subsystem for Linux), and the below instructions assume a Linux environment.
+>
+> **Requirement:** Python 3.10 or later is required to use `shaprpy`.
+
+## Changelog
+
+For a list of changes and updates to the `shaprpy` package, see the [shaprpy CHANGELOG](https://norskregnesentral.github.io/shapr/py_changelog.html).
+
+---
+
+## Installation
+
+These instructions assume you already have **pip** and **R** installed and available to the Python environment in which you want to run `shaprpy`.
+
+- Official instructions for installing `pip` can be found [here](https://pip.pypa.io/en/stable/installation/).
+- Official instructions for installing R can be found [here](https://cran.r-project.org/).
+
+On Debian/Ubuntu-based systems, R can also be installed via:
+```bash
+sudo apt update
+sudo apt install r-base r-base-dev -y
+```
+
+### 1. Install the R package `shapr`
+
+`shaprpy` requires the R package `shapr` (version 1.0.5 or newer).
+In your R environment, install the latest version from CRAN using:
+
+```bash
+Rscript -e 'install.packages("shapr", repos="https://cran.rstudio.com")'
+```
+
+### 2. Ensure R is discoverable (R_HOME and PATH)
+
+Sometimes `shaprpy` cannot automatically locate your R installation. To ensure proper detection, verify that:
+- R is available in your system `PATH`, **or**
+- The `R_HOME` environment variable is set to your R installation directory.
+
+Example:
+```bash
+export R_HOME=$(R RHOME)
+export PATH=$PATH:$(R RHOME)/bin
+```
+
+### 3. Install the Python wrapper
+
+Install directly from PyPI with:
+
+```bash
+pip install shaprpy
+```
+
+#### Local development install (for contributors)
+If you have cloned the repository and want to install in development mode for local changes, navigate to the `./python` directory and run:
+```bash
+pip install -e .
+```
+The `-e` flag installs in editable mode, allowing local code changes to be reflected immediately.
+
+---
+
+## Quick Demo
+
+```python
+from sklearn.ensemble import RandomForestRegressor
+from shaprpy import explain
+from shaprpy.datasets import load_california_housing
+
+# Load example data
+dfx_train, dfx_test, dfy_train, dfy_test = load_california_housing()
+
+# Fit a model
+model = RandomForestRegressor()
+model.fit(dfx_train, dfy_train.values.flatten())
+
+# Explain predictions
+explanation = explain(
+    model=model,
+    x_train=dfx_train,
+    x_explain=dfx_test,
+    approach="empirical",
+    phi0=dfy_train.mean().item(),
+    seed=1
+)
+
+print(explanation["shapley_values_est"])
+```
+
+---
+
+## Supported Models
+
+`shaprpy` can explain predictions from models built with:
+- [`scikit-learn`](https://scikit-learn.org/)
+- [`keras`](https://keras.io/) (Sequential API)
+- [`xgboost`](https://xgboost.readthedocs.io/)
+
+For other model types, you can supply:
+- A custom `predict_model` function
+- (Optionally) a custom `get_model_specs` function
+to `shaprpy.explain`.
+
+---
+
+## Examples
+
+See the `/examples` folder for runnable examples, including:
+- A custom PyTorch model
+- The **regression paradigm** described in [Olsen et al. (2024)](https://link.springer.com/article/10.1007/s10618-024-01016-z),
+  which shows:
+  - How to specify the regression model
+  - How to enable automatic cross-validation of hyperparameters
+  - How to apply pre-processing steps before fitting regression models

shaprpy-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+shaprpy/__init__.py,sha256=Z7UA4ws5uuPUny9uRpnn6o3PGv5ONWKjhRzBOv-YJJc,1528
+shaprpy/_explain.py,sha256=k_OH_wqewAB6iRodW2aWI_gprw0hra9vyI3Ir-jQkqE,23831
+shaprpy/datasets.py,sha256=ptX-fcD9evlpEdqXrmCTXwcYTao0vTPv93k5C5PYS2g,1295
+shaprpy/utils.py,sha256=_kD5ZW9bp3kyTXhtS-jz4zKAdql4pOH6KZehFJTxaRk,2461
+shaprpy-0.3.0.dist-info/licenses/LICENSE,sha256=hABnnsrNduCr-dp2Cy4-XOroRGzhaw7LefBhxlY0gjQ,48
+shaprpy-0.3.0.dist-info/licenses/LICENSE.md,sha256=9Gwz5ov3rmu9AK8fTEZUj4pPXL5ROOlzcNqukEKxNOY,1077
+shaprpy-0.3.0.dist-info/METADATA,sha256=82ke02a2Al423a_GoQyg9UQthpGgIOBEAHhjPXPP9fU,5675
+shaprpy-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+shaprpy-0.3.0.dist-info/top_level.txt,sha256=4LqZ5SreryN3N5zgxtxKjyAeDUo6ggO9w1s0eRTak78,8
+shaprpy-0.3.0.dist-info/RECORD,,

shaprpy-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shaprpy-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2019
+COPYRIGHT HOLDER: Norsk Regnesentral

shaprpy-0.3.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2019 Norsk Regnesentral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shaprpy-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shaprpy