machinelens.core.data_classes package

Submodules

machinelens.core.data_classes.classification module

Classification-specific dataclasses for diagnostics.

class machinelens.core.data_classes.classification.CalibrationCurveData(prob_true: ndarray, prob_pred: ndarray, label: str)

Bases: object

Calibration curve data for reliability diagrams.

prob_true

True probability in each bin.

Type:

np.ndarray

prob_pred

Mean predicted probability in each bin.

Type:

np.ndarray

label

Human-readable label for the class.

Type:

str

label: str

prob_pred: ndarray

prob_true: ndarray

class machinelens.core.data_classes.classification.ClassificationMetrics(accuracy: float, precision: float, recall: float, f1_score: float, mcc: float, roc_auc: float | None = None, pr_auc: float | None = None, brier_score: float | None = None, log_loss: float | None = None)

Bases: object

Scalar classification evaluation metrics for one subset.

accuracy

Overall accuracy.

Type:

float

precision

Precision (macro or binary).

Type:

float

recall

Recall (macro or binary).

Type:

float

f1_score

F1-score (macro or binary).

Type:

float

Attributes:

brier_score

log_loss

pr_auc

roc_auc

accuracy: float

brier_score: float | None = None

f1_score: float

log_loss: float | None = None

mcc: float

pr_auc: float | None = None

precision: float

recall: float

roc_auc: float | None = None

class machinelens.core.data_classes.classification.ClassificationSubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray | None = None, std_residuals: ndarray | None = None, abs_residuals: ndarray | None = None, y_prob: ndarray | None = None)

Bases: SubsetData

Extended subset data carrying probability arrays (classification).

y_prob

Predicted class probabilities (n_samples, n_classes). None when the estimator does not support predict_proba.

Type:

np.ndarray or None

Attributes:

abs_residuals

residuals

std_residuals

y_prob

y_prob: ndarray | None = None

class machinelens.core.data_classes.classification.MisclassificationResult(results_df: DataFrame)

Bases: object

Per-feature statistical analysis of misclassified samples.

results_df

Feature-level test results with columns like feature, stat, p_value, adj_p_value, effect_size, significant.

Type:

pd.DataFrame

results_df: DataFrame

class machinelens.core.data_classes.classification.PrCurveData(precision_arr: ndarray, recall_arr: ndarray, average_precision: float, baseline: float, label: str)

Bases: object

Precision-Recall curve data for a single class (or binary).

precision_arr

Precision values at each threshold.

Type:

np.ndarray

recall_arr

Recall values at each threshold.

Type:

np.ndarray

average_precision

Average precision score (area under the PR curve).

Type:

float

baseline

No-skill baseline (positive class prevalence).

Type:

float

label

Human-readable label.

Type:

str

average_precision: float

baseline: float

label: str

precision_arr: ndarray

recall_arr: ndarray

class machinelens.core.data_classes.classification.RocCurveData(fpr: ndarray, tpr: ndarray, auc_score: float, label: str)

Bases: object

ROC curve data for a single class (or binary problem).

fpr

False-positive rates.

Type:

np.ndarray

tpr

True-positive rates.

Type:

np.ndarray

auc_score

Area Under the ROC Curve.

Type:

float

label

Human-readable label, e.g. "binary" or "class_2".

Type:

str

auc_score: float

fpr: ndarray

label: str

tpr: ndarray

class machinelens.core.data_classes.classification.ThresholdAnalysisData(thresholds: ndarray, precision: ndarray, recall: ndarray, f1_score: ndarray, label: str)

Bases: object

Threshold decision analysis data.

thresholds

Decision thresholds.

Type:

np.ndarray

precision

Precision scores for each threshold.

Type:

np.ndarray

recall

Recall scores for each threshold.

Type:

np.ndarray

f1_score

F1 scores for each threshold.

Type:

np.ndarray

label

Human-readable label for the class.

Type:

str

f1_score: ndarray

label: str

precision: ndarray

recall: ndarray

thresholds: ndarray

machinelens.core.data_classes.regression module

