Model Sources¶

Univariate feature ranking.

algorithm in {"shapiro", "variance", "covariance"}. The Shapiro-Wilk and variance algorithms operate on X alone; "covariance" ranks features by absolute sample covariance with y and therefore requires y to be present.

Output schema (SCHEMA_RANK1D): feature: Utf8, score: Float64, rank: Int64. Rows are pre-sorted by descending score so rank=1 is always the top feature.

Pairwise feature ranking — long-form correlation matrix.

algorithm in {"pearson", "spearman", "kendall", "covariance"}. All algorithms now run in Rust (Kendall uses Knight's O(n log n)).

Output schema (SCHEMA_RANK2D): feature_x: Utf8, feature_y: Utf8, correlation: Float64 — one row per ordered pair of features, p × p rows total.

Per-sample silhouette values, sorted within cluster descending.

Returns one row per sample with columns sample_id (original X index), y_position (sequential 0..n-1 stack order — used by mark_silhouette to render bars in a tightly-packed Rousseeuw layout), cluster, and silhouette_value.

k is informational; if provided, the result is filtered to clusters in range(k).

Explained-variance ratio per principal component plus the cumulative running sum.

If the wrapped model exposes explained_variance_ratio_ (e.g. sklearn.decomposition.PCA), reads it directly (backward compat). Otherwise computes from raw X via Rust SVD.

Low-dimensional embedding of X via UMAP / t-SNE / PCA.

Returns dim_0 … dim_{n_components-1} plus a label column (y when provided, else zeros — used to color the scatter). random_state is taken from the source's random_state.

2D embedding of cluster centers + cluster size.

Returns one row per cluster with cluster (Int64), x / y (Float64, the 2D embedded coordinate), and size (Int64, sample count). Requires the wrapped model to expose cluster_centers_.

Learning curve: score per (train_size, fold, split).

Returns long-form rows — one per (train_size, fold, split). Each row carries the per-fold score plus the per-(train_size, split) aggregates mean_score, std_score, lower, upper (95% CI on the mean). Chart builders dedupe by (train_size, split) to render a ribbon + line; the per-fold rows enable per-fold strip overlays if a future caller wants them.

Validation curve: score per (param_value, fold, split).

Same shape as learning_curve but parameterized by an estimator hyperparameter sweep. param is the kwarg name on the wrapped estimator (e.g. "alpha" for Ridge).

Per-fold cross-validation scores.

Returns one row per (fold, split) — train and test scores for each cross-validation fold. Chart builders use this for boxplot / bar / strip distributions across folds.

Regularization-strength sweep for linear models.

Returns one row per (alpha, fold) — the per-fold test score on the held-out split — plus per-alpha mean_score / std_score aggregates. Chart builders dedupe by alpha to render a single line, and use argmax(mean_score) to mark the best alpha.

Feature importance per feature, sorted by descending |importance|.

method="builtin" reads the wrapped model's feature_importances_ (tree-based estimators) or coef_ (linear estimators, averaged absolute value across classes for multi-output linears). std is zero in this path — sklearn's built-in attribute exposes no per-feature variance.

method="permutation" calls sklearn's permutation_importance with n_repeats/scoring and populates std with the per-feature standard deviation across repeats.

Long-form SHAP values per (sample, feature, class).

Returns a DataFrame with sample_id, feature, shap_value, feature_value, feature_value_normalized, class_label.

• Regression: class_label is the constant "target" on every row.
• Binary classifiers: class_label is the positive-class name on every row; SHAP values are for the positive class.
• Multi-class classifiers: one row per (sample, feature, class); class_label carries the class name. The result has n_samples * n_features * n_classes rows total.

Explainer is auto-picked by model capability:

• coef_: shap.LinearExplainer (deterministic, fast).
• feature_importances_: shap.TreeExplainer (deterministic for tree ensembles).
• otherwise: shap.KernelExplainer (model-agnostic; uses the first min(50, N) rows of X as the background unless an explicit background array is passed).

Partial dependence per feature.

kind="average" (default) returns the marginal PD curve per feature with sample_id = -1 (one row per grid point per feature).

kind="individual" returns per-sample ICE curves: one row per (feature, sample_id, grid_point) triple with sample_id in [0, n_samples). Chart builders pair this with the detail encoding channel on sample_id to render one polyline per sample.

kind="both" returns the union of the two: ICE rows plus average rows (sample_id = -1), so a downstream chart can overlay both layers on the same DataFrame.

ROC curve(s). One row per (class, threshold). auc repeats per class.

For binary classifiers with average=None (default), returns a single curve on the positive (second) class. For multiclass, returns one-vs-rest curves per class; pass average in {"micro", "macro", "weighted"} to additionally include a summary curve under class="<average>".

Precision-recall curve(s). One row per (class, threshold).

For binary classifiers, returns a single curve on the positive (second) class — average is accepted for API symmetry with the multiclass path but has no effect because binary classifiers have only one curve to draw. For multiclass:

• average=None (default) — returns one-vs-rest curves per class.
• average in {"micro", "macro", "weighted"} — returns a single summary curve with class="<average>" and no per-class rows. Macro / weighted variants interpolate per- class precision over a shared recall grid (100 points); micro ravels the binarized labels into one curve. threshold is NaN on every row of macro / weighted summaries (recall-grid interpolation discards thresholds) and follows sklearn's padding convention for micro.

threshold is NaN at the final (recall=0) point of every per-class curve per sklearn's convention.

Calibration (reliability) curve for binary classifiers.

Returns one row per non-empty bin with mean_predicted, fraction_positive, and count. Delegates to the calibration_kernel Rust kernel.

Cumulative-gain curve per class. Appends a 2-row class='baseline' diagonal for plotting reference.

Lift curve per class. Appends a 2-row class='baseline' line at lift=1.0.

Discrimination threshold sweep — binary classifiers only.

Sweeps n_thresholds evenly-spaced thresholds in [0, 1] and reports precision, recall, F1, and queue_rate at each. queue_rate is the hand-computed fraction (y_score >= t).mean().

When cv is an int, runs the same sweep on each fold's held-out scores from a freshly-cloned + re-fit estimator and averages per-threshold metrics across folds. Pass a splitter object with a .split() method to override.

Confusion matrix in long form: one row per (actual, predicted) cell.

normalize: None for raw counts, "true"/"pred"/"all" for sklearn-style normalization. value is the (possibly normalized) count; value_fmt is a stringified label suitable for mark_text overlay (integer counts when unnormalized, two-decimal fractions when normalized).

Return y_true, y_pred, residual, studentized_residual, cooks_distance, leverage.

leverage is the diagonal of the hat matrix H = X (XᵀX)⁻¹ Xᵀ for linear estimators (those exposing coef_); NaN otherwise. Used by the residuals-vs-leverage panel of multi-panel residuals charts.

Return y_true + one column per class with predicted probability.

Build a ComparedModelSource over one ModelSource per model.

Each value in models is wrapped in its own ModelSource with the shared X and y. The returned ComparedModelSource proxies every derived-data method through all wrapped sources and stamps the model name as a model column on the concatenated output, so downstream chart builders can route color="model".

Parameters:

Returns:

Examples:

>>> import ferrum as fm
>>> from sklearn.linear_model import Ridge, Lasso
>>> cms = fm.ModelSource.compare(
...     {"ridge": Ridge().fit(X, y), "lasso": Lasso().fit(X, y)},
...     X, y, random_state=0,
... )
>>> fm.roc_chart(cms)          # overlay both ROC curves
>>> cms.model_names
['ridge', 'lasso']