machinelens package#

Subpackages#

Submodules#

machinelens.utils module#

Utility functions for MachineLens.

Module contents#

MachineLens — Deep diagnostics, explainability, and reporting for ML models.

class machinelens.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

class machinelens.DiagnosticResults(problem_type: str, model_name: str, algorithm_family: str, feature_names: List[str] = <factory>, train_data: SubsetData | None = None, test_data: SubsetData | None = None, train_metrics: RegressionMetrics | None = None, test_metrics: RegressionMetrics | None = None, train_clf_metrics: ClassificationMetrics | None = None, test_clf_metrics: ClassificationMetrics | None = None, train_qq: QQData | None = None, test_qq: QQData | None = None, train_linearity_lowess: LowessData | None = None, test_linearity_lowess: LowessData | None = None, train_scale_loc_lowess: LowessData | None = None, test_scale_loc_lowess: LowessData | None = None, leverage: ndarray | None = None, leverage_lowess: LowessData | None = None, cooks_distance: ndarray | None = None, outlier_analysis: OutlierAnalysisResult | None = None, train_confusion_matrix: DataFrame | None = None, test_confusion_matrix: DataFrame | None = None, train_roc_curves: List[RocCurveData] | None = None, test_roc_curves: List[RocCurveData] | None = None, train_pr_curves: List[PrCurveData] | None = None, test_pr_curves: List[PrCurveData] | None = None, train_calibration_curves: List[CalibrationCurveData] | None = None, test_calibration_curves: List[CalibrationCurveData] | None = None, train_threshold_analysis: List[ThresholdAnalysisData] | None = None, test_threshold_analysis: List[ThresholdAnalysisData] | None = None, train_misclassification: MisclassificationResult | None = None, test_misclassification: MisclassificationResult | None = None, train_shap: ShapData | None = None, test_shap: ShapData | None = None)[source]#

Bases: object

Complete diagnostic state for a model — single source of truth.

This object is the strict contract between the processing layer (ModelAnalyzer) and the visualisation layer (DiagnosticPlotter). Every calculation result has a dedicated, typed field — no opaque dictionaries.

problem_type#

"classification" or "regression".

Type:: str

model_name#

Human-readable name of the estimator class.

Type:: str

algorithm_family#

Pretty-printed sklearn sub-module family.

Type:: str

feature_names#

Feature column names.

Type:: list of str

train_data / test_data: Aligned arrays for each subset (type depends on problem).

train_metrics / test_metrics: Scalar evaluation metrics for each subset.

Regression-specific fields: *_qq, *_linearity_lowess, *_scale_loc_lowess, leverage, leverage_lowess, cooks_distance, outlier_analysis.

Classification-specific fields: *_confusion_matrix, *_roc_curves, *_pr_curves, *_misclassification.

Attributes:

cooks_distance
leverage
leverage_lowess
outlier_analysis
test_calibration_curves
test_clf_metrics
test_confusion_matrix
test_data
test_linearity_lowess
test_metrics
test_misclassification
test_pr_curves
test_qq
test_roc_curves
test_scale_loc_lowess
test_shap
test_threshold_analysis
train_calibration_curves
train_clf_metrics
train_confusion_matrix
train_data
train_linearity_lowess
train_metrics
train_misclassification
train_pr_curves
train_qq
train_roc_curves
train_scale_loc_lowess
train_shap
train_threshold_analysis

algorithm_family: str#

cooks_distance: ndarray | None = None#

feature_names: List[str]#

leverage: ndarray | None = None#

leverage_lowess: LowessData | None = None#

model_name: str#

outlier_analysis: OutlierAnalysisResult | None = None#

problem_type: str#

test_calibration_curves: List[CalibrationCurveData] | None = None#

test_clf_metrics: ClassificationMetrics | None = None#

test_confusion_matrix: DataFrame | None = None#

test_data: SubsetData | None = None#

test_linearity_lowess: LowessData | None = None#

test_metrics: RegressionMetrics | None = None#

test_misclassification: MisclassificationResult | None = None#

test_pr_curves: List[PrCurveData] | None = None#

test_qq: QQData | None = None#

test_roc_curves: List[RocCurveData] | None = None#

test_scale_loc_lowess: LowessData | None = None#

test_shap: ShapData | None = None#

test_threshold_analysis: List[ThresholdAnalysisData] | None = None#

train_calibration_curves: List[CalibrationCurveData] | None = None#

train_clf_metrics: ClassificationMetrics | None = None#

train_confusion_matrix: DataFrame | None = None#

train_data: SubsetData | None = None#

train_linearity_lowess: LowessData | None = None#

train_metrics: RegressionMetrics | None = None#

train_misclassification: MisclassificationResult | None = None#

train_pr_curves: List[PrCurveData] | None = None#

train_qq: QQData | None = None#

train_roc_curves: List[RocCurveData] | None = None#

train_scale_loc_lowess: LowessData | None = None#

train_shap: ShapData | None = None#

train_threshold_analysis: List[ThresholdAnalysisData] | None = None#

class machinelens.ModelAnalyzer(interface: ModelInterface)[source]#

Bases: object

Calculation engine that produces DiagnosticResults.

This analyzer automatically delegates calculations to the specialized RegressionAnalyzer or ClassificationAnalyzer based on the detected problem type, keeping the domain logic perfectly split and decoupled.

Parameters:: interface (ModelInterface) – A validated interface wrapping the fitted model and data splits.

Examples

>>> from machinelens.core import ModelInterface
>>> from machinelens.analyzer import ModelAnalyzer
>>> mi = ModelInterface(model, X_train, X_test, y_train, y_test, y_pred)
>>> analyzer = ModelAnalyzer(mi)
>>> results = analyzer.analyze()

Methods

analyze()

Run all diagnostics and return a populated result object.

analyze() → DiagnosticResults[source]#

Run all diagnostics and return a populated result object.

Returns:: Fully populated diagnostic state.
Return type:: DiagnosticResults

Bases: object

Encapsulate model data and provide validation utilities.

This class standardizes how the MachineLens library interacts with scikit-learn compatible models. It wraps a fitted estimator alongside its training/test splits and predictions, automatically validating inputs and classifying the model’s task type and algorithm family.

model#

The wrapped scikit-learn estimator.

Type:: BaseEstimator

X_train#

Training feature matrix.

Type:: PandasLike or None

X_test#

Test feature matrix.

Type:: PandasLike or None

y_train#

Training target values.

Type:: ArrayLike or None

y_test#

Test target values (ground truth).

Type:: ArrayLike or None

y_pred#

Model predictions on the test set.

Type:: ArrayLike or None

problem_type#

Detected problem type: "classification", "regression", "clustering", or "unknown".

Type:: str

results#

Dictionary with model metadata and analysis results.

Type:: ModelResults

problem_type: str#

results: Dict[str, str | Dict[str, Any]]#