Regression-specific dataclasses for diagnostics.

class machinelens.core.data_classes.regression.OutlierAnalysisResult(results_df: DataFrame, threshold: float, lowess_curves: Dict[str, ~machinelens.core.data_classes.shared.LowessData]=<factory>)

Bases: object

Statistical analysis of residual outliers.

results_df

Per-feature statistical test results (p-values, effect sizes, significance flags), sorted by adjusted p-value.

Type:

pd.DataFrame

threshold

The standardised-residual threshold used to classify outliers.

Type:

float

lowess_curves

LOWESS smoothing curves for features flagged as significant, keyed by feature name.

Type:

dict of str → LowessData

lowess_curves: Dict[str, LowessData]

results_df: DataFrame

threshold: float

class machinelens.core.data_classes.regression.QQData(theoretical: ndarray, sample: ndarray, slope: float, intercept: float, r_value: float, ci_lower: ndarray, ci_upper: ndarray)

Bases: object

Q-Q (Quantile-Quantile) plot coordinates and reference line.

theoretical

Theoretical quantiles from the standard normal.

Type:

np.ndarray

sample

Ordered sample quantiles.

Type:

np.ndarray

slope

Slope of the best-fit reference line.

Type:

float

intercept

Intercept of the best-fit reference line.

Type:

float

r_value

Pearson correlation coefficient of the fit.

Type:

float

ci_lower

Lower 95 % CI envelope.

Type:

np.ndarray

ci_upper

Upper 95 % CI envelope.

Type:

np.ndarray

ci_lower: ndarray

ci_upper: ndarray

intercept: float

r_value: float

sample: ndarray

slope: float

theoretical: ndarray

class machinelens.core.data_classes.regression.RegressionMetrics(mae: float, mse: float, rmse: float, r2: float, r2_adjusted: float, mape: float, n_samples: int)

Bases: object

Scalar regression evaluation metrics for one subset.

mae

Mean Absolute Error.

Type:

float

mse

Mean Squared Error.

Type:

float

rmse

Root Mean Squared Error.

Type:

float

r2

Coefficient of determination (R²).

Type:

float

r2_adjusted

Adjusted R².

Type:

float

mape

Mean Absolute Percentage Error (%).

Type:

float

n_samples

Number of observations used.

Type:

int

mae: float

mape: float

mse: float

n_samples: int

r2: float

r2_adjusted: float

rmse: float

class machinelens.core.data_classes.regression.RegressionSubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray = <factory>, std_residuals: ndarray = <factory>, abs_residuals: ndarray = <factory>)

Bases: SubsetData

Extended subset data carrying residual arrays (regression only).

residuals

Raw residuals (y_true - y_pred).

Type:

np.ndarray

std_residuals

Standardised residuals (residuals / RMSE).

Type:

np.ndarray

abs_residuals

Absolute residuals (|residuals|).

Type:

np.ndarray

Attributes:

abs_residuals

residuals

std_residuals

machinelens.core.data_classes.results module

Strongly-typed data structures for diagnostic results.

This module defines the Data Object Layer — a hierarchy of dataclass objects that serve as the strict contract and single source of truth for a model’s diagnostic state.

class machinelens.core.data_classes.results.CalibrationCurveData(prob_true: ndarray, prob_pred: ndarray, label: str)

Bases: object

Calibration curve data for reliability diagrams.

prob_true

True probability in each bin.

Type:

np.ndarray

prob_pred

Mean predicted probability in each bin.

Type:

np.ndarray

label

Human-readable label for the class.

Type:

str

label: str

prob_pred: ndarray

prob_true: ndarray

class machinelens.core.data_classes.results.ClassificationMetrics(accuracy: float, precision: float, recall: float, f1_score: float, mcc: float, roc_auc: float | None = None, pr_auc: float | None = None, brier_score: float | None = None, log_loss: float | None = None)

Bases: object

Scalar classification evaluation metrics for one subset.

accuracy

Overall accuracy.

Type:

float

precision

Precision (macro or binary).

Type:

float

recall

Recall (macro or binary).

