shapley-value-regression 0.0.0__tar.gz

shapley_value_regression-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+ 
+Copyright (c) 2026 Sarbadal Pal
+ 
+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.

shapley_value_regression-0.0.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: shapley-value-regression
+Version: 0.0.0
+Summary: A simple library to calculate Shapley values for regression models using pandas and scikit-learn.
+Author: Sarbadal Pal
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: tabulate>=0.10
+Dynamic: license-file
+
+# Shapley Value Regression
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+
+# Introduction:
+
+In the econometric literature multicollinearity is defined as the incidence of
+high degree of correlation among some or all regressor variables. Strong multicollinearity has
+deleterious effects on the confidence intervals of linear regression coefficients (β in the linear
+regression model y=Xβ+u). Although it does not affect the explanatory power ($R^2$) of the
+regressors or unbiasedness of the estimated coefficients associated with them, it does inflate
+their standard error of estimate rendering test of hypothesis misleading or paradoxical, often
+such that although $R^2$ could be very high, individual coefficients may all have poor Student’s tvalues.
+Thus, strong multicollinearity may lead to failure in rejecting a false null hypothesis of
+ineffectiveness of the regressor variable to the regressand variable (type II error). Very
+frequently, it also affects the sign of the regression coefficients. However, it has been pointed
+out that the incidence of high degree of correlation (measured in terms of a large condition
+number; Belsley et al., 1980) among some or all regressor variables alone (unsupported by large
+variance of error in the regressand variable, y) has little effect on the precision of regression
+coefficients. Large condition number coupled with a large variance of error in the regressand
+variable destabilizes the regression estimator; either of the two in isolation cannot cause much
+harm, although the condition number is relatively more potent in determining the stability of
+estimated regression coefficients (Mishra, 2004-a).
+
+
+### Shapley value regression:
+> This is an entirely different strategy to assess the contribution of
+regressor variables to the regressand variable. It owes its origin in the theory of cooperative
+games (Shapley, 1953). The value of $R^2$ obtained by fitting a linear regression model y=Xβ+u is
+considered as the value of a cooperative game played by X (whose members, xj ϵ X; j=1, m,
+work in a coalition) against y (explaining it). The analyst does not have enough information to
+disentangle the contributions made by the individual members xj ϵ X; j=1, m, but only their joint
+1 contribution ($R^2$) is known. The Shapley value decomposition imputes the most likely
+contribution of each individual xj ϵ X; j=1, m, to $R^2$.
+
+### An algorithm to impute the contribution of individual variables to Shapley value:
+>Let there be m number of regressor variables in the model y=Xβ+u. Let X(p, r) be the r-membered subset
+of X in which the pth regressor appears and X(q, r) be the r-membered subset of X in which the
+pth regressor does not appear. Further, let $R^2(p, r)$ be the $R^2$ obtained by regression of y on X(p,
+r) and $R^2(q, r)$ be the $R^2$ obtained by regression of y on X(q, r). Then, the share of the regressor
+variable p (that is xp ϵ X) is given by
+
+$$
+S(p) = \frac{1}{m}\frac{\sum_{i=1}^{m}\left[R^2(p,r) - R^2(q, r-1)\right]}{k}.
+$$
+
+Moreover, $R^2(q,0) = 0$. Here k is the number of cases in which the evaluation in [.] was carried
+out. The sum of all $S(p)$ for p=1, m (that is, $\sum_{p=1}^{m}S(p)$) is the $R^2$ of y=Xβ+u : (all xj ϵ X) or the
+total value of the game:
+
+$$
+R^2 = \sum_{p=1}^{m}S(p) = \sum_{p=1}^{m}\frac{1}{m}\sum_{r=1}^{k}\frac{\sum_{c=1}^{k}\left[R^2(p,r)-R^2(q, r-1)\right]}{k}.
+$$
+
+### Computational details of share of $X_j$ in $R^2$:
+
+|r  | r-1 |x1 |x2 |x3 |x4 |$R^2$   |K   | operation   | values  | Sum/k     | Grand value |
+|---|:----|:--|:--|:--|:--|:-------|:---|:------------|:--------|:----------|:-----------:|
+|4  |     |1  |2  |3  |4  |0.98237 |    |plus         |+0.98237 |           |             |
+|   |3    |   |2  |3  |4  |0.97282 |    |minus        |-0.97282 |           |             |
+|   |     |   |   |   |   |        |k=1 |Sum/k        |         |0.009556   |             |
+|3  |     |1  |2  |3  |   |0.98228 |    |plus         |+0.98228 |           |             |
+|3  |     |1  |2  |   |4  |0.98233 |    |plus         |+0.98233 |           |             |
+|3  |     |1  |   |3  |4  |0.98128 |    |plus         |+0.98128 |           |             |
+|   |2    |   |2  |3  |   |0.84702 |    |minus        |-0.84702 |           |             |
+|   |2    |   |2  |3  |   |0.68006 |    |minus        |-0.68006 |           |             |
+|   |2    |   |2  |3  |   |0.93529 |    |minus        |-0.93529 |           |             |
+|   |     |   |   |   |   |        |k=3 |Sum/k        |         |0.161175   |             |
+|2  |     |1  |2  |   |   |0.97867 |    |plus         |+0.97867 |           |             |
+|2  |     |1  |   |3  |   |0.54816 |    |plus         |+0.54816 |           |             |
+|2  |     |1  |   |   |4  |0.97247 |    |plus         |+0.97247 |           |             |
+|   |1    |   |2  |   |   |0.66626 |    |minus        |-0.66626 |           |             |
+|   |1    |   |   |3  |   |0.28587 |    |minus        |-0.28587 |           |             |
+|   |1    |   |   |   |4  |0.67454 |    |minus        |-0.67454 |           |             |
+|   |     |   |   |   |   |        |k=3 |Sum/k        |         |0.290878   |             |
+|1  |     |1  |   |   |   |0.53394 |    |plus         |+0.53394 |           |             |
+|   |     |   |   |   |   |        |k=1 |Sum/k        |         |0.533948   |             |
+|   |     |   |   |   |   |        |    |Sum(sum/k)/m |         |           |**0.248889** |
+
+## Time Complexity
+
+For estimated execution time and scalability details by number of regressors, see [TIMEComplexity.md](TIMEComplexity.md).
+
+## Example: Use as a package
+
+Install locally in editable mode from the project root:
+
+```bash
+pip install -e .
+```
+
+Then import and use the package in Python:
+
+```python
+from shapley import ShapleyValue
+from shapley.data.load import get_dataset_info, load_dataset
+
+dataset_key = "death_rate"
+
+info = get_dataset_info(dataset_key)
+df = load_dataset(dataset_key)
+
+sv = ShapleyValue(df, info["default_X"], info["target"])
+contributions = sv.get_shapley_contribution(verbose=False)
+
+print(contributions)
+```
+
+Expected output format:
+
+```text
+Regressor                                      Share
+lower_95_confidence_interval_for_death_rate    <float>
+upper_95_confidence_interval_for_death_rate    <float>
+recent_5_year_trend_2_in_death_rates           <float>
+average_deaths_per_year                        <float>
+Total                                          <float>
+```
+
+Get contribution for a single regressor:
+
+```python
+contribution, details = sv.get_shapley_contribution_of("average_deaths_per_year")
+print(contribution)
+print(details.head())
+```
+
+Available packaged datasets:
+
+- `death_rate`
+- `distance_metro`
+
+## Example: Use your own pandas DataFrame
+
+You can also pass your own DataFrame directly, as long as selected feature columns and target column are numeric.
+
+```python
+import pandas as pd
+
+from shapley import ShapleyValue
+
+# User-provided dataset
+df = pd.DataFrame(
+	{
+		"sq_feet": [950, 1100, 1300, 1600, 1800, 2100],
+		"age_years": [20, 15, 12, 10, 8, 5],
+		"bedrooms": [2, 2, 3, 3, 4, 4],
+		"distance_km": [8.0, 7.2, 6.5, 5.0, 4.0, 3.0],
+		"price_usd": [220000, 250000, 290000, 340000, 390000, 450000],
+	}
+)
+
+X = ["sq_feet", "age_years", "bedrooms", "distance_km"]
+y = "price_usd"
+
+sv = ShapleyValue(df, X, y)
+
+# All feature contributions
+contributions = sv.get_shapley_contribution(verbose=False)
+print(contributions)
+
+# Single feature contribution and detailed intermediate table
+sq_feet_share, sq_feet_details = sv.get_shapley_contribution_of("sq_feet")
+print("sq_feet share:", sq_feet_share)
+print(sq_feet_details.head())
+```

