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

fdars_core/explain/
ale_lime.rs
