machinelens.plots package#

Submodules#

machinelens.plots.plots module#

Visualization layer for the MachineLens library.

This module provides the DiagnosticPlotter class, which consumes DiagnosticResults and generates highly polished, interactive Plotly charts. These charts are styled with a premium dark-slate aesthetic and designed for zero-friction JSON serialization.

class machinelens.plots.plots.DiagnosticPlotter(results: DiagnosticResults)[source]#

Bases: object

Visualization suite for MachineLens diagnostic results.

This class reads from a strongly-typed DiagnosticResults object and generates interactive, premium Plotly figures. It is completely decoupled from any computing tasks, acting purely as a visual rendering engine.

All figure objects returned can be easily serialized to JSON via fig.to_json() for rendering in web frontends.

Parameters:: results (DiagnosticResults) – The complete calculated diagnostic results to visualize.

Methods

`plot_act_vs_pred`([subset])	Alias for plot_actual_vs_predicted.
`plot_actual_vs_predicted`([subset])	Plot Actual vs. Predicted values.
`plot_calibration_curve`([subset])	Plot Calibration curves (Reliability diagrams).
`plot_class_distribution`([subset])	Plot the Actual vs. Predicted Class Distributions.
`plot_confusion_matrix`([subset])	Plot a labeled, proportional Confusion Matrix heatmap.
`plot_leverage`()	Plot Standardized Residuals vs Leverage.
`plot_metrics`([subset])	Plot a highly stylized Summary Metrics Card.
`plot_misclass`([subset])	Alias for plot_misclassification_features.
`plot_misclassification_features`([subset])	Plot the Misclassification Feature diagnostic.
`plot_outliers`()	Plot Outliers diagnostic.
`plot_post_pred`([subset])	Alias for plot_posterior_predictive.
`plot_posterior_predictive`([subset])	Plot the Posterior Predictive Density comparison.
`plot_pr_curve`([subset])	Plot Precision-Recall (PR) curves with baseline reference line.
`plot_prob_dist`([subset])	Alias for plot_probability_distribution.
`plot_probability_distribution`([subset])	Plot the distribution of predicted probabilities.
`plot_qq`([subset])	Plot a Normal Q-Q Plot of Standardized Residuals.
`plot_res_dist`([subset])	Alias for plot_residual_distribution.
`plot_res_vs_act`([subset])	Alias for plot_residuals_vs_actual.
`plot_res_vs_pred`([subset])	Alias for plot_residuals.
`plot_residual_distribution`([subset])	Plot a histogram of residuals with an overlaid normal distribution curve.
`plot_residuals`([subset])	Plot Residuals vs. Predicted values.
`plot_residuals_vs_actual`([subset])	Plot Residuals vs. Actual target values.
`plot_roc_curve`([subset])	Plot Receiver Operating Characteristic (ROC) curves.
`plot_scale_loc`([subset])	Alias for plot_scale_location.
`plot_scale_location`([subset])	Generate a Scale-Location Plot.
`plot_shap_beeswarm`([subset])	Plot the SHAP beeswarm chart.
`plot_shap_summary`([subset])	Plot the SHAP summary (global feature importance) as a bar chart.
`plot_threshold_analysis`([subset])	Plot Precision, Recall, and F1-Score across thresholds.
`save_dashboard_bundle`([filepath])	Save the full train/test diagnostic bundle directly to a file.
`to_json_bundle`([subset])	Serialize a pre-packaged bundle of all available diagnostic charts.
`to_json_full_bundle`()	Serialize a full diagnostics bundle containing train, test, and split tables.

plot_act_vs_pred(subset: str = 'test') → Figure[source]#

Alias for plot_actual_vs_predicted.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_actual_vs_predicted(subset: str = 'test') → Figure[source]#

Plot Actual vs. Predicted values.

Includes an identity reference line (y = x) representing ideal fit. Points are colored by absolute residual values to highlight mistakes.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_calibration_curve(subset: str = 'test') → Figure[source]#

Plot Calibration curves (Reliability diagrams).

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_class_distribution(subset: str = 'test') → Figure[source]#

Plot the Actual vs. Predicted Class Distributions.

Displays class proportions as a grouped bar chart to immediately highlight prediction biases and class imbalances.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_confusion_matrix(subset: str = 'test') → Figure[source]#

Plot a labeled, proportional Confusion Matrix heatmap.

Shows both raw sample count and row-wise accuracy percentages in each cell.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_leverage() → Figure[source]#

Plot Standardized Residuals vs Leverage.

Useful for identifying highly influential data points or outliers in predictor space. Marker sizes are proportional to Cook’s Distance.

Returns:: The Plotly figure object.
Return type:: go.Figure

plot_metrics(subset: str = 'test') → Figure[source]#

Plot a highly stylized Summary Metrics Card.

Renders scalar model metrics as a publication-grade graphical card.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_misclass(subset: str = 'test') → Figure[source]#

Alias for plot_misclassification_features.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_misclassification_features(subset: str = 'test') → Figure[source]#

