Skip to main content

solow_metrics/
lib.rs

1//! # solow-metrics
2//!
3//! Model-evaluation metrics for the Solow statistical stack — the numbers you
4//! report after a fit, not the ones an estimator uses internally.
5//!
6//! The crate is organised by task:
7//!
8//! * [`regression`] — continuous-target losses and scores: mean squared error,
9//!   RMSE, mean absolute error, MAPE, sMAPE, R², explained variance,
10//!   max-error, mean pinball loss for quantile regression, Tweedie / Poisson
11//!   / Gamma deviances, and their sample-weighted variants.
12//! * [`classification`] — labels and probabilities: confusion matrix, accuracy,
13//!   balanced accuracy, precision / recall / Fβ with `macro` / `micro` /
14//!   `weighted` / per-class averaging, Matthews correlation, Cohen's κ (linear
15//!   and quadratic weighting), zero-one loss, hinge loss, binary log-loss,
16//!   Brier score, and — for scored classifiers — the ROC and precision-recall
17//!   curves, ROC-AUC (binary, one-vs-rest and Hand-Till one-vs-one for
18//!   multiclass), and average precision.
19//! * [`calibration`] — probability-calibration diagnostics: reliability curves
20//!   with uniform or quantile bins, expected and maximum calibration error,
21//!   and the Sanders / Murphy decomposition of the Brier score.
22//! * [`forecast`] — time-series specific losses: MASE, RMSSE, pinball loss for
23//!   prediction quantiles, interval coverage, the mean interval score
24//!   (Winkler) for prediction bands, and the Harvey-Leybourne-Newbold
25//!   small-sample-corrected Diebold-Mariano test for equal predictive
26//!   accuracy of two forecasts.
27//!
28//! All functions take ndarray views so they compose with slices, subranges, and
29//! matrix rows without copies. Every metric returns a `Result` because pairs
30//! with mismatched shapes, negative sample weights, unknown classes, or
31//! degenerate inputs (a constant target for R², a single-class label vector for
32//! ROC-AUC, …) are user errors, not silent NaNs.
33//!
34//! The metric names, signatures, and averaging semantics deliberately mirror
35//! the canonical `the reference` API so that ports and cross-checks are literal
36//! — a reader can translate a the reference example one call at a time.
37//!
38//! ## Example
39//!
40//! ```
41//! use ndarray::array;
42//! use solow_metrics::{mean_squared_error, r2_score};
43//!
44//! let y_true = array![3.0, -0.5, 2.0, 7.0];
45//! let y_pred = array![2.5, 0.0, 2.0, 8.0];
46//!
47//! let mse = mean_squared_error(y_true.view(), y_pred.view(), None).unwrap();
48//! let r2  = r2_score(y_true.view(), y_pred.view(), None).unwrap();
49//!
50//! assert!((mse - 0.375).abs() < 1e-12);
51//! // R² = 1 - SS_res / SS_tot = 1 - 1.5 / 29.1875.
52//! assert!((r2 - (1.0 - 1.5 / 29.1875)).abs() < 1e-10);
53//! ```
54
55#![forbid(unsafe_code)]
56#![warn(missing_docs)]
57
58pub mod bayesian;
59pub mod calibration;
60pub mod calibrators;
61pub mod classification;
62pub mod cluster;
63pub mod comparison;
64pub mod conformal;
65pub mod effect_size;
66pub mod forecast;
67pub mod inspection;
68pub mod pairwise;
69pub mod regression;
70pub mod report;
71
72pub use bayesian::{psis_loo, waic, PsisLooResult, WaicResult};
73pub use calibration::{
74    brier_decomposition, expected_calibration_error, maximum_calibration_error, reliability_curve,
75    BinStrategy, BrierDecomposition, ReliabilityBin,
76};
77pub use calibrators::{IsotonicRegression, PlattScaling, TemperatureScaling};
78pub use classification::{
79    accuracy_score, average_precision_score, balanced_accuracy_score, binary_focal_loss,
80    binary_log_loss, brier_score_loss, cohen_kappa_score, confusion_matrix, fbeta_score,
81    hinge_loss, log_loss, matthews_corrcoef, multiclass_brier_score, multiclass_focal_loss,
82    precision_recall_curve, precision_recall_fscore, ranked_probability_score, roc_auc_ovo_score,
83    roc_auc_ovr_score, roc_auc_score, roc_curve, top_k_accuracy_score, top_label_calibration_error,
84    zero_one_loss, Average, KappaWeights, MulticlassAuc, PrecisionRecallFScore,
85    RocCurve as RocCurveResult,
86};
87pub use comparison::{
88    friedman_test, nemenyi_critical_difference, wilcoxon_signed_rank, FriedmanResult,
89    WilcoxonResult,
90};
91pub use cluster::{
92    adjusted_mutual_info_score, adjusted_rand_score, calinski_harabasz_score, completeness_score,
93    davies_bouldin_score, fowlkes_mallows_score, homogeneity_score,
94    normalized_mutual_info_score, silhouette_score, v_measure_score, MiAverage,
95};
96pub use conformal::{JackknifePlus, PredictionInterval, SplitConformal};
97pub use effect_size::{
98    cliffs_delta, cohens_d, cramers_v, eta_squared, glass_delta, hedges_g, omega_squared,
99};
100pub use forecast::{
101    diebold_mariano, giacomini_white_test, interval_coverage, mase, mean_interval_score,
102    pinball_loss, rmsse, DieboldMarianoResult, DmLoss, GiacominiWhiteResult,
103};
104pub use inspection::{
105    accumulated_local_effects, partial_dependence, permutation_importance, AccumulatedLocalEffects,
106    FeatureImportance, PartialDependence,
107};
108pub use pairwise::{
109    chi2_kernel, cosine_similarity, laplacian_kernel, linear_kernel, pairwise_distances,
110    polynomial_kernel, rbf_kernel, sigmoid_kernel, PairwiseMetric,
111};
112pub use report::{classification_report, ClassificationReport, ClassificationRow};
113pub use regression::{
114    d2_absolute_error_score, d2_tweedie_score, explained_variance_score, huber_loss, log_cosh_loss,
115    max_error, mean_absolute_error, mean_absolute_percentage_error, mean_gamma_deviance,
116    mean_pinball_loss, mean_poisson_deviance, mean_squared_error, mean_squared_log_error,
117    mean_tweedie_deviance, median_absolute_error, r2_score, root_mean_squared_error,
118    root_mean_squared_log_error, symmetric_mean_absolute_percentage_error, RegressionReport,
119};
120
121/// Commonly used imports.
122///
123/// `use solow_metrics::prelude::*;` brings every metric name plus the shared
124/// [`Average`], [`KappaWeights`], [`MulticlassAuc`], [`BinStrategy`], and
125/// [`DmLoss`] enums into scope in one line.
126pub mod prelude {
127    pub use crate::bayesian::{psis_loo, waic, PsisLooResult, WaicResult};
128    pub use crate::calibration::{
129        brier_decomposition, expected_calibration_error, maximum_calibration_error,
130        reliability_curve, BinStrategy, BrierDecomposition, ReliabilityBin,
131    };
132    pub use crate::calibrators::{IsotonicRegression, PlattScaling, TemperatureScaling};
133    pub use crate::classification::{
134        accuracy_score, average_precision_score, balanced_accuracy_score, binary_focal_loss,
135        binary_log_loss, brier_score_loss, cohen_kappa_score, confusion_matrix, fbeta_score,
136        hinge_loss, log_loss, matthews_corrcoef, multiclass_brier_score, multiclass_focal_loss,
137        precision_recall_curve, precision_recall_fscore, ranked_probability_score,
138        roc_auc_ovo_score, roc_auc_ovr_score, roc_auc_score, roc_curve, top_k_accuracy_score,
139        top_label_calibration_error, zero_one_loss, Average, KappaWeights, MulticlassAuc,
140    };
141    pub use crate::comparison::{
142        friedman_test, nemenyi_critical_difference, wilcoxon_signed_rank, FriedmanResult,
143        WilcoxonResult,
144    };
145    pub use crate::conformal::{JackknifePlus, PredictionInterval, SplitConformal};
146    pub use crate::forecast::{
147        diebold_mariano, giacomini_white_test, interval_coverage, mase, mean_interval_score,
148        pinball_loss, rmsse, DmLoss,
149    };
150    pub use crate::inspection::{
151        accumulated_local_effects, partial_dependence, permutation_importance,
152        AccumulatedLocalEffects, FeatureImportance, PartialDependence,
153    };
154    pub use crate::regression::{
155        d2_absolute_error_score, d2_tweedie_score, explained_variance_score, huber_loss,
156        log_cosh_loss, max_error, mean_absolute_error, mean_absolute_percentage_error,
157        mean_gamma_deviance, mean_pinball_loss, mean_poisson_deviance, mean_squared_error,
158        mean_squared_log_error, mean_tweedie_deviance, median_absolute_error, r2_score,
159        root_mean_squared_error, root_mean_squared_log_error,
160        symmetric_mean_absolute_percentage_error, RegressionReport,
161    };
162}