bids_modeling/
lib.rs

1#![deny(unsafe_code)]
2//! BIDS Statistical Models implementation.
3//!
4//! This crate implements the [BIDS-StatsModels](https://bids-standard.github.io/stats-models/)
5//! specification for defining reproducible neuroimaging analysis pipelines as
6//! declarative JSON documents. It corresponds to PyBIDS' `bids.modeling` module.
7//!
8//! # Overview
9//!
10//! A BIDS Stats Model defines a directed acyclic graph (DAG) of analysis nodes,
11//! each operating at a specific level of the BIDS hierarchy (run, session,
12//! subject, dataset). Data flows from lower levels to higher levels through
13//! edges, with contrasts propagating upward.
14//!
15//! # Components
16//!
17//! - [`StatsModelsGraph`] — The top-level model graph loaded from a JSON file.
18//!   Validates structure, wires edges between nodes, and executes the full
19//!   analysis pipeline. Can export to Graphviz DOT format.
20//!
21//! - [`StatsModelsNode`] — A single analysis node with a statistical model
22//!   specification, variable transformations, contrasts, and dummy contrasts.
23//!   Nodes group data by entity values and produce [`StatsModelsNodeOutput`]s.
24//!
25//! - [`TransformSpec`] and [`apply_transformations()`] — The `pybids-transforms-v1`
26//!   transformer implementing Rename, Copy, Factor, Scale, Threshold, Select,
27//!   Delete, Replace, Split, Concatenate, Orthogonalize, Lag, and more.
28//!
29//! - [`HrfModel`], [`spm_hrf()`], [`glover_hrf()`] — Hemodynamic response function
30//!   kernels (SPM and Glover canonical forms with optional time and dispersion
31//!   derivatives). Uses a pure-Rust `gammaln` implementation matching SciPy's
32//!   cephes to machine epsilon.
33//!
34//! - [`auto_model()`] — Automatically generates a BIDS Stats Model JSON for
35//!   each task in a dataset, with Factor(trial_type) at the run level and
36//!   pass-through nodes at higher levels.
37//!
38//! - [`GlmSpec`], [`MetaAnalysisSpec`] — Statistical model specifications with
39//!   design matrix construction, VIF computation, and formatted output.
40//!
41//! # Example
42//!
43//! ```no_run
44//! use bids_modeling::StatsModelsGraph;
45//!
46//! let mut graph = StatsModelsGraph::from_file(
47//!     std::path::Path::new("model-default_smdl.json")
48//! ).unwrap();
49//! graph.validate().unwrap();
50//! println!("DOT graph:\n{}", graph.write_graph());
51//!
52//! // Execute the model
53//! let outputs = graph.run();
54//! for output in &outputs {
55//!     println!("Node: {}, Contrasts: {}", output.node_name, output.contrasts.len());
56//! }
57//! ```
58
59pub mod auto_model;
60pub mod graph;
61pub mod hrf;
62pub mod node;
63pub mod spec;
64pub mod transformations;
65
66pub use auto_model::auto_model;
67pub use graph::StatsModelsGraph;
68pub use hrf::{HrfModel, compute_regressor, glover_hrf, spm_hrf};
69pub use node::{
70    ContrastInfo, StatsModelsEdge, StatsModelsNode, StatsModelsNodeOutput, build_groups,
71};
72pub use spec::{
73    GlmSpec, MetaAnalysisSpec, Term, compute_vif, dummies_to_vec, format_correlation_matrix,
74    format_design_matrix,
75};
76pub use transformations::{
77    TransformSpec, TransformerManager, apply_transformations, expand_wildcards,
78};
bids_modeling/lib.rs

bids_modeling/
lib.rs