Type:

float

f1_score

F1-score (macro or binary).

Type:

float

Attributes:

brier_score

log_loss

pr_auc

roc_auc

accuracy: float

brier_score: float | None = None

f1_score: float

log_loss: float | None = None

mcc: float

pr_auc: float | None = None

precision: float

recall: float

roc_auc: float | None = None

class machinelens.core.data_classes.results.ClassificationSubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray | None = None, std_residuals: ndarray | None = None, abs_residuals: ndarray | None = None, y_prob: ndarray | None = None)

Bases: SubsetData

Extended subset data carrying probability arrays (classification).

y_prob

Predicted class probabilities (n_samples, n_classes). None when the estimator does not support predict_proba.

Type:

np.ndarray or None

Attributes:

abs_residuals

residuals

std_residuals

y_prob

y_prob: ndarray | None = None

class machinelens.core.data_classes.results.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)

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.core.data_classes.results.LowessData(x_smooth: ndarray, y_smooth: ndarray, ci_lower: ndarray, ci_upper: ndarray)

Bases: object

LOWESS smoothing curve with a 95 % bootstrap confidence band.

x_smooth

Sorted x-coordinates of the smoothed curve.

Type:

np.ndarray

y_smooth

Smoothed y-values.

Type:

np.ndarray

ci_lower

Lower bound of the 95 % confidence interval.

Type:

np.ndarray

ci_upper

Upper bound of the 95 % confidence interval.

Type:

np.ndarray

ci_lower: ndarray

ci_upper: ndarray

x_smooth: ndarray

y_smooth: ndarray

class machinelens.core.data_classes.results.MisclassificationResult(results_df: DataFrame)

Bases: object

Per-feature statistical analysis of misclassified samples.

results_df

Feature-level test results with columns like feature, stat, p_value, adj_p_value, effect_size, significant.

Type:

pd.DataFrame

results_df: DataFrame

class machinelens.core.data_classes.results.OutlierAnalysisResult(results_df: DataFrame, threshold: float, lowess_curves: Dict[str, ~machinelens.core.data_classes.shared.LowessData]=<factory>)

Bases: object

Statistical analysis of residual outliers.

results_df

Per-feature statistical test results (p-values, effect sizes, significance flags), sorted by adjusted p-value.

Type:

pd.DataFrame

threshold

The standardised-residual threshold used to classify outliers.

Type:

float

lowess_curves

LOWESS smoothing curves for features flagged as significant, keyed by feature name.

Type:

dict of str → LowessData

lowess_curves: Dict[str, LowessData]

results_df: DataFrame

threshold: float

class machinelens.core.data_classes.results.PrCurveData(precision_arr: ndarray, recall_arr: ndarray, average_precision: float, baseline: float, label: str)

Bases: object

Precision-Recall curve data for a single class (or binary).

precision_arr

Precision values at each threshold.

Type:

np.ndarray

recall_arr

Recall values at each threshold.

Type:

np.ndarray

average_precision

Average precision score (area under the PR curve).

Type:

float

baseline

No-skill baseline (positive class prevalence).

Type:

float

label

Human-readable label.

Type:

str

average_precision: float

baseline: float

label: str

precision_arr: ndarray

recall_arr: ndarray

class machinelens.core.data_classes.results.QQData(theoretical: ndarray, sample: ndarray, slope: float, intercept: float, r_value: float, ci_lower: ndarray, ci_upper: ndarray)

Bases: object

Q-Q (Quantile-Quantile) plot coordinates and reference line.

theoretical

Theoretical quantiles from the standard normal.

Type:

np.ndarray

sample

Ordered sample quantiles.

Type:

np.ndarray

slope

Slope of the best-fit reference line.

Type:

float

intercept

Intercept of the best-fit reference line.

Type:

float

r_value

Pearson correlation coefficient of the fit.

Type:

float

ci_lower

Lower 95 % CI envelope.

Type:

np.ndarray

ci_upper

Upper 95 % CI envelope.

Type:

np.ndarray

ci_lower: ndarray

