fde-tabular 1.0.0__py3-none-any.whl

fde/__init__.py

@@ -0,0 +1,12 @@
+"""FDE: Feasible Diverse Ensembles for tabular classification."""
+__version__ = "1.0.0"
+__all__ = ["FDEClassifier", "__version__"]
+
+
+def __getattr__(name):
+    # FDEClassifier is imported on first use, so that the command line can print its first message before the
+    # learner libraries load
+    if name == "FDEClassifier":
+        from .classifier import FDEClassifier
+        return FDEClassifier
+    raise AttributeError(name)

fde/classifier.py

@@ -0,0 +1,308 @@
+"""FDEClassifier: Feasible Diverse Ensemble.
+
+Procedure (the configuration evaluated in the accompanying paper):
+  1. Metric of a run: macro-F1 when there are two classes and the minority share is below 0.15, weighted-F1
+     otherwise.
+  2. The training rows are cut into 3 stratified outer folds. For each fold, on its fit rows, and once on all rows,
+     two things are built: the best tuned learner, and the members — class-weighted, imbalance-specific and
+     rebalanced ones, plus those of fde.extended (large-budget GBDTs, an MLP, large forests).
+  3. Combiner: stacking (multinomial logistic regression over the probabilities of the best learner and the
+     members) followed by per-class probability scales; both are fitted on out-of-fold probabilities.
+  4. Acceptance rule, cross-fitted over the pooled outer-fold predictions: the ensemble is used only if three
+     conditions hold — the lower 5% bootstrap quantile of its gain over the best tuned learner is above 0, its
+     weight in the all-rows fit is non-zero, and it differs from the best learner on at least one outer-fold row.
+     Otherwise the best tuned learner is kept. No imbalance level is treated differently.
+members="light" drops the extended members of step 2, which makes the ensemble lighter and faster but somewhat less
+accurate in the accompanying paper.
+"""
+import json, os, sys, time
+
+import joblib
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import StratifiedKFold
+
+from . import __version__, device
+from .combiners import GRID_WIDE, apply, fast_score, fit_combiner
+from .deploy_test import OUTER_FOLDS, acceptance_rule, gate_metric
+from .extended import KINDS, fit_member, raw_frame
+from .learners import Member
+from .members import inner_splits, member_task, pick_best, recipes, tune_one, tuned_types
+
+FAMILIES = ("cwc2", "imb", "rbc2")
+MARGIN = 0.0                       # the ensemble is used when the lower bound of its gain lies above 0
+
+
+def imbalance_group(y):
+    cnt = np.bincount(y); cnt = cnt[cnt > 0]; ir = cnt.max() / cnt.min()
+    return ("balanced" if ir < 3 else "low" if ir < 10 else "moderate" if ir < 50 else "extreme"), float(ir)
+
+
+def prepare_frame(X):
+    """Column names as strings, non-numeric columns as objects holding NaN for missing values, and numbers that
+    arrive as text converted to numbers. Categorical columns are left raw; each learner encodes them on its own
+    training rows."""
+    X = pd.DataFrame(X).copy()
+    X.columns = [str(c) for c in X.columns]
+    for c in X.columns:
+        if not pd.api.types.is_numeric_dtype(X[c]):
+            X[c] = X[c].astype("object").where(X[c].notna(), np.nan)
+    for c in X.columns:
+        if not pd.api.types.is_numeric_dtype(X[c]):
+            v = pd.to_numeric(X[c].astype("string").str.strip(), errors="coerce")
+            nn = X[c].notna() & (X[c].astype("string").str.strip() != "")
+            if nn.sum() > 0 and v[nn].notna().mean() >= 0.95:
+                X[c] = v.astype(float)
+    return X.reset_index(drop=True)
+
+
+def console():
+    """Rich console on stderr for progress and messages (plain text when stderr is not a terminal)."""
+    from rich.console import Console
+    return Console(stderr=True, highlight=False)
+
+
+def _say(con, verbose):
+    from rich.markup import escape
+    return (lambda msg, style="": con.print(f"[bold cyan]fde[/] " + (f"[{style}]{escape(msg)}[/]" if style else escape(msg)))) \
+        if verbose else (lambda msg, style="": None)
+
+
+def plan_jobs(n_jobs, X):
+    """Parallel jobs from what the machine has free: usable CPU cores (one is left for the system) and available
+    memory (each job is given about 30 times the size of the data, at least 300 MB). Returns (jobs, description)."""
+    import psutil
+    try:
+        cores = len(os.sched_getaffinity(0))
+    except AttributeError:                               # not available on Windows and macOS
+        cores = os.cpu_count() or 1
+    free = psutil.virtual_memory().available
+    per_job = max(300e6, 30 * float(pd.DataFrame(X).memory_usage(deep=True).sum()))
+    auto = max(1, min(cores - 1, int(free // per_job)))
+    jobs = auto if n_jobs in (None, -1) else max(1, min(int(n_jobs), cores))
+    return jobs, f"{cores} CPU cores, {free / 1e9:.1f} GB memory free -> {jobs} parallel jobs"
+
+
+def gpu_note(want):
+    """Device actually used, and a line for the system check."""
+    name = device.available()
+    if want == "gpu" and name:
+        return "gpu", f"{name}, used for XGBoost, CatBoost and the MLP (results can differ slightly from the CPU)"
+    if want == "gpu":
+        return "cpu", "no CUDA GPU found, so the CPU is used"
+    return "cpu", (f"{name} found, not used (--device gpu uses it)" if name else "none found; the CPU is used")
+
+
+def _call(key, fn, args, dev="cpu"):
+    """One parallel task on device `dev`; library notices (deprecations, CUDA probing) are not shown."""
+    import warnings
+    device.use(dev)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return key, fn(*args)
+
+
+# rough relative cost of tuning each learner type, used only to start the slow tasks first and to weight the progress bar
+COST = {"cat": 20, "rf": 3, "et": 3, "xgb": 2, "lgbm": 2, "hgb": 2, "svc": 2, "mlp": 2, "catn_cat": 6, "nn_mlp": 3}
+
+
+def _weight(key):
+    return float(COST.get(key[-1] if isinstance(key, tuple) else key, 1))
+
+
+def _ansi_ok(stream):
+    """True when the terminal shows colours; on Windows 10 and later this switches on the console's colour mode."""
+    if not stream.isatty():
+        return False
+    if os.name != "nt":
+        return True
+    try:
+        import ctypes
+        k = ctypes.windll.kernel32; h = k.GetStdHandle(-12); mode = ctypes.c_uint32()
+        return bool(k.GetConsoleMode(h, ctypes.byref(mode)) and k.SetConsoleMode(h, mode.value | 0x0004))
+    except Exception:
+        return False
+
+
+class _Bar:
+    """One-line progress bar on stderr (terminal only): stage, bar, percentage, tasks done, elapsed and remaining time,
+    and the tasks still running. Redrawn twice a second, so that the clock keeps moving while a long task runs."""
+
+    def __init__(self, n, work, stage, on):
+        self.n, self.work, self.stage, self.done, self.got, self.t0, self.what = n, max(work, 1e-9), stage, 0, 0.0, time.time(), "starting"
+        self.on = on and sys.stderr.isatty()
+        if not self.on:
+            return
+        enc = (getattr(sys.stderr, "encoding", "") or "").lower().replace("-", "")
+        self.full, self.empty = ("\u2588", "\u2591") if enc in ("utf8", "utf16", "utf16le") else ("#", "-")
+        c = _ansi_ok(sys.stderr)
+        self.c = (lambda code, t: f"\033[{code}m{t}\033[0m") if c else (lambda code, t: t)
+        import threading
+        self.stop = threading.Event(); threading.Thread(target=self._tick, daemon=True).start()
+
+    def _tick(self):
+        while not self.stop.wait(0.5):
+            self.draw()
+
+    def step(self, weight, what):
+        self.done += 1; self.got += weight; self.what = what; self.draw()
+
+    def draw(self):
+        if not self.on:
+            return
+        el = time.time() - self.t0; frac = min(self.got / self.work, 1.0); w = 26; k = int(w * frac)
+        rem = max(el / frac - el, 0) if frac > 0 else 0
+        fmt = lambda t: f"{int(t // 60)}:{int(t % 60):02d}"
+        bar = self.c("32", self.full * k) + self.c("90", self.empty * (w - k))
+        line = (f"\r{self.c('1', self.stage)}  {bar} {self.c('1', f'{100 * frac:3.0f}%')}  {self.done}/{self.n}  "
+                f"{fmt(el)} elapsed  {self.c('36', '~' + fmt(rem) + ' left')}  {self.c('90', self.what[:30]):30s}")
+        sys.stderr.write(line); sys.stderr.flush()
+
+    def close(self):
+        if self.on:
+            self.stop.set(); sys.stderr.write("\r" + " " * 130 + "\r"); sys.stderr.flush()
+
+
+def _run(tasks, n_jobs, stage, verbose, say, dev="cpu", con=None):
+    """Runs {key: (fn, args, label)} on n_jobs processes, slow tasks first, with a progress bar; returns {key: result}."""
+    from joblib import Parallel, delayed
+    order = sorted(tasks, key=_weight, reverse=True); out, t0 = {}, time.time()
+    bar = _Bar(len(order), sum(_weight(k) for k in order), stage, verbose)
+    try:
+        for key, r in Parallel(n_jobs=n_jobs, backend="loky", return_as="generator_unordered")(
+                delayed(_call)(key, tasks[key][0], tasks[key][1], dev) for key in order):
+            out[key] = r; left = [k for k in order if k not in out]
+            names = sorted({str(k[-1]) if isinstance(k, tuple) else str(k) for k in left})
+            bar.step(_weight(key), f"{len(left)} left: {', '.join(names)}" if left else "finishing")
+    finally:
+        bar.close()
+    say(f"{stage}: {len(order)} tasks in {time.time() - t0:.0f} s", "green")
+    return out
+
+
+def _probs(models, labs, X, Xr=None):
+    return {l: models[l].predict_proba(Xr if l in KINDS else X).astype(np.float32).astype(np.float64)
+            for l in ["P1"] + labs if l in models}
+
+
+class FDEClassifier:
+    """Feasible Diverse Ensemble for tabular classification, in scikit-learn style.
+
+    Parameters
+    ----------
+    random_state : int, seed shared by every split, search and member.
+    n_jobs : int, parallel tasks; -1 (default) chooses from the free CPU cores and memory (see plan_jobs). Each tuned
+        learner is single-threaded. Results do not depend on n_jobs.
+    trials : int, Optuna trials for each learner type (20 in the evaluated configuration).
+    members : "full" (default) or "light", the latter keeping only the imbalance-handling members: lighter and
+        faster.
+    member_threads : int, threads per extended member (4 in the evaluated configuration).
+    device : "cpu" (default; the results of the accompanying paper) or "gpu" (XGBoost, CatBoost and the MLP on the first
+        CUDA GPU; faster on large data, results can differ slightly from the CPU; falls back to the CPU without a GPU).
+    verbose : int, 0 silent; 1 progress messages on stderr; 2 also prints the report when fitting ends.
+    """
+
+    def __init__(self, random_state=0, n_jobs=-1, trials=20, members="full", member_threads=4, device="cpu", verbose=0):
+        self.random_state, self.n_jobs, self.trials = random_state, n_jobs, trials
+        self.members, self.member_threads, self.device, self.verbose = members, member_threads, device, verbose
+
+    def fit(self, X, y):
+        t0 = time.time()
+        if self.members not in ("full", "light"):
+            raise ValueError('members must be "full" or "light"')
+        if self.device not in ("cpu", "gpu"):
+            raise ValueError('device must be "cpu" or "gpu"')
+        Xr, self.cat_ = raw_frame(X)
+        X = prepare_frame(X); y_raw = pd.Series(np.asarray(y)).astype(str)
+        self.classes_ = np.array(sorted(y_raw.unique()))
+        y = y_raw.map({c: i for i, c in enumerate(self.classes_)}).to_numpy(dtype=np.int64)
+        self.columns_ = list(X.columns); K = len(self.classes_); seed = self.random_state
+        if K < 2:
+            raise ValueError("at least two classes are required")
+        self.metric_ = gate_metric(y); self.group_, ir = imbalance_group(y)
+        rounds = list(StratifiedKFold(OUTER_FOLDS, shuffle=True, random_state=seed).split(np.zeros(len(y)), y))
+        sub = lambda D, i: D.iloc[i].reset_index(drop=True)
+        sets = [(sub(X, i), y[i], sub(Xr, i)) for i, _ in rounds] + [(X, y, Xr)]
+        names = [f"fold {k + 1}/3" for k in range(3)] + ["all rows"]
+        con = console(); say = _say(con, self.verbose)
+        say(f"{len(y)} rows, {K} classes, metric {self.metric_}, members: {self.members}")
+        say("checking the system ...", "dim")
+        jobs, machine = plan_jobs(self.n_jobs, X)
+        say(f"  CPU and memory: {machine}")
+        self.device_used_, gpu_line = gpu_note(self.device)
+        say(f"  GPU: {gpu_line}")
+        splits = [inner_splits(yf, seed, 3) for _, yf, _ in sets]
+        types = tuned_types(len(y))
+        # stage 1: every learner type in every fit set is tuned as its own task
+        tuned = _run({(k, mt): (tune_one, (Xf, yf, K, self.metric_, seed, splits[k], self.trials, mt), f"{names[k]}: {mt}")
+                      for k, (Xf, yf, _) in enumerate(sets) for mt in types}, jobs, "Stage 1/3 Tuning learners", self.verbose, say, self.device_used_, con)
+        # stage 2: the best learner and every member of every fit set, each as its own task
+        best, tasks = [], {}
+        for k, (Xf, yf, Xrf) in enumerate(sets):
+            mt, p, inner, pool, tune = pick_best({t: tuned[(k, t)] for t in types})
+            rec, others = recipes(Xf, K, seed, mt, p, pool, FAMILIES)
+            best.append({"best_type": mt, "best_params": p, "inner_score": inner, "pool": {t: round(v[0], 5) for t, v in pool.items()},
+                         "tune_seconds": tune, "other_types": others, "n_rows": len(yf)})
+            cols = list(Xf.columns)
+            tasks[(k, "P1")] = (member_task, ((lambda mt=mt, p=p: Member(mt, p, cols, K, seed)), Xf, yf, splits[k], K, True), f"{names[k]}: P1")
+            for lab, make in rec:
+                tasks[(k, lab)] = (member_task, (make, Xf, yf, splits[k], K, True), f"{names[k]}: {lab}")
+            for kind in KINDS if self.members == "full" else ():
+                tasks[(k, kind)] = (fit_member, (kind, Xrf, yf, K, seed, self.cat_, self.member_threads), f"{names[k]}: {kind}")
+        built = _run(tasks, jobs, "Stage 2/3 Building members", self.verbose, say, self.device_used_, con)
+        oofs, models = [{} for _ in sets], [{} for _ in sets]
+        for (k, lab), (o, m) in built.items():
+            oofs[k][lab] = o.astype(np.float32).astype(np.float64); models[k][lab] = m
+        # stage 3: the combiner of every fit set
+        labs = [sorted(l for l in oofs[k] if l != "P1") for k in range(4)]
+        comb = _run({k: (fit_combiner, ("stack_scaled", oofs[k], labs[k], sets[k][1], K, self.metric_, seed, GRID_WIDE), names[k])
+                     for k in range(4)}, jobs, "Stage 3/3 Combiners", self.verbose, say, "cpu", con)
+        out = [{"models": models[k], "spec": comb[k][0], "weight": comb[k][2], "info": best[k], "labs": labs[k]} for k in range(4)]
+        cf_ref, cf_cand = np.zeros(len(y), int), np.zeros(len(y), int)
+        for (i, j), r in zip(rounds, out[:3]):
+            p = _probs(r["models"], r["labs"], sub(X, j), sub(Xr, j))
+            cf_ref[j] = p["P1"].argmax(1); cf_cand[j] = apply(r["spec"], p).argmax(1)
+        rule = acceptance_rule(y, cf_ref, cf_cand, metric=self.metric_, seed=0, K=K, margin=MARGIN)
+        full = out[3]
+        self.uses_ensemble_ = bool(rule.accept and full["weight"] > 0 and np.any(cf_cand != cf_ref))
+        self.decision_ = ("used" if self.uses_ensemble_ else "not_consistent" if not rule.accept
+                          else "same_predictions" if not np.any(cf_cand != cf_ref) else "no_member_weight")
+        if self.uses_ensemble_:
+            self.model_ = full
+        else:
+            self.model_ = {"models": {"P1": full["models"]["P1"]}, "spec": {"kind": "best"}, "labs": [], "info": full["info"]}
+        self.crossfit_ = {"reference": fast_score(y, cf_ref, K, self.metric_), "ensemble": fast_score(y, cf_cand, K, self.metric_)}
+        if self.uses_ensemble_:
+            say(f"Acceptance rule: the ensemble predicted better on the training folds, so it is used ({1 + len(full['labs'])} models)", "bold green")
+        else:
+            say("Acceptance rule: the best tuned learner alone was as good on the training folds, so it is kept (one model)", "bold cyan")
+        say(f"Done in {time.time() - t0:.0f} s", "bold green")
+        info = self.model_["info"]
+        self.report_ = {"version": __version__, "rows": len(y), "classes": [str(c) for c in self.classes_], "imbalance_ratio": round(ir, 3),
+                        "imbalance_group": self.group_, "metric": self.metric_, "best_learner": info["best_type"],
+                        "best_learner_inner_score": round(info["inner_score"], 5),
+                        "acceptance_rule": {"lower_bound": round(rule.lower_bound, 5), "gain": round(rule.gain, 5), "margin": MARGIN,
+                                            "accepted": bool(rule.accept)},
+                        "crossfit_scores": self.crossfit_, "decision": self.decision_,
+                        "uses_ensemble": self.uses_ensemble_, "models_in_predictor": 1 + (len(self.model_["labs"]) if self.uses_ensemble_ else 0),
+                        "options": {"members": self.members, "trials": self.trials, "member_threads": self.member_threads,
+                                    "device": self.device_used_},
+                        "fit_seconds": round(time.time() - t0, 1)}
+        if self.verbose >= 2:
+            print(json.dumps(self.report_, indent=1))
+        return self
+
+    def predict_proba(self, X):
+        Xr = raw_frame(X, self.cat_)[0]
+        X = prepare_frame(X)[self.columns_]
+        return apply(self.model_["spec"], _probs(self.model_["models"], self.model_["labs"], X, Xr))
+
+    def predict(self, X):
+        return self.classes_[self.predict_proba(X).argmax(1)]
+
+    def save(self, path):
+        joblib.dump(self, path)
+
+    @staticmethod
+    def load(path):
+        return joblib.load(path)

fde/cli.py

@@ -0,0 +1,216 @@
+"""Command line: fde demo | fit | predict | evaluate.
+
+  fde demo [--members full|light] [--trials 5] [--jobs -1]   (evaluate on the breast cancer data shipped with
+              scikit-learn; no file or download needed; quick settings by default)
+
+  fde fit --data train.csv --target y --out model.fde [--seed 0] [--jobs -1] [--trials 20] [--members full|light]
+  fde predict --model model.fde --data new.csv [--proba] [--out predictions.csv]
+  fde evaluate --data data.csv --target y [--test-size 0.2] [--seed 0] ...   (holds out a stratified part of the
+              data and scores FDE against the best tuned learner on it, reporting macro-F1, weighted-F1 and
+              balanced accuracy; the run metric is whichever F1 column applies)
+"""
+import argparse, json, sys
+
+
+def _read(path):
+    import pandas as pd
+    return pd.read_parquet(path) if path.endswith(".parquet") else pd.read_csv(path, low_memory=False)
+
+
+def _clf(a):
+    from .classifier import FDEClassifier
+    return FDEClassifier(random_state=a.seed, n_jobs=a.jobs, trials=a.trials, members=a.members, device=a.device,
+                         verbose=0 if a.quiet else 1)
+
+
+def _scores(y, p):
+    from sklearn.metrics import balanced_accuracy_score, f1_score
+    return {"macro_f1": round(f1_score(y, p, average="macro"), 5), "weighted_f1": round(f1_score(y, p, average="weighted"), 5),
+            "balanced_accuracy": round(balanced_accuracy_score(y, p), 5)}
+
+
+NAMES = {"hgb": "HistGradientBoosting", "xgb": "XGBoost", "lgbm": "LightGBM", "cat": "CatBoost", "rf": "random forest",
+         "et": "extra trees", "svc": "SVC", "knn": "k-nearest neighbours", "lr": "logistic regression", "nb": "naive Bayes",
+         "mlp": "MLP", "dt": "decision tree"}
+METRIC = {"wF1": "weighted-F1", "macroF1": "macro-F1"}
+
+
+def _summary(r, test=None, n_test=None, saved=None):
+    """Readable result on stdout: the decision and the held-out scores first (highlighted), then the details, the
+    reasons and how the data were split. Plain text when stdout is not a terminal."""
+    from rich import box
+    from rich.console import Console, Group
+    from rich.panel import Panel
+    from rich.table import Table
+    from rich.text import Text
+    con, o, used = Console(highlight=False), r["options"], r["uses_ensemble"]
+    n = r["models_in_predictor"]
+    head = (Text(f"Ensemble used ({n} models: best learner, members and combiner)", style="bold green") if used else
+            Text("Best tuned learner kept (one model; the ensemble was not needed)", style="bold cyan"))
+    parts = [head]
+    if test:
+        t = Table(box=box.SIMPLE_HEAD, show_edge=False, pad_edge=False, header_style="bold")
+        t.add_column(f"held-out rows ({n_test})"); t.add_column("FDE", justify="right"); t.add_column("best tuned learner", justify="right")
+        for k, lab in (("macro_f1", "macro-F1"), ("weighted_f1", "weighted-F1"), ("balanced_accuracy", "balanced accuracy")):
+            a, b = test["fde"][k], test["best_tuned_learner"][k]
+            t.add_row(lab, Text(f"{a:.4f}", style="bold green" if a > b else ""), Text(f"{b:.4f}", style="bold green" if b > a else ""))
+        parts += [Text(""), t, Text("FDE kept the best tuned learner, so both columns are the same." if not used else
+                                    "Higher scores are in green.", style="dim")]
+    con.print(); con.print(Panel(Group(*parts), title="[bold]FDE result[/]", border_style="green" if used else "cyan", expand=False))
+    g = Table.grid(padding=(0, 2)); g.add_column(style="bold"); g.add_column()
+    cls = ", ".join(r["classes"][:6]) + (", ..." if len(r["classes"]) > 6 else "")
+    imb = "balanced" if r["imbalance_group"] == "balanced" else f"{r['imbalance_group']} imbalance"
+    g.add_row("Data", f"{r['rows']} training rows, {len(r['classes'])} classes ({cls}), {imb} (ratio {r['imbalance_ratio']:.1f})")
+    g.add_row("Best learner", f"{NAMES.get(r['best_learner'], r['best_learner'])} (inner {METRIC[r['metric']]} {r['best_learner_inner_score']:.4f})")
+    g.add_row("Fit time", f"{r['fit_seconds']:.0f} s ({o['trials']} trials, {o['members']} members, {o['device'].upper()})")
+    if saved:
+        g.add_row("Saved to", saved)
+    g.add_row("Why", _why(r))
+    con.print(g)
+    steps = ([f"{n_test} rows were set aside before fitting and used only for the held-out scores."] if test else []) + [
+        "On the training rows, 3 outer folds decided whether the ensemble is used, judged on rows that each fold's "
+        "models had not seen.",
+        "Inside every fold, the learners were tuned and the combiner fitted on 3 inner folds; every imputer, encoder "
+        "and scaler was fitted on its own training rows only."]
+    con.print(f"\n[bold]How {'it was evaluated' if test else 'the model was chosen'}[/] [dim](no row is used both to choose a model and to score it)[/]")
+    from rich.padding import Padding
+    lst = Table.grid(padding=(0, 1)); lst.add_column(justify="right", style="dim"); lst.add_column(style="dim")
+    for i, x in enumerate(steps, 1):
+        lst.add_row(f"{i}.", x)
+    lst.add_row("", "To compare with another tool, score it on the same held-out rows; scores computed on rows that were "
+                    "also used for tuning come out higher than they will be on new data." if test else
+                    "To see how the model does on new data, use `fde evaluate` or score your own held-out rows.")
+    con.print(Padding(lst, (0, 0, 0, 2)))
+    con.print()
+
+
+# share of runs that used the ensemble in the accompanying study (53 datasets x 5 seeds), by imbalance group
+STUDY = {"balanced": 8, "low": 54, "moderate": 83, "extreme": 83}
+GROUP = {"balanced": "balanced data (imbalance ratio below 3)", "low": "data with low imbalance (ratio 3 to 10)",
+         "moderate": "data with moderate to extreme imbalance (ratio 10 or more)",
+         "extreme": "data with moderate to extreme imbalance (ratio 10 or more)"}
+
+
+def _why(r):
+    """Plain-language reasons for the decision, from the cross-fitted scores of the training folds."""
+    cf, m = r["crossfit_scores"], METRIC[r["metric"]]
+    ref, ens, d = cf["reference"], cf["ensemble"], r.get("decision")
+    seen = (f"On training rows that each fold's models had not seen, the ensemble scored {ens:.4f} and the best tuned "
+            f"learner {ref:.4f} ({m}).")
+    if d == "used":
+        why = (" The ensemble was better, and its advantage held in at least 95% of the bootstrap resamples of those rows, "
+               "so FDE uses it. Its members (learners refitted with class weights, on rebalanced samples, and "
+               "imbalance-specific ensembles" + (", plus large-budget GBDTs, an MLP and large forests" if r["options"]["members"] == "full" else "")
+               + ") correct some of the errors of the best tuned learner.")
+    elif d == "not_consistent" and ens > ref:
+        why = (" The ensemble scored a little higher, but the advantage did not hold in at least 95% of the bootstrap "
+               "resamples, so it may be chance. FDE keeps the single model, which is simpler and faster to predict.")
+    elif d == "not_consistent":
+        why = (" The ensemble was not better, so FDE keeps the single model, which is simpler and faster to predict.")
+    elif d == "same_predictions":
+        why = " The ensemble made the same predictions as the best tuned learner, so FDE keeps the single model."
+    else:
+        why = " The combiner gave the members no weight, so FDE keeps the single model."
+    ctx = (f" For comparison: in the accompanying study (full member set), the ensemble was used in "
+           f"{STUDY[r['imbalance_group']]}% of runs on {GROUP[r['imbalance_group']]}.")
+    return seen + why + ctx
+
+
+def _evaluate(X, y, a):
+    import numpy as np
+    import pandas as pd
+    from sklearn.model_selection import train_test_split
+    from .classifier import prepare_frame
+    y = pd.Series(y).astype(str).to_numpy()
+    tr, te = train_test_split(np.arange(len(y)), test_size=a.test_size, stratify=y, random_state=a.seed)
+    clf = _clf(a).fit(X.iloc[tr], y[tr])
+    p = clf.predict(X.iloc[te]); best = clf.model_["models"]["P1"]
+    pb = clf.classes_[best.predict_proba(prepare_frame(X.iloc[te])[clf.columns_]).argmax(1)]
+    test = {"fde": _scores(y[te], p), "best_tuned_learner": _scores(y[te], pb)}
+    if a.json:
+        print(json.dumps({"report": clf.report_, "test": test}, indent=1))
+    else:
+        _summary(clf.report_, test, len(te))
+
+
+def _common(s, trials=20, members="full"):
+    s.add_argument("--seed", type=int, default=0, help="seed shared by every split, search and member (default: 0)")
+    s.add_argument("--jobs", type=int, default=-1, help="parallel tasks; -1 chooses from the free CPU cores and memory (default: -1)")
+    s.add_argument("--trials", type=int, default=trials, help=f"Optuna trials for each learner type (default: {trials})")
+    s.add_argument("--members", choices=("full", "light"), default=members,
+                   help=f"light keeps the imbalance-handling members only: faster, slightly less accurate (default: {members})")
+    s.add_argument("--device", choices=("cpu", "gpu"), default="cpu",
+                   help="gpu trains XGBoost, CatBoost and the MLP on a CUDA GPU: faster on large data, results can differ "
+                        "slightly from the CPU (default: cpu)")
+    s.add_argument("--quiet", action="store_true", help="no progress messages")
+    s.add_argument("--json", action="store_true", help="print the full report as JSON instead of the summary")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="fde", description="Feasible Diverse Ensembles for tabular classification")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name, text in (("fit", "fit FDE and save the model"),
+                       ("evaluate", "fit on part of the data, then score the holdout")):
+        s = sub.add_parser(name, help=text, description=text)
+        s.add_argument("--data", required=True, help="input data (CSV or Parquet)")
+        s.add_argument("--target", required=True, help="column that holds the labels")
+        _common(s)
+        if name == "fit":
+            s.add_argument("--out", required=True, help="where to save the fitted model")
+        else:
+            s.add_argument("--test-size", type=float, default=0.2,
+                           help="fraction of rows held out, stratified by class (default: 0.2)")
+    text = ("evaluate FDE on example data, no file or download needed; quick settings by default (5 trials, light "
+            "members). --example breast-cancer: the best tuned learner is enough; --example imbalanced: the ensemble is used")
+    s = sub.add_parser("demo", help=text, description=text); _common(s, trials=5, members="light")
+    s.add_argument("--example", choices=("breast-cancer", "imbalanced"), default="breast-cancer",
+                   help="breast-cancer: 569 rows, balanced classes; imbalanced: 2,000 synthetic rows, 10%% minority (default: breast-cancer)")
+    s.add_argument("--test-size", type=float, default=0.2, help="fraction of rows held out, stratified by class (default: 0.2)")
+    s = sub.add_parser("predict", help="score new rows with a fitted model, as labels or probabilities",
+                       description="score new rows with a fitted model, as labels or probabilities")
+    s.add_argument("--model", required=True, help="model saved by fde fit")
+    s.add_argument("--data", required=True, help="input data (CSV or Parquet)")
+    s.add_argument("--proba", action="store_true", help="write class probabilities rather than labels")
+    s.add_argument("--out", default=None, help="CSV to write (default: standard output)")
+    a = ap.parse_args(argv)
+    if a.cmd in ("demo", "fit", "evaluate") and not a.quiet:
+        print("fde loading the learner libraries (a few seconds on the first run) ...", file=sys.stderr, flush=True)
+    if a.cmd == "fit":
+        d = _read(a.data); clf = _clf(a).fit(d.drop(columns=[a.target]), d[a.target]); clf.save(a.out)
+        if a.json:
+            print(json.dumps(clf.report_, indent=1))
+        else:
+            _summary(clf.report_, saved=a.out)
+    elif a.cmd == "predict":
+        import pandas as pd
+        from .classifier import FDEClassifier
+        clf = FDEClassifier.load(a.model); d = _read(a.data)
+        out = pd.DataFrame(clf.predict_proba(d), columns=[f"p_{c}" for c in clf.classes_]) if a.proba else pd.DataFrame({"prediction": clf.predict(d)})
+        if a.out:
+            out.to_csv(a.out, index=False)
+        else:
+            out.to_csv(sys.stdout, index=False)
+    elif a.cmd == "demo":
+        quick = f"quick settings: {a.trials} trials, {a.members} members (the paper's settings: --trials 20 --members full)"
+        if a.example == "breast-cancer":
+            from sklearn.datasets import load_breast_cancer
+            d = load_breast_cancer(as_frame=True); X, y = d.data, d.target.map(dict(enumerate(d.target_names)))
+            what = "breast cancer data (569 rows, 30 columns, 2 balanced classes)"
+        else:
+            import numpy as np
+            import pandas as pd
+            from sklearn.datasets import make_classification
+            Xa, ya = make_classification(n_samples=2000, n_features=20, n_informative=6, n_redundant=4, weights=[0.9, 0.1],
+                                         flip_y=0.02, class_sep=0.8, random_state=1)
+            X, y = pd.DataFrame(Xa, columns=[f"x{i}" for i in range(20)]), np.where(ya == 1, "minority", "majority")
+            what = "synthetic imbalanced data (2,000 rows, 20 columns, 10% minority class)"
+        if not a.quiet:
+            from rich.console import Console
+            Console(stderr=True, highlight=False).print(f"[bold cyan]fde[/] demo: {what}; [dim]{quick}[/]")
+        _evaluate(X, y, a)
+    else:
+        d = _read(a.data); _evaluate(d.drop(columns=[a.target]), d[a.target], a)
+
+
+if __name__ == "__main__":
+    main()