fdars_core/
lib.rs

1//! # fdars-core
2//!
3//! Core algorithms for Functional Data Analysis in Rust.
4//!
5//! This crate provides pure Rust implementations of various FDA methods including:
6//! - Functional data operations (mean, derivatives, norms)
7//! - Depth measures (Fraiman-Muniz, modal, band, random projection, etc.)
8//! - Distance metrics (Lp, Hausdorff, DTW, Fourier, etc.)
9//! - Basis representations (B-splines, P-splines, Fourier)
10//! - Clustering (k-means, fuzzy c-means)
11//! - Smoothing (Nadaraya-Watson, local linear/polynomial regression)
12//! - Outlier detection
13//! - Regression (PCA, PLS, ridge)
14//! - Seasonal analysis (period estimation, peak detection, seasonal strength)
15//! - Detrending and decomposition for non-stationary data
16//!
17//! ## Imports
18//!
19//! Items are organized into domain-specific submodules. Prefer importing from
20//! the submodule for clarity:
21//!
22//! ```rust,no_run
23//! use fdars_core::matrix::FdMatrix;
24//! use fdars_core::alignment::{karcher_mean, elastic_align_pair, AlignmentOutput};
25//! use fdars_core::spm::{spm_phase1, spm_monitor, SpmConfig};
26//! use fdars_core::regression::fdata_to_pc_1d;
27//! use fdars_core::scalar_on_function::{fregre_lm, fregre_pls};
28//! use fdars_core::cv::{cv_fdata_with_metrics, regression_metrics};
29//! use fdars_core::distance::pairwise_distance_matrix;
30//! ```
31//!
32//! All public items are also re-exported at the crate root for convenience:
33//! ```rust,no_run
34//! use fdars_core::{FdMatrix, karcher_mean, spm_phase1, fdata_to_pc_1d};
35//! ```
36//!
37//! The [`prelude`] module provides the most commonly used types:
38//! ```rust,no_run
39//! use fdars_core::prelude::*;
40//! ```
41//!
42//! ## Feature Flags
43//!
44//! | Feature | Default | Description |
45//! |---------|---------|-------------|
46//! | `parallel` | **yes** | Enables rayon-based parallelism via `iter_maybe_parallel!` macro |
47//! | `linalg` | no | Enables `faer` and `anofox-regression` dependencies (requires Rust 1.84+). Gates `ridge_regression_fit`. Not WASM-compatible. |
48//! | `serde` | no | Adds `Serialize`/`Deserialize` to core types (`FdMatrix`, `FpcaResult`, `SpmChart`, etc.) and enables `serde_json::Value` in `ExplainLayer.extra`. |
49//! | `js` | no | Enables `getrandom/js` for WASM builds. |
50//!
51//! ## Data Layout
52//!
53//! Functional data is represented using the [`FdMatrix`] type, a column-major matrix
54//! wrapping a flat `Vec<f64>` with safe `(i, j)` indexing and dimension tracking:
55//! - For n observations with m evaluation points: `data[(i, j)]` gives observation i at point j
56//! - 2D surfaces (n observations, m1 x m2 grid): stored as n x (m1*m2) matrices
57//! - Zero-copy column access via `data.column(j)`, row gather via `data.row(i)`
58//! - nalgebra interop via `to_dmatrix()` / `from_dmatrix()` for SVD operations
59
60#![allow(clippy::needless_range_loop)]
61#![allow(clippy::too_many_arguments)]
62#![allow(clippy::type_complexity)]
63
64pub mod error;
65pub(crate) mod linalg;
66pub mod matrix;
67pub mod parallel;
68
69pub use error::FdarError;
70
71#[cfg(test)]
72pub(crate) mod test_helpers;
73
74pub mod alignment;
75pub mod andrews;
76
77// Shared utility modules
78pub mod basis;
79pub mod classification;
80pub mod clustering;
81pub mod cv;
82pub mod depth;
83pub mod detrend;
84pub mod distance;
85pub mod famm;
86pub mod fdata;
87pub mod fof_regression;
88pub mod function_on_scalar;
89pub mod function_on_scalar_2d;
90pub mod gmm;
91pub mod helpers;
92pub mod irreg_fdata;
93pub mod landmark;
94pub mod metric;
95pub mod outliers;
96pub mod regression;
97pub mod scalar_on_function;
98pub mod seasonal;
99pub mod simulation;
100pub mod smoothing;
101pub mod streaming_depth;
102pub mod tolerance;
103pub mod utility;
104pub mod validation;
105pub mod warping;
106pub mod wire;
107
108// Covariance kernels and Gaussian processes
109pub mod covariance;
110
111// Statistical Process Monitoring
112pub mod spm;
113
114// Elastic analysis modules
115pub mod conformal;
116pub mod elastic;
117pub mod elastic_changepoint;
118pub mod elastic_explain;
119pub mod elastic_fpca;
120pub mod elastic_regression;
121pub mod explain;
122pub mod explain_generic;
123pub mod prelude;
124pub mod scoring;
125pub mod smooth_basis;
126
127// Re-export matrix types
128pub use matrix::{FdCurveSet, FdMatrix};
129
130// Re-export Andrews curves types
131pub use andrews::{andrews_loadings, andrews_transform, AndrewsLoadings, AndrewsResult};
132
133// Re-export covariance kernel types
134pub use covariance::{
135    covariance_matrix, generate_gaussian_process, CovKernel, GaussianProcessResult,
136};
137
138// Re-export alignment types and functions
139pub use alignment::{
140    align_to_target, alignment_quality, amplitude_distance, amplitude_self_distance_matrix,
141    bayesian_align_pair, compose_warps, curve_geodesic, curve_geodesic_nd, cut_dendrogram,
142    diagnose_alignment, diagnose_pairwise, elastic_align_pair, elastic_align_pair_closed,
143    elastic_align_pair_constrained, elastic_align_pair_multires, elastic_align_pair_nd,
144    elastic_align_pair_penalized, elastic_align_pair_with_landmarks, elastic_cross_distance_matrix,
145    elastic_cross_distance_matrix_banded, elastic_cross_distance_matrix_with_band,
146    elastic_decomposition, elastic_depth, elastic_distance, elastic_distance_closed,
147    elastic_distance_nd, elastic_outlier_detection, elastic_partial_match,
148    elastic_self_distance_matrix, elastic_self_distance_matrix_banded,
149    elastic_self_distance_matrix_with_band, gauss_model, hierarchical_from_distances, horiz_fpns,
150    invert_warp, joint_gauss_model, karcher_covariance_nd, karcher_mean, karcher_mean_banded,
151    karcher_mean_closed, karcher_mean_nd, karcher_mean_with_band, karcher_median,
152    kmedoids_from_distances, lambda_cv, orbit_representative, pairwise_consistency, pca_nd,
153    peak_persistence, phase_boxplot, phase_distance_pair, phase_self_distance_matrix,
154    reparameterize_curve, robust_karcher_mean, shape_confidence_interval, shape_distance,
155    shape_mean, shape_self_distance_matrix, srsf_inverse, srsf_inverse_nd, srsf_transform,
156    srsf_transform_nd, transfer_alignment, tsrvf_from_alignment, tsrvf_from_alignment_with_method,
157    tsrvf_inverse, tsrvf_transform, tsrvf_transform_with_method, warp_complexity,
158    warp_inverse_error, warp_smoothness, warp_statistics, AlignmentDiagnostic,
159    AlignmentDiagnosticSummary, AlignmentQuality, AlignmentResult, AlignmentResultNd,
160    AlignmentSetResult, BayesianAlignConfig, BayesianAlignmentResult, ClosedAlignmentResult,
161    ClosedKarcherMeanResult, ConstrainedAlignmentResult, DecompositionResult, Dendrogram,
162    DiagnosticConfig, ElasticDepthResult, ElasticOutlierConfig, ElasticOutlierResult, FpnsResult,
163    GenerativeModelResult, GeodesicPath, GeodesicPathNd, KMedoidsConfig, KMedoidsResult,
164    KarcherMeanResult, KarcherMeanResultNd, LambdaCvConfig, LambdaCvResult, Linkage,
165    MultiresConfig, OrbitRepresentative, PartialMatchConfig, PartialMatchResult, PcaNdResult,
166    PersistenceDiagramResult, PhaseBoxplot, RobustKarcherConfig, RobustKarcherResult,
167    ShapeCiConfig, ShapeCiResult, ShapeDistanceResult, ShapeMeanResult, ShapeQuotient,
168    TransferAlignConfig, TransferAlignResult, TransportMethod, TsrvfResult, WarpPenaltyType,
169    WarpStatistics,
170};
171
172// Re-export commonly used items
173pub use helpers::{
174    aic, bandwidth_candidates_from_dists, bic, cumulative_trapz, extract_curves, fdata_interpolate,
175    fdata_interpolate_with_policy, gaussian_kernel, gradient, gradient_nonuniform,
176    gradient_uniform, impute_missing_values, l2_distance, linear_interp, quantile_sorted,
177    r_squared, r_squared_adj, simpsons_weights, simpsons_weights_2d, spline_interpolate,
178    spline_interpolate_with_policy, trapz, ExtrapolationPolicy, ImputationMethod,
179    InterpolationMethod, DEFAULT_CONVERGENCE_TOL, NUMERICAL_EPS,
180};
181
182// Re-export warping utilities
183pub use warping::{
184    exp_map_sphere, gam_to_psi, gam_to_psi_smooth, inner_product_l2, inv_exp_map_sphere,
185    invert_gamma, l2_norm_l2, normalize_warp, phase_distance, psi_to_gam,
186};
187
188// Re-export seasonal analysis types
189pub use seasonal::{
190    autoperiod, autoperiod_fdata, cfd_autoperiod, cfd_autoperiod_fdata, hilbert_transform, sazed,
191    sazed_fdata, AutoperiodCandidate, AutoperiodResult, CfdAutoperiodResult, ChangeDetectionResult,
192    ChangePoint, ChangeType, DetectedPeriod, InstantaneousPeriod, Peak, PeakDetectionResult,
193    PeriodEstimate, SazedComponents, SazedResult, StrengthMethod,
194};
195
196// Re-export landmark registration types
197pub use landmark::{
198    detect_and_register, detect_landmarks, landmark_register, Landmark, LandmarkKind,
199    LandmarkResult,
200};
201
202// Re-export detrending types
203pub use detrend::{DecomposeResult, StlConfig, StlResult, TrendResult};
204
205// Re-export simulation types
206pub use simulation::{EFunType, EValType};
207
208// Re-export irregular fdata types
209pub use irreg_fdata::{IrregFdata, KernelType};
210
211// Re-export tolerance band types
212pub use tolerance::{
213    conformal_prediction_band, elastic_tolerance_band, elastic_tolerance_band_with_config,
214    equivalence_test, equivalence_test_one_sample, exponential_family_tolerance_band,
215    fpca_tolerance_band, phase_tolerance_band, scb_mean_degras, BandType,
216    ElasticToleranceBandResult, ElasticToleranceConfig, EquivalenceBootstrap,
217    EquivalenceTestResult, ExponentialFamily, MultiplierDistribution, NonConformityScore,
218    PhaseToleranceBand, ToleranceBand,
219};
220
221// Re-export FAMM types
222pub use famm::{fmm, fmm_predict, fmm_test_fixed, FmmResult, FmmTestResult};
223
224// Re-export function-on-function regression types
225pub use fof_regression::{fof_cv, fof_regression, predict_fof, FofCvResult, FofResult};
226
227// Re-export function-on-scalar regression types
228pub use function_on_scalar::{
229    fanova, fosr, fosr_fpc, predict_fosr, FanovaResult, FosrFpcResult, FosrResult,
230};
231pub use function_on_scalar_2d::{fosr_2d, predict_fosr_2d, FosrResult2d, Grid2d};
232
233// Re-export scalar-on-function regression types
234pub use scalar_on_function::{
235    bootstrap_ci_fregre_lm, bootstrap_ci_functional_logistic, fregre_basis_cv, fregre_cv,
236    fregre_huber, fregre_l1, fregre_lm, fregre_lm_multi, fregre_lm_multi_cv, fregre_np_cv,
237    fregre_np_from_distances, fregre_np_mixed, fregre_pls, functional_logistic,
238    model_selection_ncomp, predict_fregre_lm, predict_fregre_lm_multi, predict_fregre_np,
239    predict_fregre_np_from_distances, predict_fregre_pls, predict_fregre_robust,
240    predict_functional_logistic, BootstrapCiResult, FregreBasisCvResult, FregreCvResult,
241    FregreLmResult, FregreNpCvResult, FregreNpResult, FregreRobustResult, FunctionalLogisticResult,
242    ModelSelectionResult, MultiCvResult, MultiFregreLmResult, PlsRegressionResult,
243    SelectionCriterion,
244};
245
246// Re-export generic explainability types
247pub use explain_generic::{
248    generic_ale, generic_anchor, generic_conditional_permutation_importance,
249    generic_counterfactual, generic_domain_selection, generic_friedman_h, generic_lime,
250    generic_pdp, generic_permutation_importance, generic_prototype_criticism, generic_saliency,
251    generic_shap_values, generic_sobol_indices, generic_stability, generic_vif, FpcPredictor,
252    TaskType,
253};
254
255// Re-export explainability types
256pub use elastic_explain::{elastic_pcr_attribution, ElasticAttributionResult};
257pub use explain::{
258    anchor_explanation, anchor_explanation_logistic, beta_decomposition,
259    beta_decomposition_logistic, calibration_diagnostics, conditional_permutation_importance,
260    conditional_permutation_importance_logistic, conformal_prediction_residuals,
261    counterfactual_logistic, counterfactual_regression, dfbetas_dffits, domain_selection,
262    domain_selection_logistic, expected_calibration_error, explanation_stability,
263    explanation_stability_logistic, fpc_ale, fpc_ale_logistic, fpc_permutation_importance,
264    fpc_permutation_importance_logistic, fpc_shap_values, fpc_shap_values_logistic, fpc_vif,
265    fpc_vif_logistic, friedman_h_statistic, friedman_h_statistic_logistic, functional_pdp,
266    functional_pdp_logistic, functional_saliency, functional_saliency_logistic,
267    influence_diagnostics, lime_explanation, lime_explanation_logistic, loo_cv_press,
268    pointwise_importance, pointwise_importance_logistic, prediction_intervals, prototype_criticism,
269    regression_depth, regression_depth_logistic, significant_regions, significant_regions_from_se,
270    sobol_indices, sobol_indices_logistic, AleResult, AnchorCondition, AnchorResult, AnchorRule,
271    BetaDecomposition, CalibrationDiagnosticsResult, ConditionalPermutationImportanceResult,
272    ConformalPredictionResult, CounterfactualResult, DepthType, DfbetasDffitsResult,
273    DomainSelectionResult, EceResult, FpcPermutationImportance, FpcShapValues, FriedmanHResult,
274    FunctionalPdpResult, FunctionalSaliencyResult, ImportantInterval, InfluenceDiagnostics,
275    LimeResult, LooCvResult, PointwiseImportanceResult, PredictionIntervalResult,
276    PrototypeCriticismResult, RegressionDepthResult, SignificanceDirection, SignificantRegion,
277    SobolIndicesResult, StabilityAnalysisResult, VifResult,
278};
279
280// Re-export classification types
281pub use classification::{
282    fclassif_cv, fclassif_cv_with_config, fclassif_dd, fclassif_kernel, fclassif_knn,
283    fclassif_knn_fit, fclassif_lda, fclassif_lda_fit, fclassif_qda, fclassif_qda_fit,
284    kernel_classify_from_distances, knn_classify_from_distances, ClassifCvConfig, ClassifCvResult,
285    ClassifFit, ClassifMethod, ClassifResult,
286};
287
288// Re-export conformal prediction types
289pub use conformal::{
290    conformal_classif, conformal_elastic_logistic, conformal_elastic_pcr,
291    conformal_elastic_pcr_with_config, conformal_elastic_regression,
292    conformal_elastic_regression_with_config, conformal_fregre_lm, conformal_fregre_np,
293    conformal_generic_classification, conformal_generic_regression, conformal_logistic,
294    cv_conformal_classification, cv_conformal_regression, jackknife_plus_regression,
295    ClassificationScore, ConformalClassificationResult, ConformalConfig, ConformalMethod,
296    ConformalRegressionResult,
297};
298
299// Re-export GMM clustering types
300pub use gmm::{
301    gmm_cluster, gmm_cluster_with_config, gmm_em, predict_gmm, CovType, GmmClusterConfig,
302    GmmClusterResult, GmmResult,
303};
304
305// Re-export streaming depth types
306pub use streaming_depth::{
307    FullReferenceState, RollingReference, SortedReferenceState, StreamingBd, StreamingDepth,
308    StreamingFraimanMuniz, StreamingMbd,
309};
310
311// Re-export smooth basis types
312pub use smooth_basis::{
313    basis_nbasis_cv, basis_nbasis_cv_with_config, bspline_penalty_matrix, fourier_penalty_matrix,
314    smooth_basis, smooth_basis_gcv, smooth_basis_gcv_with_config, BasisCriterion,
315    BasisNbasisCvConfig, BasisNbasisCvResult, BasisType, FdPar, SmoothBasisGcvConfig,
316    SmoothBasisResult,
317};
318
319// Re-export elastic FPCA types
320pub use elastic_fpca::{
321    horiz_fpca, horiz_fpca_from_alignment, joint_fpca, joint_fpca_from_alignment, vert_fpca,
322    vert_fpca_from_alignment, HorizFpcaResult, JointFpcaResult, VertFpcaResult,
323};
324
325// Re-export elastic regression types
326pub use elastic_regression::{
327    elastic_logistic, elastic_logistic_with_config, elastic_pcr, elastic_pcr_with_config,
328    elastic_regression, elastic_regression_with_config, predict_elastic_logistic,
329    predict_elastic_regression, predict_scalar_on_shape, scalar_on_shape, ElasticConfig,
330    ElasticLogisticResult, ElasticPcrConfig, ElasticPcrResult, ElasticRegressionResult,
331    IndexMethod, PcaMethod, ScalarOnShapeConfig, ScalarOnShapeResult,
332};
333
334// Re-export SPM types
335pub use spm::{
336    arl0_ewma_t2, arl0_spe, arl0_t2, arl1_t2, elastic_spm_monitor, elastic_spm_phase1,
337    evaluate_rules, ewma_scores, frcc_monitor, frcc_phase1, hotelling_t2, hotelling_t2_regularized,
338    mf_spm_monitor, mf_spm_phase1, mfpca, nelson_rules, profile_monitor, profile_phase1,
339    select_ncomp, spe_contributions, spe_control_limit, spe_limit_robust,
340    spe_moment_match_diagnostic, spe_multivariate, spe_univariate, spm_amewma_monitor,
341    spm_cusum_monitor, spm_cusum_monitor_with_restart, spm_ewma_monitor, spm_mewma_monitor,
342    spm_monitor, spm_monitor_from_fields, spm_monitor_partial, spm_monitor_partial_batch,
343    spm_phase1, spm_phase1_iterative, t2_contributions, t2_contributions_mfpca, t2_control_limit,
344    t2_limit_robust, t2_pc_contributions, t2_pc_significance, western_electric_rules, AmewmaConfig,
345    AmewmaMonitorResult, ArlConfig, ArlResult, ChartRule, ControlLimit, ControlLimitMethod,
346    CusumConfig, CusumMonitorResult, DomainCompletion, ElasticSpmChart, ElasticSpmConfig,
347    ElasticSpmMonitorResult, EwmaConfig, EwmaMonitorResult, FrccChart, FrccConfig,
348    FrccMonitorResult, IterativePhase1Config, IterativePhase1Result, MewmaConfig,
349    MewmaMonitorResult, MfSpmChart, MfpcaConfig, MfpcaResult, NcompMethod, PartialDomainConfig,
350    PartialMonitorResult, ProfileChart, ProfileMonitorConfig, ProfileMonitorResult, RuleViolation,
351    SpmChart, SpmConfig, SpmMonitorResult,
352};
353
354// Re-export elastic changepoint types
355pub use elastic_changepoint::{
356    elastic_amp_changepoint, elastic_fpca_changepoint, elastic_ph_changepoint, ChangepointResult,
357    ChangepointType, FpcaChangepointMethod,
358};
359
360// Re-export cross-validation utilities
361pub use cv::{
362    classification_metrics, create_folds, create_stratified_folds, cv_fdata, cv_fdata_with_metrics,
363    fold_indices, metric_accuracy, metric_f1, metric_mae, metric_precision, metric_r_squared,
364    metric_recall, metric_rmse, regression_metrics, subset_rows, subset_vec, CvFdataResult,
365    CvMetrics, CvSelectionResult, CvType, MetricFn,
366};
367
368// Re-export distance utilities
369pub use distance::{
370    cross_distance_matrix, euclidean_distance_matrix, l2_distance_matrix, pairwise_distance_matrix,
371};
372
373// Re-export validation utilities
374pub use validation::{
375    validate_dist_mat, validate_fdata, validate_labels, validate_ncomp, validate_response,
376};
377
378// Re-export smoothing CV types
379pub use smoothing::{
380    cv_smoother, gcv_smoother, knn_gcv, knn_lcv, optim_bandwidth, CvCriterion, KnnCvResult,
381    OptimBandwidthResult,
382};
383
384// Re-export regression types
385pub use regression::{fdata_to_pc_1d, fdata_to_pls_1d, FpcaResult, PlsResult};
386#[cfg(feature = "linalg")]
387pub use regression::{ridge_regression_fit, RidgeResult};
388
389// Re-export clustering types
390pub use clustering::{
391    calinski_harabasz, calinski_harabasz_from_distances, fuzzy_cmeans_fd, kmeans_fd,
392    silhouette_score, silhouette_score_from_distances, FuzzyCmeansResult, KmeansResult,
393};
394
395// Re-export distance metric types and functions
396pub use metric::{
397    dtw_cross_1d, dtw_distance, dtw_self_1d, fourier_cross_1d, fourier_self_1d, hausdorff_3d,
398    hausdorff_cross_1d, hausdorff_cross_2d, hausdorff_self_1d, hausdorff_self_2d, hshift_cross_1d,
399    hshift_self_1d, lp_cross_1d, lp_cross_2d, lp_self_1d, lp_self_2d, soft_dtw_barycenter,
400    soft_dtw_cross_1d, soft_dtw_distance, soft_dtw_div_cross_1d, soft_dtw_div_self_1d,
401    soft_dtw_divergence, soft_dtw_self_1d, SoftDtwBarycenterResult,
402};
403
404// Re-export depth measure functions
405pub use depth::{
406    band_1d, fraiman_muniz_1d, fraiman_muniz_2d, functional_spatial_1d, functional_spatial_2d,
407    kernel_functional_spatial_1d, kernel_functional_spatial_2d, modal_1d, modal_2d,
408    modified_band_1d, modified_epigraph_index_1d, random_projection_1d,
409    random_projection_1d_seeded, random_projection_2d, random_tukey_1d, random_tukey_1d_seeded,
410    random_tukey_2d,
411};
412
413// Re-export outlier detection functions
414pub use outliers::{
415    detect_outliers_lrt, magnitude_shape_outlyingness, outliergram, outliers_threshold_lrt,
416    outliers_threshold_lrt_with_dist, MagnitudeShapeResult, OutligramResult,
417};
418
419// Re-export utility functions
420pub use utility::{
421    compute_adot, inner_product, inner_product_matrix, integrate_simpson, knn_loocv, knn_predict,
422    pcvm_statistic, rp_stat, RpStatResult,
423};
424
425// Re-export functional data operation types and functions
426pub use fdata::{
427    center_1d, depth_based_median, deriv_1d, deriv_2d, functional_covariance, functional_std,
428    functional_variance, geometric_median_1d, geometric_median_2d, mean_1d, mean_2d, norm_lp_1d,
429    normalize, normalize_with_argvals, trim_mean, Deriv2DResult, NormalizationMethod,
430};
431
432// Re-export basis representation types and functions
433pub use basis::{
434    basis_to_fdata, basis_to_fdata_1d, bspline_basis, bspline_basis_from_knots,
435    construct_bspline_knots, difference_matrix, fdata_to_basis, fdata_to_basis_1d, fourier_basis,
436    fourier_basis_with_period, fourier_fit_1d, pspline_evaluate, pspline_fit_1d, pspline_fit_gcv,
437    select_basis_auto_1d, select_fourier_nbasis_gcv, BasisAutoSelectionResult,
438    BasisProjectionResult, FourierFitResult, ProjectionBasisType, PsplineFitResult,
439    SingleCurveSelection,
440};
441
442// Re-export functional scoring metrics
443pub use scoring::{
444    functional_explained_variance, functional_mae, functional_mape, functional_mse, functional_msle,
445};
fdars_core/lib.rs

fdars_core/
lib.rs
