catfishml 0.4.0

NeuroSplit Boosting for tabular data with differentiable soft trees and neural gating.

catfishml

catfishml is a Python library for OmniBoost++: generalized boosting with adaptive routing across heterogeneous weak learners (linear, spline/GAM-like, adaptive-depth MLP, differentiable soft tree).

Why catfishml

• Adaptive residual router with complexity/redundancy penalties.
• Additive boosting in natural predictor space with Newton-style targets.
• Numeric + categorical support (categorical embeddings).
• Missing value handling with SimpleImputer or MICE-style IterativeImputer.
• Adaptive behavior:
  • automatic objective/distribution and metric selection,
  • linearity probe (auto linear vs nonlinear mode),
  • adaptive MLP depth + adaptive tree depth.
• CPU/GPU via PyTorch.
• Automatic dependency install for missing core libraries (can be disabled).

Install

pip install catfishml

For development:

pip install -e .[dev]

Quick start

import pandas as pd
from catfishml import FishyCatClassifier

X = pd.DataFrame(
    {
        "age": [25, 31, 45, None, 39, 22, 55],
        "income": [2200, 3400, 7600, 5100, None, 1900, 8800],
        "city": ["A", "B", "A", "C", "B", None, "A"],
    }
)
y = [0, 0, 1, 1, 0, 0, 1]

model = FishyCatClassifier(
    n_estimators=40,
    tree_depth=3,
    metrics="auto",
    auto_metric=True,
    impute_strategy="auto",
    candidate_families="auto",
    install_missing_libraries=True,
    n_jobs=4,
    verbose=1,
)

model.fit(X, y)
print(model.evaluate(X, y))
print(model.predict_proba(X)[:3])
fig = model.plot_visualization(kind="overview")
print(model.get_statistics())
print(model.get_history(as_dataframe=True).head())

Main API

• FishyCatBooster
• FishyCatClassifier

For regression, use FishyCatBooster(task="regression", ...).

Common parameters:

• metrics: metric name ("auto", "accuracy", "auc", "logloss", "rmse", "mae", "r2") or callable.
• auto_metric: if True, metric and training validation feedback are auto-selected by task/data.
• impute_strategy: "auto", "simple", "iterative", or "none".
• structure_mode: "auto", "linear", "nonlinear".
• boosting_order: 1 (gradient) or 2 (Newton-like weighted residuals).
• candidate_families: "auto" or subset of ["linear", "spline", "adaptive_mlp", "soft_tree"].
• plot_visualization(kind=...): loss/routing/depth/overview diagnostics.
• get_statistics(): full training + data summary.
• get_history(as_dataframe=True): per-iteration history (loss, metric, ETA, routing).
• view_data(X, transformed=True/False): inspect raw or transformed data.
• auto_install_dependencies: auto-installs missing libs using pip at runtime.
• install_plot_dependencies: if True, auto-installs plotting dependencies too.
• full_report(X, y): one-shot report (statistics + history + evaluation).
• available_components(): list of all integrated learner families/features.

Notes

• This repository provides a practical implementation of OmniBoost++ ideas; it is not a strict reproduction of a specific paper.
• For larger datasets, run on GPU: device="cuda".

License

MIT