licketysplit 0.1.0__tar.gz

licketysplit-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include pyproject.toml
+include setup.py
+include setup.cfg
+
+recursive-include src/licketysplit *.py
+recursive-include src/licketysplit *.cpp
+recursive-include src/licketysplit *.hpp
+recursive-include src/licketysplit *.h
+recursive-include src/licketysplit/cpp *.cpp
+recursive-include src/licketysplit/cpp *.hpp
+recursive-include src/licketysplit/cpp *.h

licketysplit-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: licketysplit
+Version: 0.1.0
+Summary: Near-optimal decision trees via LicketySPLIT
+Author: Varun Babbar, Hayden McTavish, Zakk Heile, Margo Seltzer, Cynthia Rudin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zakk-h/LicketySPLIT
+Project-URL: Repository, https://github.com/zakk-h/LicketySPLIT
+Project-URL: Issues, https://github.com/zakk-h/LicketySPLIT/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: pandas>=1.5
+
+# LicketySPLIT
+
+Near-optimal decision tree learning via LicketySPLIT.
+
+# LicketySPLIT
+
+LicketySPLIT is a Python package with a C++ backend for learning sparse decision trees for classification. It builds on the LicketySPLIT algorithm from [Near Optimal Decision Trees in a SPLIT Second](https://arxiv.org/abs/2502.15988) and generalizes it with recursive pilot ideas as in [From Rashomon Theory to PRAXIS: Efficient Decision Tree Rashomon Sets](https://arxiv.org/abs/2606.00202).
+
+The package supports binary and multi-class classification, optional sample weights, efficient subproblem caching, and threshold-based binarization for continuous features.
+
+See the example notebook [here.](https://github.com/zakk-h/LicketySPLIT/blob/main/example.ipynb)
+
+## Objective
+
+LicketySPLIT learns a sparse decision tree by attempting to minimize a regularized empirical training objective.
+
+For an unweighted dataset with `n` training samples, the objective is
+
+```text
+objective(tree) = training_mistakes(tree) + lambda_leaf * n * number_of_leaves(tree)
+```
+
+where:
+
+- `training_mistakes(tree)` is the number of training samples misclassified by the tree
+- `number_of_leaves(tree)` is the number of leaves in the tree
+- `lambda_leaf` is the leaf regularization parameter
+- `n` is the number of training samples
+
+For a weighted dataset, `n` is replaced with the sum of weights and the `training_mistakes(tree)` penalizes incorrect points by their weight instead of by 1.
+
+## Classification setting
+
+Labels should be encoded as contiguous nonnegative integers:
+
+```python
+0, 1, 2, ..., num_classes - 1
+```
+
+## Features
+
+LicketySPLIT expects binary input features. For continuous data, use `ThresholdGuessBinarizer` to generate binary threshold features.
+
+```python
+from licketysplit import ThresholdGuessBinarizer
+
+binarizer = ThresholdGuessBinarizer(
+    learning_rate=0.1,
+    n_estimators=100,
+    max_depth=3,
+    random_state=0,
+    column_elimination=False,
+)
+
+X_train_bin = binarizer.fit_transform(X_train_raw, y_train)
+X_test_bin = binarizer.transform(X_test_raw)
+
+feature_names = binarizer.get_feature_names_out()
+```
+
+Each generated feature has the form
+
+```text
+original_feature <= threshold
+```
+
+## Basic usage
+
+```python
+from licketysplit import LicketySPLIT
+
+model = LicketySPLIT(
+    cache_mode="fingerprint",
+    cost_caching_enabled=True,
+)
+
+model.fit(
+    X_train_bin,
+    y_train,
+    lambda_leaf=0.001,
+    depth_budget=6,
+    lookahead_k=1,
+)
+
+y_pred = model.predict(X_test_bin)
+```
+
+## Full example
+
+A complete notebook showing loading data, binarization, fitting, prediction, tree inspection, plotting, caching, and sample weights is available [here](https://github.com/zakk-h/LicketySPLIT/blob/main/example.ipynb).
+
+## References
+
+This package builds on the LicketySPLIT algorithm from:
+
+[Near Optimal Decision Trees in a SPLIT Second](https://arxiv.org/abs/2502.15988)
+
+and generalizes it with a pilot algorithm approach as in:
+
+[From Rashomon Theory to PRAXIS: Efficient Decision Tree Rashomon Sets](https://arxiv.org/abs/2606.00202)

licketysplit-0.1.0/README.md

@@ -0,0 +1,100 @@
+# LicketySPLIT
+
+Near-optimal decision tree learning via LicketySPLIT.
+
+# LicketySPLIT
+
+LicketySPLIT is a Python package with a C++ backend for learning sparse decision trees for classification. It builds on the LicketySPLIT algorithm from [Near Optimal Decision Trees in a SPLIT Second](https://arxiv.org/abs/2502.15988) and generalizes it with recursive pilot ideas as in [From Rashomon Theory to PRAXIS: Efficient Decision Tree Rashomon Sets](https://arxiv.org/abs/2606.00202).
+
+The package supports binary and multi-class classification, optional sample weights, efficient subproblem caching, and threshold-based binarization for continuous features.
+
+See the example notebook [here.](https://github.com/zakk-h/LicketySPLIT/blob/main/example.ipynb)
+
+## Objective
+
+LicketySPLIT learns a sparse decision tree by attempting to minimize a regularized empirical training objective.
+
+For an unweighted dataset with `n` training samples, the objective is
+
+```text
+objective(tree) = training_mistakes(tree) + lambda_leaf * n * number_of_leaves(tree)
+```
+
+where:
+
+- `training_mistakes(tree)` is the number of training samples misclassified by the tree
+- `number_of_leaves(tree)` is the number of leaves in the tree
+- `lambda_leaf` is the leaf regularization parameter
+- `n` is the number of training samples
+
+For a weighted dataset, `n` is replaced with the sum of weights and the `training_mistakes(tree)` penalizes incorrect points by their weight instead of by 1.
+
+## Classification setting
+
+Labels should be encoded as contiguous nonnegative integers:
+
+```python
+0, 1, 2, ..., num_classes - 1
+```
+
+## Features
+
+LicketySPLIT expects binary input features. For continuous data, use `ThresholdGuessBinarizer` to generate binary threshold features.
+
+```python
+from licketysplit import ThresholdGuessBinarizer
+
+binarizer = ThresholdGuessBinarizer(
+    learning_rate=0.1,
+    n_estimators=100,
+    max_depth=3,
+    random_state=0,
+    column_elimination=False,
+)
+
+X_train_bin = binarizer.fit_transform(X_train_raw, y_train)
+X_test_bin = binarizer.transform(X_test_raw)
+
+feature_names = binarizer.get_feature_names_out()
+```
+
+Each generated feature has the form
+
+```text
+original_feature <= threshold
+```
+
+## Basic usage
+
+```python
+from licketysplit import LicketySPLIT
+
+model = LicketySPLIT(
+    cache_mode="fingerprint",
+    cost_caching_enabled=True,
+)
+
+model.fit(
+    X_train_bin,
+    y_train,
+    lambda_leaf=0.001,
+    depth_budget=6,
+    lookahead_k=1,
+)
+
+y_pred = model.predict(X_test_bin)
+```
+
+## Full example
+
+A complete notebook showing loading data, binarization, fitting, prediction, tree inspection, plotting, caching, and sample weights is available [here](https://github.com/zakk-h/LicketySPLIT/blob/main/example.ipynb).
+
+## References
+
+This package builds on the LicketySPLIT algorithm from:
+
+[Near Optimal Decision Trees in a SPLIT Second](https://arxiv.org/abs/2502.15988)
+
+and generalizes it with a pilot algorithm approach as in:
+
+[From Rashomon Theory to PRAXIS: Efficient Decision Tree Rashomon Sets](https://arxiv.org/abs/2606.00202)

licketysplit-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = [
+  "setuptools>=64",
+  "wheel",
+  "pybind11>=2.13",
+  "numpy>=1.23"
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "licketysplit"
+version = "0.1.0"
+description = "Near-optimal decision trees via LicketySPLIT"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Varun Babbar" },
+  { name = "Hayden McTavish" },
+  { name = "Zakk Heile" },
+  { name = "Margo Seltzer" },
+  { name = "Cynthia Rudin" }
+]
+dependencies = [
+  "numpy>=1.23",
+  "matplotlib>=3.6",
+  "scikit-learn>=1.1",
+  "pandas>=1.5"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: C++",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/zakk-h/LicketySPLIT"
+Repository = "https://github.com/zakk-h/LicketySPLIT"
+Issues = "https://github.com/zakk-h/LicketySPLIT/issues"

licketysplit-0.1.0/setup.cfg

@@ -0,0 +1,16 @@
+[metadata]
+name = licketysplit
+
+[options]
+package_dir = 
+	= src
+packages = find:
+include_package_data = True
+
+[options.packages.find]
+where = src
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

licketysplit-0.1.0/setup.py

@@ -0,0 +1,96 @@
+import os
+import platform
+from setuptools import setup, Extension
+from setuptools.command.build_ext import build_ext
+import pybind11
+
+
+def is_truthy_env(name: str) -> bool:
+    return os.environ.get(name, "").lower() in ("1", "true", "yes", "on")
+
+
+class BuildExt(build_ext):
+    c_opts = {
+        "msvc": [
+            "/O2",
+            "/std:c++17",
+        ],
+        "unix": [
+            "-O3",
+            "-DNDEBUG",
+            "-funroll-loops",
+        ],
+    }
+
+    l_opts = {
+        "msvc": [],
+        "unix": [],
+    }
+
+    def build_extensions(self):
+        ct = self.compiler.compiler_type
+        system = platform.system().lower()
+        machine = platform.machine().lower()
+
+        opts = self.c_opts.get(ct, []).copy()
+        link_opts = self.l_opts.get(ct, []).copy()
+
+        if ct == "unix":
+            opts += ["-std=c++17", "-fPIC"]
+
+            if system != "darwin":
+                opts += ["-flto"]
+                link_opts += ["-flto", "-lm"]
+
+            if machine in ("x86_64", "amd64"):
+                opts += ["-mpopcnt"]
+                print("** Building LicketySPLIT with x86 POPCNT support")
+            elif machine in ("arm64", "aarch64"):
+                print("** Building LicketySPLIT on ARM64; skipping x86 -mpopcnt")
+            else:
+                print(f"** Building LicketySPLIT on unknown Unix arch {machine}; skipping popcount-specific flags")
+
+        elif ct == "msvc":
+            print("** Building LicketySPLIT with MSVC safe flags")
+
+        aggressive = is_truthy_env("AGGRESSIVE")
+
+        if aggressive and ct == "unix":
+            if machine in ("x86_64", "amd64"):
+                opts += [
+                    "-mbmi",
+                    "-mbmi2",
+                    "-mavx2",
+                ]
+                print("** Building LicketySPLIT with additional aggressive x86 flags")
+            elif machine in ("arm64", "aarch64"):
+                print("** AGGRESSIVE requested on ARM64; no extra portable flags added")
+        elif aggressive and ct != "unix":
+            print("** AGGRESSIVE requested on non-Unix compiler; using safe flags")
+
+        for ext in self.extensions:
+            ext.extra_compile_args = opts
+            ext.extra_link_args = link_opts
+
+        build_ext.build_extensions(self)
+
+
+ext_modules = [
+    Extension(
+        "licketysplit._core",
+        sources=[
+            "src/licketysplit/_core.cpp",
+        ],
+        include_dirs=[
+            pybind11.get_include(),
+            "src/licketysplit/cpp",
+        ],
+        language="c++",
+    ),
+]
+
+
+setup(
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": BuildExt},
+)