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

fdars_core/
lib.rs
