Model Sources¶

Ordered (name, ModelSource) pairs for each wrapped model.

The public accessor over the wrapped sources, in registration order. Chart builders iterate this to compose one panel per model without reaching into the private _sources mapping.

Returns:

Build one frame per wrapped model via frame_fn and stack them.

The callable-form sibling of the auto-dispatch in _dispatch: _dispatch calls a fixed ModelSource method name per model, while stack accepts an arbitrary per-model callable, for chart builders that need to compose several method calls (e.g. class selection before aggregation) before stacking. Both share the same iteration-and-stamping idiom, in registration order, with a model: Utf8 column recording each source's registered name.

Parameters:

Returns:

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.

Univariate feature ranking.

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.

Parameters:

Pairwise feature ranking — long-form correlation matrix.

All algorithms 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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

2D embedding of cluster centers + cluster size.

Returns one row per cluster with cluster (Utf8 — a stringified 0..k-1 index, matching SCHEMA_INTERCLUSTER_DISTANCE and the emitted column), x / y (Float64, the 2D embedded coordinate), and size (Int64, sample count). Requires the wrapped model to expose cluster_centers_.

Parameters:

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.

Parameters:

Return validation-curve scores per (param_value, fold, split).

Same shape as learning_curve but parameterized by an estimator hyperparameter sweep.

Parameters:

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.

Parameters:

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.

Parameters:

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

Parameters:

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).

Parameters:

Partial dependence per feature.

Parameters:

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

For binary classifiers, returns a single curve on the positive (second) class. For multiclass, returns one-vs-rest curves per class.

Parameters:

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

For binary classifiers, returns a single curve on the positive (second) class. For multiclass, average=None returns one-vs-rest curves per class, while 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 at the final (recall=0) point of every per-class curve per sklearn's convention. For macro / weighted summaries it is NaN on every row (recall-grid interpolation discards thresholds); micro follows sklearn's padding convention.

Parameters:

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.

Parameters:

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().

Parameters:

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

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).

Parameters:

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']