shaprpy 0.3.0__tar.gz

shaprpy-0.3.0/LICENSE

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

shaprpy-0.3.0/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/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include src/shaprpy *.py
+prune shaprpy

shaprpy-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,130 @@
+# 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/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shaprpy"
+version = "0.3.0"
+description = "Python wrapper for the R package shapr (via rpy2)"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Martin Jullum" },
+  { name = "Lars Henry Berge Olsen" },
+  { name = "Didrik Nielsen" }
+]
+requires-python = ">3.10"
+keywords = ["explainable-ai", "shapley-values", "machine-learning", "model-interpretability"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+dependencies = [
+  "rpy2>=3.5.1",
+  "numpy>=1.22.3",
+  "pandas>=1.4.2",
+  "scikit-learn>=1.0.0",
+  "tabulate>=0.8.10",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=7.0.0",
+  "syrupy>=4.0.0",
+  "xgboost>=1.5.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/NorskRegnesentral/shapr"
+Documentation = "https://norskregnesentral.github.io/shapr/shaprpy.html"
+Issues = "https://github.com/NorskRegnesentral/shapr/issues"
+Changelog = "https://github.com/NorskRegnesentral/shapr/blob/main/python/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["shaprpy*" ]
+
+[tool.setuptools.dynamic]
+# (none needed now)
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+  "--strict-markers",
+  "--strict-config",
+  "-ra",
+]
+markers = [
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+  "snapshot: marks tests as snapshot/output tests",
+]

shaprpy-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shaprpy-0.3.0/src/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)