https://github.com/khanlab/snakedwi
https://github.com/khanlab/snakedwi
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/khanlab/snakedwi
- Owner: khanlab
- License: mit
- Created: 2020-08-06T16:09:46.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2026-02-02T16:46:44.000Z (6 months ago)
- Last Synced: 2026-02-03T05:39:04.189Z (6 months ago)
- Language: Perl
- Size: 49.4 MB
- Stars: 2
- Watchers: 1
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# snakedwi
[](https://snakedwi.readthedocs.io/en/latest/?badge=latest)
BIDS app and Snakemake workflow for diffusion-weighted imaging (DWI) pre-processing.
## Overview
snakedwi is a comprehensive workflow for preprocessing diffusion MRI data following the BIDS (Brain Imaging Data Structure) standard. The workflow includes:
- **Denoising** - Optional MP-PCA denoising
- **Susceptibility distortion correction (SDC)** - Multiple methods including TOPUP, SynthSR, SDCFlows, and SynB0
- **Eddy current correction** - FSL's eddy with optional GPU acceleration and slice-to-volume correction
- **Brain masking** - Multiple methods including BET, SyN registration, and SynthStrip
- **Gradient non-linearity correction** - Optional scanner-specific correction
- **Registration to T1w** - Rigid and deformable registration options
- **Quality control** - Automatic QC reports with eddy_quad
## Installation
### Prerequisites
- [pixi](https://pixi.sh/) - A fast package manager
### Install with pixi
1. Clone the repository:
```bash
git clone https://github.com/khanlab/snakedwi.git
cd snakedwi
```
2. Install dependencies with pixi:
```bash
pixi install
```
This will install snakedwi and all its dependencies in an isolated environment.
## Usage
### Basic Usage
Run the workflow with Apptainer (recommended for using containerized tools):
```bash
pixi run snakedwi /path/to/bids/dir /path/to/output/dir participant --use-apptainer
```
### Dry Run
To see what the workflow will do without running it:
```bash
pixi run snakedwi /path/to/bids/dir /path/to/output/dir participant --use-apptainer -np
```
### Running with Multiple Cores
To use all available cores:
```bash
pixi run snakedwi /path/to/bids/dir /path/to/output/dir participant --use-apptainer --cores all
```
### Common Options
- `--use-apptainer`: Use Apptainer/Singularity containers for tool dependencies
- `--participant_label`: Process specific subject(s), e.g., `--participant_label 001 002`
- `--sdc_method`: Choose susceptibility distortion correction method (`optimal`, `topup`, `synthsr`, `sdcflow`, `synb0`, `none`)
- `--masking_method`: Brain masking method (`b0_BET`, `b0_SyN`, `b0_synthstrip`)
- `--cores`: Number of cores to use (e.g., `--cores 8` or `--cores all`)
- `-np`: Dry-run mode (show what will be executed without running)
### Example with Options
```bash
pixi run snakedwi /path/to/bids/dir /path/to/output/dir participant \
--use-apptainer \
--participant_label 001 \
--sdc_method topup \
--masking_method b0_synthstrip \
--cores 8
```
## Input Data Requirements
Your input data must be organized according to the [BIDS specification](https://bids.neuroimaging.io/), specifically:
- DWI data in `sub-*/dwi/` with `.nii.gz` images and corresponding `.json` sidecar files
- Optional T1w anatomical images in `sub-*/anat/`
- Metadata including `PhaseEncodingDirection` in JSON files
## Output
Processed DWI data will be saved in the specified output directory following the BIDS derivatives format, including:
- Preprocessed DWI images
- Brain masks
- QC reports
- Transformation matrices
- Processing metadata
## Documentation
For detailed documentation, visit: [https://snakedwi.readthedocs.io](https://snakedwi.readthedocs.io)
## Development
### Running Tests
To run the test suite:
```bash
pixi run test_all
```
### Code Formatting
To format code:
```bash
pixi run quality_fix
```
To check code quality:
```bash
pixi run quality_check
```
## Citation
If you use snakedwi in your research, please cite:
```
Khan, A. R. (2024). snakedwi: BIDS app and Snakemake workflow for DWI pre-processing.
https://github.com/khanlab/snakedwi
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Issues**: Report bugs or request features at [GitHub Issues](https://github.com/khanlab/snakedwi/issues)
- **Documentation**: [https://snakedwi.readthedocs.io](https://snakedwi.readthedocs.io)
- **Repository**: [https://github.com/khanlab/snakedwi](https://github.com/khanlab/snakedwi)
## Acknowledgments
snakedwi is developed and maintained by the Khan Lab at Western University.