Crate bids_core 

Core types and abstractions for working with BIDS datasets.

This crate provides the foundational building blocks used by all other bids-* crates:

• Entity and EntityValue — BIDS entity definitions (subject, session, task, run, …) with regex-based extraction from file paths and typed value coercion.
• BidsFile — Representation of a single file in a BIDS dataset, with automatic file type detection, entity extraction, suffix/extension parsing, and companion file lookup.
• BidsMetadata — Ordered key-value metadata dictionary backed by IndexMap, supporting typed access (get_f64, get_str, get_array, …) and deserialization into arbitrary structs.
• DatasetDescription — Typed representation of dataset_description.json with validation, derivative detection, and legacy field migration.
• Config — Layout configuration defining entity patterns and path templates, loadable from built-in configs (bids, derivatives) or custom JSON files.
• PaddedInt — Zero-padded integer type that preserves formatting (e.g., "02") while comparing numerically.
• BidsError — Comprehensive error enum covering I/O, JSON, validation, entity, filter, database, and path-building errors.

BIDS Entities

BIDS filenames encode metadata as key-value pairs separated by underscores:

sub-01_ses-02_task-rest_run-01_bold.nii.gz
^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^^^ ^^^^
subject session  task     run   suffix

The entities module defines the canonical entity ordering and provides functions to parse entities from paths, sort them, and coerce values to the correct types (string, padded integer, float, boolean).

Example

use bids_core::{BidsFile, Config, DatasetDescription};

// Parse entities from a filename
let config = Config::bids();
let entities = bids_core::entities::parse_file_entities(
    "sub-01/eeg/sub-01_task-rest_eeg.edf",
    &config.entities,
);
assert_eq!(entities.get("subject").unwrap().as_str_lossy(), "01");
assert_eq!(entities.get("task").unwrap().as_str_lossy(), "rest");

Re-exports

pub use config::Config;

pub use dataset_description::DatasetDescription;

pub use entities::Entities;

pub use entities::Entity;

pub use entities::EntityValue;

pub use entities::StringEntities;

pub use error::BidsError;

pub use error::Result;

pub use file::BidsFile;

pub use file::CopyMode;

pub use file::FileType;

pub use metadata::BidsMetadata;

pub use padded_int::PaddedInt;

pub use utils::collect_associated_files;

pub use utils::convert_json_keys;

pub use utils::matches_entities;

Modules

config

Layout configuration: entity patterns and path templates.

dataset_description

Typed representation of dataset_description.json.

entities

BIDS entity definitions, parsing, and canonical ordering.

error

Error types for the BIDS crate ecosystem.

file

BIDS file representation with type detection, entity access, and companion lookup.

genetic

Genetic descriptor files (genetic_info.json, genetic_database.json).

hed

HED (Hierarchical Event Descriptors) tag parsing.

metadata

Metadata dictionary for BIDS files.

padded_int

Zero-padded integer type that preserves original formatting.

timeseries

Common trait for multichannel time-series data across modalities.

utils

Utility functions: entity matching, file grouping, and case conversion.

Macros

entities

Convenience macro for building an Entities map inline.

Functions

try_read_companion

Helper for modality crates: try to read from a companion file path.