NeuroTabular

NeuroTabular is a PyTorch library for binary classification, multiclass classification, and single-output regression on heterogeneous pandas DataFrames. It exposes a compact scikit-learn-style API, handles numerical and categorical columns automatically, and keeps preprocessing inside the estimator so training and inference share the same learned state.

NeuroTabular 1.0.2 is a compatibility patch candidate for the stable 1.0 API. It removes the Python metadata restriction that rejected Python 3.13 installs. Conventional CPython 3.11–3.14 has executed Linux CPU coverage; Python 3.10 remains legacy compatible. Runtime algorithms, defaults and valid-input predictions are unchanged. See the release notes, support scope, API boundary and target contract. It targets small or medium in-memory tabular datasets, without SOTA or universal superiority claims over gradient-boosted trees.

Highlights

• retain CPU prediction-path overhead reductions from 0.3.1;
• NeuroTabularClassifier automatically handles binary and multiclass targets;
• NeuroTabularRegressor learns a continuous target and predicts in original units;
• automatic numerical, object, string, categorical, and boolean handling;
• training-only median imputation, standard scaling, missing indicators, categorical vocabularies, rare buckets, quantile knots, and log-frequency side features;
• declared-but-unobserved pandas Categorical levels remain truly unseen;
• adaptive categorical embedding widths with a compact aggregate width budget;
• scalar numerical inputs by default, with affine, periodic, and piecewise representations available explicitly for experiments;
• compact residual MLP backbone with optional lightweight input gating;
• AdamW, cosine learning-rate scheduling, automatic batching, deterministic validation, early stopping, and strict best-checkpoint restoration;
• sample_weight across all tasks and class_weight="balanced" for classification, with zero-weight rows ignored before target discovery, splitting, and preprocessing;
• transactional re-fitting: a failed refit preserves a previously fitted model;
• caller Python, NumPy, and PyTorch CPU RNG states are restored after fitting;
• explicit checks for unsafe float32 conversion and complex-valued inputs;
• CPU/CUDA device diagnostics, synchronized CUDA usability probing, and AMP only on compatible CUDA hardware;
• scikit-learn cloning, pipelines, and cross-validation compatibility;
• pickle/joblib round trips validated in fresh processes for all three tasks;
• conventional Python 3.11–3.14 coverage and Python 3.10 legacy compatibility;
• Linux CPU checks, proposed expanded Windows/macOS CI, and installed-artifact checks.

The default configuration is intentionally conservative: scalar numerical representation, categorical frequency features enabled, no feature gate, and no full-data refit. Experimental research ideas are not enabled by default without broader evidence.

Installation

Use conventional CPython 3.11–3.14. After 1.0.2 is published to production PyPI:

python -m pip install neurotabular

In a fresh Kaggle or Colab notebook using a supported Python runtime:

!pip install neurotabular
from neurotabular import NeuroTabularClassifier

This candidate has been tested locally on exact CPython 3.13.15, including normal PyPI dependency resolution. It has not been executed inside Kaggle or Colab. TestPyPI publication alone does not make the ordinary PyPI command install 1.0.2. Check neurotabular.__version__ after installation. Restart an existing notebook session if it already imported another version.

Python 3.10 works in the tested legacy stack but is upstream EOL. Python 3.15 passes the full Linux CPU code suite using the official PyTorch CPU channel; ordinary PyPI installation is currently limited by missing Torch wheels. If you need 3.15, install Torch using its documented channel before NeuroTabular:

python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install neurotabular

This is an explicit alternative installation path. CPython 3.11–3.14 is preferred for the ordinary one-command experience. The upstream distribution gap has no promised resolution date. See the PyTorch 2.14 announcement.

Native Windows execution of this candidate is locally blocked by Application Control, with no bypass attempted. macOS is not locally validated; current Torch wheels on Apple Silicon and older Intel support differ. Physical NVIDIA CUDA remains best effort and unvalidated. The support scope distinguishes these platform limits from executed Linux evidence.

From a local checkout:

python -m venv .venv

Activate that environment before installing (choose the command for your shell):

source .venv/bin/activate  # Linux/macOS bash

.\.venv\Scripts\Activate.ps1  # Windows PowerShell

Then use its Python:

python -m pip install --upgrade pip
python -m pip install -e .

