QuNex Recipes: Executable, Human-Readable Workflows for Reproducible Neuroimaging Research

This paper introduces QuNex recipes, a framework within the QuNex platform that defines neuroimaging workflows in transparent, executable, and human-readable formats to ensure complete reproducibility and facilitate the sharing of best practices by requiring only the software version, recipe file, and data for replication.

The Gist

Imagine you are trying to bake a very complex, multi-layered cake for a science fair. In the world of neuroimaging (studying the brain), this "cake" is a scientific study that turns raw brain scan data into a discovery about how the brain works.

For a long time, baking this cake was a nightmare. Researchers had to use dozens of different kitchen tools (software programs), mix ingredients in specific orders, and adjust temperatures constantly. If you wanted to recreate someone else's cake, you'd have to read a 50-page handwritten note that said things like, "Add flour, but maybe a little less if the kitchen is humid," or "Mix for 3 minutes, but stop if the mixer sounds weird."

Because these instructions were so vague and scattered, it was nearly impossible to bake the exact same cake twice. This made science hard to trust and hard to share.

Enter "QuNex Recipes."

This paper introduces a new way to do brain research that is like switching from handwritten notes to a smart, digital recipe app that actually does the baking for you.

Here is how it works, using simple analogies:

1. The "Master Recipe" (The YAML File)

Instead of writing a long, confusing paragraph of instructions, researchers now write a single, clean file called a Recipe.

• The Analogy: Think of this as a digital shopping list and instruction manual combined. It says: "First, take the raw ingredients (brain scans). Then, chop them (preprocessing). Then, bake them at exactly 350 degrees (analysis). Finally, frost them (results)."
• Why it's cool: It's written in a language called YAML. It looks like a simple, organized list that both humans can read easily and computers can understand perfectly. No more guessing!

2. The "Smart Kitchen" (The Container)

In the old days, if you tried to bake someone else's cake, you might not have the exact same brand of mixer or the same type of oven. The cake would turn out different.

• The Analogy: QuNex brings a portable, self-contained kitchen (a "container") with you. This kitchen comes with every tool, ingredient, and appliance version needed to bake the cake perfectly, no matter where you are.
• The Result: If you send your recipe and your data to a friend in another country, they can drop it into their "QuNex Kitchen," press one button, and get the exact same cake you made.

3. The "One-Button" Magic

Previously, to run a study, a researcher might have to type 50 different commands into a computer, one by one. If they made a typo in command #24, the whole thing failed, and they had to start over.

• The Analogy: With QuNex Recipes, you just press "Start." The system reads the recipe, grabs the ingredients, runs every step in the perfect order, checks the quality at every stage (like a sous-chef tasting the sauce), and stops if something goes wrong.
• The Benefit: It turns a complex, error-prone process into a simple "Click and Go" experience.

4. The "Time-Travel" Feature (Reproducibility)

Science relies on the idea that if you repeat an experiment, you should get the same result.

• The Analogy: With this new system, sharing a study is like sharing a time capsule. You only need to send three things:
  1. The Recipe (the instructions).
  2. The Ingredients (the raw brain data).
  3. The Kitchen Version (the specific software version used).
• Anyone, anywhere, can open that time capsule and recreate the study perfectly, years later. This solves the "mystery of the missing steps" that plagues science.

5. Mixing and Matching (Flexibility)

Sometimes a researcher wants to use a special tool that isn't in the standard kitchen.

• The Analogy: QuNex Recipes are like a kitchen with a "Bring Your Own Tool" drawer. If you have a special gadget (a custom script or a different software tool), you can plug it right into the middle of the recipe. The system handles it seamlessly, so the whole process still runs automatically.

Why Does This Matter?

Before this, sharing a brain study was like sharing a story where the author forgot to mention how they mixed the ingredients. Now, QuNex Recipes provide the full, transparent, step-by-step video of the entire process.

