bettertrees 0.1.0__py3-none-any.whl

bettertrees/__init__.py

@@ -0,0 +1,57 @@
+"""Small, readable sums of trees for binary classification, under a budget of cuts.
+
+- ``BudgetClassifier(max_splits=b)``: the recommended start, no tuning: the Interleaved
+  Tree Model with the fixed rule of the benchmark for a budget of b cuts.
+- ``InterleavedTreeClassifier`` (the Interleaved Tree Model, ITM): a logit sum of small
+  trees; each step adds the best cut of any tree (or a new root) by Newton gain and
+  re-fits all leaves. Growth from FIGS (Tan et al., 2022), re-fit from RGF.
+  ``FIGSClassifier`` is an alias (the same class under its older name).
+- ``FastDecisionTreeClassifier`` / ``FastDecisionTreeClassifierCV``: a single tree
+  (exact and histogram engines), with leaf count and shrinkage chosen by CV.
+- ``SumOfOptimalTrees``: a logit sum of a few Newton-optimal trees (depth 1-3).
+- ``CompactTreeBooster``: shrunken boosting of optimal trees counted in distinct
+  cuts (identical trees merged).
+- ``AdditiveTreeBooster``: a long sum of optimal depth-1/2 trees with early stopping.
+- ``LightGBMRefitClassifier`` / ``from_lightgbm``: a LightGBM model imported as an
+  editable sum, with its leaves refitted jointly.
+
+The sums (binary classification) expose ``rules()``, ``explain()``, ``to_dict()``,
+``predict_contributions()``, ``plot_shapes()``, ``plot_contributions()`` and the
+editing API; the single tree is multiclass and has ``export_text()``.
+``bettertrees.experimental`` has no API stability guarantee; ``bettertrees.lab`` holds
+research code with negative or inconclusive results (no API, no stability, not public).
+"""
+
+from .autotune import FastDecisionTreeClassifierCV
+from .estimator import FastDecisionTreeClassifier
+from .sums import (
+    AdditiveTreeBooster,
+    BudgetClassifier,
+    CompactTreeBooster,
+    FIGSClassifier,
+    InterleavedTreeClassifier,
+    LightGBMRefitClassifier,
+    SumOfOptimalTrees,
+    from_lightgbm,
+)
+
+__version__ = "0.1.0"
+
+__all__ = ["AdditiveTreeBooster", "BudgetClassifier",
+           "CompactTreeBooster", "FIGSClassifier", "FastDecisionTreeClassifier",
+           "FastDecisionTreeClassifierCV", "InterleavedTreeClassifier", "LightGBMRefitClassifier",
+           "SumOfOptimalTrees", "__version__", "from_lightgbm"]
+
+
+# moved to bettertrees.lab; still importable from here, resolved on first use (kept for
+# the benchmark)
+_MOVED = {"BaggedFIGSClassifier": "robust", "RashomonFIGSClassifier": "robust",
+          "fit_multilevel_tree": "multilevel"}
+
+
+def __getattr__(name):
+    if name in _MOVED:
+        from importlib import import_module
+
+        return getattr(import_module(f".lab.{_MOVED[name]}", __name__), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

bettertrees/_data.py

@@ -0,0 +1,115 @@
+"""Node containers and input validation; no Numba here.
+
+``NodeArrays`` and ``Split`` only group arrays/scalars: there is no object per
+node. Validation converts X to C-contiguous float32 and drops zero-weight rows
+before any binning, support count or split.
+"""
+
+from typing import NamedTuple
+
+import numpy as np
+from sklearn.utils.multiclass import check_classification_targets
+
+
+class NodeArrays(NamedTuple):
+    """Contiguous arrays; root 0, children -1 at leaves, feature -1 at leaves.
+
+    Each position identifies a node. class_weight has shape (capacity, K) and
+    holds per-class masses, not probabilities. No published leaf may have zero
+    total mass. threshold is float64; X is float32. The builder returns the
+    arrays trimmed to the nodes actually used.
+    """
+
+    left: np.ndarray
+    right: np.ndarray
+    feature: np.ndarray
+    threshold: np.ndarray
+    missing_left: np.ndarray
+    class_weight: np.ndarray
+    n_samples: np.ndarray
+
+
+class Split(NamedTuple):
+    """Best cut: feature=-1 means there is no admissible cut.
+
+    gain is the LOCAL Gini decrease; the builder weights it by the mass
+    relative to the root when applying min_impurity_decrease. threshold is
+    always on the original scale; bin_threshold=-1 in the exact engine. n_left
+    counts active rows regardless of the magnitude of their positive weights.
+    """
+
+    feature: int
+    threshold: float
+    missing_left: bool
+    gain: float
+    n_left: int
+    bin_threshold: int
+
+
+def validate_X(X, *, n_features=None):
+    """Convert a dense numeric matrix to C-contiguous float32, allowing NaN.
+
+    Rejects empty, complex, infinite (including conversion overflow) and sparse
+    inputs and a wrong number of columns. Does not modify the argument. Its
+    cost is part of the fit/predict time of the public API.
+    """
+    raw = np.asarray(X)
+    if raw.ndim != 2 or 0 in raw.shape or raw.dtype.kind not in "biuf":
+        raise ValueError("X must be a non-empty dense numeric array.")
+    with np.errstate(over="ignore", invalid="ignore"):
+        out = np.ascontiguousarray(raw, dtype=np.float32)
+    if np.isinf(out).any():
+        raise ValueError("X cannot contain infinity or values outside the float32 range.")
+    if n_features is not None and out.shape[1] != n_features:
+        raise ValueError("The number of columns differs from training.")
+    return out
+
+
+def prepare_training_data(X, y, sample_weight=None):
+    """Validate training data and return (X32, y_int32, weights64, original_classes).
+
+    Accepts a one-dimensional binary/multiclass target, including strings.
+    classes follows np.unique; its index breaks ties at prediction. Weights
+    must be finite, non-negative, aligned and have a positive sum. Zero-weight
+    rows take no part in bins, minimum support or splits; classes_ keeps every
+    class observed before that exclusion. The inputs are never modified and
+    no holdout is used.
+    """
+    X = validate_X(X)
+    target = np.asarray(y)
+    if target.ndim != 1 or len(target) != len(X):
+        raise ValueError("y must have one label per row of X.")
+    check_classification_targets(target)
+    classes, encoded = np.unique(target, return_inverse=True)
+    weights = (np.ones(len(X), dtype=np.float64) if sample_weight is None
+               else np.asarray(sample_weight, dtype=np.float64))
+    if weights.shape != (len(X),) or not np.isfinite(weights).all():
+        raise ValueError("sample_weight deve ser um vetor finito alinhado a X.")
+    if (weights < 0).any() or not (weights > 0).any():
+        raise ValueError("Sample weights must be non-negative with a positive sum.")
+    if not np.isfinite(weights.sum()):
+        raise ValueError("The sum of the weights exceeds the float64 range.")
+    active = weights > 0
+    if not active.all():
+        X, encoded, weights = X[active], encoded[active], weights[active]
+    return (np.ascontiguousarray(X), np.ascontiguousarray(encoded, dtype=np.int32),
+            np.ascontiguousarray(weights), classes)
+
+
+def allocate_nodes(capacity, n_classes):
+    """Allocate node arrays for an UNTRAINED tree, all nodes initially leaves.
+
+    The builder starts small, grows the arrays geometrically and fills the
+    masses before publishing the tree; it avoids allocating 2**max_depth up front.
+    """
+    if capacity < 1 or n_classes < 1:
+        raise ValueError("capacity e n_classes devem ser positivos.")
+    return NodeArrays(
+        np.full(capacity, -1, dtype=np.int32),
+        np.full(capacity, -1, dtype=np.int32),
+        np.full(capacity, -1, dtype=np.int32),
+        np.full(capacity, np.nan, dtype=np.float64),
+        np.zeros(capacity, dtype=np.bool_),
+        np.zeros((capacity, n_classes), dtype=np.float64),
+        np.zeros(capacity, dtype=np.int64),
+    )

bettertrees/_typing.py

@@ -0,0 +1,20 @@
+"""Small shared aliases for the public API; no pandas or plotting dependencies.
+
+ArrayLike covers NumPy arrays, sequences and objects exposing __array__, including
+pandas DataFrames/Series. Shapes and column semantics are validated at runtime.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, TypeAlias, TypeVar
+
+import numpy as np
+from numpy.typing import ArrayLike as ArrayLike
+from numpy.typing import NDArray
+
+FloatArray: TypeAlias = NDArray[np.float64]
+LabelArray: TypeAlias = NDArray[Any]
+IndexArray: TypeAlias = NDArray[np.intp]
+FeatureNames: TypeAlias = Sequence[str] | NDArray[Any]
+Seed: TypeAlias = int | None
+MonotoneConstraints: TypeAlias = Mapping[int | str, int]
+SelfT = TypeVar("SelfT")

bettertrees/autotune.py

@@ -0,0 +1,193 @@
+"""Choice of capacity and shrinkage by internal cross-validation.
+
+A best-first tree with L leaves is the prefix of the first L-1 expansions of
+the tree with L_max leaves: the expansion order does not depend on the budget.
+So each inner fold needs ONE fit (with L_max); every capacity and every lambda
+of hierarchical shrinkage is scored on it. The final choice is refitted on the
+full training set with the winning parameters.
+
+References
+----------
+Agarwal, Tan, Ronen, Singh, Yu. "Hierarchical Shrinkage: Improving the Accuracy
+and Interpretability of Tree-Based Methods." ICML 2022 (the leaf shrinkage).
+Friedman, Hastie, Tibshirani. "Additive logistic regression: a statistical view
+of boosting." Annals of Statistics, 2000 (best-first growth by gain).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from numbers import Integral, Real
+from typing import Literal
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.model_selection import StratifiedKFold
+from sklearn.utils.validation import check_is_fitted
+
+from ._data import prepare_training_data
+from ._typing import ArrayLike, FeatureNames, FloatArray, IndexArray, LabelArray, Seed, SelfT
+from .estimator import FastDecisionTreeClassifier
+from .postprocess import expansion_steps, hierarchical_shrinkage_probabilities, prefix_leaf_ids
+
+# Wide grid: tuned sklearn + HS often picks > 256 leaves and lambda > 200;
+# stopping at 256/200 cost 0.7% log-loss in the benchmark.
+# Leaves beyond n/min_samples_leaf are never reached, so small n pays nothing.
+DEFAULT_LEAVES = (4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096)
+DEFAULT_SHRINKAGE = (1.0, 5.0, 20.0, 50.0, 200.0, 500.0, 1000.0)
+
+
+def _log_loss(y, proba, weights):
+    picked = np.clip(proba[np.arange(len(y)), y], 1e-15, 1.0)
+    return float(-np.average(np.log(picked), weights=weights))
+
+
+class FastDecisionTreeClassifierCV(ClassifierMixin, BaseEstimator):
+    """Best-first tree whose number of leaves and shrinkage are chosen by CV.
+
+    Parameters
+    ----------
+    leaves_grid : sequence of int >= 2
+        Candidate capacities (maximum number of leaves).
+    shrinkage_grid : sequence of float > 0
+        Candidate ``leaf_shrinkage`` values.
+    cv : int >= 2
+        Stratified inner folds; the criterion is the validation log-loss.
+        Each class with positive sample weight needs at least ``cv`` rows.
+        Zero-weight rows do not enter the inner folds; the final tree retains
+        all classes observed in ``y``.
+    min_samples_leaf, splitter, max_bins, n_jobs, random_state
+        Passed to ``FastDecisionTreeClassifier`` (no pruning: truncating by
+        prefix needs node ids in expansion order).
+
+    Attributes
+    ----------
+    best_params_ : dict
+        The chosen ``max_leaf_nodes`` and ``leaf_shrinkage``.
+    best_estimator_ : FastDecisionTreeClassifier
+        The tree refitted on all rows with ``best_params_``.
+    cv_scores_ : ndarray of shape (len(leaves_grid), len(shrinkage_grid))
+        Mean validation log-loss of each pair.
+    classes_, n_features_in_, feature_names_in_
+        As in ``best_estimator_``.
+
+    Examples
+    --------
+    >>> from sklearn.datasets import load_breast_cancer
+    >>> from bettertrees import FastDecisionTreeClassifierCV
+    >>> X, y = load_breast_cancer(return_X_y=True)
+    >>> tree = FastDecisionTreeClassifierCV(leaves_grid=(4, 8), shrinkage_grid=(1.0, 10.0))
+    >>> sorted(tree.fit(X, y).best_params_)
+    ['leaf_shrinkage', 'max_leaf_nodes']
+    """
+
+    classes_: LabelArray
+    n_features_in_: int
+    feature_names_in_: LabelArray
+    cv_scores_: FloatArray
+    best_params_: dict[str, int | float]
+    best_estimator_: FastDecisionTreeClassifier
+
+    def __init__(self, *, leaves_grid: Sequence[int] = DEFAULT_LEAVES,
+                 shrinkage_grid: Sequence[float] = DEFAULT_SHRINKAGE, cv: int = 3,
+                 min_samples_leaf: int = 5, splitter: Literal["hist", "exact"] = "hist",
+                 max_bins: int = 255, n_jobs: int = 1, random_state: Seed = 0) -> None:
+        self.leaves_grid = leaves_grid
+        self.shrinkage_grid = shrinkage_grid
+        self.cv = cv
+        self.min_samples_leaf = min_samples_leaf
+        self.splitter = splitter
+        self.max_bins = max_bins
+        self.n_jobs = n_jobs
+        self.random_state = random_state
+
+    def _tree(self, **extra):
+        return FastDecisionTreeClassifier(
+            splitter=self.splitter, min_samples_leaf=self.min_samples_leaf,
+            max_bins=self.max_bins, n_jobs=self.n_jobs,
+            random_state=self.random_state, **extra)
+
+    def fit(self: SelfT, X: ArrayLike, y: ArrayLike,
+            sample_weight: ArrayLike | None = None) -> SelfT:
+        try:
+            leaves = list(self.leaves_grid)
+        except TypeError as exc:
+            raise ValueError("leaves_grid must contain integers >= 2.") from exc
+        if not leaves or any(isinstance(v, bool | np.bool_)
+                             or not isinstance(v, Integral) or v < 2 for v in leaves):
+            raise ValueError("leaves_grid must contain integers >= 2.")
+        try:
+            shrinkage = list(self.shrinkage_grid)
+        except TypeError as exc:
+            raise ValueError("shrinkage_grid must contain finite values > 0.") from exc
+        if not shrinkage or any(isinstance(v, bool | np.bool_)
+                                or not isinstance(v, Real)
+                                or not np.isfinite(v) or v <= 0 for v in shrinkage):
+            raise ValueError("shrinkage_grid must contain finite values > 0.")
+        if (isinstance(self.cv, bool | np.bool_)
+                or not isinstance(self.cv, Integral) or self.cv < 2):
+            raise ValueError("cv must be an integer >= 2.")
+        leaves = sorted({int(v) for v in leaves})
+        shrinkage = sorted({float(v) for v in shrinkage})
+        self._tree()._validate_parameters()
+        X_input = X  # the final fit gets the original input, so it keeps the column names
+        y_input = y
+        X, encoded, weights, classes = prepare_training_data(X, y, sample_weight)
+        counts = np.bincount(encoded, minlength=len(classes))
+        if np.any(counts[counts > 0] < self.cv):
+            raise ValueError(
+                "Each class with positive sample weight must have at least cv rows.")
+        y = classes[encoded]
+        scores = np.zeros((len(leaves), len(shrinkage)))
+        folds = StratifiedKFold(n_splits=int(self.cv), shuffle=True,
+                                random_state=self.random_state)
+        for fit_rows, val_rows in folds.split(X, encoded):
+            model = self._tree(max_leaf_nodes=leaves[-1]).fit(
+                X[fit_rows], y[fit_rows], sample_weight=weights[fit_rows])
+            nodes = model.nodes_
+            steps = expansion_steps(nodes)
+            # Classes missing from the inner fold: column with probability ~0.
+            columns = np.searchsorted(classes, model.classes_)
+            X_val = model._validate_predict_X(X[val_rows])
+            y_val, w_val = encoded[val_rows], weights[val_rows]
+            node_probs = []
+            for lam in shrinkage:
+                inner = hierarchical_shrinkage_probabilities(nodes, lam)
+                full = np.full((len(inner), len(classes)), 1e-15)
+                full[:, columns] = inner
+                node_probs.append(full)
+            for i, n_leaves in enumerate(leaves):
+                ids = prefix_leaf_ids(X_val, nodes, steps, n_leaves)
+                for j, probs in enumerate(node_probs):
+                    scores[i, j] += _log_loss(y_val, probs[ids], w_val) / int(self.cv)
+        i, j = np.unravel_index(int(np.argmin(scores)), scores.shape)
+        best_params = dict(max_leaf_nodes=leaves[i], leaf_shrinkage=shrinkage[j])
+        best_estimator = self._tree(**best_params).fit(
+            X_input, y_input, sample_weight=sample_weight)
+        self.best_params_, self.cv_scores_ = best_params, scores
+        self.best_estimator_ = best_estimator
+        self.classes_ = self.best_estimator_.classes_
+        self.n_features_in_ = self.best_estimator_.n_features_in_
+        # the inner tree validates names at predict time; mirror them here (sklearn contract)
+        if hasattr(self.best_estimator_, "feature_names_in_"):
+            self.feature_names_in_ = self.best_estimator_.feature_names_in_
+        else:
+            self.__dict__.pop("feature_names_in_", None)
+        return self
+
+    def predict_proba(self, X: ArrayLike) -> FloatArray:
+        check_is_fitted(self, "best_estimator_")
+        return self.best_estimator_.predict_proba(X)
+
+    def predict(self, X: ArrayLike) -> LabelArray:
+        check_is_fitted(self, "best_estimator_")
+        return self.best_estimator_.predict(X)
+
+    def apply(self, X: ArrayLike) -> IndexArray:
+        check_is_fitted(self, "best_estimator_")
+        return self.best_estimator_.apply(X)
+
+    def export_text(self, feature_names: FeatureNames | None = None, precision: int = 4) -> str:
+        """The selected tree as text (see ``FastDecisionTreeClassifier.export_text``)."""
+        check_is_fitted(self, "best_estimator_")
+        return self.best_estimator_.export_text(feature_names, precision)

bettertrees/bins.py

@@ -0,0 +1,247 @@
+"""Learning and applying bin edges (NaN -> bin 0).
+
+Quantile histograms follow the approach popularized by LightGBM (Ke et al.,
+NeurIPS 2017) and scikit-learn's HistGradientBoosting: at most 255 bins per
+feature, missing values in a dedicated bin.
+
+Numba kernels in this module do not call kernels from other modules: Numba's
+cache is invalidated per file and does not track cross-module dependencies.
+"""
+
+from concurrent.futures import ThreadPoolExecutor
+
+import numpy as np
+from numba import njit, prange
+
+
+def _count_balanced_cut_positions(counts, max_bins):
+    """Positions i (a cut between the i-th and the (i+1)-th distinct value).
+
+    Pure quantiles waste the budget when a few values hold most of the mass:
+    several quantiles fall on the same value, ``unique`` merges them, and the
+    tail of distinct values gets few bins. Here, values whose count is at least
+    the average mass per free bin get their own bins (iterating, since each
+    one frees budget), and the rest is split by count among the runs of light
+    values between them. Without ties (all counts 1) this reproduces
+    equal-count bins, like quantiles.
+    """
+    n_values = len(counts)
+    heavy = np.zeros(n_values, dtype=bool)
+    while True:
+        free_bins = max_bins - int(heavy.sum())
+        rest = float(counts[~heavy].sum())
+        if free_bins <= 0 or rest <= 0:
+            break
+        new = ~heavy & (counts >= rest / free_bins)
+        if not new.any():
+            break
+        heavy |= new
+    free_bins = max(1, max_bins - int(heavy.sum()))
+    target = max(float(counts[~heavy].sum()) / free_bins, 1.0)
+    positions = set()
+    for i in np.flatnonzero(heavy):
+        if i > 0:
+            positions.add(int(i) - 1)
+        if i < n_values - 1:
+            positions.add(int(i))
+    # Runs of light values between heavy values (or at the ends).
+    start = 0
+    while start < n_values:
+        if heavy[start]:
+            start += 1
+            continue
+        stop = start
+        while stop < n_values and not heavy[stop]:
+            stop += 1
+        run = counts[start:stop]
+        run_bins = int(round(float(run.sum()) / target))
+        if run_bins > 1 and stop - start > 1:
+            cumulative = np.cumsum(run)
+            goals = cumulative[-1] * np.arange(1, run_bins) / run_bins
+            inner = np.unique(np.searchsorted(cumulative, goals, side="left"))
+            positions.update(int(start + i) for i in inner if start + i < stop - 1)
+        start = stop
+    positions = np.array(sorted(positions), dtype=np.int64)
+    # Rounding may exceed the budget: merge the pair of neighbouring bins
+    # with the smallest count until it fits.
+    while len(positions) > max_bins - 1:
+        bounds = np.r_[-1, positions, n_values - 1]
+        cumulative = np.r_[0, np.cumsum(counts)]
+        sizes = cumulative[bounds[1:] + 1] - cumulative[bounds[:-1] + 1]
+        merged = sizes[:-1] + sizes[1:]
+        positions = np.delete(positions, int(np.argmin(merged)))
+    return positions
+
+
+def _fit_bin_edges_column(col, max_bins, quantiles):
+    """Learn the cuts of one column; a standalone function for parallelism."""
+    finite = col[~np.isnan(col)]
+    unique, counts = np.unique(finite, return_counts=True)
+    unique = unique.astype(np.float64)
+    # Bin 0 is reserved for NaN and uint8 holds at most ids 1..255.
+    # So keep every interval only when they fit in the budget; high
+    # cardinality goes through the split by count.
+    if len(unique) <= max_bins:
+        cuts = unique[:-1] / 2 + unique[1:] / 2
+    else:
+        positions = _count_balanced_cut_positions(counts, max_bins)
+        cuts = unique[positions] / 2 + unique[positions + 1] / 2
+    return np.ascontiguousarray(cuts, dtype=np.float64)
+
+
+def fit_bin_edges(X, max_bins=255, n_jobs=1):
+    """Learn the edges ONLY on the validated training data, ignoring NaN.
+
+    Returns a tuple of increasing float64 vectors with at most max_bins-1 cuts.
+    Uses midpoints when there are few unique values, which preserves indicator
+    columns; otherwise unweighted quantiles without sampling. Constant and
+    all-NaN columns get an empty vector. max_bins in [2, 255] fits uint8 with
+    bin 0 reserved for NaN. Weights affect impurity, not the location of these
+    quantiles.
+    """
+    if (isinstance(max_bins, (bool, np.bool_))
+            or not isinstance(max_bins, (int, np.integer))
+            or not 2 <= max_bins <= 255):
+        raise ValueError("max_bins must be an integer between 2 and 255.")
+    if (isinstance(n_jobs, (bool, np.bool_))
+            or not isinstance(n_jobs, (int, np.integer)) or n_jobs < 1):
+        raise ValueError("n_jobs must be a positive integer.")
+    quantiles = np.arange(1, max_bins) / max_bins
+    columns = tuple(X[:, j] for j in range(X.shape[1]))
+    if n_jobs == 1:
+        return tuple(_fit_bin_edges_column(col, max_bins, quantiles)
+                     for col in columns)
+    with ThreadPoolExecutor(max_workers=int(n_jobs)) as pool:
+        return tuple(pool.map(
+            lambda col: _fit_bin_edges_column(col, max_bins, quantiles),
+            columns))
+
+
+@njit(cache=True)
+def _count_binary_values(values):
+    """Count zeros in a 0/1 column; return -1 on any other value."""
+    zeros = 0
+    for value in values:
+        if value == 0:
+            zeros += 1
+        elif value != 1:
+            return -1
+    return zeros
+
+
+def _fit_bin_edges_binary(X, max_bins=255):
+    """Learn edges with quantiles identical to the reference on 0/1 columns.
+
+    The shortcut avoids partitioning large indicator columns. Other columns
+    keep the original path; `fit_bin_edges` remains the production baseline.
+    """
+    if (isinstance(max_bins, (bool, np.bool_))
+            or not isinstance(max_bins, (int, np.integer))
+            or not 2 <= max_bins <= 255):
+        raise ValueError("max_bins must be an integer between 2 and 255.")
+    edges = []
+    quantiles = np.arange(1, max_bins) / max_bins
+    for col in X.T:
+        finite = col[~np.isnan(col)]
+        unique = np.unique(finite).astype(np.float64)
+        if len(unique) <= max_bins:
+            cuts = unique[:-1] / 2 + unique[1:] / 2
+        else:
+            zeros = _count_binary_values(finite)
+            if zeros >= 0:
+                if zeros == 0 or zeros == len(finite):
+                    cuts = np.empty(0, dtype=np.float64)
+                else:
+                    positions = (len(finite) - 1) * quantiles
+                    lower = np.floor(positions).astype(np.int64)
+                    upper = np.ceil(positions).astype(np.int64)
+                    cuts = np.unique(np.where(upper < zeros, 0.0,
+                                              np.where(lower >= zeros, 1.0,
+                                                       positions - lower)))
+                    cuts = cuts[cuts < 1.0]
+            else:
+                finite_min = float(finite.min())
+                finite_max = float(finite.max())
+                cuts = np.unique(np.quantile(finite, quantiles))
+                cuts = cuts[(cuts >= finite_min) & (cuts < finite_max)]
+        edges.append(np.ascontiguousarray(cuts, dtype=np.float64))
+    return tuple(edges)
+
+
+def transform_bins(X, edges):
+    """Apply frozen edges and return C-contiguous uint8 with the shape of X.
+
+    NaN -> 0; finite values -> 1..B. A value equal to an edge goes to the lower
+    bin (searchsorted side='left'), exactly like X <= threshold at prediction.
+    New extremes fall into the outer bins; quantiles are never recomputed.
+    Internal contract: X already validated and edges produced by fit_bin_edges.
+    """
+    if len(edges) != X.shape[1]:
+        raise ValueError("One list of edges is required per column.")
+    result = np.empty(X.shape, dtype=np.uint8)
+    for j, cuts in enumerate(edges):
+        result[:, j] = np.searchsorted(cuts, X[:, j], side="left") + 1
+        result[np.isnan(X[:, j]), j] = 0
+    return result
+
+
+@njit(cache=True)
+def _transform_bins_row_major_kernel(X, padded_edges, lengths):
+    """Apply side='left' row by row, respecting the C layout of X and of the output."""
+    result = np.empty(X.shape, dtype=np.uint8)
+    for i in range(X.shape[0]):
+        for j in range(X.shape[1]):
+            value = X[i, j]
+            if np.isnan(value):
+                result[i, j] = 0
+            else:
+                lo, hi = 0, lengths[j]
+                while lo < hi:
+                    mid = (lo + hi) // 2
+                    if padded_edges[j, mid] < value:
+                        lo = mid + 1
+                    else:
+                        hi = mid
+                result[i, j] = lo + 1
+    return result
+
+
+@njit(cache=True, parallel=True)
+def _transform_bins_row_major_parallel_kernel(X, padded_edges, lengths):
+    """Row-major transform, parallel over rows, without changing the cuts."""
+    result = np.empty(X.shape, dtype=np.uint8)
+    for i in prange(X.shape[0]):
+        for j in range(X.shape[1]):
+            value = X[i, j]
+            if np.isnan(value):
+                result[i, j] = 0
+            else:
+                lo, hi = 0, lengths[j]
+                while lo < hi:
+                    mid = (lo + hi) // 2
+                    if padded_edges[j, mid] < value:
+                        lo = mid + 1
+                    else:
+                        hi = mid
+                result[i, j] = lo + 1
+    return result
+
+
+def transform_bins_row_major(X, edges, n_jobs=1):
+    """Row-major variant; reproduces the NumPy reference bins exactly.
+
+    Preparing the edges is part of the measured time. `transform_bins` stays
+    available as a comparable baseline; both require an already validated X.
+    """
+    if len(edges) != X.shape[1]:
+        raise ValueError("One list of edges is required per column.")
+    if (isinstance(n_jobs, (bool, np.bool_)) or not isinstance(n_jobs, (int, np.integer))
+            or n_jobs < 1):
+        raise ValueError("n_jobs must be a positive integer.")
+    lengths = np.fromiter((len(cuts) for cuts in edges), count=len(edges), dtype=np.int64)
+    padded = np.zeros((len(edges), int(lengths.max(initial=0))), dtype=np.float64)
+    for j, cuts in enumerate(edges):
+        padded[j, :len(cuts)] = cuts
+    if n_jobs == 1:
+        return _transform_bins_row_major_kernel(X, padded, lengths)
+    return _transform_bins_row_major_parallel_kernel(X, padded, lengths)