treeig 0.2.1__tar.gz → 0.2.2__tar.gz

treeig-0.2.2/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.2.2
+
+- Change `TreeIGNumeric` and `make_scalar_fn` to derive classification scores
+  by default when no native margin exists: binary log odds or centered
+  multiclass log probabilities. `compute_numeric` inherits this default.
+  Callers requiring the former class-probability output must explicitly set
+  `probability_to_score=False`. Zero probabilities require an explicit
+  `probability_floor` for finite scores; no floor is chosen silently.
+
+- Add an agent documentation index, sitemap, canonical URLs, page descriptions,
+  and build checks for documentation discovery. Clarify exact versus numerical
+  model support, baseline guarantees, and related-project links.
+- Lead the README and documentation landing page with the piecewise-constant
+  gradient argument, and move the derivative-impulse figure above the fold.
+- State completeness precision relative to the fitted model's own arithmetic
+  rather than unqualified floating-point precision.
+
+## 0.2.1
+
+- Separate numerical jump-detection tolerance from absolute and relative completeness-warning tolerances; retain raw residual diagnostics.
+- Clarify jump-based fallback behavior, bundled-event completeness, and XGBoost prediction precision.
+- Check numeric regression tests with unexpected runtime warnings treated as errors in CI.
+
+## 0.2.0
+
+- Add optional `treeig.GPUTreeIG` prediction attribution with persistent CUDA model and weighted-baseline state and reusable observation buffers.
+- Keep CPU `TreeIG` as the default; load CUDA only when constructing `GPUTreeIG`.
+- Add the `cuda` installation extra, simulator equivalence tests, and GPU usage and benchmark documentation.
+- Correct GitHub project links and restrict release publishing to version tags.
+
+GPUTreeIG is part of `treeig`, not a separate distribution. GPU performance depends on the workload; existing T4 measurements are examples rather than guarantees.

