bids_variables/lib.rs
1#![deny(unsafe_code)]
2//! BIDS variable system for representing experimental data at multiple levels.
3//!
4//! This crate implements the variable hierarchy used in BIDS statistical modeling,
5//! corresponding to PyBIDS' `bids.variables` module. Variables represent columns
6//! from BIDS tabular files (events, participants, sessions, scans, physio, etc.)
7//! and can exist at different levels of the BIDS hierarchy.
8//!
9//! # Variable Types
10//!
11//! - [`SimpleVariable`] — A variable with string/numeric values and an entity
12//! index. Used for participants.tsv, sessions.tsv, and scans.tsv data.
13//! Supports filtering, cloning with replacement, and tabular export.
14//!
15//! - [`SparseRunVariable`] — An event-based variable with onset, duration, and
16//! amplitude vectors (from `_events.tsv`). Can be converted to dense
17//! representation via [`SparseRunVariable::to_dense()`] using GCD-based
18//! bin sizing and linear interpolation.
19//!
20//! - [`DenseRunVariable`] — A uniformly-sampled time series (from physio, stim,
21//! or regressors files). Supports resampling to different rates and TR-based
22//! downsampling.
23//!
24//! # Node Hierarchy
25//!
26//! Variables are organized into a [`NodeIndex`] that mirrors the BIDS hierarchy:
27//!
28//! - **Dataset level** — Participant-level variables (age, sex, group)
29//! - **Subject level** — Session-level variables
30//! - **Session level** — Scan-level variables (acquisition time, etc.)
31//! - **Run level** — Event and continuous variables for individual runs
32//!
33//! # Loading Variables
34//!
35//! Use [`load_variables()`] to automatically extract all variables from a
36//! `BidsLayout`:
37//!
38//! ```no_run
39//! # use bids_layout::BidsLayout;
40//! # let layout = BidsLayout::new("/path").unwrap();
41//! let index = bids_variables::load_variables(&layout, None, None).unwrap();
42//! let run_collections = index.get_run_collections(
43//! &bids_core::entities::StringEntities::new()
44//! );
45//! ```
46//!
47//! # Collections
48//!
49//! [`VariableCollection`] groups multiple `SimpleVariable`s by name, while
50//! [`RunVariableCollection`] groups sparse and dense run variables. Collections
51//! can be merged across runs using [`merge_collections()`].
52
53pub mod collections;
54pub mod io;
55pub mod node;
56pub mod variables;
57
58pub use collections::{RunVariableCollection, VariableCollection, merge_collections};
59pub use io::load_variables;
60pub use node::{Node, NodeIndex, RunInfo, RunNode};
61pub use variables::{DenseRunVariable, SimpleVariable, SparseRunVariable};