BBOP Preprocessing Pipeline

DOI: 10.5281/zenodo.20308891

---

📦 Version

BBOP v0.7.0 (Modular Backend Architecture Update)

---

BBOP (BabelBrain Optimized Preprocessing) is an open-source preprocessing and targeting pipeline for transcranial focused ultrasound (tFUS/TUS) research.

It is a modular, reproducible pipeline designed for preprocessing and planning workflows with BabelBrain with optional Brainsight integration.

It integrates MRI preprocessing, modular head-model generation workflows, ROI targeting, and transducer trajectory planning into a single, structured environment.

BBOP now supports both:

• classic SimNIBS CHARM workflows
• PETRA-based density workflows via the SimNIBS petra2density toolbox

---

🚀 Quick Start

git clone https://github.com/franzroman/BBOP.git MyStudy_BBOP
cd MyStudy_BBOP
nano BBOP_config.sh # Select preprocessing backend in BBOP_config.sh
./BBOP --check
./BBOP sub-XXX

• Replace MyStudy_BBOP with your project/study name.

• 💡 Run ./BBOP --check to verify your environment before processing data.

• Replace "sub-XXX" with your subject ID (e.g., sub-01).

• Edit BBOP_config.sh. This can be done with any text editor (e.g., VS Code).

That is the entire user workflow.

---

📖 Citation

If you use BBOP in academic work, please cite:

Schmid FR, Atkinson-Clement C.
BBOP: BabelBrain- and Brainsight-Oriented Preprocessing (v0.7.0).
Zenodo. https://doi.org/10.5281/zenodo.20308891

---

⚠️ What changed in v0.7.0

BBOP v0.7.0 introduces a modular preprocessing-backend architecture.

Users can now choose between:

• classic_charm

  • legacy BBOP workflow
  • Step 3 resampling + Step 4a SimNIBS CHARM

• petra2density

  • PETRA-native workflow
  • skips Step 3
  • uses Step 4b (petra2density)
  • preserves native PETRA-space processing

Additional changes:

• Step 4 renamed to Step 4a
• new Step 4b (petra2density)
• optional legacy QC (Step 6)
• expanded environment checks
• improved config-driven execution

---

📘 Full Walkthrough

For a detailed step-by-step guide, see:

BBOP Walkthrough

⏱ Runtime

The following runtimes are representative example runs and may vary substantially across systems and datasets.

Example Runtime 1 — NIfTI input (T1 + T2)

Subject: sub-Chen01-7T
Input: T1 and T2 (NIfTI)
System: Apple Mac M4 Pro (48 GB RAM)

Step	Description	Runtime
1	DICOM → NIfTI prep	~0 s
2	Canonical anatomy	~0 s
3	Resampling (1 mm)	~4 s
4a	SimNIBS (CHARM)	~29 min
5	Targeting	~11 s
6	Legacy QC	~2 s
7	pCT (optional)	skipped
8	TUS-entry	~3 min

Total runtime: ~32 minutes

---

Example Runtime 2a — DICOM input (classic_charm backend)

Subject: sub-KC_PILOT
Input: T1, T2, and PETRA (DICOM)
Backend: classic_charm
System: Apple Mac M4 Pro (48 GB RAM)

Step	Description	Runtime
1	DICOM → NIfTI prep	~0 s
2	Canonical anatomy	~1 s
3	Resampling (1 mm)	~2 s
4a	SimNIBS (CHARM)	~35 min
5	Targeting	~14 s
6	Legacy QC	~3 s
7	pCT (optional)	skipped
8	TUS-entry	~3 min

Total runtime: ~48 minutes

---

Example Runtime 2b — DICOM input (petra2density backend)

Subject: sub-KC_PILOT
Input: T1, T2, and PETRA (DICOM)
Backend: petra2density
System: Apple Mac M4 Pro (48 GB RAM)

Step	Description	Runtime
1	DICOM → NIfTI prep	~0 s
2	Canonical anatomy	~1 s
3	Resampling (1 mm)	skipped
4b	petra2density (incl. CHARM)	~39 min
5	Targeting	~35 s
6	Legacy QC	skipped
7	pCT (optional)	skipped
8	TUS-entry	~3 min

Total runtime: ~43 minutes

---

⚠️ Runtime varies depending on hardware, input modality (NIfTI vs DICOM), and enabled modules.

💡 SimNIBS (Steps 4a and 4b) is the main computational bottleneck.

💡 The petra2density backend skips Step 3 and legacy QC, but internally performs additional PETRA-space registration, CHARM processing, and density-map generation.

---

🧠 Conceptual Design

BBOP is not just a script.

It is a self-contained project environment:

MyStudy_BBOP/
├── BBOP                ← launcher
├── BBOP_config.sh      ← user configuration
├── Raw-Data/
├── Analysis/
├── Scripts/
└── Tools/

Each project:

• owns its data
• owns its config
• runs independently

BBOP is designed around a modular orchestration philosophy:

• preprocessing backends are interchangeable
• optional modules can be enabled or skipped
• workflows remain reproducible through centralized configuration
• new preprocessing methods can be integrated without redesigning downstream targeting and trajectory-planning steps