Plot the Misclassification Feature diagnostic.

Highlights the feature density boundaries of the top significant feature that separates Correctly Predicted vs. Misclassified samples.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_outliers() → Figure[source]#

Plot Outliers diagnostic.

Displays the values of the top significant outlier-predicting feature grouped by standardized residual magnitude, highlighting anomalous samples.

Returns:: The Plotly figure object.
Return type:: go.Figure

plot_post_pred(subset: str = 'test') → Figure[source]#

Alias for plot_posterior_predictive.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_posterior_predictive(subset: str = 'test') → Figure[source]#

Plot the Posterior Predictive Density comparison.

Compares the density/KDE curves of the actual and predicted values to verify if the model captures the shape, modality, and spread of the true target variable.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_pr_curve(subset: str = 'test') → Figure[source]#

Plot Precision-Recall (PR) curves with baseline reference line.

Highly recommended for class-imbalanced datasets. Includes Average Precision (AP) scores.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_prob_dist(subset: str = 'test') → Figure[source]#

Alias for plot_probability_distribution.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_probability_distribution(subset: str = 'test') → Figure[source]#

Plot the distribution of predicted probabilities.

Categorizes samples into Correctly Predicted vs. Misclassified, showing the confidence distribution (winning class probability). Helps visualize model calibration and uncertainty.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_qq(subset: str = 'test') → Figure[source]#

Plot a Normal Q-Q Plot of Standardized Residuals.

Highlights departures from normality with a 95% confidence interval envelope. Points are dynamically colored by their distance from the theoretical line.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_res_dist(subset: str = 'test') → Figure[source]#

Alias for plot_residual_distribution.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_res_vs_act(subset: str = 'test') → Figure[source]#

Alias for plot_residuals_vs_actual.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_res_vs_pred(subset: str = 'test') → Figure[source]#

Alias for plot_residuals.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_residual_distribution(subset: str = 'test') → Figure[source]#

Plot a histogram of residuals with an overlaid normal distribution curve.

Helps verify if the model errors are symmetrically distributed and normally concentrated around zero.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_residuals(subset: str = 'test') → Figure[source]#

Plot Residuals vs. Predicted values.

Overlays a horizontal zero line (y = 0) and the LOWESS trend line with bootstrap confidence intervals to identify systematic bias or non-linearity.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_residuals_vs_actual(subset: str = 'test') → Figure[source]#

Plot Residuals vs. Actual target values.

Helps visualize error behavior across the target’s true range. Systematic trends suggest missing non-linear relationships.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_roc_curve(subset: str = 'test') → Figure[source]#

Plot Receiver Operating Characteristic (ROC) curves.

Overlays diagonal no-skill guideline and calculates AUC scores. Handles both binary and multi-class classification formats seamlessly.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_scale_loc(subset: str = 'test') → Figure[source]#

Alias for plot_scale_location.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_scale_location(subset: str = 'test') → Figure[source]#

Generate a Scale-Location Plot.

Plots Predicted Values vs. sqrt(|Standardized Residuals|). Overlays a LOWESS smoothed line to check homoscedasticity. A flat trend line indicates constant residual variance.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

plot_shap_beeswarm(subset: str = 'test') → Figure[source]#

Plot the SHAP beeswarm chart.

Parameters:: subset (str, default="test") – The subset to evaluate.
Returns:: The Plotly figure.
Return type:: go.Figure

plot_shap_summary(subset: str = 'test') → Figure[source]#

Plot the SHAP summary (global feature importance) as a bar chart.

Parameters:: subset (str, default="test") – The subset to evaluate.
Returns:: The Plotly figure.
Return type:: go.Figure

plot_threshold_analysis(subset: str = 'test') → Figure[source]#

Plot Precision, Recall, and F1-Score across thresholds.

Parameters:: subset (str, default="test") – The data subset to plot ("train" or "test").
Returns:: The Plotly figure object.
Return type:: go.Figure

save_dashboard_bundle(filepath: str = 'dashboard/active_bundle.json') → None[source]#

Save the full train/test diagnostic bundle directly to a file.

(defaulting to the dashboard’s active bundle path).

Parameters:: filepath (str, default="dashboard/active_bundle.json") – The filepath to write the bundle JSON to.

to_json_bundle(subset: str = 'test') → str[source]#

Serialize a pre-packaged bundle of all available diagnostic charts.

Perfect for sending over HTTP or rendering directly in drag-and-drop dashboards. Uses the exact 18 standard endpoints as dictionary keys.

Parameters:: subset (str, default="test") – The subset of charts to compile ("train" or "test").
Returns:: A JSON string containing the complete mapped dictionary of figures.
Return type:: str

to_json_full_bundle() → str[source]#

Serialize a full diagnostics bundle containing train, test, and split tables.

Returns:: A JSON string containing ‘problem_type’, ‘test’, ‘train’, and ‘tables’.
Return type:: str

Module contents#

Interactive premium visualization plotters for MachineLens.

class machinelens.plots.DiagnosticPlotter(results: DiagnosticResults)[source]#