README.md

NiWrap

🧠 Modern Neuroimaging Made Simple

NiWrap provides seamless, programmatic access to powerful neuroimaging command-line tools through clean, type-safe APIs in Python, TypeScript, and R (coming soon). Stop struggling with command-line parameters and focus on your neuroimaging workflows.

✨ Key Features

• Type-Safe APIs: Leverage full IDE autocompletion and type checking
• Extensive Coverage: Access tools from FSL, FreeSurfer, ANTs, MRTrix3, and more
• Cross-Language Support: Use the same tools in Python, TypeScript, or R
• Consistent Interface: Uniform API design across all neuroimaging packages
• Container Integration: Seamlessly run tools in Docker, Singularity, or other container environments
• Structured Outputs: All functions return organized output paths for simple pipeline creation

🧰 Supported Packages

Package	Default Version	API Coverage
AFNI	24.2.06
ANTs	2.5.3
Convert3D	1.1.0
dcm2niix	1.0.20240202
FastSurfer	2.3.3
FreeSurfer	7.4.1
FSL	6.0.4
Greedy	1.0.1
MRTrix3	3.0.4
MRTrix3Tissue	5.2.8
NiftyReg	1.4.0
Connectome Workbench	2.1.0

API Coverage: The percentages shown represent the proportion of tool binaries with available NiWrap descriptors, not the completeness of each descriptor.

🚀 Getting Started

Installation

Python

pip install niwrap

TypeScript/JavaScript

npm install niwrap
# or
yarn add niwrap

R (Coming Soon)

# Not yet available on CRAN
# Coming soon!

Basic Usage Examples

Python

from niwrap import fsl, ants, mrtrix

# Optional: Use Docker to run all tools (no local installation needed)
import niwrap
niwrap.use_docker()

# Run FSL's BET brain extraction
outputs = fsl.bet(
    infile="input.nii.gz",
    maskfile="brain.nii.gz",
    fractional_intensity=0.5,
    binary_mask=True,
)
# outputs.outfile -> "brain.nii.gz"
# outputs.binary_mask -> "brain_mask.nii.gz"

# Calculate fiber orientation distributions with MRTrix3
fod_outputs = mrtrix.dwi2fod(
    algorithm="csd",
    dwi="dwi.mif",
    response_odf=[
        mrtrix.dwi2fod_response_odf_params(
            response="wm_response.txt",
            odf="wmfod.mif",
        ),
    ]
)
# fod_outputs.response_odf[0].odf -> "wmfod.mif"

TypeScript/JavaScript

import { niwrap, fsl, ants, mrtrix3 } from 'niwrap';

// Optional: Use Docker to run all tools (no local installation needed)
niwrap.useDocker();

// Run FSL's BET brain extraction
const outputs = await fsl.bet({
    input: "input.nii.gz",
    output: "brain.nii.gz",
    f: 0.5
});
// outputs.outputFile -> "brain.nii.gz"
// outputs.maskFile -> "brain_mask.nii.gz"

// Calculate fiber orientation distributions with MRTrix3
const fodOutputs = await mrtrix3.dwi2fod({
    algorithm: "csd",
    in_file: "dwi.mif",
    wm_txt: "wm_response.txt",
    wm_odf: "wmfod.mif"
});
// fodOutputs.wmOdf -> "wmfod.mif"

R (Coming Soon)

library(niwrap)

# Optional: Use Docker to run all tools (no local installation needed)
niwrap$use_docker()

# Run FSL's BET brain extraction
outputs <- fsl$bet("input.nii.gz", "brain.nii.gz", fractional_intensity=0.5)
# outputs$output_file -> "brain.nii.gz"
# outputs$mask_file -> "brain_mask.nii.gz"

# More functionality coming soon!

🔧 Container Orchestration

NiWrap handles container orchestration for you, making it easy to run tools without installing them locally:

Python

import niwrap

# Use Docker containers
niwrap.use_docker()

# Use Singularity containers
niwrap.use_singularity()

# Custom container configuration
niwrap.use_docker()

TypeScript/JavaScript

import { niwrap } from 'niwrap';

// Use Docker containers
niwrap.useDocker();

// Use Singularity containers
niwrap.useSingularity();

// Custom container configuration
niwrap.useDocker({
    bindMounts: ["/data:/data"],
    envs: {"CUDA_VISIBLE_DEVICES": "0"}
});

R (Coming Soon)

library(niwrap)

# Use Docker containers
niwrap$use_docker()

# Use Singularity containers
niwrap$use_singularity()

# Custom container configuration
niwrap$use_docker(
    bind_mounts = c("/data:/data"),
    envs = list(CUDA_VISIBLE_DEVICES = "0")
)

🔍 How It Works

NiWrap is powered by the Styx compiler, which transforms structured descriptors (using the Boutiques standard) into type-safe language bindings. This repository contains the descriptors, while the compiled packages are available in separate repositories:

• niwrap-python
• niwrap-js
• niwrap-r (in development)

📚 Documentation

For complete documentation on using NiWrap, configuring Styx, and contributing to the project, please visit our Styx Book.

📋 Prerequisites

To use NiWrap without containers, you need to have the corresponding neuroimaging packages installed on your system. Using the container integration features (use_docker() or use_singularity()) eliminates this requirement.

🤝 Contributing

We welcome contributions! Whether you want to add support for new neuroimaging tools, improve existing descriptors, or fix bugs, please feel free to open an issue or submit a pull request.

See our contribution guide for more information.

📄 License

NiWrap is released under the MIT License. See the LICENSE file for details.

Important Note: NiWrap provides wrappers for third-party neuroimaging tools, each with its own license. Please consult the license terms of each individual tool before use in your projects. NiWrap does not modify or redistribute these tools; it simply provides interfaces to them.

📚 Citation

If you use NiWrap in your research, please consider citing:

@article {rupprecht2025styx,
	author = {Rupprecht, Florian JM and Kai, Jason and Shrestha, Biraj and Giavasis, Steven and Xu, Ting and Glatard, Tristan and Milham, Michael P and Kiar, Gregory},
	title = {Styx: A multi-language API Generator for Command-Line Tools},
	elocation-id = {2025.07.24.666435},
	year = {2025},
	doi = {10.1101/2025.07.24.666435},
	publisher = {Cold Spring Harbor Laboratory},
	URL = {https://www.biorxiv.org/content/early/2025/07/30/2025.07.24.666435},
	eprint = {https://www.biorxiv.org/content/early/2025/07/30/2025.07.24.666435.full.pdf},
	journal = {bioRxiv}
}

🔗 Related Projects

• Styx Compiler
• Styx Documentation
• Boutiques