It lowers the barrier for new scientists (you don't need to be a coding wizard to run a complex study), speeds up research, and ensures that the discoveries we make about the human brain are solid, reliable, and can be built upon by others. It turns neuroimaging from a chaotic art into a precise, reproducible science.

Technical Summary

1. Problem Statement

Neuroimaging research faces significant challenges regarding reproducibility, transparency, and workflow integration.

• Complexity: Processing pipelines often require combining multiple software tools (e.g., FreeSurfer, FSL, AFNI, HCP pipelines) with distinct dependencies and parameter sets.
• Documentation Gaps: Even when using containerized tools to ensure software version consistency, the specific configuration of workflows (parameter choices, command sequences, and custom scripts) is rarely documented in a unified, human-readable format.
• Limitations of Existing Tools:
  • Preprocessing-focused tools (e.g., fMRIPrep, qsiprep) are robust but limited to preprocessing and lack flexibility for custom post-processing or external script integration.
  • GUI-based tools (e.g., DPABI, CONN) use binary formats (.mat) that hinder version control and transparency.
  • General workflow managers (e.g., Snakemake, Nextflow, Nipype) require high programming expertise and often lack native support for neuroimaging standards (BIDS) or predefined end-to-end pipelines.
• The Result: Reproducing a study often requires extensive manual reconstruction of undocumented steps, limiting open collaboration and scientific validation.

2. Methodology: The QuNex Recipes Framework

The authors introduce QuNex Recipes, a framework integrated into the QuNex (Quantitative Neuroimaging Environment & Toolbox) platform. This framework defines and executes complete neuroimaging workflows (from data onboarding to analysis) using a standardized, declarative approach.

• Format: Recipes are defined as YAML files, chosen for being compact, human-readable, and machine-parsable.
• Structure:
  • Global Parameters: Optional parameters applying to all commands.
  • Recipes Block: Contains one or more named workflows, each comprising a sequence of commands.
  • Hierarchical Parameter System: Parameters are resolved at four levels of precedence:
    1. Command-line call (highest priority).
    2. Command-specific parameters.
    3. Recipe-level parameters.
    4. Global parameters (lowest priority).
• Execution Engine:
  • Recipes are executed via the qunex_container run_recipe command within a versioned Singularity/Apptainer container.
  • The system supports dynamic parameter injection using Mustache notation ({{...}}) to substitute environment variables or external values at runtime.
  • External Script Integration: The framework allows the execution of custom Bash, Python, R scripts, or binaries at any stage of the workflow, not just as pre/post hooks.
• Workflow Management:
  • Logging: Generates three levels of logs (Recipe, Summary, Command) to capture exact invocations, parameters, and outputs for provenance tracking.
  • Checkpointing: Supports resuming failed jobs from the last successful step without re-running completed portions.
  • Scalability: Integrates with HPC schedulers (SLURM, PBS, GridEngine) to handle batch processing and parallel execution across sessions.
  • XNAT Integration: The framework is designed to work within the XNAT imaging informatics platform, simplifying access control and data management for large-scale studies.

3. Key Contributions

1. Unified End-to-End Workflow Definition: Unlike tools limited to preprocessing, QuNex Recipes support the entire pipeline: data onboarding, preprocessing, quality control (QC), and advanced analysis.
2. One-Command Reproducibility: A study can be fully replicated by providing only three items: (a) the QuNex version, (b) the recipe file, and (c) the input data.
3. Human-Readable Transparency: By using YAML, the entire analytic logic is visible and editable without proprietary binary formats, facilitating peer review and method sharing.
4. Seamless Hybrid Execution: The ability to chain native QuNex commands with external custom scripts allows researchers to integrate specialized tools (e.g., specific diffusion models) without breaking the reproducibility chain.
5. Community Library: The authors established a public, version-controlled repository (qunex_run_recipe) containing validated recipes for diverse use cases (HCP data, diffusion modeling, functional connectivity), encouraging community contribution.

4. Results

The paper demonstrates the framework's utility through two representative use cases:

• Case 1: End-to-End Processing (Raw DICOM to Analysis):
  • A single recipe file processed raw DICOM data through import, validation, HCP Minimal Preprocessing Pipelines (structural and functional), ICA-based denoising, surface matching, and finally computed Global Brain Connectivity (GBC) maps.
  • Comparison: The authors contrasted the recipe approach with traditional command-line invocation, showing the recipe was significantly shorter, less prone to error, and easier to read.
• Case 2: Modular Analysis on Existing Data:
  • A recipe was used to download preprocessed HCP data from an S3 bucket via an external script, onboard it, and perform advanced diffusion modeling (DTIFit and GPU-accelerated NODDI) on over 1,000 sessions.
  • This demonstrated the framework's ability to integrate external data sources, custom scripts, and high-performance computing resources (GPU scheduling) within a reproducible workflow.

5. Significance and Impact

• Bridging the Gap: QuNex Recipes bridge the gap between the flexibility of custom scripting and the rigor of reproducible science. It lowers the technical barrier for non-programmers while maintaining advanced configurability for experts.
• Standardization: It provides a standardized way to describe and share neuroimaging workflows, moving the field toward "executable papers" where methods can be run, not just read.
• Scalability: By integrating with HPC schedulers and XNAT, the framework supports large-scale, multi-site studies (e.g., Human Connectome Project) that were previously difficult to manage reproducibly.
• Future Outlook: The authors envision a growing ecosystem of community-submitted recipes, creating a foundation for collaborative, transparent, and cumulative neuroimaging research.

Limitations Noted: The current implementation schedules the entire recipe as a single job (though parallelism exists within the job), which may be suboptimal for massive datasets compared to a Directed Acyclic Graph (DAG) approach where individual sub-tasks are scheduled separately. Additionally, the large container size (20GB) and requirement for HPC/XNAT infrastructure present deployment hurdles for smaller labs.