fw-bids-curate

A Python library for automating BIDS-compliant metadata curation in Flywheel.

Description

The fw-bids-curate tool helps standardize neuroimaging datasets according to the Brain Imaging Data Structure (BIDS) specification within the Flywheel platform. It automates the process of applying BIDS metadata to projects, sessions, acquisitions, and files in Flywheel, making datasets ready for BIDS export and analysis.

Features

• Applies BIDS metadata to Flywheel containers (projects, sessions, acquisitions) and files
• Supports multiple curation templates (Default, ReproIn, BIDS-v1, and custom templates)
• Handles intricacies like run counting and "IntendedFor" field resolution across sessions
• Supports curation of entire projects or individual subjects/sessions
• Includes dry-run option for testing without modifying data

Installation

# Clone the repository
git clone https://gitlab.com/flywheel-io/scientific-solutions/lib/bids-suite/fw-bids-curate.git
cd fw-bids-curate

pip install -r requirements.txt

Usage

Command Line Interface

python fw_bids_curate/curate.py --api-key YOUR_API_KEY [options]

Required Arguments

• --api-key: Your Flywheel API key

Project Selection (one required)

• -p PROJECT_LABEL: The Flywheel project label
• -g GROUP_ID: Optional Flywheel group ID when using project label
• --subject SUBJECT_ID: A specific Flywheel subject ID to curate
• --session SESSION_ID: A specific Flywheel session ID to curate

Additional Options

• --reset: Clear existing BIDS metadata before curation
• --recurate_project: Re-curate the project (default=True)
• --template-type TEMPLATE_NAME: Template type to use (Default, ReproIn, or Custom)
• --template-file TEMPLATE_PATH: Custom template file path (overrides template-type)
• --pickle_tree: Use/save pickled context for debugging
• --dry_run: Run without updating Flywheel metadata
• --verbosity LEVEL: Debug level (0, 10, 20)

As a Library

import flywheel

from fw_bids_curate.curate import curate_bids

# Initialize Flywheel client
fw = flywheel.Client('YOUR_API_KEY')

# Curate a project
curate_bids(
    fw,
    project_id='project_id',
    template_name='ReproIn'  # or 'Default', 'BIDS-v1', etc.
)

Templates

The tool supports several types of templates:

• Default: Basic BIDS template
• BIDS-v1: Template compliant with BIDS v1.x
• ReproIn: Template designed for the ReproIn convention
• Custom: User-defined templates

Templates are located in the fw_bids_curate/templates/ directory. Custom templates can be specified using the --template-file option.

Example Workflows

Curate an Entire Project

python fw_bids_curate/curate.py --api-key YOUR_API_KEY \
  -p "My BIDS Project" --template-type ReproIn

Curate a Single Subject

python fw_bids_curate/curate.py --api-key YOUR_API_KEY \
  --subject 5f8a1b2c3d4e5f6a7b8c9d0e --template-type BIDS-v1

Dry Run to Test Without Changes

python fw_bids_curate/curate.py --api-key YOUR_API_KEY -p "My BIDS Project" --dry_run

Contributing

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

License

This project is licensed under the terms applicable to Flywheel products and services.

Acknowledgments

• Flywheel.io team and community
• The BIDS community (https://bids.neuroimaging.io/)