If your shell prevents activation, use .venv/bin/python on Linux/macOS or .\.venv\Scripts\python.exe on Windows in place of python; no policy change is needed. Confirm python -c "import neurotabular; print(neurotabular.__version__)".

For development and verification:

python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m pytest -W error

Runtime requirements are NumPy 1.24+, pandas 2.0+, scikit-learn 1.3+, and PyTorch 2.0+. Pip also resolves Python-specific joblib floors for stdlib, caching and parallel-worker compatibility. LightGBM and CatBoost are optional benchmark-only comparisons and are not runtime dependencies.

Quick start

Binary classification:

import pandas as pd
from neurotabular import NeuroTabularClassifier

X = pd.DataFrame(
    {
        "age": [22, 45, 31, 54, 28, 61],
        "income": [32_000, 78_000, None, 91_000, 46_000, 105_000],
        "city": ["Rome", "Milan", "Rome", "Turin", None, "Milan"],
    }
)
y = [0, 1, 0, 1, 0, 1]

model = NeuroTabularClassifier()
model.fit(X, y)

labels = model.predict(X)
probabilities = model.predict_proba(X)[:, 1]

Multiclass classification uses the same estimator, without a task parameter:

from sklearn.datasets import load_iris
from neurotabular import NeuroTabularClassifier

X, y = load_iris(return_X_y=True, as_frame=True)
clf = NeuroTabularClassifier().fit(X, y)
probabilities = clf.predict_proba(X)  # shape (150, 3), columns follow clf.classes_
labels = clf.predict(X)

Regression:

from sklearn.datasets import load_diabetes
from neurotabular import NeuroTabularRegressor

X, y = load_diabetes(return_X_y=True, as_frame=True)
reg = NeuroTabularRegressor().fit(X, y)
prediction = reg.predict(X)  # original target units, shape (442,)

These examples demonstrate the API; evaluate quality on a separate test set.

Integer-coded categorical columns should be named explicitly:

model = NeuroTabularClassifier(categorical_features=["postal_code"])

For a user-controlled holdout:

model.fit(X_train, y_train, eval_set=(X_valid, y_valid))

Preprocessing is fitted only on the training rows. Categories and numerical statistics from an external validation frame never enter the learned training preprocessor.

Optional representations

The release default should be the starting point. Alternatives are explicit:

affine = NeuroTabularClassifier(numerical_embedding="affine")
piecewise = NeuroTabularClassifier(numerical_embedding="piecewise")
gated = NeuroTabularClassifier(feature_gating=True)

periodic and piecewise numerical embeddings are implemented and tested but were not selected as defaults in the internal ablation suite. Likewise, full_data_refit=True retrains on all primary rows for the selected number of epochs; it remains opt-in because its quality/cost trade-off was not consistently better in development experiments.

Validation, metrics, and weights

Without eval_set, NeuroTabular creates a deterministic validation split, stratified for classification and shuffled without stratification for regression. Classifier eval_metric accepts "loss" and "accuracy"; "roc_auc" is binary-only. Regressor metrics are "loss" (MSE), "rmse", "mae", and "r2". Loss is the default for every task. The strictly best observed model state is restored after early stopping; min_delta controls patience rather than blocking restoration of a smaller strict improvement.

Use class_weight="balanced" for inverse-frequency class weighting or pass non-negative per-row sample_weight values to fit. If both are supplied for classification, their effects are multiplied. Rows with zero effective sample weight are ignored before target validation and preprocessing.

Regression uses train-only weighted population mean and standard deviation for the target, with MSE on the standardized scale and an automatic inverse transform at prediction. A constant training target produces the exact constant. See the API reference for task-specific details.

Persistence

Pickle and joblib round trips are tested in fresh processes for binary, multiclass, and regression models. Use matching package/dependency versions when loading persisted models; cross-version and cross-device persistence compatibility is not guaranteed. Only load trusted pickle/joblib artifacts. See the usage guide.

Devices and performance

device="auto" performs a real synchronized CUDA kernel probe. It falls back to CPU with a diagnostic warning if CUDA is reported but unusable. An explicit CUDA request fails with diagnostic details instead of silently changing devices.

Training data is converted once and kept on the selected device, batches are formed with index tensors, and inference is batched. AMP is enabled only after a compatible CUDA probe. CPU execution uses a plain null context when AMP is disabled.

