fw-bids-utils

Overview

fw-bids-utils is a Python package that holds helper methods used across the fw-bids suite. This library provides common functionality for working with BIDS (Brain Imaging Data Structure) datasets in the Flywheel ecosystem. While care should be taken to add methods to the appropriate fw-bids subsuite as needs arise, this module contains methods that should be maintained in a common repo. An example of a common method is the classifications class. Changes to classifications will impact import_bids as well as curate_bids.

Installation

Using pip

pip install fw-bids-utils

From source

git clone https://github.com/flywheel-io/fw-bids-utils.git
cd fw-bids-utils
pip install -e .

Dependencies

This package requires Python 3.11+ and includes the following dependencies:

• flywheel-gear-toolkit
• jsonschema
• rtstatlib
• fw-meta For development, additional dependencies are available in requirements-dev.txt:
• pytest
• pytest-cov
• pytest-mock

Modules

classifications

Contains utilities for BIDS classification mapping:

• determine_modality: Determine which modality a file belongs to based on the parent directory's name
• search_classifications: Robust search on a filename to determine classifications

validate

Provides validation utilities for BIDS datasets:

• validate_bids: Validate a BIDS dataset using the bids-validator
• validate_project_label: Validate that a project label exists and is unique

helpers

General helper functions:

• String processing with process_string_template and format_value
• Dictionary utilities like dict_lookup, dict_set, and dict_match
• Project and session ID helpers

Usage Examples

Working with BIDS Classifications

from fw_bids_utils.classifications import determine_modality, search_classifications
# Determine the modality from a filename
modality = determine_modality("sub-01_T1w")
# Result: "anat"
# Get classification information
classification = search_classifications("anat", "T1w")
# Result: {"Measurement": "T1", "Intent": "Structural"}

Validating BIDS Datasets

from fw_bids_utils.validate import validate_bids
# Validate a BIDS dataset
is_valid = validate_bids("/path/to/bids/dataset")

Using Helpers

from fw_bids_utils.helpers import process_string_template
context = {
    "subject": {"code": "01"},
    "session": {"label": "session1"},
    "file": {"info": {"BIDS": {"Modality": "T1w"}}}
}
# Process a template string
filename = process_string_template(
    "sub-<subject.code>_ses-<session.label>_{file.info.BIDS.Modality}.nii.gz",
    context
)
# Result: "sub-01_ses-session1_T1w.nii.gz"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.