bids_io/lib.rs
1#![deny(unsafe_code)]
2//! File I/O utilities for BIDS datasets.
3//!
4//! This crate handles reading and writing the file formats used in BIDS:
5//!
6//! - **TSV** — Tab-separated value files (`.tsv`, `.tsv.gz`) used for events,
7//! channels, electrodes, participants, sessions, and scans tables. See [`tsv`].
8//! - **JSON sidecars** — Metadata files that accompany data files, following the
9//! BIDS inheritance principle where more-specific sidecars override less-specific
10//! ones. See [`json`].
11//! - **Path building** — Construct BIDS-compliant file paths from entity key-value
12//! pairs using configurable patterns with optional sections (`[/ses-{session}]`),
13//! value constraints (`{suffix<T1w|T2w>}`), and defaults (`{datatype|anat}`).
14//! See [`path_builder`].
15//! - **File writing** — Write data to files with configurable conflict resolution
16//! strategies (fail, skip, overwrite, append) and support for symlinks.
17//! See [`writer`].
18//!
19//! # BIDS Inheritance Principle
20//!
21//! JSON sidecar files apply to all data files in the same directory and below.
22//! When multiple sidecars match a data file, they are merged with the most
23//! specific file (closest to the data) taking precedence:
24//!
25//! ```text
26//! dataset/
27//! task-rest_eeg.json ← least specific (applies to all rest EEG)
28//! sub-01/
29//! sub-01_task-rest_eeg.json ← most specific (applies only to sub-01)
30//! eeg/
31//! sub-01_task-rest_eeg.edf
32//! ```
33
34pub mod gradient;
35pub mod json;
36pub mod path_builder;
37pub mod tsv;
38pub mod writer;
39
40pub use gradient::{GradientTable, read_bvals, read_bvecs};
41pub use json::{find_sidecars, merge_json_sidecars, read_json, read_json_sidecar};
42pub use path_builder::build_path;
43pub use tsv::{TsvRow, read_tsv, read_tsv_gz};
44pub use writer::{ConflictStrategy, write_to_file};