Most optional tools are contained directly within the BBOP environment (Tools/).

Only core external dependencies (e.g., FSL, SimNIBS, MATLAB) must be installed globally.

---

🔬 Pipeline Overview

Inputs

• T1 MRI (required)
• T2 MRI (optional)
• PETRA MRI (optional)
• ZTE MRI (optional)
• ROI definitions (YAML)

Outputs

• Preprocessed MRI and/or density maps
• SimNIBS head model (m2m_<SUBJECT>)
• ROI masks and coordinates
• Optional PETRA-space density maps
• Optional legacy QC metrics
• Optional pseudo-CT
• Optional TUS-entry optimization

---

🔁 Processing Flow

Raw MRI
   ↓
DICOM → NIfTI
   ↓
Canonical anatomy
   ↓
┌──────────────────────────────┐
│ Preprocessing backend choice │
└──────────────────────────────┘
              ↓
┌───────────────────────────────┐
│ classic_charm backend         │
└───────────────────────────────┘
│      Resampling (1 mm)        │
│           ↓                   │
│      Step 4a: CHARM           │
└───────────────────────────────┘
              OR
┌───────────────────────────────┐
│ petra2density backend         │
└───────────────────────────────┘
│   Resampling (1mm) skipped    │
│           ↓                   │
│  Step 4b: petra2density       │
│  (PETRA-space registration +  │
│  CHARM + density map)         │
└───────────────────────────────┘
   ↓
Targeting (ROIs)
   ↓
[Legacy QC optional]
   ↓
[pCT optional]
   ↓
[TUS-entry optional]

---

🔬 Detailed Steps

Step 1 — DICOM → NIfTI

• Converts raw data
• Initializes subject structure
• Creates BBOP directory hierarchy

Step 2 — Canonical anatomy

• Identifies T1/T2/PETRA/ZTE
• Standardizes filenames
• Stages canonical anatomical inputs
• Organizes unused files into MR-cache

Step 3 — Resampling (classic_charm backend only)

• Resamples T1/T2 to 1 mm isotropic resolution
• Used only for the classic_charm backend
• Skipped for petra2density

Step 4a — SimNIBS (CHARM)

• Legacy BBOP preprocessing backend
• Generates subject-specific head model
• Produces m2m_<SUBJECT>

Step 4b — petra2density

• PETRA-native preprocessing backend
• Registers T1 to PETRA space
• Runs CHARM internally
• Generates PETRA-based density maps
• Produces p2d_density.nii.gz
• Produces m2m_<SUBJECT>

Step 5 — Targeting

• MNI → subject coordinate transform
• ROI mask warping
• Optional coordinate-based masks
• Compatible with both preprocessing backends

Step 6 — Legacy QC (optional)

• T1–T2 difference image
• Statistical summaries
• Primarily retained for backward compatibility

Step 7 — pseudo-CT (optional)

• PETRA → CT conversion via MATLAB
• Based on the UCL petra-to-ct toolbox
• Independent of the petra2density backend

Step 8 — TUS-entry (optional)

• Optimal transducer placement
• Optional trajectory computation
• Supports direct trajectory export for BabelBrain

---

⚙️ Configuration (BBOP_config.sh)

This is the only file users must edit.

💡 All workflow behavior in BBOP is controlled centrally through BBOP_config.sh.

The high-level launcher (./BBOP sub-XXX) automatically forwards these configuration flags to the underlying pipeline wrapper.

---

ROIs

ROIS=(caudate_da_rh mfg5_internal_v3)

Must match entries in:

Raw-Data/Pipeline/BBOP_ROIs.yaml

---

Preprocessing backend

Flag	Description
--backend classic_charm	Step 3 resampling + Step 4a SimNIBS CHARM
--backend petra2density	Skip Step 3 and use Step 4b (petra2density)

Example:

PREPROC_FLAGS=(
  --backend petra2density
)

---

Targeting flags (Step 5)

Flag	Description
--coords	Convert coordinates
--maskwarp	Warp masks
--coordmask	Generate spherical masks
--all	Enable all
--none	Disable targeting
--radius-mm R	Sphere radius

---

Legacy QC flags (Step 6)

Flag	Description
--with-QC	Enable legacy T1/T2 QC
--without-QC	Skip legacy QC

Example:

QC_FLAGS=(
  --without-QC
)

---

pseudo-CT flags (Step 7)

Flag	Description
--with-pCT	Enable pCT
--without-pCT	Disable pCT

---

TUS-entry flags (Step 8)

Flag	Description
--with-TUSentry	Enable
--without-TUSentry	Disable
--trajectory	Export trajectory
--min-cm X	Minimum distance
--max-cm Y	Maximum distance
--tusentry-dir PATH	Custom toolbox

---

🧩 Dependencies

Required core dependencies

These dependencies must be installed globally and accessible in the user environment.

• Bash
• FSL
• SimNIBS 4.6
• Python
  • numpy
  • nibabel
  • yaml
• R
  • oro.nifti