ci_upper: ndarray

intercept: float

r_value: float

sample: ndarray

slope: float

theoretical: ndarray

class machinelens.core.data_classes.results.RegressionMetrics(mae: float, mse: float, rmse: float, r2: float, r2_adjusted: float, mape: float, n_samples: int)

Bases: object

Scalar regression evaluation metrics for one subset.

mae

Mean Absolute Error.

Type:

float

mse

Mean Squared Error.

Type:

float

rmse

Root Mean Squared Error.

Type:

float

r2

Coefficient of determination (R²).

Type:

float

r2_adjusted

Adjusted R².

Type:

float

mape

Mean Absolute Percentage Error (%).

Type:

float

n_samples

Number of observations used.

Type:

int

mae: float

mape: float

mse: float

n_samples: int

r2: float

r2_adjusted: float

rmse: float

class machinelens.core.data_classes.results.RegressionSubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray = <factory>, std_residuals: ndarray = <factory>, abs_residuals: ndarray = <factory>)

Bases: SubsetData

Extended subset data carrying residual arrays (regression only).

residuals

Raw residuals (y_true - y_pred).

Type:

np.ndarray

std_residuals

Standardised residuals (residuals / RMSE).

Type:

np.ndarray

abs_residuals

Absolute residuals (|residuals|).

Type:

np.ndarray

Attributes:

abs_residuals

residuals

std_residuals

class machinelens.core.data_classes.results.RocCurveData(fpr: ndarray, tpr: ndarray, auc_score: float, label: str)

Bases: object

ROC curve data for a single class (or binary problem).

fpr

False-positive rates.

Type:

np.ndarray

tpr

True-positive rates.

Type:

np.ndarray

auc_score

Area Under the ROC Curve.

Type:

float

label

Human-readable label, e.g. "binary" or "class_2".

Type:

str

auc_score: float

fpr: ndarray

label: str

tpr: ndarray

class machinelens.core.data_classes.results.ShapData(feature_names: ~typing.List[str], base_value: float | ~typing.List[float], shap_values: ~numpy.ndarray, mean_abs_shap: ~numpy.ndarray, eval_index: ~typing.List[int] = <factory>, feature_values: ~numpy.ndarray | None = None)

Bases: object

Stores SHAP values and metadata for local and global explainability.

feature_names

The names of the features used in the model.

Type:

list of str

base_value

The base (expected) value of the model’s predictions.

Type:

float or list of float

shap_values

The matrix of local SHAP values for each instance and feature. Shape: (n_samples, n_features).

Type:

np.ndarray

mean_abs_shap

Mean absolute SHAP values per feature across the dataset.

Type:

np.ndarray

eval_index

The original dataset row indices corresponding to each row in shap_values. Used by the frontend to map selection events (which carry original indices) to the correct SHAP row.

Type:

list of int

feature_values

The raw feature values for the evaluated set, same shape as shap_values. Required by the Beeswarm plot for coloring.

Type:

np.ndarray or None

Attributes:

feature_values

base_value: float | List[float]

eval_index: List[int]

feature_names: List[str]

feature_values: ndarray | None = None

mean_abs_shap: ndarray

shap_values: ndarray

class machinelens.core.data_classes.results.SubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray | None = None, std_residuals: ndarray | None = None, abs_residuals: ndarray | None = None)

Bases: object

Aligned arrays for a single data subset (train or test).

X_data

Feature matrix, index-aligned with the target arrays.

Type:

pd.DataFrame

y_true

Ground-truth target values (1-D).

Type:

np.ndarray

y_pred

Model predictions (1-D), same length as y_true.

Type:

np.ndarray

Attributes:

abs_residuals

residuals

std_residuals

X_data: DataFrame

abs_residuals: ndarray | None = None

residuals: ndarray | None = None

std_residuals: ndarray | None = None

y_pred: ndarray

y_true: ndarray

class machinelens.core.data_classes.results.ThresholdAnalysisData(thresholds: ndarray, precision: ndarray, recall: ndarray, f1_score: ndarray, label: str)

