Metadata-Version: 2.4
Name: fw-bids-utils
Version: 0.1.0
Summary: Utilities for the Flywheel BIDS suite.
Keywords: Flywheel,flywheel,BIDS,SDK
Author: Flywheel
Author-email: Flywheel <support@flywheel.io>
License-Expression: MIT
Classifier: Topic :: Scientific/Engineering
Requires-Dist: fw-gear>=0.3,<0.4
Requires-Python: >=3.11, <4
Project-URL: Repository, https://gitlab.com/flywheel-io/scientific-solutions/lib/bids-suite/fw-bids-utils
Description-Content-Type: text/markdown

# fw-bids-utils

[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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

```bash
pip install fw-bids-utils
```

### From source

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

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

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

### Using Helpers

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

[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) This project
is licensed under the MIT License - see the LICENSE file for details.