shapley_value_regression-0.0.0/README.md

@@ -0,0 +1,168 @@
+# Shapley Value Regression
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+
+# Introduction:
+
+In the econometric literature multicollinearity is defined as the incidence of
+high degree of correlation among some or all regressor variables. Strong multicollinearity has
+deleterious effects on the confidence intervals of linear regression coefficients (β in the linear
+regression model y=Xβ+u). Although it does not affect the explanatory power ($R^2$) of the
+regressors or unbiasedness of the estimated coefficients associated with them, it does inflate
+their standard error of estimate rendering test of hypothesis misleading or paradoxical, often
+such that although $R^2$ could be very high, individual coefficients may all have poor Student’s tvalues.
+Thus, strong multicollinearity may lead to failure in rejecting a false null hypothesis of
+ineffectiveness of the regressor variable to the regressand variable (type II error). Very
+frequently, it also affects the sign of the regression coefficients. However, it has been pointed
+out that the incidence of high degree of correlation (measured in terms of a large condition
+number; Belsley et al., 1980) among some or all regressor variables alone (unsupported by large
+variance of error in the regressand variable, y) has little effect on the precision of regression
+coefficients. Large condition number coupled with a large variance of error in the regressand
+variable destabilizes the regression estimator; either of the two in isolation cannot cause much
+harm, although the condition number is relatively more potent in determining the stability of
+estimated regression coefficients (Mishra, 2004-a).
+
+
+### Shapley value regression:
+> This is an entirely different strategy to assess the contribution of
+regressor variables to the regressand variable. It owes its origin in the theory of cooperative
+games (Shapley, 1953). The value of $R^2$ obtained by fitting a linear regression model y=Xβ+u is
+considered as the value of a cooperative game played by X (whose members, xj ϵ X; j=1, m,
+work in a coalition) against y (explaining it). The analyst does not have enough information to
+disentangle the contributions made by the individual members xj ϵ X; j=1, m, but only their joint
+1 contribution ($R^2$) is known. The Shapley value decomposition imputes the most likely
+contribution of each individual xj ϵ X; j=1, m, to $R^2$.
+
+### An algorithm to impute the contribution of individual variables to Shapley value:
+>Let there be m number of regressor variables in the model y=Xβ+u. Let X(p, r) be the r-membered subset
+of X in which the pth regressor appears and X(q, r) be the r-membered subset of X in which the
+pth regressor does not appear. Further, let $R^2(p, r)$ be the $R^2$ obtained by regression of y on X(p,
+r) and $R^2(q, r)$ be the $R^2$ obtained by regression of y on X(q, r). Then, the share of the regressor
+variable p (that is xp ϵ X) is given by
+
+$$
+S(p) = \frac{1}{m}\frac{\sum_{i=1}^{m}\left[R^2(p,r) - R^2(q, r-1)\right]}{k}.
+$$
+
+Moreover, $R^2(q,0) = 0$. Here k is the number of cases in which the evaluation in [.] was carried
+out. The sum of all $S(p)$ for p=1, m (that is, $\sum_{p=1}^{m}S(p)$) is the $R^2$ of y=Xβ+u : (all xj ϵ X) or the
+total value of the game:
+
+$$
+R^2 = \sum_{p=1}^{m}S(p) = \sum_{p=1}^{m}\frac{1}{m}\sum_{r=1}^{k}\frac{\sum_{c=1}^{k}\left[R^2(p,r)-R^2(q, r-1)\right]}{k}.
+$$
+
+### Computational details of share of $X_j$ in $R^2$:
+
+|r  | r-1 |x1 |x2 |x3 |x4 |$R^2$   |K   | operation   | values  | Sum/k     | Grand value |
+|---|:----|:--|:--|:--|:--|:-------|:---|:------------|:--------|:----------|:-----------:|
+|4  |     |1  |2  |3  |4  |0.98237 |    |plus         |+0.98237 |           |             |
+|   |3    |   |2  |3  |4  |0.97282 |    |minus        |-0.97282 |           |             |
+|   |     |   |   |   |   |        |k=1 |Sum/k        |         |0.009556   |             |
+|3  |     |1  |2  |3  |   |0.98228 |    |plus         |+0.98228 |           |             |
+|3  |     |1  |2  |   |4  |0.98233 |    |plus         |+0.98233 |           |             |
+|3  |     |1  |   |3  |4  |0.98128 |    |plus         |+0.98128 |           |             |
+|   |2    |   |2  |3  |   |0.84702 |    |minus        |-0.84702 |           |             |
+|   |2    |   |2  |3  |   |0.68006 |    |minus        |-0.68006 |           |             |
+|   |2    |   |2  |3  |   |0.93529 |    |minus        |-0.93529 |           |             |
+|   |     |   |   |   |   |        |k=3 |Sum/k        |         |0.161175   |             |
+|2  |     |1  |2  |   |   |0.97867 |    |plus         |+0.97867 |           |             |
+|2  |     |1  |   |3  |   |0.54816 |    |plus         |+0.54816 |           |             |
+|2  |     |1  |   |   |4  |0.97247 |    |plus         |+0.97247 |           |             |
+|   |1    |   |2  |   |   |0.66626 |    |minus        |-0.66626 |           |             |
+|   |1    |   |   |3  |   |0.28587 |    |minus        |-0.28587 |           |             |
+|   |1    |   |   |   |4  |0.67454 |    |minus        |-0.67454 |           |             |
+|   |     |   |   |   |   |        |k=3 |Sum/k        |         |0.290878   |             |
+|1  |     |1  |   |   |   |0.53394 |    |plus         |+0.53394 |           |             |
+|   |     |   |   |   |   |        |k=1 |Sum/k        |         |0.533948   |             |
+|   |     |   |   |   |   |        |    |Sum(sum/k)/m |         |           |**0.248889** |
+
+## Time Complexity
+
+For estimated execution time and scalability details by number of regressors, see [TIMEComplexity.md](TIMEComplexity.md).
+
+## Example: Use as a package
+
+Install locally in editable mode from the project root:
+
+```bash
+pip install -e .
+```
+
+Then import and use the package in Python:
+
+```python
+from shapley import ShapleyValue
+from shapley.data.load import get_dataset_info, load_dataset
+
+dataset_key = "death_rate"
+
+info = get_dataset_info(dataset_key)
+df = load_dataset(dataset_key)
+
+sv = ShapleyValue(df, info["default_X"], info["target"])
+contributions = sv.get_shapley_contribution(verbose=False)
+
+print(contributions)
+```
+
+Expected output format:
+
+```text
+Regressor                                      Share
+lower_95_confidence_interval_for_death_rate    <float>
+upper_95_confidence_interval_for_death_rate    <float>
+recent_5_year_trend_2_in_death_rates           <float>
+average_deaths_per_year                        <float>
+Total                                          <float>
+```
+
+Get contribution for a single regressor:
+
+```python
+contribution, details = sv.get_shapley_contribution_of("average_deaths_per_year")
+print(contribution)
+print(details.head())
+```
+
+Available packaged datasets:
+
+- `death_rate`
+- `distance_metro`
+
+## Example: Use your own pandas DataFrame
+
+You can also pass your own DataFrame directly, as long as selected feature columns and target column are numeric.
+
+```python
+import pandas as pd
+
+from shapley import ShapleyValue
+
+# User-provided dataset
+df = pd.DataFrame(
+	{
+		"sq_feet": [950, 1100, 1300, 1600, 1800, 2100],
+		"age_years": [20, 15, 12, 10, 8, 5],
+		"bedrooms": [2, 2, 3, 3, 4, 4],
+		"distance_km": [8.0, 7.2, 6.5, 5.0, 4.0, 3.0],
+		"price_usd": [220000, 250000, 290000, 340000, 390000, 450000],
+	}
+)
+
+X = ["sq_feet", "age_years", "bedrooms", "distance_km"]
+y = "price_usd"
+
+sv = ShapleyValue(df, X, y)
+
+# All feature contributions
+contributions = sv.get_shapley_contribution(verbose=False)
+print(contributions)
+
+# Single feature contribution and detailed intermediate table
+sq_feet_share, sq_feet_details = sv.get_shapley_contribution_of("sq_feet")
+print("sq_feet share:", sq_feet_share)
+print(sq_feet_details.head())
+```

