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	Status	Version	API Coverage
AFNI	Experimental	24.2.06	565/611 (92.5%)
ANTs	Experimental	2.5.3	71/113 (62.8%)
Connectome Workbench	Experimental	1.5.0	202/202 (100% 🎉)
Convert3D	Experimental	1.1.0	4/4 (100% 🎉)
FSL	Experimental	6.0.5	245/313 (78.3%)
FastSurfer	Experimental	2.3.3	1/1 (100% 🎉)
FreeSurfer	Experimental	7.4.1	696/789 (88.2%)
Greedy	Experimental	1.0.1	1/1 (100% 🎉)
MRTrix3	Well tested	3.0.4	115/121 (95.0%)
MRTrix3Tissue	Well tested	5.2.8	1/1 (100% 🎉)
NiftyReg	Experimental	1.4.0	7/7 (100% 🎉)
dcm2niix	Experimental	1.0.20240202	1/1 (100% 🎉)

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:

% Placeholder - please cite our soon to be released preprint.
@software{niwrap,
  author = {The NiWrap Contributors},
  title = {NiWrap: Type-Safe Neuroimaging Tool Wrappers},
  url = {https://github.com/styx-api/niwrap},
  year = {2023}
}

🔗 Related Projects

• Styx Compiler
• Styx Documentation
• Boutiques