Bases: object

Threshold decision analysis data.

thresholds

Decision thresholds.

Type:

np.ndarray

precision

Precision scores for each threshold.

Type:

np.ndarray

recall

Recall scores for each threshold.

Type:

np.ndarray

f1_score

F1 scores for each threshold.

Type:

np.ndarray

label

Human-readable label for the class.

Type:

str

f1_score: ndarray

label: str

precision: ndarray

recall: ndarray

thresholds: ndarray

machinelens.core.data_classes.shap module

SHAP data structures for model explainability.

class machinelens.core.data_classes.shap.ShapData(feature_names: ~typing.List[str], base_value: float | ~typing.List[float], shap_values: ~numpy.ndarray, mean_abs_shap: ~numpy.ndarray, eval_index: ~typing.List[int] = <factory>, feature_values: ~numpy.ndarray | None = None)

Bases: object

Stores SHAP values and metadata for local and global explainability.

feature_names

The names of the features used in the model.

Type:

list of str

base_value

The base (expected) value of the model’s predictions.

Type:

float or list of float

shap_values

The matrix of local SHAP values for each instance and feature. Shape: (n_samples, n_features).

Type:

np.ndarray

mean_abs_shap

Mean absolute SHAP values per feature across the dataset.

Type:

np.ndarray

eval_index

The original dataset row indices corresponding to each row in shap_values. Used by the frontend to map selection events (which carry original indices) to the correct SHAP row.

Type:

list of int

feature_values

The raw feature values for the evaluated set, same shape as shap_values. Required by the Beeswarm plot for coloring.

Type:

np.ndarray or None

Attributes:

feature_values

base_value: float | List[float]

eval_index: List[int]

feature_names: List[str]

feature_values: ndarray | None = None

mean_abs_shap: ndarray

shap_values: ndarray

machinelens.core.data_classes.shared module

Shared data structures for diagnostic results.

class machinelens.core.data_classes.shared.LowessData(x_smooth: ndarray, y_smooth: ndarray, ci_lower: ndarray, ci_upper: ndarray)

Bases: object

LOWESS smoothing curve with a 95 % bootstrap confidence band.

x_smooth

Sorted x-coordinates of the smoothed curve.

Type:

np.ndarray

y_smooth

Smoothed y-values.

Type:

np.ndarray

ci_lower

Lower bound of the 95 % confidence interval.

Type:

np.ndarray

ci_upper

Upper bound of the 95 % confidence interval.

Type:

np.ndarray

ci_lower: ndarray

ci_upper: ndarray

x_smooth: ndarray

y_smooth: ndarray

class machinelens.core.data_classes.shared.SubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray | None = None, std_residuals: ndarray | None = None, abs_residuals: ndarray | None = None)

Bases: object

Aligned arrays for a single data subset (train or test).

X_data

Feature matrix, index-aligned with the target arrays.

Type:

pd.DataFrame

y_true

Ground-truth target values (1-D).

Type:

np.ndarray

y_pred

Model predictions (1-D), same length as y_true.

Type:

np.ndarray

Attributes:

abs_residuals

residuals

std_residuals

X_data: DataFrame

abs_residuals: ndarray | None = None

residuals: ndarray | None = None

std_residuals: ndarray | None = None

y_pred: ndarray

y_true: ndarray

Module contents

Strongly-typed data classes and contracts for MachineLens.

class machinelens.core.data_classes.CalibrationCurveData(prob_true: ndarray, prob_pred: ndarray, label: str)

Bases: object

Calibration curve data for reliability diagrams.

prob_true

True probability in each bin.

Type:

np.ndarray

prob_pred

Mean predicted probability in each bin.

Type:

np.ndarray

label

Human-readable label for the class.

Type:

str

label: str

prob_pred: ndarray

prob_true: ndarray

class machinelens.core.data_classes.ClassificationMetrics(accuracy: float, precision: float, recall: float, f1_score: float, mcc: float, roc_auc: float | None = None, pr_auc: float | None = None, brier_score: float | None = None, log_loss: float | None = None)

