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 function_on_scalar;
88pub mod function_on_scalar_2d;
89pub mod gmm;
90pub mod helpers;
91pub mod irreg_fdata;
92pub mod landmark;
93pub mod metric;
94pub mod outliers;
95pub mod regression;
96pub mod scalar_on_function;
97pub mod seasonal;
98pub mod simulation;
99pub mod smoothing;
100pub mod streaming_depth;
101pub mod tolerance;
102pub mod utility;
103pub mod validation;
104pub mod warping;
105pub mod wire;
106
107// Covariance kernels and Gaussian processes
108pub mod covariance;
109
110// Statistical Process Monitoring
111pub mod spm;
112
113// Elastic analysis modules
114pub mod conformal;
115pub mod elastic;
116pub mod elastic_changepoint;
117pub mod elastic_explain;
118pub mod elastic_fpca;
119pub mod elastic_regression;
120pub mod explain;
121pub mod explain_generic;
122pub mod prelude;
123pub mod smooth_basis;
124
125// Re-export matrix types
126pub use matrix::{FdCurveSet, FdMatrix};
127
128// Re-export Andrews curves types
129pub use andrews::{andrews_loadings, andrews_transform, AndrewsLoadings, AndrewsResult};
130
131// Re-export covariance kernel types
132pub use covariance::{
133    covariance_matrix, generate_gaussian_process, CovKernel, GaussianProcessResult,
134};
135
136// Re-export alignment types and functions
137pub use alignment::{
138    align_to_target, alignment_quality, amplitude_distance, amplitude_self_distance_matrix,
139    bayesian_align_pair, compose_warps, curve_geodesic, curve_geodesic_nd, cut_dendrogram,
140    diagnose_alignment, diagnose_pairwise, elastic_align_pair, elastic_align_pair_closed,
141    elastic_align_pair_constrained, elastic_align_pair_multires, elastic_align_pair_nd,
142    elastic_align_pair_penalized, elastic_align_pair_with_landmarks, elastic_cross_distance_matrix,
143    elastic_decomposition, elastic_depth, elastic_distance, elastic_distance_closed,
144    elastic_distance_nd, elastic_outlier_detection, elastic_partial_match,
145    elastic_self_distance_matrix, gauss_model, hierarchical_from_distances, horiz_fpns,
146    invert_warp, joint_gauss_model, karcher_covariance_nd, karcher_mean, karcher_mean_closed,
147    karcher_mean_nd, karcher_median, kmedoids_from_distances, lambda_cv, orbit_representative,
148    pairwise_consistency, pca_nd, peak_persistence, phase_boxplot, phase_distance_pair,
149    phase_self_distance_matrix, reparameterize_curve, robust_karcher_mean,
150    shape_confidence_interval, shape_distance, shape_mean, shape_self_distance_matrix,
151    srsf_inverse, srsf_inverse_nd, srsf_transform, srsf_transform_nd, transfer_alignment,
152    tsrvf_from_alignment, tsrvf_from_alignment_with_method, tsrvf_inverse, tsrvf_transform,
153    tsrvf_transform_with_method, warp_complexity, warp_inverse_error, warp_smoothness,
154    warp_statistics, AlignmentDiagnostic, AlignmentDiagnosticSummary, AlignmentQuality,
155    AlignmentResult, AlignmentResultNd, AlignmentSetResult, BayesianAlignConfig,
156    BayesianAlignmentResult, ClosedAlignmentResult, ClosedKarcherMeanResult,
157    ConstrainedAlignmentResult, DecompositionResult, Dendrogram, DiagnosticConfig,
158    ElasticDepthResult, ElasticOutlierConfig, ElasticOutlierResult, FpnsResult,
159    GenerativeModelResult, GeodesicPath, GeodesicPathNd, KMedoidsConfig, KMedoidsResult,
160    KarcherMeanResult, KarcherMeanResultNd, LambdaCvConfig, LambdaCvResult, Linkage,
161    MultiresConfig, OrbitRepresentative, PartialMatchConfig, PartialMatchResult, PcaNdResult,
162    PersistenceDiagramResult, PhaseBoxplot, RobustKarcherConfig, RobustKarcherResult,
163    ShapeCiConfig, ShapeCiResult, ShapeDistanceResult, ShapeMeanResult, ShapeQuotient,
164    TransferAlignConfig, TransferAlignResult, TransportMethod, TsrvfResult, WarpPenaltyType,
165    WarpStatistics,
166};
167
168// Re-export commonly used items
169pub use helpers::{
170    aic, bandwidth_candidates_from_dists, bic, cumulative_trapz, extract_curves, fdata_interpolate,
171    gaussian_kernel, gradient, gradient_nonuniform, gradient_uniform, l2_distance, linear_interp,
172    quantile_sorted, r_squared, r_squared_adj, simpsons_weights, simpsons_weights_2d, trapz,
173    InterpolationMethod, DEFAULT_CONVERGENCE_TOL, NUMERICAL_EPS,
174};
175
176// Re-export warping utilities
177pub use warping::{
178    exp_map_sphere, gam_to_psi, gam_to_psi_smooth, inner_product_l2, inv_exp_map_sphere,
179    invert_gamma, l2_norm_l2, normalize_warp, phase_distance, psi_to_gam,
180};
181
182// Re-export seasonal analysis types
183pub use seasonal::{
184    autoperiod, autoperiod_fdata, cfd_autoperiod, cfd_autoperiod_fdata, hilbert_transform, sazed,
185    sazed_fdata, AutoperiodCandidate, AutoperiodResult, CfdAutoperiodResult, ChangeDetectionResult,
186    ChangePoint, ChangeType, DetectedPeriod, InstantaneousPeriod, Peak, PeakDetectionResult,
187    PeriodEstimate, SazedComponents, SazedResult, StrengthMethod,
188};
189
190// Re-export landmark registration types
191pub use landmark::{
192    detect_and_register, detect_landmarks, landmark_register, Landmark, LandmarkKind,
193    LandmarkResult,
194};
195
196// Re-export detrending types
197pub use detrend::{DecomposeResult, StlConfig, StlResult, TrendResult};
198
199// Re-export simulation types
200pub use simulation::{EFunType, EValType};
201
202// Re-export irregular fdata types
203pub use irreg_fdata::{IrregFdata, KernelType};
204
205// Re-export tolerance band types
206pub use tolerance::{
207    conformal_prediction_band, elastic_tolerance_band, elastic_tolerance_band_with_config,
208    equivalence_test, equivalence_test_one_sample, exponential_family_tolerance_band,
209    fpca_tolerance_band, phase_tolerance_band, scb_mean_degras, BandType,
210    ElasticToleranceBandResult, ElasticToleranceConfig, EquivalenceBootstrap,
211    EquivalenceTestResult, ExponentialFamily, MultiplierDistribution, NonConformityScore,
212    PhaseToleranceBand, ToleranceBand,
213};
214
215// Re-export FAMM types
216pub use famm::{fmm, fmm_predict, fmm_test_fixed, FmmResult, FmmTestResult};
217
218// Re-export function-on-scalar regression types
219pub use function_on_scalar::{
220    fanova, fosr, fosr_fpc, predict_fosr, FanovaResult, FosrFpcResult, FosrResult,
221};
222pub use function_on_scalar_2d::{fosr_2d, predict_fosr_2d, FosrResult2d, Grid2d};
223
224// Re-export scalar-on-function regression types
225pub use scalar_on_function::{
226    bootstrap_ci_fregre_lm, bootstrap_ci_functional_logistic, fregre_basis_cv, fregre_cv,
227    fregre_huber, fregre_l1, fregre_lm, fregre_np_cv, fregre_np_from_distances, fregre_np_mixed,
228    fregre_pls, functional_logistic, model_selection_ncomp, predict_fregre_lm, predict_fregre_np,
229    predict_fregre_np_from_distances, predict_fregre_pls, predict_fregre_robust,
230    predict_functional_logistic, BootstrapCiResult, FregreBasisCvResult, FregreCvResult,
231    FregreLmResult, FregreNpCvResult, FregreNpResult, FregreRobustResult, FunctionalLogisticResult,
232    ModelSelectionResult, PlsRegressionResult, SelectionCriterion,
233};
234
235// Re-export generic explainability types
236pub use explain_generic::{
237    generic_ale, generic_anchor, generic_conditional_permutation_importance,
238    generic_counterfactual, generic_domain_selection, generic_friedman_h, generic_lime,
239    generic_pdp, generic_permutation_importance, generic_prototype_criticism, generic_saliency,
240    generic_shap_values, generic_sobol_indices, generic_stability, generic_vif, FpcPredictor,
241    TaskType,
242};
243
244// Re-export explainability types
245pub use elastic_explain::{elastic_pcr_attribution, ElasticAttributionResult};
246pub use explain::{
247    anchor_explanation, anchor_explanation_logistic, beta_decomposition,
248    beta_decomposition_logistic, calibration_diagnostics, conditional_permutation_importance,
249    conditional_permutation_importance_logistic, conformal_prediction_residuals,
250    counterfactual_logistic, counterfactual_regression, dfbetas_dffits, domain_selection,
251    domain_selection_logistic, expected_calibration_error, explanation_stability,
252    explanation_stability_logistic, fpc_ale, fpc_ale_logistic, fpc_permutation_importance,
253    fpc_permutation_importance_logistic, fpc_shap_values, fpc_shap_values_logistic, fpc_vif,
254    fpc_vif_logistic, friedman_h_statistic, friedman_h_statistic_logistic, functional_pdp,
255    functional_pdp_logistic, functional_saliency, functional_saliency_logistic,
256    influence_diagnostics, lime_explanation, lime_explanation_logistic, loo_cv_press,
257    pointwise_importance, pointwise_importance_logistic, prediction_intervals, prototype_criticism,
258    regression_depth, regression_depth_logistic, significant_regions, significant_regions_from_se,
259    sobol_indices, sobol_indices_logistic, AleResult, AnchorCondition, AnchorResult, AnchorRule,
260    BetaDecomposition, CalibrationDiagnosticsResult, ConditionalPermutationImportanceResult,
261    ConformalPredictionResult, CounterfactualResult, DepthType, DfbetasDffitsResult,
262    DomainSelectionResult, EceResult, FpcPermutationImportance, FpcShapValues, FriedmanHResult,
263    FunctionalPdpResult, FunctionalSaliencyResult, ImportantInterval, InfluenceDiagnostics,
264    LimeResult, LooCvResult, PointwiseImportanceResult, PredictionIntervalResult,
265    PrototypeCriticismResult, RegressionDepthResult, SignificanceDirection, SignificantRegion,
266    SobolIndicesResult, StabilityAnalysisResult, VifResult,
267};
268
269// Re-export classification types
270pub use classification::{
271    fclassif_cv, fclassif_cv_with_config, fclassif_dd, fclassif_kernel, fclassif_knn,
272    fclassif_knn_fit, fclassif_lda, fclassif_lda_fit, fclassif_qda, fclassif_qda_fit,
273    kernel_classify_from_distances, knn_classify_from_distances, ClassifCvConfig, ClassifCvResult,
274    ClassifFit, ClassifMethod, ClassifResult,
275};
276
277// Re-export conformal prediction types
278pub use conformal::{
279    conformal_classif, conformal_elastic_logistic, conformal_elastic_pcr,
280    conformal_elastic_pcr_with_config, conformal_elastic_regression,
281    conformal_elastic_regression_with_config, conformal_fregre_lm, conformal_fregre_np,
282    conformal_generic_classification, conformal_generic_regression, conformal_logistic,
283    cv_conformal_classification, cv_conformal_regression, jackknife_plus_regression,
284    ClassificationScore, ConformalClassificationResult, ConformalConfig, ConformalMethod,
285    ConformalRegressionResult,
286};
287
288// Re-export GMM clustering types
289pub use gmm::{
290    gmm_cluster, gmm_cluster_with_config, gmm_em, predict_gmm, CovType, GmmClusterConfig,
291    GmmClusterResult, GmmResult,
292};
293
294// Re-export streaming depth types
295pub use streaming_depth::{
296    FullReferenceState, RollingReference, SortedReferenceState, StreamingBd, StreamingDepth,
297    StreamingFraimanMuniz, StreamingMbd,
298};
299
300// Re-export smooth basis types
301pub use smooth_basis::{
302    basis_nbasis_cv, basis_nbasis_cv_with_config, bspline_penalty_matrix, fourier_penalty_matrix,
303    smooth_basis, smooth_basis_gcv, smooth_basis_gcv_with_config, BasisCriterion,
304    BasisNbasisCvConfig, BasisNbasisCvResult, BasisType, FdPar, SmoothBasisGcvConfig,
305    SmoothBasisResult,
306};
307
308// Re-export elastic FPCA types
309pub use elastic_fpca::{
310    horiz_fpca, horiz_fpca_from_alignment, joint_fpca, joint_fpca_from_alignment, vert_fpca,
311    vert_fpca_from_alignment, HorizFpcaResult, JointFpcaResult, VertFpcaResult,
312};
313
314// Re-export elastic regression types
315pub use elastic_regression::{
316    elastic_logistic, elastic_logistic_with_config, elastic_pcr, elastic_pcr_with_config,
317    elastic_regression, elastic_regression_with_config, predict_elastic_logistic,
318    predict_elastic_regression, predict_scalar_on_shape, scalar_on_shape, ElasticConfig,
319    ElasticLogisticResult, ElasticPcrConfig, ElasticPcrResult, ElasticRegressionResult,
320    IndexMethod, PcaMethod, ScalarOnShapeConfig, ScalarOnShapeResult,
321};
322
323// Re-export SPM types
324pub use spm::{
325    arl0_ewma_t2, arl0_spe, arl0_t2, arl1_t2, elastic_spm_monitor, elastic_spm_phase1,
326    evaluate_rules, ewma_scores, frcc_monitor, frcc_phase1, hotelling_t2, hotelling_t2_regularized,
327    mf_spm_monitor, mf_spm_phase1, mfpca, nelson_rules, profile_monitor, profile_phase1,
328    select_ncomp, spe_contributions, spe_control_limit, spe_limit_robust,
329    spe_moment_match_diagnostic, spe_multivariate, spe_univariate, spm_amewma_monitor,
330    spm_cusum_monitor, spm_cusum_monitor_with_restart, spm_ewma_monitor, spm_mewma_monitor,
331    spm_monitor, spm_monitor_from_fields, spm_monitor_partial, spm_monitor_partial_batch,
332    spm_phase1, spm_phase1_iterative, t2_contributions, t2_contributions_mfpca, t2_control_limit,
333    t2_limit_robust, t2_pc_contributions, t2_pc_significance, western_electric_rules, AmewmaConfig,
334    AmewmaMonitorResult, ArlConfig, ArlResult, ChartRule, ControlLimit, ControlLimitMethod,
335    CusumConfig, CusumMonitorResult, DomainCompletion, ElasticSpmChart, ElasticSpmConfig,
336    ElasticSpmMonitorResult, EwmaConfig, EwmaMonitorResult, FrccChart, FrccConfig,
337    FrccMonitorResult, IterativePhase1Config, IterativePhase1Result, MewmaConfig,
338    MewmaMonitorResult, MfSpmChart, MfpcaConfig, MfpcaResult, NcompMethod, PartialDomainConfig,
339    PartialMonitorResult, ProfileChart, ProfileMonitorConfig, ProfileMonitorResult, RuleViolation,
340    SpmChart, SpmConfig, SpmMonitorResult,
341};
342
343// Re-export elastic changepoint types
344pub use elastic_changepoint::{
345    elastic_amp_changepoint, elastic_fpca_changepoint, elastic_ph_changepoint, ChangepointResult,
346    ChangepointType, FpcaChangepointMethod,
347};
348
349// Re-export cross-validation utilities
350pub use cv::{
351    classification_metrics, create_folds, create_stratified_folds, cv_fdata, cv_fdata_with_metrics,
352    fold_indices, metric_accuracy, metric_f1, metric_mae, metric_precision, metric_r_squared,
353    metric_recall, metric_rmse, regression_metrics, subset_rows, subset_vec, CvFdataResult,
354    CvMetrics, CvSelectionResult, CvType, MetricFn,
355};
356
357// Re-export distance utilities
358pub use distance::{
359    cross_distance_matrix, euclidean_distance_matrix, l2_distance_matrix, pairwise_distance_matrix,
360};
361
362// Re-export validation utilities
363pub use validation::{
364    validate_dist_mat, validate_fdata, validate_labels, validate_ncomp, validate_response,
365};
366
367// Re-export smoothing CV types
368pub use smoothing::{
369    cv_smoother, gcv_smoother, knn_gcv, knn_lcv, optim_bandwidth, CvCriterion, KnnCvResult,
370    OptimBandwidthResult,
371};
372
373// Re-export regression types
374pub use regression::{fdata_to_pc_1d, fdata_to_pls_1d, FpcaResult, PlsResult};
375#[cfg(feature = "linalg")]
376pub use regression::{ridge_regression_fit, RidgeResult};
377
378// Re-export clustering types
379pub use clustering::{
380    calinski_harabasz, calinski_harabasz_from_distances, fuzzy_cmeans_fd, kmeans_fd,
381    silhouette_score, silhouette_score_from_distances, FuzzyCmeansResult, KmeansResult,
382};
383
384// Re-export distance metric types and functions
385pub use metric::{
386    dtw_cross_1d, dtw_distance, dtw_self_1d, fourier_cross_1d, fourier_self_1d, hausdorff_3d,
387    hausdorff_cross_1d, hausdorff_cross_2d, hausdorff_self_1d, hausdorff_self_2d, hshift_cross_1d,
388    hshift_self_1d, lp_cross_1d, lp_cross_2d, lp_self_1d, lp_self_2d, soft_dtw_barycenter,
389    soft_dtw_cross_1d, soft_dtw_distance, soft_dtw_div_cross_1d, soft_dtw_div_self_1d,
390    soft_dtw_divergence, soft_dtw_self_1d, SoftDtwBarycenterResult,
391};
392
393// Re-export depth measure functions
394pub use depth::{
395    band_1d, fraiman_muniz_1d, fraiman_muniz_2d, functional_spatial_1d, functional_spatial_2d,
396    kernel_functional_spatial_1d, kernel_functional_spatial_2d, modal_1d, modal_2d,
397    modified_band_1d, modified_epigraph_index_1d, random_projection_1d,
398    random_projection_1d_seeded, random_projection_2d, random_tukey_1d, random_tukey_1d_seeded,
399    random_tukey_2d,
400};
401
402// Re-export outlier detection functions
403pub use outliers::{
404    detect_outliers_lrt, magnitude_shape_outlyingness, outliergram, outliers_threshold_lrt,
405    outliers_threshold_lrt_with_dist, MagnitudeShapeResult, OutligramResult,
406};
407
408// Re-export utility functions
409pub use utility::{
410    compute_adot, inner_product, inner_product_matrix, integrate_simpson, knn_loocv, knn_predict,
411    pcvm_statistic, rp_stat, RpStatResult,
412};
413
414// Re-export functional data operation types and functions
415pub use fdata::{
416    center_1d, deriv_1d, deriv_2d, geometric_median_1d, geometric_median_2d, mean_1d, mean_2d,
417    norm_lp_1d, normalize, normalize_with_argvals, Deriv2DResult, NormalizationMethod,
418};
419
420// Re-export basis representation types and functions
421pub use basis::{
422    basis_to_fdata, basis_to_fdata_1d, bspline_basis, bspline_basis_from_knots,
423    construct_bspline_knots, difference_matrix, fdata_to_basis, fdata_to_basis_1d, fourier_basis,
424    fourier_basis_with_period, fourier_fit_1d, pspline_evaluate, pspline_fit_1d, pspline_fit_gcv,
425    select_basis_auto_1d, select_fourier_nbasis_gcv, BasisAutoSelectionResult,
426    BasisProjectionResult, FourierFitResult, ProjectionBasisType, PsplineFitResult,
427    SingleCurveSelection,
428};
fdars_core/lib.rs

fdars_core/
lib.rs
