fdars-core 0.13.0

Functional Data Analysis algorithms in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! ALE (Accumulated Local Effects) and LIME (Local Surrogate).

use crate::error::FdarError;
use crate::matrix::FdMatrix;
use crate::scalar_on_function::{FregreLmResult, FunctionalLogisticResult};

// ===========================================================================
// ALE (Accumulated Local Effects)
// ===========================================================================

/// Result of Accumulated Local Effects analysis.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct AleResult {
    /// Bin midpoints (length n_bins_actual).
    pub bin_midpoints: Vec<f64>,
    /// ALE values centered to mean zero (length n_bins_actual).
    pub ale_values: Vec<f64>,
    /// Bin edges (length n_bins_actual + 1).
    pub bin_edges: Vec<f64>,
    /// Number of observations in each bin (length n_bins_actual).
    pub bin_counts: Vec<usize>,
    /// Which FPC component was analyzed.
    pub component: usize,
}

/// ALE plot for an FPC component in a linear functional regression model.
///
/// ALE measures the average local effect of varying one FPC score on predictions,
/// avoiding the extrapolation issues of PDP.
///
/// # Errors
///
/// See [`crate::explain_generic::generic_ale`] for error conditions.
#[must_use = "expensive computation whose result should not be discarded"]
pub fn fpc_ale(
    fit: &FregreLmResult,
    data: &FdMatrix,
    scalar_covariates: Option<&FdMatrix>,
    component: usize,
    n_bins: usize,
) -> Result<AleResult, FdarError> {
    crate::explain_generic::generic_ale(fit, data, scalar_covariates, component, n_bins)
}

/// ALE plot for an FPC component in a functional logistic regression model.
///
/// # Errors
///
/// See [`crate::explain_generic::generic_ale`] for error conditions.
#[must_use = "expensive computation whose result should not be discarded"]
pub fn fpc_ale_logistic(
    fit: &FunctionalLogisticResult,
    data: &FdMatrix,
    scalar_covariates: Option<&FdMatrix>,
    component: usize,
    n_bins: usize,
) -> Result<AleResult, FdarError> {
    crate::explain_generic::generic_ale(fit, data, scalar_covariates, component, n_bins)
}

// ===========================================================================
// LIME (Local Surrogate)
// ===========================================================================

/// Result of a LIME local surrogate explanation.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct LimeResult {
    /// Index of the observation being explained.
    pub observation: usize,
    /// Local FPC-level attributions, length ncomp.
    pub attributions: Vec<f64>,
    /// Local intercept.
    pub local_intercept: f64,
    /// Local R^2 (weighted).
    pub local_r_squared: f64,
    /// Kernel width used.
    pub kernel_width: f64,
}

/// LIME explanation for a linear functional regression model.
///
/// # Errors
///
/// See [`crate::explain_generic::generic_lime`] for error conditions.
#[must_use = "expensive computation whose result should not be discarded"]
pub fn lime_explanation(
    fit: &FregreLmResult,
    data: &FdMatrix,
    scalar_covariates: Option<&FdMatrix>,
    observation: usize,
    n_samples: usize,
    kernel_width: f64,
    seed: u64,
) -> Result<LimeResult, FdarError> {
    crate::explain_generic::generic_lime(
        fit,
        data,
        scalar_covariates,
        observation,
        n_samples,
        kernel_width,
        seed,
    )
}

/// LIME explanation for a functional logistic regression model.
///
/// # Errors
///
/// See [`crate::explain_generic::generic_lime`] for error conditions.
#[must_use = "expensive computation whose result should not be discarded"]
pub fn lime_explanation_logistic(
    fit: &FunctionalLogisticResult,
    data: &FdMatrix,
    scalar_covariates: Option<&FdMatrix>,
    observation: usize,
    n_samples: usize,
    kernel_width: f64,
    seed: u64,
) -> Result<LimeResult, FdarError> {
    crate::explain_generic::generic_lime(
        fit,
        data,
        scalar_covariates,
        observation,
        n_samples,
        kernel_width,
        seed,
    )
}