Bases: object

Scalar classification evaluation metrics for one subset.

accuracy

Overall accuracy.

Type:

float

precision

Precision (macro or binary).

Type:

float

recall

Recall (macro or binary).

Type:

float

f1_score

F1-score (macro or binary).

Type:

float

Attributes:

brier_score

log_loss

pr_auc

roc_auc

accuracy: float

brier_score: float | None = None

f1_score: float

log_loss: float | None = None

mcc: float

pr_auc: float | None = None

precision: float

recall: float

roc_auc: float | None = None

class machinelens.core.data_classes.ClassificationSubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray | None = None, std_residuals: ndarray | None = None, abs_residuals: ndarray | None = None, y_prob: ndarray | None = None)

Bases: SubsetData

Extended subset data carrying probability arrays (classification).

y_prob

Predicted class probabilities (n_samples, n_classes). None when the estimator does not support predict_proba.

Type:

np.ndarray or None

Attributes:

abs_residuals

residuals

std_residuals

y_prob

y_prob: ndarray | None = None

class machinelens.core.data_classes.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)

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.core.data_classes.LowessData(x_smooth: ndarray, y_smooth: ndarray, ci_lower: ndarray, ci_upper: ndarray)

Bases: object

LOWESS smoothing curve with a 95 % bootstrap confidence band.

x_smooth

Sorted x-coordinates of the smoothed curve.

Type:

np.ndarray

y_smooth

Smoothed y-values.

Type:

np.ndarray

ci_lower

Lower bound of the 95 % confidence interval.

Type:

np.ndarray

ci_upper

Upper bound of the 95 % confidence interval.

Type:

np.ndarray

ci_lower: ndarray

ci_upper: ndarray

x_smooth: ndarray

y_smooth: ndarray

class machinelens.core.data_classes.MisclassificationResult(results_df: DataFrame)

Bases: object

Per-feature statistical analysis of misclassified samples.

results_df

Feature-level test results with columns like feature, stat, p_value, adj_p_value, effect_size, significant.

Type:

pd.DataFrame

results_df: DataFrame

class machinelens.core.data_classes.OutlierAnalysisResult(results_df: DataFrame, threshold: float, lowess_curves: Dict[str, ~machinelens.core.data_classes.shared.LowessData]=<factory>)

Bases: object

Statistical analysis of residual outliers.

results_df

Per-feature statistical test results (p-values, effect sizes, significance flags), sorted by adjusted p-value.

Type:

pd.DataFrame

threshold

The standardised-residual threshold used to classify outliers.

Type:

float

lowess_curves

LOWESS smoothing curves for features flagged as significant, keyed by feature name.

Type:

dict of str → LowessData

lowess_curves: Dict[str, LowessData]

results_df: DataFrame

threshold: float

class machinelens.core.data_classes.PrCurveData(precision_arr: ndarray, recall_arr: ndarray, average_precision: float, baseline: float, label: str)

Bases: object

Precision-Recall curve data for a single class (or binary).

precision_arr

Precision values at each threshold.

Type:

np.ndarray

recall_arr

Recall values at each threshold.

Type:

np.ndarray

average_precision

Average precision score (area under the PR curve).

Type:

float

baseline

No-skill baseline (positive class prevalence).

Type:

float

label

Human-readable label.

Type:

str

average_precision: float

baseline: float

label: str

precision_arr: ndarray

recall_arr: ndarray

class machinelens.core.data_classes.QQData(theoretical: ndarray, sample: ndarray, slope: float, intercept: float, r_value: float, ci_lower: ndarray, ci_upper: ndarray)

Bases: object

Q-Q (Quantile-Quantile) plot coordinates and reference line.

theoretical

Theoretical quantiles from the standard normal.

Type:

np.ndarray

sample

Ordered sample quantiles.

Type:

np.ndarray

slope

Slope of the best-fit reference line.

Type:

float

intercept

Intercept of the best-fit reference line.

Type:

float

r_value

Pearson correlation coefficient of the fit.

Type:

float

ci_lower