shapley_value_regression-0.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shapley-value-regression"
+version = "0.0.0"
+description = "A simple library to calculate Shapley values for regression models using pandas and scikit-learn."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Sarbadal Pal"}]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas>=2.0",
+    "scikit-learn>=1.3",
+    "tabulate>=0.10"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+shapley = [
+    "*.py",
+    "data/*.csv",
+]

shapley_value_regression-0.0.0/setup.cfg

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

shapley_value_regression-0.0.0/src/docs/source/conf.py

@@ -0,0 +1,51 @@
+import os
+import sys
+import time
+ 
+os.environ["TZ"] = "Asia/Kolkata"
+time.tzset()
+
+# Add your package root to PYTHONPATH
+sys.path.insert(0, os.path.abspath('../..'))
+
+def setup(app):
+    app.add_js_file('custom.js')
+
+html_title = 'Shapley Value'
+project = 'Shapley Value'
+copyright = '2026, Sarbadal Pal'
+author = 'Sarbadal Pal'
+release = '0.0.1'
+ 
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'myst_parser',
+    'sphinx_togglebutton',
+    'sphinx_copybutton',
+]
+ 
+templates_path = ['_templates']
+exclude_patterns = []
+
+html_context = { 
+    "READTHEDOCS": False,
+    "display_lower_left": False,
+}
+ 
+# html_theme = 'furo'
+html_theme = 'sphinx_rtd_theme'
+html_last_updated_use_utc = False
+html_last_updated_fmt = "%Y-%m-%d %H:%M:%S IST"
+ 
+html_static_path = ['_static']
+html_css_files = [
+    'custom.css',
+    'font.css',
+]
+
+html_allow_unsafe = True
+html_show_sphinx = False
+html_copy_source = False
+html_show_sourcelink = False