{treeig-0.2.1 → treeig-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treeig
-Version: 0.2.1
+Version: 0.2.2
 Summary: Exact Integrated Gradients for tree ensembles.
 Author: Ludger Hentschel
 License-Expression: BSD-3-Clause
@@ -26,6 +26,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: numba>=0.58
 Provides-Extra: docs
 Requires-Dist: sphinx<9,>=7; extra == "docs"
+Requires-Dist: sphinx-sitemap<3,>=2.6; extra == "docs"
 Requires-Dist: myst-parser<5,>=3; extra == "docs"
 Requires-Dist: pydata-sphinx-theme<0.17,>=0.16; extra == "docs"
 Provides-Extra: cuda
@@ -62,36 +63,49 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/treeig.svg)](https://pypi.org/project/treeig/)
 [![Documentation](https://img.shields.io/badge/docs-user%20guide-blue)](https://ludgerhentschel.github.io/treeig/)
 
-TreeIG computes exact Integrated Gradients for tree-based models. It attributes
-the change in a model's scalar output from a baseline to an observation to the
-input features. For one baseline $x_0$,
+TreeIG is a Python package for Integrated Gradients feature attribution on
+supported numeric tree models. Install and import it as `treeig`. Given a fitted
+model, a baseline point or weighted background, and evaluation rows, `TreeIG`
+returns feature contributions and completeness diagnostics.
 
-$$\sum_j \phi_j = F(x) - F(x_0).$$
+**TreeIG computes exact Integrated Gradients for supported numeric tree models.
+A tree's gradient is zero almost everywhere; its integrated gradient is not.**
 
-TreeIG finds the split boundaries crossed along the straight-line path and sums
-their prediction jumps. For supported models, this avoids numerical integration
-and sampling. Weighted baseline distributions are supported as well.
+Check [supported models](https://ludgerhentschel.github.io/treeig/models.html) before choosing an interface.
+`TreeIG` uses exact structural split crossings; [TreeIGNumeric](https://ludgerhentschel.github.io/treeig/numeric.html)
+is a separately selected numerical fallback. Exact classification explains raw
+margins or logits. Exact parsing requires finite numeric inputs and does not
+support categorical splits or missing-value routing. Installing the CatBoost
+extra does not add an exact CatBoost backend.
 
-The method is developed in Ludger Hentschel's
-[**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
-It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
-[**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
-
-## Why Integrated Gradients works for trees
+Tree ensembles are piecewise constant, so $\nabla F = 0$ except on a
+measure-zero set of split boundaries. Numerical Integrated Gradients therefore
+recovers approximately nothing, which is why IG has largely been confined to
+differentiable models.
 
-A tree prediction is constant between splits, so its ordinary gradient is zero
-almost everywhere. But the prediction jumps at split boundaries. Those jumps
-are the contribution that an ordinary pointwise gradient misses: in the
-distributional interpretation, each jump is an impulse whose integral equals
-the jump's height.
+The pointwise gradient is not the full derivative. In the distributional sense,
+$F'$ carries an impulse at each split boundary whose integral equals the
+prediction jump there.
 
 ![A prediction step, its derivative impulse, and its integrated contribution](https://raw.githubusercontent.com/LudgerHentschel/treeig/main/docs/Figure_TreeGradient.svg)
 
 The top panel shows a single prediction step; the middle shows its derivative
 as an impulse at the split; the bottom shows the accumulated contribution.
-Integrating across the split recovers the prediction change. TreeIG applies
-this idea along the path from a baseline to an observation, assigning each
-crossing's jump to its split feature and summing across trees.
+Integrating across the split recovers the prediction change.
+
+TreeIG enumerates the boundaries crossed by the straight-line path from baseline
+to observation, assigns each jump to its split feature, and sums across trees.
+No quadrature and no sampling are involved, and completeness
+
+$$\sum_j \phi_j = F(x) - F(x_0)$$
+
+holds to the floating-point precision of the fitted model's own arithmetic.
+Weighted baseline distributions are supported directly.
+
+The method is developed in Ludger Hentschel's
+[**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
+It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
+[**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
 
 ## Installation
 
@@ -105,7 +119,9 @@ for plotting. The first attribution call includes Numba compilation.
 
 ## Quickstart
 
-With a fitted supported model and numeric evaluation data:
+This snippet assumes a fitted supported model and numeric evaluation data.
+For a standalone example that creates data, fits a model, and checks prediction
+reconstruction, start with [the complete quickstart](https://ludgerhentschel.github.io/treeig/getting-started.html).
 
 ```python
 from treeig import TreeIG
@@ -136,7 +152,11 @@ splits and missing-value routing are not supported by the exact parser.
 
 `TreeIGNumeric` provides a numerical fallback for other piecewise-constant models,
 including numeric-input CatBoost and probability-only classifiers. Its resolution
-requires care. See [supported models](https://ludgerhentschel.github.io/treeig/models.html)
+requires care. For probability-only classifiers, it defaults to binary log odds
+or centered multiclass log scores; class probabilities require explicit
+`probability_to_score=False`. Zero probabilities require an explicit
+`probability_floor` for score conversion. A small completeness
+residual alone does not establish accurate individual feature allocations. See [supported models](https://ludgerhentschel.github.io/treeig/models.html)
 and [the numerical guide](https://ludgerhentschel.github.io/treeig/numeric.html).
 
 TreeIG and TreeSHAP answer different attribution questions. TreeIG can be fast
@@ -146,6 +166,9 @@ explain the distinction and report measured examples.
 
 ## Documentation
 
+For automated readers, [llms.txt](https://ludgerhentschel.github.io/treeig/llms.txt)
+maps the guides, complete examples, and rendered API reference.
+
 The [user guide](https://ludgerhentschel.github.io/treeig/)
 covers a complete runnable example, baseline distributions, classification,
 plots, loss attribution, numerical conventions, and performance. The Sphinx
@@ -161,6 +184,18 @@ the reported workloads. Performance depends on the problem. See
 [GPU documentation](https://ludgerhentschel.github.io/treeig/gpu.html)
 for installation and limitations.
 
+## Related projects
+
+| Package | When to use it |
+|---|---|
+| [UnifiedIG](https://ludgerhentschel.github.io/unifiedig/) (`unifiedig`) | A common Integrated Gradients interface across supported tree and smooth model families. |
+| [CBaseline](https://ludgerhentschel.github.io/cbaseline/) (`cbaseline`) | Construct empirical reference distributions; TreeIG accepts its backgrounds with their weights directly. |
+| [skgrad](https://ludgerhentschel.github.io/skgrad/) (`skgrad`) | Obtain analytic input gradients and Jacobians for supported smooth scikit-learn models. |
+
+Use TreeIG directly when you need its tree-specific attribution interface.
+See [the Integrated Gradients stack](https://ludgerhentschel.github.io/treeig/ig-stack.html)
+for how the packages compose and why output scales must agree.
+
 ## Citation and license
 
 If you use TreeIG in your work, please cite the
@@ -176,3 +211,5 @@ If you use TreeIG in your work, please cite the
 ```
 
 Released under the [BSD-3-Clause license](https://github.com/LudgerHentschel/treeig/blob/main/LICENSE).
+
+Release maintainers: see [Publishing releases](docs/publishing.md).

{treeig-0.2.1 → treeig-0.2.2}/README.md

@@ -3,37 +3,50 @@
 [![PyPI version](https://img.shields.io/pypi/v/treeig.svg)](https://pypi.org/project/treeig/)
 [![Documentation](https://img.shields.io/badge/docs-user%20guide-blue)](https://ludgerhentschel.github.io/treeig/)
 
-TreeIG computes exact Integrated Gradients for tree-based models. It attributes
-the change in a model's scalar output from a baseline to an observation to the
-input features. For one baseline $x_0$,
+TreeIG is a Python package for Integrated Gradients feature attribution on
+supported numeric tree models. Install and import it as `treeig`. Given a fitted
+model, a baseline point or weighted background, and evaluation rows, `TreeIG`
+returns feature contributions and completeness diagnostics.
+
+**TreeIG computes exact Integrated Gradients for supported numeric tree models.
+A tree's gradient is zero almost everywhere; its integrated gradient is not.**
+
+Check [supported models](https://ludgerhentschel.github.io/treeig/models.html) before choosing an interface.
+`TreeIG` uses exact structural split crossings; [TreeIGNumeric](https://ludgerhentschel.github.io/treeig/numeric.html)
+is a separately selected numerical fallback. Exact classification explains raw
+margins or logits. Exact parsing requires finite numeric inputs and does not
+support categorical splits or missing-value routing. Installing the CatBoost
+extra does not add an exact CatBoost backend.
+
+Tree ensembles are piecewise constant, so $\nabla F = 0$ except on a
+measure-zero set of split boundaries. Numerical Integrated Gradients therefore
+recovers approximately nothing, which is why IG has largely been confined to
+differentiable models.
+
+The pointwise gradient is not the full derivative. In the distributional sense,
+$F'$ carries an impulse at each split boundary whose integral equals the
+prediction jump there.
 
-$$\sum_j \phi_j = F(x) - F(x_0).$$
+![A prediction step, its derivative impulse, and its integrated contribution](https://raw.githubusercontent.com/LudgerHentschel/treeig/main/docs/Figure_TreeGradient.svg)
+
+The top panel shows a single prediction step; the middle shows its derivative
+as an impulse at the split; the bottom shows the accumulated contribution.
+Integrating across the split recovers the prediction change.
+
+TreeIG enumerates the boundaries crossed by the straight-line path from baseline
+to observation, assigns each jump to its split feature, and sums across trees.
+No quadrature and no sampling are involved, and completeness
 
-TreeIG finds the split boundaries crossed along the straight-line path and sums
-their prediction jumps. For supported models, this avoids numerical integration
-and sampling. Weighted baseline distributions are supported as well.
+$$\sum_j \phi_j = F(x) - F(x_0)$$
+
+holds to the floating-point precision of the fitted model's own arithmetic.
+Weighted baseline distributions are supported directly.
 
 The method is developed in Ludger Hentschel's
 [**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
 It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
 [**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
 
-## Why Integrated Gradients works for trees
-
-A tree prediction is constant between splits, so its ordinary gradient is zero
-almost everywhere. But the prediction jumps at split boundaries. Those jumps
-are the contribution that an ordinary pointwise gradient misses: in the
-distributional interpretation, each jump is an impulse whose integral equals
-the jump's height.
-
-![A prediction step, its derivative impulse, and its integrated contribution](https://raw.githubusercontent.com/LudgerHentschel/treeig/main/docs/Figure_TreeGradient.svg)
-
-The top panel shows a single prediction step; the middle shows its derivative
-as an impulse at the split; the bottom shows the accumulated contribution.
-Integrating across the split recovers the prediction change. TreeIG applies
-this idea along the path from a baseline to an observation, assigning each
-crossing's jump to its split feature and summing across trees.
-
 ## Installation
 
 ```bash
@@ -46,7 +59,9 @@ for plotting. The first attribution call includes Numba compilation.
 
 ## Quickstart
 
-With a fitted supported model and numeric evaluation data:
+This snippet assumes a fitted supported model and numeric evaluation data.
+For a standalone example that creates data, fits a model, and checks prediction
+reconstruction, start with [the complete quickstart](https://ludgerhentschel.github.io/treeig/getting-started.html).
 
 ```python
 from treeig import TreeIG
@@ -77,7 +92,11 @@ splits and missing-value routing are not supported by the exact parser.
 
 `TreeIGNumeric` provides a numerical fallback for other piecewise-constant models,
 including numeric-input CatBoost and probability-only classifiers. Its resolution
-requires care. See [supported models](https://ludgerhentschel.github.io/treeig/models.html)
+requires care. For probability-only classifiers, it defaults to binary log odds
+or centered multiclass log scores; class probabilities require explicit
+`probability_to_score=False`. Zero probabilities require an explicit
+`probability_floor` for score conversion. A small completeness
+residual alone does not establish accurate individual feature allocations. See [supported models](https://ludgerhentschel.github.io/treeig/models.html)
 and [the numerical guide](https://ludgerhentschel.github.io/treeig/numeric.html).
 
 TreeIG and TreeSHAP answer different attribution questions. TreeIG can be fast
@@ -87,6 +106,9 @@ explain the distinction and report measured examples.
 
 ## Documentation
 
+For automated readers, [llms.txt](https://ludgerhentschel.github.io/treeig/llms.txt)
+maps the guides, complete examples, and rendered API reference.
+
 The [user guide](https://ludgerhentschel.github.io/treeig/)
 covers a complete runnable example, baseline distributions, classification,
 plots, loss attribution, numerical conventions, and performance. The Sphinx
@@ -102,6 +124,18 @@ the reported workloads. Performance depends on the problem. See
 [GPU documentation](https://ludgerhentschel.github.io/treeig/gpu.html)
 for installation and limitations.
 
+## Related projects
+
+| Package | When to use it |
+|---|---|
+| [UnifiedIG](https://ludgerhentschel.github.io/unifiedig/) (`unifiedig`) | A common Integrated Gradients interface across supported tree and smooth model families. |
+| [CBaseline](https://ludgerhentschel.github.io/cbaseline/) (`cbaseline`) | Construct empirical reference distributions; TreeIG accepts its backgrounds with their weights directly. |
+| [skgrad](https://ludgerhentschel.github.io/skgrad/) (`skgrad`) | Obtain analytic input gradients and Jacobians for supported smooth scikit-learn models. |
+
+Use TreeIG directly when you need its tree-specific attribution interface.
+See [the Integrated Gradients stack](https://ludgerhentschel.github.io/treeig/ig-stack.html)
+for how the packages compose and why output scales must agree.
+
 ## Citation and license
 
 If you use TreeIG in your work, please cite the
@@ -117,3 +151,5 @@ If you use TreeIG in your work, please cite the
 ```
 
 Released under the [BSD-3-Clause license](https://github.com/LudgerHentschel/treeig/blob/main/LICENSE).
+
+Release maintainers: see [Publishing releases](docs/publishing.md).

{treeig-0.2.1 → treeig-0.2.2}/docs/api.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Look up TreeIG, TreeIGNumeric, Explanation, and public functions in the rendered API reference."
+---
+
 # API reference
 
 The primary interfaces are `TreeIG` for exact structural attribution,

{treeig-0.2.1 → treeig-0.2.2}/docs/baselines.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Choose TreeIG baseline points or weighted reference distributions, including CBaseline backgrounds."
+---
+
 # Choosing baselines and batching
 
 The baseline determines the question an attribution answers. With one baseline,
@@ -14,15 +20,18 @@ model need not satisfy $F(\sum_k w_k b_k)=\sum_k w_k F(b_k)$.
 
 For Integrated Gradients, the baseline determines the prediction contrast
 being explained. **[CBaseline](https://github.com/LudgerHentschel/cbaseline) is the
-preferred way to construct TreeIG baselines.** CBaseline produces empirical,
-prediction-neutral baseline *distributions* whose weighted mean model output is
-the chosen reference prediction. TreeIG then explains the model prediction
-relative to that reference level rather than relative to an arbitrary feature
-vector such as the feature-wise mean.
+preferred way to construct TreeIG baselines.** Its calibrated mode produces
+empirical baseline *distributions* whose weighted mean model output meets the
+chosen reference prediction within numerical tolerances, or raises on failure.
+Equal-weight selections approximate neutrality and report their residual.
+TreeIG explains the model prediction relative to the **achieved weighted mean**,
+so preserve both the rows and weights when passing a background.
 
 TreeIG accepts a CBaseline `Background` directly and evaluates its weighted
 baseline paths efficiently. See CBaseline for construction choices and the
-interpretation of the reference prediction `f0`.
+interpretation of the reference prediction `f0`: start with
+[background modes](https://ludgerhentschel.github.io/cbaseline/backgrounds.html)
+and [diagnostics](https://ludgerhentschel.github.io/cbaseline/diagnostics.html).
 
 A single representative observation, domain-specific neutral input, or fixed
 benchmark case is also supported. A sample mean is convenient for a first

{treeig-0.2.1 → treeig-0.2.2}/docs/building.md

@@ -9,6 +9,7 @@ From the repository root, using Python 3.11 or later:
 ```bash
 python -m pip install -e ".[docs]"
 python -m sphinx -W --keep-going -b html docs docs/_build/html
+python scripts/check_docs_discovery.py
 ```
 
 Open `docs/_build/html/index.html` in a browser. Documentation dependencies are
@@ -26,3 +27,19 @@ job publishes the site. No package version change or release tag is required.
 Edit the topic pages under `docs/`; keep the README focused on installation,
 a first example, and links into the guide. Version information comes from
 `pyproject.toml`. Generated HTML should not be committed.
+
+## Discovery files
+
+Maintain the repository-root `llms.txt` as an annotated map to the published
+site. Sphinx copies this single source through `html_extra_path`. Link to
+rendered API pages so readers receive expanded signatures and docstrings,
+rather than the autodoc instructions in raw Sphinx sources.
+
+`sphinx-sitemap` generates `sitemap.xml` using `html_baseurl`, which also supplies
+canonical page URLs. Important pages define descriptions in `myst.html_meta`
+YAML front matter. Keep `docs/requirements.txt` and the `docs` extra synchronized.
+
+The discovery check runs after the HTML build in CI. It checks the index copy,
+local targets, sitemap URLs, canonical links, descriptions, and expanded API and
+example content. After deployment, check the public `/treeig/llms.txt` and
+`/treeig/sitemap.xml` endpoints and external links in the index.

{treeig-0.2.1 → treeig-0.2.2}/docs/concepts.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Understand TreeIG numerical conventions, path crossings, and completeness."
+---
+
 # Attribution and interpretation
 
 ## Why TreeIG?

{treeig-0.2.1 → treeig-0.2.2}/docs/conf.py

@@ -8,7 +8,7 @@ project = "TreeIG"
 author = "Ludger Hentschel"
 copyright = "2026, Ludger Hentschel"
 release = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]["version"]
-extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.mathjax"]
+extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.mathjax", "sphinx_sitemap"]
 myst_enable_extensions = ["dollarmath"]
 myst_heading_anchors = 3
 exclude_patterns = ["_build"]
@@ -21,3 +21,9 @@ napoleon_google_docstring = False
 
 templates_path = ["_templates"]
 html_sidebars = {"**": ["documentation-nav.html"]}
+
+html_baseurl = "https://ludgerhentschel.github.io/treeig/"
+# Publish the single maintained repository index with the documentation.
+html_extra_path = ["../llms.txt"]
+sitemap_url_scheme = "{link}"
+sitemap_excludes = ["search.html", "genindex.html", "py-modindex.html"]

{treeig-0.2.1 → treeig-0.2.2}/docs/examples.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Run complete TreeIG examples for XGBoost regression and LightGBM multiclass margins."
+---
+
 # Worked examples
 
 These examples use synthetic data so they can run without downloading datasets.

{treeig-0.2.1 → treeig-0.2.2}/docs/explanations.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Interpret TreeIG feature contributions, classification targets, result shapes, and completeness diagnostics."
+---
+
 # Reading and plotting results
 
 ## Explanation objects and SHAP plots
@@ -78,8 +84,10 @@ ig = tig.TreeIG(model, baseline=x0, target=2)
 phi_class_2 = ig.attribute(X_eval)
 ```
 
-Exact TreeIG attributes raw class margins. TreeIGNumeric can use the explicit
-probability-derived score convention above when no native margin exists.
+Exact TreeIG attributes raw class margins. When no native margin exists,
+TreeIGNumeric defaults to binary log odds or centered multiclass log scores
+derived from probabilities. See [numerical classification conventions](numeric.md)
+for explicit floors at zero and the opt-in class-probability mode.
 
 ## Functional interface
 

{treeig-0.2.1 → treeig-0.2.2}/docs/getting-started.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Install TreeIG and run a complete regression example with fitted tree models, baseline inputs, and completeness checks."
+---
+
 # Getting started
 
 ## Installation

{treeig-0.2.1 → treeig-0.2.2}/docs/ig-stack.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Choose between TreeIG, UnifiedIG, CBaseline, and skgrad for tree paths, attribution, reference distributions, and input derivatives."
+---
+
 # The Integrated Gradients Stack
 
 | Package | Responsibility |
@@ -29,5 +35,5 @@ combine a score gradient with a probability-valued baseline prediction.
   evaluate analytic gradients, including supported preprocessing pipelines.
 - [TreeIG documentation](https://ludgerhentschel.github.io/treeig/):
   compute Integrated Gradients for supported tree models.
-- [UnifiedIG guide](https://github.com/LudgerHentschel/unifiedig/blob/main/docs/how-it-works.md):
+- [UnifiedIG guide](https://ludgerhentschel.github.io/unifiedig/how-it-works.html):
   select the attribution backend through a common interface.

treeig-0.2.2/docs/index.md

@@ -0,0 +1,106 @@
+---
+myst:
+  html_meta:
+    description: "TreeIG computes exact Integrated Gradients for supported numeric tree models, with weighted baselines and a separate numerical fallback."
+---
+
+# TreeIG documentation
+
+TreeIG is a Python package for Integrated Gradients feature attribution on
+supported numeric tree models. Install and import it as `treeig`. Given a fitted
+model, a baseline point or weighted background, and evaluation rows, `TreeIG`
+returns feature contributions and completeness diagnostics.
+
+**TreeIG computes exact Integrated Gradients for supported numeric tree models.
+A tree's gradient is zero almost everywhere; its integrated gradient is not.**
+
+Check [supported models](models.md) before choosing an interface.
+`TreeIG` uses exact structural split crossings; [TreeIGNumeric](numeric.md)
+is a separately selected numerical fallback. Exact classification explains raw
+margins or logits. Exact parsing requires finite numeric inputs and does not
+support categorical splits or missing-value routing. Installing the CatBoost
+extra does not add an exact CatBoost backend.
+
+Tree ensembles are piecewise constant, so $\nabla F = 0$ except on a
+measure-zero set of split boundaries. Numerical Integrated Gradients therefore
+recovers approximately nothing, which is why IG has largely been confined to
+differentiable models.
+
+The pointwise gradient is not the full derivative. In the distributional sense,
+$F'$ carries an impulse at each split boundary whose integral equals the
+prediction jump there.
+
+![A prediction step, its derivative impulse, and its integrated contribution](Figure_TreeGradient.svg)
+
+The top panel shows a single prediction step; the middle shows its derivative
+as an impulse at the split; the bottom shows the accumulated contribution.
+Integrating across the split recovers the prediction change.
+
+TreeIG enumerates the boundaries crossed by the straight-line path from baseline
+to observation, assigns each jump to its split feature, and sums across trees.
+No quadrature and no sampling are involved, and completeness
+
+$$\sum_j \phi_j = F(x) - F(x_0)$$
+
+holds to the floating-point precision of the fitted model's own arithmetic.
+Weighted baseline distributions are supported directly.
+
+The CPU `TreeIG` class is the main interface. Start with a runnable example,
+then choose the baseline distribution and output scale that express the
+comparison you want to explain.
+
+The method is developed in Ludger Hentschel's
+[**TreeIG: Exact Integrated Gradients for Tree-Based Models**](https://www.ludgerhentschel.com/PDFs/Hentschel%20'26g.pdf).
+It builds on Integrated Gradients introduced by Sundararajan, Taly, and Yan in
+[**Axiomatic Attribution for Deep Networks** (ICML 2017)](https://proceedings.mlr.press/v70/sundararajan17a.html).
+
+## Explore the guide
+
+For automated readers, [llms.txt](https://ludgerhentschel.github.io/treeig/llms.txt)
+maps the guides, complete examples, and rendered API reference.
+
+Read [getting started](getting-started.md), [baselines](baselines.md),
+[supported models](models.md), and [worked examples](examples.md) first.
+For more detail, see [results and plotting](explanations.md),
+[loss attribution](loss.md), [numerical conventions](concepts.md),
+[TreeIGNumeric](numeric.md), and [performance](performance.md).
+
+## Related projects
+
+| Package | When to use it |
+|---|---|
+| [UnifiedIG](https://ludgerhentschel.github.io/unifiedig/) (`unifiedig`) | A common Integrated Gradients interface across supported tree and smooth model families. |
+| [CBaseline](https://ludgerhentschel.github.io/cbaseline/) (`cbaseline`) | Construct empirical reference distributions; TreeIG accepts its backgrounds with their weights directly. |
+| [skgrad](https://ludgerhentschel.github.io/skgrad/) (`skgrad`) | Obtain analytic input gradients and Jacobians for supported smooth scikit-learn models. |
+
+Use TreeIG directly when you need its tree-specific attribution interface.
+See [the Integrated Gradients stack](https://ludgerhentschel.github.io/treeig/ig-stack.html)
+for how the packages compose and why output scales must agree.
+
+```{toctree}
+:maxdepth: 2
+:caption: User guide
+
+getting-started
+examples
+baselines
+models
+explanations
+loss
+concepts
+numeric
+performance
+comparison
+gpu
+ig-stack
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Reference
+
+api
+references
+building
+publishing
+```

{treeig-0.2.1 → treeig-0.2.2}/docs/models.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Check exact TreeIG model support, classification margins, parser restrictions, and models requiring TreeIGNumeric."
+---
+
 # Supported models
 
 TreeIG currently supports tree models with finite numeric feature inputs.

{treeig-0.2.1 → treeig-0.2.2}/docs/numeric.md

@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Use TreeIGNumeric for explicit numerical jump detection and understand probability outputs, score conversion, and resolution limits."
+---
+
 # TreeIGNumeric
 
 TreeIGNumeric is a model-agnostic fallback that recovers the crossing-sum
@@ -36,10 +42,10 @@ Two caveats on coverage:
   feature along the straight-line path is not meaningful, which is a property of
   Integrated Gradients itself, not of the implementation. TreeIGNumeric works on
   CatBoost (and similar) models with numeric or one-hot-encoded inputs.
-- **Probability-averaging classifiers.** By default, TreeIGNumeric retains its
-  original behavior and explains one class probability. With
-  `probability_to_score=True`, it instead explains binary log odds or a
-  centered multiclass log score. Zero probabilities require an explicit
+- **Probability-averaging classifiers.** By default, TreeIGNumeric explains
+  binary log odds or a centered multiclass log score derived from the complete
+  probability vector (`probability_to_score=True`). Class-probability
+  attribution requires explicit `probability_to_score=False`. Zero probabilities require an explicit
   `probability_floor`; TreeIGNumeric never clips them silently.
 
 ```python
@@ -60,7 +66,7 @@ ig = tig.TreeIGNumeric(
     model,
     baseline=x0,
     target=2,                    # omit for binary positive-class log odds
-    probability_to_score=True,
+    # Score conversion is the default when no native margin exists.
     probability_floor=1e-6,     # explicit because tree probabilities may be 0
 )
 phi = ig.attribute(X_eval)
@@ -102,3 +108,14 @@ Bundling may change the feature allocation, and offsetting jumps inside a cell
 can remain invisible even with a zero residual. These are allocation limitations,
 not reasons to require exhaustive refinement or replace event detection with
 generic numerical Integrated Gradients.
+
+## Compatibility with earlier releases
+
+Previously, probability-only classifiers defaulted to class-probability
+attribution. The default now explains scores. Existing callers that require the
+previous probability-valued result must pass `probability_to_score=False`
+explicitly. This option affects only classifiers without a native margin;
+models exposing native scores continue to explain those scores. Zero class
+probabilities now raise by default during score evaluation unless an explicit
+`probability_floor` defines finite scores. Reconstruct background reference
+outputs on the same scale as the explainer before comparing attributions.