Lower 95 % CI envelope.

Type:

np.ndarray

ci_upper

Upper 95 % CI envelope.

Type:

np.ndarray

ci_lower: ndarray

ci_upper: ndarray

intercept: float

r_value: float

sample: ndarray

slope: float

theoretical: ndarray

class machinelens.core.data_classes.RegressionMetrics(mae: float, mse: float, rmse: float, r2: float, r2_adjusted: float, mape: float, n_samples: int)

Bases: object

Scalar regression evaluation metrics for one subset.

mae

Mean Absolute Error.

Type:

float

mse

Mean Squared Error.

Type:

float

rmse

Root Mean Squared Error.

Type:

float

r2

Coefficient of determination (R²).

Type:

float

r2_adjusted

Adjusted R².

Type:

float

mape

Mean Absolute Percentage Error (%).

Type:

float

n_samples

Number of observations used.

Type:

int

mae: float

mape: float

mse: float

n_samples: int

r2: float

r2_adjusted: float

rmse: float

class machinelens.core.data_classes.RegressionSubsetData(X_data: DataFrame, y_true: ndarray, y_pred: ndarray, residuals: ndarray = <factory>, std_residuals: ndarray = <factory>, abs_residuals: ndarray = <factory>)

Bases: SubsetData

Extended subset data carrying residual arrays (regression only).

residuals

Raw residuals (y_true - y_pred).

Type:

np.ndarray

std_residuals

Standardised residuals (residuals / RMSE).

Type:

np.ndarray

abs_residuals

Absolute residuals (|residuals|).

Type:

np.ndarray

Attributes:

abs_residuals

residuals

std_residuals

class machinelens.core.data_classes.RocCurveData(fpr: ndarray, tpr: ndarray, auc_score: float, label: str)

Bases: object

ROC curve data for a single class (or binary problem).

fpr

False-positive rates.

Type:

np.ndarray

tpr

True-positive rates.

Type:

np.ndarray

auc_score

Area Under the ROC Curve.

Type:

float

label

Human-readable label, e.g. "binary" or "class_2".

Type:

str

auc_score: float

fpr: ndarray

label: str

tpr: ndarray

class machinelens.core.data_classes.ShapData(feature_names: ~typing.List[str], base_value: float | ~typing.List[float], shap_values: ~numpy.ndarray, mean_abs_shap: ~numpy.ndarray, eval_index: ~typing.List[int] = <factory>, feature_values: ~numpy.ndarray | None = None)

Bases: object

Stores SHAP values and metadata for local and global explainability.

feature_names

The names of the features used in the model.

Type:

list of str

base_value

The base (expected) value of the model’s predictions.

Type:

float or list of float

shap_values

The matrix of local SHAP values for each instance and feature. Shape: (n_samples, n_features).

Type:

np.ndarray

mean_abs_shap

Mean absolute SHAP values per feature across the dataset.

Type:

np.ndarray

eval_index

The original dataset row indices corresponding to each row in shap_values. Used by the frontend to map selection events (which carry original indices) to the correct SHAP row.

Type:

list of int

feature_values

The raw feature values for the evaluated set, same shape as shap_values. Required by the Beeswarm plot for coloring.

Type:

np.ndarray or None

Attributes:

feature_values

base_value: float | List[float]

eval_index: List[int]

feature_names: List[str]

feature_values: ndarray | None = None

mean_abs_shap: ndarray

shap_values: ndarray

class machinelens.core.data_classes.ThresholdAnalysisData(thresholds: ndarray, precision: ndarray, recall: ndarray, f1_score: ndarray, label: str)

Bases: object

Threshold decision analysis data.

thresholds

Decision thresholds.

Type:

np.ndarray

precision

Precision scores for each threshold.

Type:

np.ndarray

recall

Recall scores for each threshold.

Type:

np.ndarray

f1_score

F1 scores for each threshold.

Type:

np.ndarray

label

Human-readable label for the class.

Type:

str

f1_score: ndarray

label: str

precision: ndarray

recall: ndarray

thresholds: ndarray