Skip to content

khanlab/snakebids

Repository files navigation

Snakebids

Tests codecov Documentation Status Version Python versions DOI License: MIT

Snakebids is a Python package that extends Snakemake, enabling users to create reproducible, scalable pipelines for processing neuroimaging data in the BIDS format. Snakebids workflows expose a CLI that conforms to the BIDS App guidelines.

Features

Snakebids includes all of the features of Snakemake, including flexible configuration, parallel execution, and Docker/Singularity support, plus:

  • Built-in support for BIDS datasets: Seamless workflow functionality with a wide range of BIDS datasets, accommodating various levels of complexity.
  • BIDS App Creation: Provide command-line invocations of your workflow following BIDS App guidelines, ensuring reproducibility and enhancing accessibility of your workflow.
  • BIDS Path Construction: Easy, flexible construction of valid BIDS paths following BIDS guiding principles, promoting data organization and sharing.
  • Plugin System: Extend the functionality of Snakebids by creating and using plugins to meet your workflow's needs.
  • Pybids Querying: Leverages Pybids to efficiently retrieve specific data required.

Installation

Snakebids can be installed using pip:

pip install snakebids

Usage

To create and run a Snakebids workflow, you need to:

  1. Create a Snakefile: Define the steps of your workflow, including input / output files, processing rules, and dependencies
  2. Create a configuration file: Customize workflow behaviour using a YAML configuration file. Specify input / output directories and custom workflow parameters.
  3. Run the pipeline: Execute the Snakebids pipeline by invoking the BIDS App CLI or via Snakemake executable.

For detailed instructions and examples, please refer to the documentation.

Contributing

Snakebids is an open-source project, and contributions are welcome! If you have any bug reports, feature requests, or improvements, please submit them to the issues page.

To contribute, first clone the Github repository. Snakebids dependencies are managed with Poetry (version 1.2 or higher). Please refer to the poetry website for installation instructions.

Note: Snakebids makes use of Poetry's dynamic versioning. To see a version number on locally installed Snakebids versions, you will have to also install poetry-dynamic-versioning plugin to your poetry installation (`poetry self add "poetry-dynamic-versioning[plugin]"). This is not required for contribution.

Following installation of Poetry, the development can be set up by running the following commands:

poetry install
poetry run poe setup

Snakebids uses poethepoet as a task runner. You can see what commands are available by running:

poetry run poe

Tests are done with pytest and can be run via:

poetry run poe test

Additionally, Snakebids uses pre-commit hooks (installed via the poe setup command above) to lint and format code (we use black, isort and ruff. By default, these hooks are run on every commit. Please be sure they all pass before making a PR.

License

Snakebids is distributed under the MIT License.

Acknowledgements

Snakebids extends the Snakemake workflow management system and follows the guidelines outlined by the BIDS specification.

Relevant papers

  • Mölder F, Jablonski KP, Letcher B et al. Sustainable data analysis with Snakemake [version 2; peer review: 2 approved]. F1000Research. 2021. doi: 10.12688/f1000research.29032.2