fdars_core/explain/
ale_lime.rs

1//! ALE (Accumulated Local Effects) and LIME (Local Surrogate).
2
3use crate::error::FdarError;
4use crate::matrix::FdMatrix;
5use crate::scalar_on_function::{FregreLmResult, FunctionalLogisticResult};
6
7// ===========================================================================
8// ALE (Accumulated Local Effects)
9// ===========================================================================
10
11/// Result of Accumulated Local Effects analysis.
12#[derive(Debug, Clone, PartialEq)]
13#[non_exhaustive]
14pub struct AleResult {
15    /// Bin midpoints (length n_bins_actual).
16    pub bin_midpoints: Vec<f64>,
17    /// ALE values centered to mean zero (length n_bins_actual).
18    pub ale_values: Vec<f64>,
19    /// Bin edges (length n_bins_actual + 1).
20    pub bin_edges: Vec<f64>,
21    /// Number of observations in each bin (length n_bins_actual).
22    pub bin_counts: Vec<usize>,
23    /// Which FPC component was analyzed.
24    pub component: usize,
25}
26
27/// ALE plot for an FPC component in a linear functional regression model.
28///
29/// ALE measures the average local effect of varying one FPC score on predictions,
30/// avoiding the extrapolation issues of PDP.
31///
32/// # Errors
33///
34/// See [`crate::explain_generic::generic_ale`] for error conditions.
35#[must_use = "expensive computation whose result should not be discarded"]
36pub fn fpc_ale(
37    fit: &FregreLmResult,
38    data: &FdMatrix,
39    scalar_covariates: Option<&FdMatrix>,
40    component: usize,
41    n_bins: usize,
42) -> Result<AleResult, FdarError> {
43    crate::explain_generic::generic_ale(fit, data, scalar_covariates, component, n_bins)
44}
45
46/// ALE plot for an FPC component in a functional logistic regression model.
47///
48/// # Errors
49///
50/// See [`crate::explain_generic::generic_ale`] for error conditions.
51#[must_use = "expensive computation whose result should not be discarded"]
52pub fn fpc_ale_logistic(
53    fit: &FunctionalLogisticResult,
54    data: &FdMatrix,
55    scalar_covariates: Option<&FdMatrix>,
56    component: usize,
57    n_bins: usize,
58) -> Result<AleResult, FdarError> {
59    crate::explain_generic::generic_ale(fit, data, scalar_covariates, component, n_bins)
60}
61
62// ===========================================================================
63// LIME (Local Surrogate)
64// ===========================================================================
65
66/// Result of a LIME local surrogate explanation.
67#[derive(Debug, Clone, PartialEq)]
68#[non_exhaustive]
69pub struct LimeResult {
70    /// Index of the observation being explained.
71    pub observation: usize,
72    /// Local FPC-level attributions, length ncomp.
73    pub attributions: Vec<f64>,
74    /// Local intercept.
75    pub local_intercept: f64,
76    /// Local R^2 (weighted).
77    pub local_r_squared: f64,
78    /// Kernel width used.
79    pub kernel_width: f64,
80}
81
82/// LIME explanation for a linear functional regression model.
83///
84/// # Errors
85///
86/// See [`crate::explain_generic::generic_lime`] for error conditions.
87#[must_use = "expensive computation whose result should not be discarded"]
88pub fn lime_explanation(
89    fit: &FregreLmResult,
90    data: &FdMatrix,
91    scalar_covariates: Option<&FdMatrix>,
92    observation: usize,
93    n_samples: usize,
94    kernel_width: f64,
95    seed: u64,
96) -> Result<LimeResult, FdarError> {
97    crate::explain_generic::generic_lime(
98        fit,
99        data,
100        scalar_covariates,
101        observation,
102        n_samples,
103        kernel_width,
104        seed,
105    )
106}
107
108/// LIME explanation for a functional logistic regression model.
109///
110/// # Errors
111///
112/// See [`crate::explain_generic::generic_lime`] for error conditions.
113#[must_use = "expensive computation whose result should not be discarded"]
114pub fn lime_explanation_logistic(
115    fit: &FunctionalLogisticResult,
116    data: &FdMatrix,
117    scalar_covariates: Option<&FdMatrix>,
118    observation: usize,
119    n_samples: usize,
120    kernel_width: f64,
121    seed: u64,
122) -> Result<LimeResult, FdarError> {
123    crate::explain_generic::generic_lime(
124        fit,
125        data,
126        scalar_covariates,
127        observation,
128        n_samples,
129        kernel_width,
130        seed,
131    )
132}
fdars_core/explain/ale_lime.rs

fdars_core/explain/
ale_lime.rs
