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

fdars_core/
lib.rs