shapley_value_regression-0.0.0/src/shapley/__init__.py

@@ -0,0 +1,3 @@
+from shapley.models.shapley import ShapleyValue
+
+__all__ = ['ShapleyValue']

shapley_value_regression-0.0.0/src/shapley/data/Distance_Metro_KM.csv

@@ -0,0 +1,31 @@
+Property_ID,Sq_Feet,Age_Yrs,Bedrooms,Distance_Metro_KM,Floors,Price_USD
+101,4174,11,2,7.2,2,504000
+102,1860,16,3,7.4,1,199000
+103,2294,9,2,7.8,3,300000
+104,2130,15,3,1.2,3,330000
+105,2095,14,3,3.9,1,283000
+106,4092,14,2,1.6,3,543000
+107,2638,18,5,8.7,3,327000
+108,3169,11,3,6.4,1,395000
+109,1466,19,4,3.6,1,205000
+110,2238,2,4,1.1,3,382000
+111,1330,4,3,3.5,3,242000
+112,2482,18,4,3.6,3,361000
+113,3135,6,1,7.4,2,412000
+114,4444,8,2,6.6,2,559000
+115,4171,6,1,8.9,2,500000
+116,3919,17,2,5.0,1,468000
+117,1130,3,2,1.6,2,185000
+118,2685,13,2,7.3,1,314000
+119,4380,17,4,7.7,1,534000
+120,1769,8,2,5.8,2,279000
+121,3391,1,2,7.8,2,439000
+122,2515,19,3,5.2,2,323000
+123,4485,14,2,5.5,3,562000
+124,3853,6,4,4.6,2,520000
+125,3433,11,1,0.7,3,486000
+126,2215,7,5,1.5,1,379000
+127,1955,14,3,0.8,3,323000
+128,3324,2,2,6.5,2,427000
+129,2184,13,1,3.5,1,291000
+130,1459,16,4,5.3,1,184000