For the 0.3.1 patch, the internal P35 CPU/WSL software panel measured median latency reductions of about 31% for predict and 36% for predict_proba versus the 0.3.0 path, with bit-for-bit outputs on the frozen equivalence checks. These figures are hardware- and workload-specific; see 0.3.1 performance validation.

The frozen 0.3 development benchmark contains 330 fits across 22 task/dataset cases and three seeds, comparing NeuroTabular with four fixed tree recipes. Mean binary ROC-AUC is 0.8461, multiclass accuracy is 0.8275, and regression R² is 0.5320. These are workload-specific engineering measurements, not a claim of universal superiority. See 0.3 benchmark evidence for scope, exact aggregates, comparisons, and known failure cases. Historical 0.2 binary measurements remain in BENCHMARK_REPORT.md.

scikit-learn use

from sklearn.base import clone
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import cross_val_score

from neurotabular import NeuroTabularClassifier

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
base = NeuroTabularClassifier(max_epochs=10, random_state=7)
copy = clone(base)
scores = cross_val_score(copy, X, y, cv=3, scoring="roc_auc")

For a complete DataFrame-preserving Pipeline, CV and small grid-search example, run python examples/pipeline_workflow.py from the local development checkout.

Input to fitting and prediction must be a pandas DataFrame with unique column names. Prediction may reorder columns by learned schema, but missing or unexpected columns are rejected rather than guessed.

Documentation

Maintenance policies and stable scope

NeuroTabular 1.0.2 follows the API maintenance, deprecation, persistence, warning and versioning policies. The reviewed 1.0 API boundary is the stable public contract; items explicitly classified as experimental or internal remain outside that guarantee. Support scope documents the validated Linux Python 3.11–3.14 CPU matrix, 3.10 legacy support and remaining evidence limits. CUDA remains optional best effort with physical NVIDIA validation pending; macOS remains outside the validated support scope. Historical reference models and private validation evidence are not packaged. See the canonical policy index for sources of truth.

Complete mixed-data workflows

Run the same executable example for each supported task:

python examples/mixed_dataframe_workflow.py --task binary
python examples/mixed_dataframe_workflow.py --task multiclass
python examples/mixed_dataframe_workflow.py --task regression

It includes a train/test split, nullable and categorical features, missing and unseen values, reordered prediction columns and scores. Add --output-dir ./models for a same-runtime joblib round-trip and optional metadata JSON. The small synthetic examples demonstrate usage; they are not benchmark results or tuning recommendations. See usage. NeuroTabular 1.0.2 includes the optional input_schema_ diagnostic. The examples exercise the stable task APIs while keeping diagnostic-only fields outside the core prediction contract.

• Usage guide
• API reference
• Minimal reproducer and safe environment report
• 0.3 benchmark evidence
• 0.3.1 performance validation
• 0.3 architecture overview
• Historical 0.2 benchmark report
• Historical 0.2 performance profile
• Historical 0.2 ablation report
• Research notes
• Release notes
• Publishing guide

Limitations

• pandas DataFrame input only;
• single-output targets; no multilabel, multioutput regression, or calibrated-probability API;
• multiclass ROC-AUC is not an early-stopping metric; use loss or accuracy;
• credit-g and Titanic show weaker binary results and split sensitivity;
• car can collapse to its majority class; yeast/glass have weak rare-class coverage;
• quake has negative R² and triazines is weak and split-sensitive; see the benchmark limitations;
• no claim of state-of-the-art accuracy or tree-model superiority;
• internal validation reduces the rows used for the selected model unless optional full-data refit is enabled;
• the embedding-width budget is not a byte-level RAM/VRAM cap; very high-cardinality categoricals can still increase model size substantially;
• concurrent fit calls in the same process are not guaranteed thread-safe because fitting temporarily controls process-global RNG state;
• performance and memory measurements are hardware- and workload-specific;
• CUDA behavior is covered by fallback/probe regression tests, but physical GPU validation was not completed for this release.

Status

NeuroTabular 1.0.2 is a local Python compatibility patch candidate for the stable 1.0 API. It changes no algorithm, predictive default or public API. Linux and Windows seven-job CI evidence for the published 1.0.0 is historical evidence; each new release must pass CI on its own exact commit before publication. Independent human pilots remain unavailable and are disclosed as a soft risk.

License

NeuroTabular is created by Luca Lullo and released under the MIT License. Dependency notices are in THIRD_PARTY_NOTICES.md. See LEGAL.md for the project's legal/naming note.

Author

Created by Luca Lullo.