hessboost 0.2.1__tar.gz → 0.2.2__tar.gz

{hessboost-0.2.1 → hessboost-0.2.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hessboost"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2024"
 rust-version = "1.93"
 license = "Apache-2.0"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hessboost
-Version: 0.2.1
+Version: 0.2.2
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -132,7 +132,11 @@ every `n`-th), `xgb_model` (continued training, or tree refresh with
 `process_type="update"`), a custom objective `obj`, a `custom_metric`,
 and `callbacks`. Ctrl-C stops training at the end of the current round
 and raises `KeyboardInterrupt`. `hessboost.cv` cross-validates over
-shuffled folds, explicit folds, or a scikit-learn splitter.
+shuffled folds, explicit folds, or a scikit-learn splitter; on ranking data
+each fold must hold whole query groups (e.g. `GroupKFold` over the query
+ids). `hessboost.train_with_budget(params, dtrain, budget)` trains with one
+fitting budget in place of `eta`, tree limits, and a round count
+(PerpetualBooster's algorithm).
 
 Subclass `TrainingCallback` to stop on your own condition; `after_iteration`
 sees the round and the evaluation history, and returning `True` stops
@@ -445,6 +449,23 @@ gpu = booster.to_gpu()
 probabilities = gpu.predict(X_test)
 ```
 
+### Compact models
+
+`Booster.to_compact()` packs the trees default prediction uses into
+hessboost's bit-packed `HBTD` format (*Boosted Trees on a Diet*), which
+predicts bit-identical values and margins in a fraction of the size;
+training with `toad_penalty_feature`/`toad_penalty_threshold` shrinks it
+further. `Booster.size_report()` compares the two formats:
+
+```python
+from hessboost import CompactModel
+
+compact = booster.to_compact()
+compact.save_model("model.hbtd")
+predictions = CompactModel("model.hbtd").predict(X_test)
+print(booster.size_report().compression_ratio)
+```
+
 ### Validation folds
 
 `hessboost.folds` builds `(train_rows, test_rows)` splits for `cv` or custom
@@ -460,6 +481,24 @@ splits = folds.forward_chaining(dtrain.num_row(), 4, gap=24)
 result = hessboost.cv({"max_depth": 4}, dtrain, 100, folds=splits)
 ```
 
+### Ordered target statistics
+
+`hessboost.target_stats.OrderedTargetEncoder` replaces categorical columns
+with CatBoost-style ordered target means: a training row's encoding never
+sees its own label. `label=` supplies the target for a multi-target matrix
+or a class's 0/1 indicator. In `cv`, `target_stats=` fits the encoder on
+each fold's training rows only, so no held-out label reaches an encoding:
+
+```python
+from hessboost.target_stats import OrderedTargetEncoder
+
+encoder = OrderedTargetEncoder(seed=7)
+dtrain_encoded, stats = encoder.fit_transform(dtrain, ["city"])
+booster = hessboost.train({"max_depth": 4}, dtrain_encoded, 100)
+predictions = booster.predict(stats.transform(X_test))
+result = hessboost.cv({"max_depth": 4}, dtrain, 100, target_stats=["city"], target_encoder=encoder)
+```
+
 ### Extra training options
 
 Every hessboost training option (`path_smooth`, `extra_trees`,

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

@@ -134,7 +134,8 @@ runnable programs live in [`examples/`](examples)
 [`python/`](python) holds the Python package (`pip install hessboost`):
 `DMatrix`, `train`, `cv`, and `Booster` (taking XGBoost's parameter names),
 scikit-learn estimators, pandas and polars categorical input, and the conformal,
-distributional, tree-diffusion, ForestFlow, and in-place update extras
+distributional, tree-diffusion, ForestFlow, in-place update, ordered target
+statistics, budget training, and compact model extras
 (on macOS, `Booster.to_gpu()` batch-predicts on the Metal GPU):
 
 ```python
@@ -155,8 +156,9 @@ See [`python/README.md`](python/README.md).
 - **Objectives & metrics:** Regression (squared, log, Huber, quantile, expectile),
   binary/multiclass classification, ranking (LambdaMART, XE-NDCG), count, and survival (Cox, AFT),
   plus typed objective and metric APIs and custom loss hooks.
-- **Validation & workflow:** Cross-validation (including purged and forward time-series folds),
-  early stopping, feature importance, SHAP values and interactions, model slicing, and iteration ranges.
+- **Validation & workflow:** Cross-validation (including purged and forward time-series folds,
+  whole-query ranking folds, and per-fold target statistics), early stopping, feature importance,
+  SHAP values and interactions, model slicing, and iteration ranges.
 - **Interchange:** Native binary and JSON formats, XGBoost JSON/UBJSON import/export, LightGBM model import, and models embedded in the binary at compile time.
 - **Modern modeling (opt-in):**
   - [Conformal intervals](https://docs.rs/hessboost/latest/hessboost/conformal/): Finite-sample coverage guarantees.

{hessboost-0.2.1 → hessboost-0.2.2}/python/Cargo.lock

@@ -88,7 +88,7 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "hessboost"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "objc2",
  "objc2-foundation",
@@ -101,7 +101,7 @@ dependencies = [
 
 [[package]]
 name = "hessboost-python"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "hessboost",
  "numpy",

{hessboost-0.2.1 → hessboost-0.2.2}/python/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "hessboost-python"
 # Must equal the root crate's version: the wheel version comes from here.
-version = "0.2.1"
+version = "0.2.2"
 authors = ["Brenden Matthews <brenden@brndn.io>"]
 description = "Python bindings for hessboost"
 edition = "2024"

{hessboost-0.2.1 → hessboost-0.2.2}/python/README.md

@@ -93,7 +93,11 @@ every `n`-th), `xgb_model` (continued training, or tree refresh with
 `process_type="update"`), a custom objective `obj`, a `custom_metric`,
 and `callbacks`. Ctrl-C stops training at the end of the current round
 and raises `KeyboardInterrupt`. `hessboost.cv` cross-validates over
-shuffled folds, explicit folds, or a scikit-learn splitter.
+shuffled folds, explicit folds, or a scikit-learn splitter; on ranking data
+each fold must hold whole query groups (e.g. `GroupKFold` over the query
+ids). `hessboost.train_with_budget(params, dtrain, budget)` trains with one
+fitting budget in place of `eta`, tree limits, and a round count
+(PerpetualBooster's algorithm).
 
 Subclass `TrainingCallback` to stop on your own condition; `after_iteration`
 sees the round and the evaluation history, and returning `True` stops
@@ -406,6 +410,23 @@ gpu = booster.to_gpu()
 probabilities = gpu.predict(X_test)
 ```
 
+### Compact models
+
+`Booster.to_compact()` packs the trees default prediction uses into
+hessboost's bit-packed `HBTD` format (*Boosted Trees on a Diet*), which
+predicts bit-identical values and margins in a fraction of the size;
+training with `toad_penalty_feature`/`toad_penalty_threshold` shrinks it
+further. `Booster.size_report()` compares the two formats:
+
+```python
+from hessboost import CompactModel
+
+compact = booster.to_compact()
+compact.save_model("model.hbtd")
+predictions = CompactModel("model.hbtd").predict(X_test)
+print(booster.size_report().compression_ratio)
+```
+
 ### Validation folds
 
 `hessboost.folds` builds `(train_rows, test_rows)` splits for `cv` or custom
@@ -421,6 +442,24 @@ splits = folds.forward_chaining(dtrain.num_row(), 4, gap=24)
 result = hessboost.cv({"max_depth": 4}, dtrain, 100, folds=splits)
 ```
 
+### Ordered target statistics
+
+`hessboost.target_stats.OrderedTargetEncoder` replaces categorical columns
+with CatBoost-style ordered target means: a training row's encoding never
+sees its own label. `label=` supplies the target for a multi-target matrix
+or a class's 0/1 indicator. In `cv`, `target_stats=` fits the encoder on
+each fold's training rows only, so no held-out label reaches an encoding:
+
+```python
+from hessboost.target_stats import OrderedTargetEncoder
+
+encoder = OrderedTargetEncoder(seed=7)
+dtrain_encoded, stats = encoder.fit_transform(dtrain, ["city"])
+booster = hessboost.train({"max_depth": 4}, dtrain_encoded, 100)
+predictions = booster.predict(stats.transform(X_test))
+result = hessboost.cv({"max_depth": 4}, dtrain, 100, target_stats=["city"], target_encoder=encoder)
+```
+
 ### Extra training options
 
 Every hessboost training option (`path_smooth`, `extra_trees`,

{hessboost-0.2.1 → hessboost-0.2.2}/python/hessboost/__init__.py

@@ -19,17 +19,20 @@ Submodules:
   diffusion and flow matching
 * :mod:`hessboost.folds` -- k-fold and forward-chaining (purged) folds
 * :mod:`hessboost.online` -- adding and deleting training rows in place
+* :mod:`hessboost.target_stats` -- ordered target statistics for categorical columns
 """
 
 from importlib.metadata import version as _version
 
-from hessboost import conformal, diffusion, ebm, folds, inference, online
+from hessboost import conformal, diffusion, ebm, folds, inference, online, target_stats
 from hessboost._booster import (
     Booster,
+    CompactModel,
     Distributions,
     GpuModel,
     ImportanceType,
     ModelFormat,
+    ModelSizeReport,
 )
 from hessboost._core import Uncertainty
 from hessboost._exceptions import (
@@ -46,6 +49,7 @@ from hessboost._training import (
     TrainingCallback,
     cv,
     train,
+    train_with_budget,
 )
 
 __version__: str = _version("hessboost")
@@ -53,6 +57,7 @@ __version__: str = _version("hessboost")
 
 __all__ = [
     "Booster",
+    "CompactModel",
     "CustomMetric",
     "DMatrix",
     "Distributions",
@@ -64,6 +69,7 @@ __all__ = [
     "InvalidDataError",
     "ModelFormat",
     "ModelFormatError",
+    "ModelSizeReport",
     "Objective",
     "TrainingCallback",
     "Uncertainty",
@@ -75,5 +81,7 @@ __all__ = [
     "folds",
     "inference",
     "online",
+    "target_stats",
     "train",
+    "train_with_budget",
 ]

{hessboost-0.2.1 → hessboost-0.2.2}/python/hessboost/_booster.py

@@ -1,10 +1,11 @@
 """``Booster``, exported from :mod:`hessboost`, with its prediction and
-model-format types."""
+model-format types, and the compact and GPU layouts a booster converts to."""
 
 from __future__ import annotations
 
 import os
 from collections.abc import Sequence
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal, TypeAlias, overload
 
 import numpy as np
@@ -22,10 +23,12 @@ if TYPE_CHECKING:
 
 __all__ = [
     "Booster",
+    "CompactModel",
     "Distributions",
     "GpuModel",
     "ImportanceType",
     "ModelFormat",
+    "ModelSizeReport",
 ]
 
 Distributions = _hessboost.Distributions
@@ -61,6 +64,42 @@ def _format_for(path: PathLike, format: ModelFormat | None) -> ModelFormat:
     return "binary"
 
 
+@dataclass(frozen=True)
+class ModelSizeReport:
+    """A booster's size in the native binary and compact formats, with the
+    dictionary statistics of the *Trees on a Diet* paper, from
+    :meth:`Booster.size_report`."""
+
+    native_bytes: int
+    """The native binary model's size (every tree, covers and gains included)."""
+    compact_bytes: int
+    """The compact model's size."""
+    trees: int
+    """The trees the compact model stores (those prediction uses)."""
+    splits: int
+    """Split nodes across those trees."""
+    leaves: int
+    """Leaves across those trees."""
+    used_features: int
+    """Features the trees split on."""
+    thresholds: int
+    """Distinct thresholds and categorical sets, over every used feature."""
+    leaf_values: int
+    """Distinct leaf values."""
+
+    @property
+    def compression_ratio(self) -> float:
+        """``native_bytes / compact_bytes``."""
+        return self.native_bytes / self.compact_bytes
+
+    @property
+    def reuse_factor(self) -> float:
+        """Nodes per distinct dictionary entry, ``(splits + leaves) /
+        (thresholds + leaf_values)``: how often each threshold or leaf value
+        is shared."""
+        return (self.splits + self.leaves) / max(self.thresholds + self.leaf_values, 1)
+
+
 class Booster(_SchemaState):
     """A trained gradient-boosting model, as XGBoost's ``xgboost.Booster``.
 
@@ -160,6 +199,38 @@ class Booster(_SchemaState):
         """The number of features the model takes."""
         return self._model.num_features
 
+    def num_trees(self) -> int:
+        """The number of trees (``num_boosted_rounds() * trees per
+        iteration``; the column count of ``pred_leaf``)."""
+        return self._model.num_trees
+
+    @property
+    def num_outputs(self) -> int:
+        """Raw outputs (margins) per row: ``num_class`` for multiclass, one
+        per target or quantile otherwise."""
+        return self._model.num_outputs
+
+    @property
+    def num_targets(self) -> int:
+        """Label columns the model was trained on."""
+        return self._model.num_targets
+
+    @property
+    def num_parallel_tree(self) -> int:
+        """Trees per output per iteration (a boosted forest's size)."""
+        return self._model.num_parallel_tree
+
+    @property
+    def base_margins(self) -> list[float]:
+        """The per-output intercepts, in margin space."""
+        return self._model.base_margins
+
+    @property
+    def vector_leaves(self) -> bool:
+        """Whether each tree predicts every output (``multi_strategy=
+        "multi_output_tree"``), rather than one output per tree."""
+        return self._model.vector_leaves
+
     def _matrix(
         self, data: object, base_margin: ArrayLike | None, missing: float, validate: bool = True
     ) -> _hessboost.DMatrix:
@@ -258,6 +329,31 @@ class Booster(_SchemaState):
         """
         return GpuModel._wrap(self._model.to_gpu(), self)
 
+    def to_compact(self) -> CompactModel:
+        """This model in the bit-packed compact layout (*Boosted Trees on a
+        Diet*), for memory-constrained inference: it predicts bit-identical
+        values and margins to :meth:`predict` with the default iterations
+        (through :attr:`best_iteration`), and stores only those trees,
+        without covers and gains. Training with ``toad_penalty_feature`` and
+        ``toad_penalty_threshold`` shrinks it further. The compact model
+        keeps this booster's feature names and categories.
+
+        Raises:
+            HessboostError: The model is ``gblinear``, has ``linear_tree`` or
+                vector leaves, or splits one feature both numerically and
+                categorically.
+        """
+        return CompactModel._wrap(self._model.to_compact(), self)
+
+    def size_report(self) -> ModelSizeReport:
+        """This model's native binary versus compact size, with the compact
+        layout's dictionary statistics.
+
+        Raises:
+            HessboostError: As :meth:`to_compact`.
+        """
+        return ModelSizeReport(**self._model.size_report())
+
     def predict_distribution(
         self,
         data: object,
@@ -517,3 +613,151 @@ class GpuModel:
         matrix = model._matrix(data, base_margin, missing, validate_features)
         kind = "margin" if output_margin else "value"
         return self._core.predict(matrix, kind, Booster._range(iteration_range))
+
+
+class CompactModel(_SchemaState):
+    """A tree ensemble in hessboost's bit-packed compact format (``HBTD``,
+    *Boosted Trees on a Diet*), predicting bit-identical values and margins
+    to the :class:`Booster` it came from while taking a fraction of its
+    size. It predicts straight from the packed trees; it has no SHAP, leaf
+    or iteration-range predictions (only the trees default prediction uses
+    are stored). XGBoost cannot read the format.
+
+    Get one from :meth:`Booster.to_compact`, or load a saved one with
+    ``CompactModel(model_file)``.
+
+    Args:
+        model_file: A path or the bytes of a compact model
+            (:meth:`save_model`/:meth:`save_raw`).
+
+    Raises:
+        ModelFormatError: The content is not a valid compact model.
+        OSError: The file cannot be read.
+    """
+
+    __module__ = "hessboost"
+
+    _core: _hessboost.CompactModel
+
+    def __init__(self, model_file: PathLike | bytes | bytearray | memoryview) -> None:
+        data = (
+            bytes(model_file)
+            if isinstance(model_file, (bytes, bytearray, memoryview))
+            else read_bytes(model_file)
+        )
+        self._core = _hessboost.CompactModel.load(data)
+        self._set_schema(None, None, {})
+
+    @classmethod
+    def _wrap(cls, core: _hessboost.CompactModel, booster: Booster) -> CompactModel:
+        model = cls.__new__(cls)
+        model._core = core
+        model._set_schema(booster._feature_names, booster._feature_types, dict(booster._categories))
+        return model
+
+    @property
+    def feature_names(self) -> list[str] | None:
+        """The training features' names, if known (not stored in the file;
+        pickling keeps them). Assignable, as :attr:`Booster.feature_names`."""
+        return None if self._feature_names is None else list(self._feature_names)
+
+    @feature_names.setter
+    def feature_names(self, names: Sequence[str] | None) -> None:
+        self._feature_names = (
+            None if names is None else _data._check_names(names, self.num_features())
+        )
+
+    @property
+    def feature_types(self) -> list[str] | None:
+        """``"q"``/``"c"`` per training feature, if known."""
+        return None if self._feature_types is None else list(self._feature_types)
+
+    @property
+    def objective(self) -> str:
+        """The objective that drives :meth:`predict`."""
+        return self._core.objective
+
+    def num_features(self) -> int:
+        """The number of features the model takes."""
+        return self._core.num_features
+
+    def num_trees(self) -> int:
+        """The number of stored trees."""
+        return self._core.num_trees
+
+    @property
+    def num_outputs(self) -> int:
+        """Raw outputs (margins) per row."""
+        return self._core.num_outputs
+
+    @property
+    def size_bytes(self) -> int:
+        """The serialized size in bytes."""
+        return self._core.size_bytes
+
+    @property
+    def used_features(self) -> list[int]:
+        """The indices of the features the trees split on, ascending."""
+        return self._core.used_features
+
+    @property
+    def num_thresholds(self) -> int:
+        """Distinct thresholds and categorical sets, over every used feature."""
+        return self._core.num_thresholds
+
+    @property
+    def num_leaf_values(self) -> int:
+        """Distinct leaf values."""
+        return self._core.num_leaf_values
+
+    def predict(
+        self,
+        data: object,
+        *,
+        output_margin: bool = False,
+        validate_features: bool = True,
+        base_margin: ArrayLike | None = None,
+        missing: float = np.nan,
+    ) -> NDArray[np.float32]:
+        """Predicts every row of ``data`` (a :class:`DMatrix` or anything
+        its constructor accepts; frames are re-coded to the model's
+        categories): the objective's predictions or, with ``output_margin``,
+        raw margins, ``(rows,)`` or ``(rows, K)`` for ``K`` outputs,
+        bit-identical to :meth:`Booster.predict`.
+
+        Args:
+            validate_features: Refuse data whose feature names differ from
+                the model's.
+            base_margin: Starting margins for array input (a
+                :class:`DMatrix` carries its own).
+            missing: The missing-value marker for array input.
+        """
+        matrix = _matrix_for(
+            data,
+            ((self, "the model's"),),
+            base_margin=base_margin,
+            missing=missing,
+            validate_names=validate_features,
+        )
+        return self._core.predict(matrix._core, output_margin)
+
+    def save_raw(self) -> bytes:
+        """The serialized model."""
+        return self._core.save()
+
+    def save_model(self, fname: PathLike) -> None:
+        """Writes the model to ``fname``. Feature names and categories are
+        not part of the format; pickle the model to keep them."""
+        write_bytes(fname, self.save_raw())
+
+    def _model_state(self) -> bytes:
+        return self._core.save()
+
+    def _restore_model(self, model: bytes) -> None:
+        self._core = _hessboost.CompactModel.load(model)
+
+    def __repr__(self) -> str:
+        return (
+            f"CompactModel(objective={self.objective!r}, trees={self.num_trees()}, "
+            f"features={self.num_features()}, bytes={self.size_bytes})"
+        )

{hessboost-0.2.1 → hessboost-0.2.2}/python/hessboost/_data.py

@@ -5,7 +5,7 @@ and polars frames, scipy sparse matrices, array-likes) into the row-major
 from __future__ import annotations
 
 import sys
-from collections.abc import Mapping, Sequence
+from collections.abc import Collection, Mapping, Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, TypeAlias, TypeGuard
 
@@ -130,11 +130,16 @@ def _categorical_columns(feature_types: Sequence[str], n_cols: int) -> list[int]
 
 
 def _pandas_frame_values(
-    frame: pd.DataFrame, enable_categorical: bool, reference: Categories | None
+    frame: pd.DataFrame,
+    enable_categorical: bool,
+    reference: Categories | None,
+    unseen: Collection[int] = (),
 ) -> tuple[NDArray[np.float32], list[str], FeatureTypes, Categories]:
     """A pandas frame's values as ``float32``: numeric and boolean columns as is
     (``NA`` missing), category columns as their codes (``NaN`` missing),
-    re-coded to the ``reference`` categories of a trained model."""
+    re-coded to the ``reference`` categories of a trained model. A value the
+    reference lacks is missing, except in the ``unseen`` columns, where it
+    gets the code one past the reference's categories."""
     pd = _pandas()
     rows, cols = frame.shape
     values = np.empty((rows, cols), dtype=np.float32)
@@ -151,7 +156,14 @@ def _pandas_frame_values(
             if wanted is not None and wanted != known:
                 # Old code -> position in the training categories (-1: unseen).
                 recode = pd.Index(wanted).get_indexer(dtype.categories)
-                codes = np.where(codes >= 0, recode[codes], -1)
+                if column in unseen:
+                    recode = np.where(recode >= 0, recode, len(wanted))
+                # Only present codes index `recode`, which is empty when
+                # the frame's categories are.
+                present = codes >= 0
+                recoded = np.full(codes.shape, -1, dtype=np.int64)
+                recoded[present] = recode[codes[present]]
+                codes = recoded
                 known = wanted
             column_values = codes.astype(np.float32)
             column_values[codes < 0] = np.nan
@@ -171,14 +183,19 @@ def _pandas_frame_values(
 
 
 def _polars_frame_values(
-    frame: pl.DataFrame, enable_categorical: bool, reference: Categories | None
+    frame: pl.DataFrame,
+    enable_categorical: bool,
+    reference: Categories | None,
+    unseen: Collection[int] = (),
 ) -> tuple[NDArray[np.float32], list[str], FeatureTypes, Categories]:
     """A polars frame's values as ``float32``: numeric and boolean columns as
     is (null missing), ``Enum`` and ``Categorical`` columns as positions in
     their categories (null missing), re-coded to the ``reference``
-    categories of a trained model. An ``Enum``'s categories are its
-    dtype's; a ``Categorical``'s are its values, sorted (as pandas infers
-    them), since its physical codes index a pool other columns share."""
+    categories of a trained model (a value they lack is missing, except in
+    the ``unseen`` columns, where it gets the code one past them). An
+    ``Enum``'s categories are its dtype's; a ``Categorical``'s are its
+    values, sorted (as pandas infers them), since its physical codes index
+    a pool other columns share."""
     pl = _polars()
     rows, cols = frame.shape
     values = np.empty((rows, cols), dtype=np.float32)
@@ -202,13 +219,16 @@ def _polars_frame_values(
             positions = [
                 (value, code) for code, value in enumerate(known) if isinstance(value, str)
             ]
+            other = float(len(known)) if wanted is not None and column in unseen else None
             codes = strings.replace_strict(
                 [value for value, _ in positions],
                 [code for _, code in positions],
-                default=None,
+                default=other,
                 return_dtype=pl.Float32,
             )
-            column_values = codes.to_numpy()
+            column_values = codes.to_numpy(writable=other is not None)
+            if other is not None:
+                column_values[strings.is_null().to_numpy()] = np.nan
             types.append("c")
             categories[column] = known
         elif dtype.is_numeric() or dtype == pl.Boolean:
@@ -232,10 +252,13 @@ def features(
     enable_categorical: bool,
     reference: Categories | None,
     info: Mapping[str, object],
+    unseen: Collection[int] = (),
 ) -> Features:
     """Converts ``data`` and builds the native matrix with ``info``
     attached. ``reference`` holds a trained model's categories, to which
-    frame categorical columns are re-coded."""
+    frame categorical columns are re-coded; values it lacks are missing,
+    except in the ``unseen`` columns, where they are coded one past its
+    categories (a target encoder's unseen category)."""
     names: list[str] | None = None
     types: FeatureTypes | None = None
     categories: Categories = {}
@@ -244,10 +267,14 @@ def features(
         n_cols = int(csr.shape[1])
         values = None
     elif _is_pandas_frame(data):
-        values, names, types, categories = _pandas_frame_values(data, enable_categorical, reference)
+        values, names, types, categories = _pandas_frame_values(
+            data, enable_categorical, reference, unseen
+        )
         n_cols = values.shape[1]
     elif _is_polars_frame(data):
-        values, names, types, categories = _polars_frame_values(data, enable_categorical, reference)
+        values, names, types, categories = _polars_frame_values(
+            data, enable_categorical, reference, unseen
+        )
         n_cols = values.shape[1]
     else:
         values = as_float32(data, "data")