Metadata-Version: 2.4
Name: fw-bids-curate
Version: 0.1.0
Summary: Flywheel BIDS curate suite. Take the data in Flywheel an make the filenames BIDS-compliant for preview and export. This suite is used after `relabel-container` and is the backbone of the fw_curate_bids gear.
Keywords: Flywheel,flywheel,BIDS,SDK
Author: Flywheel
Author-email: Flywheel <support@flywheel.io>
License-Expression: MIT
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: fw-gear>=0.3,<0.4
Requires-Dist: flywheel-sdk>=20.1.4,<21
Requires-Dist: importlib-resources>=6.4.0,<7
Requires-Dist: jsonschema>=4.23.0,<5
Requires-Dist: rtstatlib>=1.0.0,<2
Requires-Dist: urllib3>=2.7.0,<3
Requires-Dist: fw-meta>=4.2.2,<5
Requires-Dist: fw-bids-utils>=0.1.1,<0.2
Requires-Python: >=3.11, <4
Project-URL: Repository, https://gitlab.com/flywheel-io/scientific-solutions/lib/bids-suite/fw-bids-curate
Provides-Extra: all
Description-Content-Type: text/markdown

# 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

```bash
# 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

```bash
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

```python
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

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

### Curate a Single Subject

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

### Dry Run to Test Without Changes

```bash
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/>)
