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

fdars_core/
lib.rs