Optional workflow dependencies

These are only required for specific optional modules.

Dependency	Required for
MATLAB	Step 7 (pseudo-CT)
SPM	Step 7 (pseudo-CT)
petra-to-ct toolbox	Step 7 (pseudo-CT)
TUS_entry toolbox	Step 8 (TUS-entry)

Included toolboxes

BBOP directly ships with several optional tools inside:

Tools/

---

🧪 Environment Check

./Scripts/BBOP_Pipeline/BBOP_check_environment.sh

Validates:

• required dependencies
• optional workflow dependencies
• MATLAB integration
• SimNIBS integration
• toolbox availability
• preprocessing backend support

---

🔁 Reproducibility Features

• Step-wise completion flags
• Idempotent execution
• Automatic skipping of completed steps
• Safe reruns
• Config-driven execution
• Backend-aware step orchestration

---

🧰 Debugging

BBOP provides two complementary logging systems:

Central pipeline log

Located in:

Analysis/Pipeline-Log/BBOP_Pipeline_Log.csv

Central pipeline log

Located in:

Analysis/Pipeline-Log/Log-Files/

Manual troubleshooting

For manual step execution and debugging workflows, see:

BBOP_pipeline_cheatsheet.md

---

🧠 Design Principles

• Minimal user friction
• Maximum reproducibility
• Modular orchestration architecture
• Backend-agnostic downstream workflows
• Transparent failure handling
• Config-driven execution
• Safe iterative development

---

📁 Example Datasets

BBOP includes representative example datasets for:

• testing
• demonstration
• backend validation
• workflow reproducibility

Included Data

The example subjects are selected to reflect common use cases in TUS preprocessing workflows:

• T1 + T2 dataset
  → enables multimodal preprocessing, backend validation, and optional QC workflows → from Chen et al. (2023): https://doi.org/10.1038/s41597-023-02400-y

• Preprocessed head model dataset (SimNIBS)
  → demonstrates compatibility with preprocessed simulation environments and adaptive pipeline behavior → from Lepping et al. (2016): https://doi.org/10.1177/0305735615604509 via SimNIBS Group Dataset

These datasets are minimally adapted to match the BBOP directory structure and naming conventions. The included examples intentionally represent different preprocessing states and acquisition scenarios to validate BBOP’s modular execution model.

---

Purpose

The example datasets are provided to:

• Allow immediate testing after cloning
• Validate pipeline structure and modular backend execution
• Demonstrate adaptive behavior across different preprocessing scenarios
• Facilitate reproducible onboarding

---

Notes

• Datasets represent different levels of preprocessing completeness
• Some datasets already contain derived outputs (e.g., m2m_<SUBJECT> folders)
• BBOP automatically detects and adapts to existing preprocessing states
• Not all optional modules (e.g., pseudo-CT, TUS-entry, legacy QC) are applicable to all datasets
• PETRA-containing datasets can be used to validate both preprocessing backends (classic_charm and petra2density)

---

Relation to External Datasets

The included examples are derived from publicly available datasets used to evaluate BBOP:

• Multimodal MRI dataset (T1 + T2, 3T / 7T)
• SimNIBS dataset with precomputed head models

These datasets were selected to validate BBOP across heterogeneous preprocessing scenarios:

1. Minimal structural input (T1-only)
2. Multimodal MRI preprocessing
3. Integration with preprocessed simulation environments
4. Adaptive backend-aware execution
5. PETRA-based preprocessing workflows

---

Important Clarification

The example datasets are intended for:

• testing and demonstration
• workflow and backend validation

They are not intended as full experimental datasets for TUS simulations.

Users should provide their own study-specific data for actual experiments. The included examples are intentionally heterogeneous and may exercise different BBOP execution paths depending on the selected preprocessing backend and enabled optional modules.

---

🧠 Additional Supported Modalities (ZTE)

BBOP also detects and stages ZTE (Zero Echo Time) scans during Step 2 as part of its modality-agnostic anatomical staging system.

Detection

ZTE files are identified using filename patterns:

*zte*.nii
*zte*.nii.gz

Output

Detected ZTE scans are staged as:

${SUBJECT}_ZTE_<LABEL>.nii

Example:

sub-03Elly_ZTE_GENERIC.nii

Behavior

• Supports multiple ZTE files per subject
• Uses the same variant classification logic as PETRA
• Handles naming collisions automatically
• Fully optional — pipeline proceeds if no ZTE is present
• Compatible with the modular preprocessing-backend architecture

Implication

ZTE support extends BBOP beyond PETRA-only skull imaging and prepares the pipeline for:

• ZTE-based pseudo-CT workflows
• Improved compatibility with external datasets
• Future modality-agnostic preprocessing backends

Disclaimer

⚠️ Full ZTE-native preprocessing workflows are not yet implemented in v0.7.0.

Current support focuses on:

• robust ZTE detection
• canonical staging
• future compatibility

---

Acknowledgements and Contributions

The trajectory file export functionality of Step 8 is an extension of the TUS_entry toolbox developed by Cyril Atkinson-Clement.