Skip to content

Add kernel-vs-legacy uplift tree parity notebook (#945) - #969

Merged
jeongyoonlee merged 1 commit into
masterfrom
feature/945-parity-notebook
Jul 24, 2026
Merged

Add kernel-vs-legacy uplift tree parity notebook (#945)#969
jeongyoonlee merged 1 commit into
masterfrom
feature/945-parity-notebook

Conversation

@jeongyoonlee

Copy link
Copy Markdown
Collaborator

What

Adds docs/examples/uplift_tree_kernel_parity.ipynb, a validation notebook for the tree-unification epic (#945) that demonstrates the experimental kernel-backed uplift trees reproduce the legacy implementation numerically.

The notebook shows, with executed outputs, that _KernelUpliftTreeClassifier / _KernelUpliftRandomForestClassifier match UpliftTreeClassifier / UpliftRandomForestClassifier bit-for-bit (max abs difference 0.0) on:

  • Single-tree criteria — KL / ED / Chi (multi-treatment) and DDP / IT / CIT / IDDP (single treatment; IDDP forces the honest approach)
  • Regularization + normalization and the honest approach
  • Whole-forest predictions

plus a fit-time speed comparison (kernel ~3x faster on the sampled data).

The last section makes the parity conditions concrete: on genuinely continuous features the two diverge because they search different split grids, but discretizing the same features restores exact parity — confirming the difference is only the split-candidate grid, not the criterion math.

Notes

  • Parity requires binary/low-cardinality features and legacy_max_depth = kernel_max_depth + 1 (both explained in the notebook).
  • The kernel classes remain experimental and private (underscore-prefixed); they are imported here only to demonstrate parity. The public classes are switched over to the kernel later in the epic ([Tree unification 9/9] Switchover + delete legacy uplift.pyx + deprecations #955).
  • Wires the notebook into the docs examples toctree (docs/examples.rst).
  • CI does not execute notebooks; committed outputs are what render in the docs.

@jeongyoonlee jeongyoonlee added the refactoring Code refactoring label Jul 24, 2026
@jeongyoonlee
jeongyoonlee marked this pull request as ready for review July 24, 2026 22:54
Add docs/examples/uplift_tree_kernel_parity.ipynb demonstrating that the
experimental kernel-backed uplift tree and forest reproduce the legacy
UpliftTreeClassifier / UpliftRandomForestClassifier numerically:

- single-tree parity across KL / ED / Chi and DDP / IT / CIT / IDDP
- tree visualization: legacy and kernel trees render through the same
  plot.uplift_tree_plot (issue #953)
- regularization, normalization, and the honest approach
- whole-forest parity, plus a fit-time speed comparison
- continuous features diverge (different split grids); discretizing them
  restores exact parity, showing the difference is only the candidate grid

Wire the notebook into the docs examples toctree.
@jeongyoonlee
jeongyoonlee force-pushed the feature/945-parity-notebook branch from 4dc366a to 4945f0e Compare July 24, 2026 23:05
@jeongyoonlee
jeongyoonlee merged commit dfe4680 into master Jul 24, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactoring Code refactoring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant