Visualizers¶

Sklearn-protocol diagnostic visualizers. Each visualizer follows the Viz(model).fit(X, y).show() pattern and is composable inside sklearn pipelines, GridSearchCV, and external evaluators.

For the equivalent one-liner functional API, see ferrum.plots.

Base class¶

FerrumVisualizer ¶

Base class for sklearn-protocol model-diagnostic visualizers.

Concrete visualizers either override _materialize + _build_chart (the standard model-backed flow) or override fit directly (no-model / multi-fit / label-only flow).

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted estimator that will be wrapped in a `ModelSource` at `fit` time. Pass `None` for no-model visualizers (rank / parallel coordinates / class balance).	`None`
`random_state`	`int`	Seed forwarded to the underlying `ModelSource`. Ignored when the wrapped derived-data compute is deterministic.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ROCVisualizer(model, random_state=0).fit(X, y)
>>> viz.show()                # returns a Chart
>>> viz._metrics              # headline metric(s)

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Classification¶

10b/10c classification visualizers — ROC, PR, Calibration, ConfusionMatrix, ClassificationReport.

ROCVisualizer ¶

Bases: FerrumVisualizer

ROC curve(s) for binary or multiclass classifiers.

Wraps ModelSource.roc_curve(). per_class=True (default) draws one curve per class; pass per_class=False to plot a single averaged curve. Records auc_mean as the headline metric.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted classifier (must implement `predict_proba` or `decision_function`).	required
`micro`	`bool`	Compute the micro-averaged AUC.	`True`
`macro`	`bool`	Compute the macro-averaged AUC. Takes precedence over `micro` when choosing which averaged curve to plot at `per_class=False`.	`True`
`per_class`	`bool`	Render one curve per class. When False, only the averaged curve is rendered.	`True`
`random_state`	`int`		`None`
`theme`	`Theme`		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ROCVisualizer(clf).fit(X, y)
>>> viz._metrics["auc_mean"]
0.92

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

PRVisualizer ¶

Bases: FerrumVisualizer

Precision-recall curve(s) for binary or multiclass classifiers.

Wraps ModelSource.pr_curve(). Records ap_mean (average precision averaged across classes) as the headline metric.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted classifier exposing `predict_proba` or `decision_function`.	required
`random_state`	`int`		`None`
`theme`	`Theme`		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.PRVisualizer(clf).fit(X, y)
>>> viz._metrics["ap_mean"]
0.88

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

CalibrationVisualizer ¶

Bases: FerrumVisualizer

Calibration (reliability) diagram for a probability classifier.

Wraps ModelSource.calibration_curve(). Records the mean squared deviation between mean_predicted and fraction_positive as calibration_error.

Parameters:

Name	Type	Description	Default
`*models`	`Any`	One or more fitted classifiers. Pass a single model for a single-curve diagram; pass two or more (or a single dict positional argument like `{"a": m_a, "b": m_b}`) to overlay multiple curves via `ComparedModelSource`.	`()`
`n_bins`	`int`	Number of bins for the calibration histogram.	`10`
`strategy`	`('uniform', 'quantile')`	Bin-edge strategy (matches `sklearn.calibration`).	`"uniform"`
`random_state`	`int`		`None`
`theme`	`Theme`		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.CalibrationVisualizer(clf, n_bins=5).fit(X, y)
>>> viz_overlay = fm.CalibrationVisualizer(clf_a, clf_b).fit(X, y)

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ConfusionMatrixVisualizer ¶

Bases: FerrumVisualizer

Confusion-matrix heatmap with per-cell counts or normalized fractions.

Wraps ModelSource.confusion_matrix(). Renders a rect-mark heatmap with cell-value text overlaid. Records accuracy (diagonal sum / total, always computed from raw counts regardless of the normalize setting).

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted classifier implementing `predict`.	required
`normalize`	`('true', 'pred', 'all')`	Row-normalization strategy passed to the chart builder. `"true"` normalizes each row by the true-class total (recall fractions); `"pred"` by the predicted-class total (precision fractions); `"all"` by the grand total; `None` shows raw counts.	`"true"`
`random_state`	`int`	Seed forwarded to `ModelSource` for reproducible train/test splits.	`None`
`theme`	`Theme`	Ferrum theme applied to the output chart.	`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ConfusionMatrixVisualizer(clf).fit(X, y)
>>> viz._metrics["accuracy"]
0.94
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ClassificationReportVisualizer ¶

Bases: FerrumVisualizer

Per-class precision, recall, and F1-score heatmap with text overlay.

Wraps _classification_report_chart(). Produces a rect-mark heatmap with one row per class and columns for precision, recall, and F1. Records f1_macro (macro-averaged F1 across all classes, computed via sklearn.metrics.f1_score) as the headline scalar metric.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted classifier implementing `predict`.	required
`random_state`	`int`	Seed forwarded to `ModelSource` for reproducible train/test splits.	`None`
`theme`	`Theme`	Ferrum theme applied to the output chart.	`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ClassificationReportVisualizer(clf).fit(X, y)
>>> viz._metrics["f1_macro"]
0.91
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

10b/10c extra classification visualizers.

Houses visualizers that don't naturally cluster with the curve-based ones in classification.py: threshold sweep, per-class error stack, and the model-free class-balance bar.

DiscriminationThresholdVisualizer ¶

Bases: FerrumVisualizer

Sweep a decision threshold for a binary classifier and plot four metric curves.

Evaluates precision, recall, f1, and queue_rate (or a caller-supplied subset) at n_thresholds evenly-spaced probability thresholds between 0 and 1. After fit, the F1-maximising threshold and its F1 score are available via _metrics.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted binary sklearn estimator that exposes `predict_proba`.	required
`n_thresholds`	`int`	Number of probability thresholds to evaluate across `[0, 1]`.	`50`
`metrics`	`tuple of str`	Which per-threshold metrics to include as curves in the chart. Passed through to the underlying `ModelSource.discrimination_threshold` call and to `mark_discrimination_threshold`.	`("precision", "recall", "f1", "queue_rate")`
`cv`	`Any`	Cross-validation strategy forwarded to `ModelSource.discrimination_threshold`. `None` uses the model as-is (no CV averaging).	`None`
`threshold_line`	`bool`	When `True`, overlays a vertical rule at the F1-maximising threshold (matches the figure-level `discrimination_threshold_chart(threshold_line=True)`).	`False`
`random_state`	`int`	Seed forwarded to `ModelSource` for any randomness in CV splits.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.DiscriminationThresholdVisualizer(model).fit(X, y)
>>> viz.show()                   # returns the four-curve Chart
>>> viz._metrics["best_threshold"], viz._metrics["best_f1"]

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ClassPredictionErrorVisualizer ¶

Bases: FerrumVisualizer

Stacked-bar chart of actual-class composition per predicted class.

For each predicted class label on the x-axis, the bar is stacked by the true class, showing how often a predicted class is correct vs. confused with another class. When normalize=True every bar is scaled to 100 % so proportions are comparable across imbalanced classes.

After fit, overall accuracy (total correct / total predictions, computed from raw counts regardless of normalize) is stored in _metrics["accuracy"].

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted sklearn classifier that exposes `predict`.	required
`normalize`	`bool`	When `True`, each predicted-class bar is scaled to sum to 1 (100 % stacked view). When `False`, bars show absolute counts.	`False`
`random_state`	`int`	Seed forwarded to `ModelSource` for any randomness in data prep.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ClassPredictionErrorVisualizer(model).fit(X, y)
>>> viz.show()                   # returns the stacked-bar Chart
>>> viz._metrics["accuracy"]     # proportion of correct predictions

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ClassBalanceVisualizer ¶

Bases: FerrumVisualizer

Bar chart of per-class label counts, computed from target labels alone.

Accepts both the standard sklearn fit(X, y) signature and the label-only shorthand fit(y) — when the second argument is omitted, the first positional argument is treated as the label array. No model is required; pass nothing for the model argument (it is always None internally).

After fit, _metrics contains:

n_classes — number of unique class labels.
imbalance_ratio — max_count / max(min_count, 1), where 1.0 indicates perfectly balanced classes and larger values indicate increasing imbalance.

Parameters:

Name	Type	Description	Default
`random_state`	`int`	Accepted for API symmetry with model-backed visualizers but intentionally never consumed — `ClassBalanceVisualizer` overrides `fit()` and never constructs a `ModelSource`. Documented as a permanent no-op so callers that script over visualizers don't have to special-case which ones accept the kwarg.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ClassBalanceVisualizer().fit(X, y)
>>> viz.show()                   # returns the per-class count bar Chart
>>> viz._metrics["imbalance_ratio"]

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Regression¶

10a regression visualizers — ResidualsVisualizer, PredictionErrorVisualizer, CooksDistanceVisualizer.

ResidualsVisualizer ¶

Bases: FerrumVisualizer

Residuals-vs-fitted diagnostic for a regression estimator.

Wraps ModelSource.predictions(). Records rmse and mae as headline metrics; the chart shows y_pred on x and the chosen residual variant on y with a horizontal reference line at zero.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted regression estimator (must implement `predict`).	required
`kind`	`('studentized', 'raw', 'scaled')`	Which residual variant to plot. `"studentized"` uses the leverage-aware hat-matrix form when `model` exposes `coef_`; otherwise falls back to internally-studentized (residual / std).	`"studentized"`
`random_state`	`int`	Forwarded to the underlying `ModelSource`.	`None`
`theme`	`Theme`		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.ResidualsVisualizer(model).fit(X, y)
>>> viz._metrics["rmse"]
1.234
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

PredictionErrorVisualizer ¶

Bases: FerrumVisualizer

Actual-vs-predicted scatter for a regression estimator.

Wraps ModelSource.predictions(). Records rmse as the headline metric; the chart shows y_true on x and y_pred on y with an optional identity line and CI / reference band overlays.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted regression estimator.	required
`reference_line`	`bool`	Overlay the dashed `y = x` diagonal.	`True`
`ci`	`float`	Confidence level in `(0, 1)`. When set, overlays a ribbon spanning the central `ci` fraction of residuals around the reference line. Raises `ValueError` if not in `(0, 1)`.	`None`
`reference_band`	`bool`	When `True` (and `ci` is None), overlays a ±1 RMSE ribbon around the reference line.	`False`
`random_state`	`int`		`None`
`theme`	`Theme`		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.PredictionErrorVisualizer(model, ci=0.95).fit(X, y)
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

CooksDistanceVisualizer ¶

Bases: FerrumVisualizer

Cook's distance diagnostic for a regression estimator.

Surfaces max_studentized (the largest absolute studentized residual) as a quick proxy for influential observations; the leverage-aware Cook's D itself is materialized by ModelSource.predictions().cooks_distance for linear estimators and is rendered by mark_residuals(cook_threshold=...). This visualizer plots the residuals chart with the leverage panel enabled.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted regression estimator (must expose `coef_` for the leverage-aware Cook's distance).	required
`threshold`	`float or 'auto'`	Cook's-distance threshold for highlighting outliers on the residuals-vs-leverage panel. Forwarded to `_residuals_chart_from_source(cook_threshold=...)`, which injects `_cook_outlier_x` / `_cook_outlier_y` columns (keyed on leverage and the studentized residual) and the leverage panel renders them as a red-filled overlay layer. `"auto"` uses the conventional `4 / n` rule (Hair et al.).	`None`
`random_state`	`int`		`None`
`theme`	`Theme`		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.CooksDistanceVisualizer(linear_model).fit(X, y)
>>> viz._metrics["max_studentized"]
3.42

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Clustering¶

10f clustering / manifold / dimensionality visualizers.

Mirrors yellowbrick's KElbow, Silhouette, InterclusterDistance, Manifold, and PCA-decomposition surfaces. Each visualizer wraps the appropriate ModelSource method and emits a ferrum chart via _build_chart.

ElbowVisualizer is the lone exception — it takes a model class rather than a fitted instance and fits one clusterer per k inside its fit() method, paralleling yellowbrick's API. Every other visualizer follows the standard FerrumVisualizer.fit(X[, y]) protocol.

SilhouetteVisualizer ¶

Bases: FerrumVisualizer

Rousseeuw silhouette plot for a fitted clusterer.

Computes per-sample silhouette coefficients via ModelSource.silhouette and renders a horizontal bar chart sorted by cluster, one bar per sample. Records mean_silhouette — the grand mean silhouette coefficient averaged across all samples — as the headline metric.

Takes a fitted estimator (not a class); for the k-sweep variant use ElbowVisualizer.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted clustering estimator (e.g. `sklearn.cluster.KMeans` instance) that exposes `labels_` (and optionally `cluster_centers_`).	required
`random_state`	`int`	Seed forwarded to the underlying `ModelSource`. Ignored when the silhouette computation is deterministic.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.cluster import KMeans
>>> model = KMeans(n_clusters=3, random_state=0).fit(X)
>>> viz = fm.SilhouetteVisualizer(model).fit(X)
>>> viz.show()
>>> viz._metrics["mean_silhouette"]

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ElbowVisualizer ¶

Bases: FerrumVisualizer

Elbow / score sweep over a range of k for a clusterer class.

Unlike other ferrum visualizers, ElbowVisualizer takes a model class (e.g. KMeans) — not a fitted instance — and constructs and fits one model per k value inside its own fit() override. The ModelSource round-trip is skipped entirely; per-k models are transient and discarded after their score is recorded. Renders a score-vs-k line chart.

Records best_k — the integer k whose score is optimal for the selected metric — as the headline metric. For "distortion" the optimal score is the minimum; for "silhouette" and "calinski_harabasz" it is the maximum (higher is better).

Parameters:

Name	Type	Description	Default
`model_class`	`type`	Uninstantiated clustering class (e.g. `sklearn.cluster.KMeans`). Must accept `n_clusters`, `random_state`, and `n_init` keyword arguments and expose `.inertia_` after fitting (for the `"distortion"` metric) or `.labels_` (for `"silhouette"` / `"calinski_harabasz"`).	required
`ks`	`sequence of int`	The candidate k values to sweep (e.g. `range(2, 11)`). Note that `"silhouette"` and `"calinski_harabasz"` are undefined at `k == 1` — such entries are silently skipped from the score sweep.	required
`metric`	`('distortion', 'silhouette', 'calinski_harabasz')`	Score to optimize. `"distortion"` (sum of squared distances to the nearest centroid, i.e. `.inertia_`) is minimized; `"silhouette"` (mean Rousseeuw silhouette coefficient) and `"calinski_harabasz"` (Calinski–Harabasz / Variance Ratio Criterion) are maximized. Any other value raises `ValueError`.	`"distortion"`
`random_state`	`int`	Integer seed passed as `random_state` to every per-k model instantiation. When `None`, seed `0` is used.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.cluster import KMeans
>>> viz = fm.ElbowVisualizer(KMeans, ks=range(2, 9)).fit(X)
>>> viz.show()
>>> viz._metrics["best_k"]

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ManifoldVisualizer ¶

Bases: FerrumVisualizer

Low-dimensional manifold-embedding scatter (UMAP / t-SNE / PCA).

Projects the input data to two dimensions via the method selected by method and renders a point chart with axes dim_0 / dim_1 colored by cluster label. The embedding is computed by ModelSource.embeddings and cached so _build_chart does not recompute it.

Takes a fitted clustering estimator whose labels_ attribute is used to color points. Pass model=None only if you override fit in a subclass and supply labels_ by other means.

Records n_samples — the number of rows in the embedding — as the headline metric.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted clustering estimator (e.g. `KMeans` instance) that exposes `labels_`. Defaults to `None` (for subclass overrides).	`None`
`method`	`str`	Embedding algorithm forwarded to `ModelSource.embeddings`. Typical values are `"umap"`, `"tsne"`, and `"pca"`.	`"umap"`
`random_state`	`int`	Seed forwarded to the underlying `ModelSource`. Controls reproducibility for stochastic embeddings such as UMAP and t-SNE.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.cluster import KMeans
>>> model = KMeans(n_clusters=4, random_state=0).fit(X)
>>> viz = fm.ManifoldVisualizer(model, method="umap").fit(X)
>>> viz.show()
>>> viz._metrics["n_samples"]

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

InterclusterDistanceVisualizer ¶

Bases: FerrumVisualizer

Cluster-center 2D embedding with cluster-size bubble overlay.

Projects cluster centers into 2D via the algorithm selected by method and renders a bubble chart where each bubble represents one cluster; bubble area encodes the cluster's sample count. Built on ferrum.intercluster_distance_chart.

Takes a fitted clustering estimator that exposes either n_clusters or cluster_centers_ so the number of clusters can be inferred.

Records max_intercluster_dist — the largest Euclidean distance from any cluster center to the centroid of all centers in the 2D embedding — as a rough measure of how spread-out the clusters are.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted clustering estimator (e.g. `KMeans` instance) that exposes `n_clusters` or `cluster_centers_`.	required
`method`	`str`	Dimensionality-reduction algorithm forwarded to `ModelSource.intercluster_distance`. Typical values include `"mds"` and `"tsne"`.	`"mds"`
`random_state`	`int`	Seed forwarded to the underlying `ModelSource`. Controls reproducibility for stochastic layout algorithms.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.cluster import KMeans
>>> model = KMeans(n_clusters=5, random_state=0).fit(X)
>>> viz = fm.InterclusterDistanceVisualizer(model).fit(X)
>>> viz.show()
>>> viz._metrics["max_intercluster_dist"]

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

PCAVarianceVisualizer ¶

Bases: FerrumVisualizer

PCA scree plot showing explained variance per principal component.

Retrieves per-component explained-variance ratios via ModelSource.pca_variance and renders a bar chart of explained-variance ratio vs. component index, optionally limited to the first n_components components. Built on ferrum.pca_scree_chart.

Takes a fitted decomposition estimator (e.g. sklearn.decomposition.PCA instance) that exposes explained_variance_ratio_.

Records first_component_var — the fraction of total variance captured by the first principal component — as the headline metric.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted decomposition estimator (e.g. `PCA` instance) that exposes `explained_variance_ratio_`.	required
`n_components`	`int`	Number of components to display in the scree plot. When `None`, all components present in the model are shown.	`None`
`random_state`	`int`	Seed forwarded to the underlying `ModelSource`. Ignored when the PCA variance computation is deterministic.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.decomposition import PCA
>>> model = PCA(n_components=10).fit(X)
>>> viz = fm.PCAVarianceVisualizer(model, n_components=5).fit(X)
>>> viz.show()
>>> viz._metrics["first_component_var"]

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Explanation (SHAP)¶

10d explanation visualizers — feature importance, SHAP family, PDP.

FeatureImportancesVisualizer ¶

Bases: FerrumVisualizer

Visualize feature importances from a fitted sklearn estimator.

Wraps importance_chart in the sklearn-protocol visualizer interface. method="builtin" reads feature_importances_ or coef_ directly from the estimator (std is 0 in this case). method="permutation" runs sklearn.inspection.permutation_importance using the supplied random_state seed. The headline metric recorded in _metrics is top_feature_importance — the importance of the highest-ranked feature after sorting.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted sklearn-compatible estimator. Must expose `feature_importances_` or `coef_` (`method="builtin"`) or support `predict` / `predict_proba` (`method="permutation"`).	required
`method`	`('builtin', 'permutation')`	Strategy for extracting importances. `"builtin"` reads the estimator attribute directly (zero standard deviation). `"permutation"` shuffles each feature and measures the drop in score.	`"builtin"`
`top_k`	`int or None`	Maximum number of features to display, ranked by importance. Pass `None` to show all features.	`20`
`orient`	`('horizontal', 'vertical')`	Bar orientation in the rendered chart.	`"horizontal"`
`error_bars`	`bool`	Whether to draw ±1 std error bars. Has no visual effect when `method="builtin"` because std is always 0 in that case.	`True`
`random_state`	`int or None`	RNG seed forwarded to `permutation_importance`. Ignored when `method="builtin"`.	`None`
`theme`	`Theme or None`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.ensemble import RandomForestClassifier
>>> model = RandomForestClassifier(n_estimators=50, random_state=0).fit(X_train, y_train)
>>> viz = fm.FeatureImportancesVisualizer(model).fit(X_train, y_train)
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

SHAPVisualizer ¶

Bases: FerrumVisualizer

Visualize SHAP values from a fitted sklearn estimator.

Wraps the shap_chart family in the sklearn-protocol visualizer interface. Requires the shap library (pip install ferrum[shap]). Three chart kinds are supported: "beeswarm" shows per-sample SHAP scatter colored by feature value; "bar" shows mean absolute SHAP aggregated per feature; "waterfall" shows the cumulative contribution for a single sample selected by sample_idx. The headline metric recorded in _metrics is top_abs_shap — the maximum mean absolute SHAP value across all features.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted sklearn-compatible estimator supported by the `shap` library (e.g. tree ensembles, linear models with a `shap.Explainer`).	required
`kind`	`('beeswarm', 'bar', 'waterfall')`	Chart style to render. `"waterfall"` requires `sample_idx` to be set; a `ValueError` is raised at `.show()` time if it is omitted.	`"beeswarm"`
`max_display`	`int`	Maximum number of features to include in the chart, ranked by mean absolute SHAP value.	`20`
`sample_idx`	`int or None`	Row index of the sample to explain. Required when `kind="waterfall"`; ignored for `"beeswarm"` and `"bar"`.	`None`
`order`	`('abs_mean', 'max')`	Feature ordering strategy applied to all three `kind` values. `"abs_mean"` ranks features by `mean(\|shap_value\|)` across the dataset; `"max"` ranks by `max(\|shap_value\|)` to surface features with high-impact outliers. For `kind="bar"` the same aggregation drives both the bar's x-value and the sort order; for `kind="waterfall"` it selects which features are shown for the single sample and the order they appear in.	`"abs_mean"`
`background`	`Any or None`	Background dataset passed to the SHAP explainer for models that require a reference distribution (e.g. kernel SHAP). Pass `None` to use the explainer's default.	`None`
`random_state`	`int or None`	RNG seed forwarded to the underlying `ModelSource`. Ignored when SHAP computation is deterministic.	`None`
`theme`	`Theme or None`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.ensemble import GradientBoostingClassifier
>>> model = GradientBoostingClassifier(random_state=0).fit(X_train, y_train)
>>> viz = fm.SHAPVisualizer(model, kind="beeswarm").fit(X_train, y_train)
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

SHAPBeeswarmVisualizer ¶

Bases: _SHAPBaseMixin, FerrumVisualizer

Per-sample SHAP scatter colored by z-scored feature value.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted sklearn-compatible estimator supported by the `shap` library (e.g. tree ensembles, linear models).	required
`max_display`	`int`	Maximum number of features ranked by `order`.	`20`
`order`	`('abs_mean', 'max')`	Feature ranking criterion. `"abs_mean"` ranks by mean absolute SHAP; `"max"` by max absolute SHAP.	`"abs_mean"`
`background`	`Any`	Background dataset passed to the SHAP explainer for kernel- SHAP models. Tree SHAP ignores this.	`None`
`per_class`	`bool`	Facet by class on multi-class classifiers.	`False`
`random_state`	forwarded to ``FerrumVisualizer``.		`None`
`theme`	forwarded to ``FerrumVisualizer``.		`None`

Examples:

>>> import ferrum as fm
>>> viz = fm.SHAPBeeswarmVisualizer(model, max_display=15).fit(X, y)
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

SHAPBarVisualizer ¶

Bases: _SHAPBaseMixin, FerrumVisualizer

Mean-absolute SHAP per feature as a horizontal bar chart.

Parameters mirror :class:SHAPBeeswarmVisualizer; see that class for the full parameter list.

Examples:

>>> import ferrum as fm
>>> from sklearn.ensemble import GradientBoostingClassifier
>>> viz = fm.SHAPBarVisualizer(GradientBoostingClassifier().fit(X_train, y_train))
>>> chart = viz.chart(X_test, y_test)

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

SHAPWaterfallVisualizer ¶

Bases: _SHAPBaseMixin, FerrumVisualizer

Cumulative per-feature SHAP contributions for one sample.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Fitted sklearn-compatible estimator supported by the `shap` library.	required
`sample_idx`	`int`	Row index (0-based) of the sample to explain. Required.	required
`max_display`	`int`	Maximum number of features to include in the waterfall, ranked by `order`.	`20`
`order`	`('abs_mean', 'max')`	Feature ranking criterion (drives both the top-`max_display` selection and the bar order).	`"abs_mean"`
`background`	`Any`	Background dataset passed to the SHAP explainer.	`None`
`per_class`	`bool`	Facet by class on multi-class classifiers.	`False`
`random_state`	forwarded to ``FerrumVisualizer``.		`None`
`theme`	forwarded to ``FerrumVisualizer``.		`None`

Raises:

Type	Description
`ValueError`	If `sample_idx` is missing at `__init__` time.

Examples:

>>> import ferrum as fm
>>> viz = fm.SHAPWaterfallVisualizer(model, sample_idx=3).fit(X, y)
>>> viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Model selection¶

10e model-selection visualizers — LearningCurve, ValidationCurve, CVScores, AlphaSelection.

LearningCurveVisualizer ¶

Bases: FerrumVisualizer

Visualize training and cross-validation scores as training size grows.

Wraps learning_curve_chart in the sklearn visualizer protocol. Call fit(X, y) to run cross-validation across the requested training-size grid; call show() to retrieve the rendered Chart. The headline metric final_test_score (mean test score at the largest training size) is recorded in _metrics and shown in repr.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Unfitted or fitted sklearn-compatible estimator.	required
`cv`	`int`	Number of cross-validation folds passed to `sklearn.model_selection.learning_curve`.	`5`
`scoring`	`str or callable`	Sklearn scoring string or callable. Defaults to the estimator's own `score` method when `None`.	`None`
`train_sizes`	`array - like`	Relative or absolute training-set sizes to evaluate. Passed directly to `learning_curve`; defaults to `np.linspace(0.1, 1.0, 5)` when `None`.	`None`
`ci_style`	`('band', 'bar')`	How to render the cross-validation confidence interval. `"band"` draws a shaded ribbon; `"bar"` draws error bars.	`"band"`
`random_state`	`int`	Seed forwarded to `ModelSource` and from there to `learning_curve` for reproducible CV splits (ChaCha8 RNG).	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.linear_model import LogisticRegression
>>> viz = fm.LearningCurveVisualizer(
...     LogisticRegression(), cv=5, scoring="accuracy"
... ).fit(X_train, y_train)
>>> chart = viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ValidationCurveVisualizer ¶

Bases: FerrumVisualizer

Visualize train/test scores as a single hyperparameter is swept.

Wraps validation_curve_chart in the sklearn visualizer protocol. For each value in values, sklearn.model_selection.validation_curve runs cv folds and records the mean score. The value that maximises the mean test score is stored as best_param in _metrics; the corresponding mean score is stored as best_test_score.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Unfitted or fitted sklearn-compatible estimator.	required
`param`	`str`	Name of the hyperparameter to sweep, e.g. `"C"` for `LogisticRegression` or `"max_depth"` for tree estimators. Must be a valid `__init__` parameter of `model`.	required
`values`	`array - like`	Grid of candidate values for `param`. Passed directly to `sklearn.model_selection.validation_curve` as `param_range`.	required
`cv`	`int`	Number of cross-validation folds.	`5`
`scoring`	`str or callable`	Sklearn scoring string or callable. Defaults to the estimator's own `score` method when `None`.	`None`
`log_scale`	`bool or 'auto'`	Whether to render the x-axis (param values) on a log scale. `"auto"` enables log scale when the ratio between the largest and smallest value exceeds 100.	`"auto"`
`ci_style`	`('band', 'bar')`	How to render the cross-validation confidence interval. `"band"` draws a shaded ribbon; `"bar"` draws error bars.	`"band"`
`random_state`	`int`	Seed forwarded to `ModelSource` for reproducible CV splits (ChaCha8 RNG).	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.svm import SVC
>>> import numpy as np
>>> viz = fm.ValidationCurveVisualizer(
...     SVC(), param="C", values=np.logspace(-3, 3, 7), cv=5
... ).fit(X_train, y_train)
>>> chart = viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

CVScoresVisualizer ¶

Bases: FerrumVisualizer

Visualize the distribution of per-fold cross-validation scores.

Wraps cv_scores_chart in the sklearn visualizer protocol. After fit(X, y), _metrics contains test_mean (mean test-fold score across all folds) and test_std (standard deviation of test-fold scores).

Parameters:

Name	Type	Description	Default
`model`	`Any`	Unfitted or fitted sklearn-compatible estimator.	required
`cv`	`int`	Number of cross-validation folds.	`5`
`scoring`	`str or callable`	Sklearn scoring string or callable. Defaults to the estimator's own `score` method when `None`.	`None`
`kind`	`('box', 'bar', 'strip')`	Chart geometry used to display the fold-score distributions.	`"box"`
`split`	`('both', 'test', 'train')`	Which CV splits to include in the chart. `"both"` shows train and test folds side by side; `"test"` or `"train"` shows only one.	`"both"`
`random_state`	`int`	Seed forwarded to `ModelSource` for reproducible CV splits (ChaCha8 RNG).	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.ensemble import RandomForestClassifier
>>> viz = fm.CVScoresVisualizer(
...     RandomForestClassifier(n_estimators=100), cv=10, kind="box"
... ).fit(X_train, y_train)
>>> chart = viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

AlphaSelectionVisualizer ¶

Bases: FerrumVisualizer

Visualize cross-validated scores over a regularization-strength grid.

Wraps alpha_selection_chart in the sklearn visualizer protocol. Designed for regularized regressors such as Ridge, Lasso, and ElasticNet — estimators that expose an alpha hyperparameter controlling L1/L2 penalty strength. For each value in alphas, cross-validation produces a mean score; the alpha that maximises the mean test score is stored as best_alpha in _metrics, and the corresponding score as best_score.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Unfitted regularized regressor with an `alpha` hyperparameter (e.g. `sklearn.linear_model.Ridge`, `Lasso`, `ElasticNet`). Passing an estimator without an `alpha` parameter will raise at `fit` time.	required
`alphas`	`array - like`	Grid of regularization-strength values to evaluate. Passed directly to the underlying `alpha_selection` compute; log-spaced grids (e.g. `np.logspace(-4, 4, 50)`) are typical.	required
`cv`	`int`	Number of cross-validation folds.	`5`
`scoring`	`str or callable`	Sklearn scoring string or callable. Defaults to the estimator's own `score` method when `None`.	`None`
`log_scale`	`bool`	Whether to render the x-axis (alpha values) on a log scale. Defaults to `True` because alpha grids are almost always log-spaced.	`True`
`highlight_best`	`bool`	When `True`, draws a vertical rule at the alpha value that maximises the mean test score.	`True`
`random_state`	`int`	Seed forwarded to `ModelSource` for reproducible CV splits (ChaCha8 RNG).	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> from sklearn.linear_model import Ridge
>>> import numpy as np
>>> viz = fm.AlphaSelectionVisualizer(
...     Ridge(), alphas=np.logspace(-4, 4, 40), cv=5
... ).fit(X_train, y_train)
>>> chart = viz.show()

fit ¶

fit(X: Any, y: Any = None) -> 'FerrumVisualizer'

Materialize derived data from X / y and build the chart.

Constructs a ModelSource from the wrapped model, calls _materialize to populate _metrics, then _build_chart to assemble the ferrum Chart. Returns self for method chaining.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix. Accepted types match `ModelSource.__init__`.	required
`y`	`array - like`	Target vector. Required by most classification / regression diagnostics; optional for unsupervised variants.	`None`

Returns:

Type	Description
`FerrumVisualizer`	`self` — the fitted visualizer instance.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Ranking¶

Phase 10g — feature-ranking visualizers (no-model variants).

Mirrors yellowbrick's Rank1D / Rank2D / ParallelCoordinates surfaces. None of these need a fitted estimator — they operate on the raw feature matrix X (with optional y for Rank1D(algorithm="covariance")) and skip the ModelSource round-trip. The chart is materialized directly from the in-house compute helpers in stats.py.

Rank1DVisualizer ¶

Bases: FerrumVisualizer

Rank features by a univariate statistic and display as a bar chart.

A no-model visualizer (model=None) that computes a scalar score for each feature column and renders them as a ranked horizontal or vertical bar chart. fit is overridden directly — the base-class ModelSource round-trip is bypassed entirely.

Records top_feature_score (the score of the highest-ranked feature) in _metrics.

Parameters:

Name	Type	Description	Default
`algorithm`	`('shapiro', 'variance', 'covariance')`	Scoring algorithm. `"shapiro"` — Shapiro-Wilk W statistic (normality score). `"variance"` — variance of each feature column. `"covariance"` — absolute covariance with the target `y`. Requires `y` to be passed at `fit` time; raises `ValueError` when `y` is `None`.	`"shapiro"`
`orient`	`('horizontal', 'vertical')`	Bar orientation of the resulting chart.	`"horizontal"`
`top_k`	`int`	If given, display only the top `top_k` features. `None` shows all features.	`None`
`color_field`	`str`	Column name forwarded to the chart's color encoding. `None` produces a single-color chart.	`None`
`random_state`	`int`	Accepted for API symmetry with model-backed visualizers but intentionally never consumed — this visualizer bypasses `ModelSource` entirely. Documented as a permanent no-op so callers that script over visualizers don't have to special-case which ones accept the kwarg.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Raises:

Type	Description
`ValueError`	When `algorithm="covariance"` and `y` is `None` at `fit` time.

Examples:

>>> import ferrum as fm
>>> import polars as pl
>>> df = pl.read_csv("wine.csv")
>>> X, y = df.drop("target"), df["target"]
>>> viz = fm.Rank1DVisualizer(algorithm="variance").fit(X)
>>> viz.show()

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Rank2DVisualizer ¶

Bases: FerrumVisualizer

Rank feature pairs by pairwise correlation and display as a heatmap.

A no-model visualizer (model=None) that computes an N×N correlation matrix and renders it as an annotated heatmap. fit is overridden directly — the base-class ModelSource round-trip is bypassed entirely.

The "kendall" algorithm routes pairwise computation through ferrum._core.kendall_tau_b (Rust) for performance.

Records max_abs_corr (the largest absolute off-diagonal correlation value) in _metrics — useful for detecting multicollinearity at a glance.

Parameters:

Name	Type	Description	Default
`algorithm`	`('pearson', 'spearman', 'kendall', 'covariance')`	Pairwise association measure. `"pearson"` — Pearson linear correlation coefficient. `"spearman"` — Spearman rank correlation. `"kendall"` — Kendall tau-b, computed via `ferrum._core.kendall_tau_b` for performance. `"covariance"` — raw covariance (not normalized to [-1, 1]).	`"pearson"`
`annot`	`bool`	Whether to annotate each heatmap cell with its numeric value.	`True`
`random_state`	`int`	Accepted for API symmetry with model-backed visualizers but intentionally never consumed — this visualizer bypasses `ModelSource` entirely. Documented as a permanent no-op so callers that script over visualizers don't have to special-case which ones accept the kwarg.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> import polars as pl
>>> df = pl.read_csv("wine.csv")
>>> X = df.drop("target")
>>> viz = fm.Rank2DVisualizer(algorithm="spearman").fit(X)
>>> viz.show()

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

ParallelCoordinatesVisualizer ¶

Bases: FerrumVisualizer

Visualize multivariate samples as a parallel-coordinates chart.

A no-model visualizer (model=None) that draws one polyline per sample across a set of parallel vertical axes (one per feature). fit is overridden directly — the base-class ModelSource round-trip is bypassed entirely.

Records n_samples and n_features in _metrics so the repr surfaces the chart's shape.

Parameters:

Name	Type	Description	Default
`features`	`list of str`	Subset of column names to include as axes. When `None`, all non-`hue` columns are used.	`None`
`hue`	`str`	Column name used to color-encode each sample line. `None` produces a single-color chart unless `fit(X, y)` is called with `y` — in that case `y` is attached as the hue column automatically.	`None`
`rescale`	`('minmax', 'zscore', None)`	Per-axis normalization applied before plotting. `"minmax"` — rescale each axis to [0, 1]. `"zscore"` — standardize each axis to zero mean, unit variance. `None` — no rescaling; raw values are plotted.	`"minmax"`
`alpha`	`float`	Opacity of each sample line (0 = fully transparent, 1 = opaque).	`0.5`
`random_state`	`int`	Accepted for API symmetry with model-backed visualizers but intentionally never consumed — this visualizer bypasses `ModelSource` entirely. Documented as a permanent no-op so callers that script over visualizers don't have to special-case which ones accept the kwarg.	`None`
`theme`	`Theme`	Per-chart theme override. Falls back to the global default when `None`.	`None`

Examples:

>>> import ferrum as fm
>>> import polars as pl
>>> df = pl.read_csv("iris.csv")
>>> viz = fm.ParallelCoordinatesVisualizer(hue="species", rescale="minmax")
>>> viz.fit(df.drop("species"), df["species"])
>>> viz.show()

score ¶

score(X: Any, y: Any) -> float

Returns 0.0 for visualizers that do not compute a test-set score.

Subclasses that wrap a fitted estimator override this to return an appropriate metric (e.g. roc_auc_score for ROCVisualizer, r2_score for ResidualsVisualizer). The base implementation returns 0.0 so that no-model / exploratory visualizers satisfy the sklearn visualizer protocol without raising.

Parameters:

Name	Type	Description	Default
`X`	`array - like`	Feature matrix, same type accepted by `fit`.	required
`y`	`array - like`	True target values.	required

Returns:

Type	Description
`float`	`0.0` for the base class; a meaningful scalar for subclasses that override this method.

show ¶

show() -> Any

Return the ferrum Chart for this visualizer.

Must be called after fit; raises RuntimeError otherwise. The returned Chart can be rendered in a notebook (_repr_svg_), saved with .save(path), or composed with other charts via + / /.

Returns:

Type	Description
`Chart`	The assembled diagnostic chart.

Raises:

Type	Description
`RuntimeError`	If `fit` has not been called yet.

Data sources¶

Per-domain split of the ModelSource adapter.

ModelSource is too large to live in a single file; the seven phase-10 domains (predictions, classification curves, importance, model selection, clustering, ranking, plus ComparedModelSource) become independent mixin modules whose seam already exists as # --- 10x --- comment headers. _base.BaseSource owns the constructor, capability detection, and cache infrastructure; each mixin contributes domain methods that use those bits via self.

External callers still import from ferrum._diagnostics.source (re-export shim) — this package is the implementation home.

BaseSource ¶

Shared state + helpers for every ModelSource domain mixin.

Not part of the public API — users import :class:ferrum.ModelSource which composes :class:BaseSource with the seven per-domain mixins. The split exists because the original monolithic implementation grew past 1500 lines along clear domain seams; keeping the seams in code matches the seams in the docs.

X `property` ¶

X: DataFrame

Feature matrix coerced to a polars DataFrame.

Returns the value supplied to __init__ (after coercion). Use this for read-only access from chart builders and external callers — source._X is an internal alias preserved for back-compat.

y `property` ¶

y: 'pl.Series | None'

Target series, or None when no y was supplied.

Returns the polars Series the constructor coerced from the y argument. None means unsupervised — methods that need ground truth raise on call.

model `property` ¶

model: Any

The wrapped fitted estimator.

Returns the model object supplied at construction time unchanged. Chart builders use it for occasional native introspection (e.g. model.classes_, model.n_clusters); prefer the public derived-data methods when one exists.

feature_names `property` ¶

feature_names: list[str]

Column labels for the feature matrix.

Returns the names supplied at construction time, or the DataFrame column names when X was a DataFrame, or ["f0", "f1", ...] for unlabeled array inputs.

Returns:

Type	Description
`list[str]`	Feature names in the same order as the columns of `X`.

capabilities `property` ¶

capabilities: frozenset[str]

Protocol attributes present on the wrapped estimator.

A frozen subset of _PROTOCOL_ATTRS ("predict", "predict_proba", "coef_", "feature_importances_", …) detected at construction time via hasattr. Derived-data methods gate on this set to pick the appropriate code path and raise AttributeError with a clear message when a required attribute is absent.

Returns:

Type	Description
`frozenset[str]`	Attribute names that are present on the wrapped model.