---

---

📋 Table of Contents

1. About The Project
2. Built With
3. Prerequisites
4. Installation
5. Workflow
6. Developer Setup
7. Testing
8. Roadmap
9. Contributing
10. License
11. Acknowledgments

---

🧠 About The Project

ExploreASL GUI provides a friendly, modern desktop interface around the ExploreASL MATLAB pipeline for processing Arterial Spin Labeling (ASL) MRI data. Whether you are a clinical researcher with dozens of subjects or a methods developer fine-tuning pipeline parameters, this GUI guides you through the entire analysis lifecycle without requiring you to write a single line of MATLAB.

Key Capabilities

Feature	Description
📂 Dataset Import	Organize raw DICOM/NIfTI data into BIDS format using a flexible source-data staging tree
🔍 Metadata Configuration	Define ASL sidecar JSON fields (labelling type, PLD, etc.) with per-scan override groups during import
⚙️ Parameter Configuration	Configure ExploreASL processing parameters (dataPar.json) through structured forms with basic/advanced field toggles
▶️ Pipeline Execution	Select subjects and modules (Structural / ASL / Population) with real-time progress tracking via .status lock files
📊 Results Visualization	Explore population statistics via scatter/swarm plots and inspect subject-level qCBF NIfTI volumes interactively
🔄 Selective Re-run	Re-process specific subjects or modules; stale locks, status files, and logs are cleaned automatically before each run

---

🛠 Built With

Layer	Technology
Desktop shell	Tauri v2 (Rust backend, WebView2 / WebKit frontend)
UI Framework	React 19 + TypeScript 6
Component Library	Mantine 9
State Management	Zustand 5
Schema Validation	Zod 4
Routing	React Router 7
Forms	React Hook Form 7
Build Tool	Vite 8
Testing	Vitest 4 + Testing Library

(back to top)

---

📋 Prerequisites

Before running ExploreASL GUI you will need two dependencies installed separately:

Dependency	Version	Link
MATLAB	R2019a or later	mathworks.com/downloads
ExploreASL	v11.1.0 or later (v2+ / develop branch preferred)	github.com/ExploreASL/ExploreASL

Platform Dependencies (for running from source only)

Dependency	Notes
Rust toolchain	Stable channel, ≥ 1.77
Node.js	≥ 20 LTS
pnpm	≥ 9
Tauri v2 system deps	Platform-specific (WebView2 on Windows, WebKit on Linux/macOS)

(back to top)

---

📦 Installation

Download a Pre-built Release (recommended for end users)

Head to the Releases page and download the installer for your operating system.

🪟 Windows

Double-click the .msi installer. The app will be installed silently and a Start Menu shortcut will be created.

🐧 Linux

sudo apt install ./exploreasl-gui_<version>_amd64.deb

After installation, type exploreasl in your application launcher.

🍎 macOS

Open the .dmg and drag the application bundle to your Applications folder.

(back to top)

---

🔧 Setting Up MATLAB & ExploreASL

The GUI requires both MATLAB and ExploreASL to be installed on your machine before it can process data. Follow the steps below for your operating system.

Step 1 — Install MATLAB

1. Go to mathworks.com/downloads and sign in with your MathWorks account. If you do not have one, your institution may provide a campus license — check with your IT or licensing department.
2. Download the MATLAB installer for your operating system (Windows, macOS, or Linux).
3. Run the installer. When prompted, select R2019a or later (R2023b or newer recommended). You do not need any additional toolboxes for ExploreASL.
4. Complete the installation and launch MATLAB once to confirm it opens without errors.

Step 2 — Install ExploreASL from GitHub

ExploreASL is a free, open-source MATLAB toolbox. You obtain it by downloading or cloning it from GitHub.

Option A — Download the ZIP (no Git required)

1. Go to github.com/ExploreASL/ExploreASL.
2. Near the top of the page, you will see a dropdown button that says main. Click it and select develop — this is the recommended version.
3. Click the green <> Code button, then select Download ZIP.
4. Extract the ZIP file:
   • Windows: Right-click the downloaded .zip file and select Extract All…, then click Extract. Move the extracted folder to a location like C:\ExploreASL.
   • macOS: Double-click the .zip file (Safari extracts it automatically). Move the resulting folder to a location like your home folder (the folder with your username).
   • Linux: Right-click the .zip file and select Extract Here, or run unzip ExploreASL-develop.zip in a terminal. Move the folder to a location like /home/your-username/ExploreASL.

Option B — Clone with Git

If you are comfortable with the command line:

git clone --branch develop https://github.com/ExploreASL/ExploreASL.git

This clones the latest develop branch (v2+), which is the recommended version.

Step 3 — Configure Execution Profiles

Instead of a single global path, ExploreASL GUI uses Execution Profiles to manage how the ExploreASL pipeline is run. This allows you to configure multiple installations or execution methods and switch between them.

1. Onboarding: When launching the app with no configured profiles, a welcome card is shown blocking project actions. Click Open Settings to set up your first profile.
2. Add Profile: In global Settings under Execution Profiles, click Add Profile and choose a profile type (currently MATLAB).
3. Paths Configuration:
   • MATLAB Path: Enter the path to the MATLAB executable (e.g. /usr/local/MATLAB/R2024b/bin/matlab on Linux/macOS or C:\Program Files\MATLAB\R2024b\bin\matlab.exe on Windows). You can click Detect MATLAB to search your system automatically or Browse to choose it manually.
   • ExploreASL Path: Browse to the folder where you extracted or cloned ExploreASL in Step 2 (containing ExploreASL.m).
4. Validation: Click Save. The GUI runs a validation command to ensure the MATLAB executable works, ExploreASL.m exists, and detects the ExploreASL version automatically.

You can add multiple profiles and switch between them from the dropdown selectors on the Import and Processing pages.

(back to top)

---

🔄 Workflow

ExploreASL GUI follows a three-phase analysis pipeline:

Raw DICOM / NIfTI
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│  Import Module                                          │
│  Ingest → Tokenize → Resolve Aliases → Metadata → Run   │
│  Stage source data into BIDS with configured sidecars   │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│  Parameters Module                                      │
│  Configure dataPar.json (Structural, ASL, Population)   │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│  Processing Module                                      │
│  Select subjects → Run modules → Monitor progress       │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│  Visualization Module                                   │
│  Scatter/swarm plots of ROI stats + NIfTI volume viewer │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│  Manifest Module                                        │
│  QC triage (Pass/Fail) → Preview → Export methods doc   │
└─────────────────────────────────────────────────────────┘

Import Dataset

ExploreASL GUI supports two different pathways to import your dataset, depending on the format of your raw files:

Pathway A: DICOM Import Wizard (default)

Use this if you have raw scanner DICOM files. The wizard walks you through five sub-steps:

1. Ingest DICOMs — Select your source directory and scan for DICOM files, with optional subfolder grouping
2. Tokenize Paths — Map folder hierarchy levels to BIDS identifiers (Subject / Session / Run / Modality)
3. Resolve Aliases — Rename subjects, order sessions/runs, and map raw scan labels to BIDS modality types
4. Acquisition Metadata — Configure ASL-specific parameters (labelling type, PLD, labelling duration) with per-scan overrides
5. Preview & Run — Review the staging layout and dataPar.json, then execute the import via dcm2niix

Pathway B: Direct BIDS Import (Skip Import)

Use this if you already have a BIDS-compliant dataset (containing NIfTI images, sidecar .json metadata, and _aslcontext.tsv files).

1. Select the BIDS folder during project creation.
2. The landing detection dialog will detect the existing BIDS structure and prompt you to Skip Import.
3. This opens the BIDS Review Panel, which automatically scans all subject sidecars, groups scans with matching acquisition parameters, and flags any skipped subjects (e.g. subjects with missing/unparseable files).
4. Assign group labels and click Confirm to populate project mappings and transition directly to pipeline parameters configuration.

Configure Global Project Data Parameters

Configure the ExploreASL dataPar.json through structured forms covering Structural, ASL, Population, and Atlas settings. Basic fields are shown by default; advanced fields are revealed per section.

Processing Pipeline Execution

Select the subjects and pipeline modules (Structural / ASL / Population) you want to process. The GUI spawns MATLAB worker processes and tracks progress via ExploreASL's .status lock files, showing per-subject step completion in real time.

Visualize Results

Load population-level statistics TSV files and explore data via scatter and swarm plots. Click any data point to load the corresponding subject's qCBF NIfTI volume in an interactive 3D viewer.

Project Manifest

After the Population pipeline completes, review per-subject QC metrics (ASL coverage, spatial CoV, motion, motion exclusion) and assign Pass / Fail verdicts with reasons. Stale detection flags verdicts set before the latest Population re-run. Export a self-contained Markdown or HTML document with per-group study parameters, software versions, QC summary statistics, and auto-generated methods paragraphs with full citations — ready for a paper's methods section or supplementary materials.

(back to top)

---

💻 Developer Setup

# 1. Clone the repository
git clone https://github.com/MauricePasternak/ExploreASL-GUI.git
cd ExploreASL-GUI

# 2. Install JavaScript dependencies
pnpm install

# 3. Start the development server (hot-reload, browser preview at http://localhost:1420)
pnpm dev

# 4. Start the full Tauri development app (requires a desktop environment)
pnpm tauri dev

Project Structure

ExploreASL_GUI/
├── src/                    # React frontend (TypeScript)
│   ├── components/         # Reusable UI components
│   ├── pages/              # Route-level page components
│   ├── stores/             # Zustand state stores
│   ├── lib/                # Utilities, schemas, debug tools
│   └── test/               # Test setup & mocks
├── src-tauri/              # Rust backend (Tauri)
│   ├── src/                # Rust source files
│   └── icons/              # Application icons
├── openspec/               # Feature specs (authoritative)
│   └── specs/              # Canonical specifications
├── e2e-tests/              # End-to-end tests (WebdriverIO + tauri-driver)
└── test/                   # Test data & datasets

Project State

• Project file: <root>/project.easl — JSON file storing the current project state
• Global settings: Stored via @tauri-apps/plugin-store (settings.json) in the OS app data directory
• Dev logs: <OS temp dir>/exploreasl-gui-logs/dev.log (uses std::env::temp_dir(), e.g. /tmp on Linux, %TEMP% on Windows)

(back to top)

---

🧪 Testing

# Run unit tests (Vitest)
pnpm test

# Run unit tests in watch mode
pnpm test:watch

# Run end-to-end tests (requires a debug build at src-tauri/target/debug/exploreasl_gui)
pnpm test:e2e

Unit tests cover schemas, Zustand stores, and utility functions. Component tests cover critical UI paths. E2E tests drive the native Tauri window via tauri-driver + WebdriverIO.

(back to top)

---

🗺 Roadmap

• Core project scaffolding (Tauri v2 + React + Mantine)
• Dataset import with BIDS staging tree
• ASL metadata configuration with per-scan overrides
• Processing parameter configuration (dataPar.json)
• Pipeline execution with real-time progress tracking
• Results visualization (population stats + NIfTI viewer)
• Project manifest export
• Import BIDS-ready datasets
• Auto-update support
• Documentation site

See open issues for a full list of planned features and known bugs.

(back to top)

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the repository
2. Switch to the develop branch (git checkout develop)
3. Create your feature branch (git checkout -b feature/AmazingFeature)
4. Commit your changes using Conventional Commits (e.g. feat: add CBF viewer)
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request
7. Apply appropriate labels to your Pull Request (e.g., enhancement, bug, documentation) so that the automated release notes classify the changes correctly.

Please read the AGENTS.md file for coding conventions, testing requirements, and agent guidelines before contributing.

(back to top)

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

---

🙏 Acknowledgments

ExploreASL Team

This GUI is built around ExploreASL, an open-source MATLAB/SPM-based pipeline for ASL MRI data analysis, developed and maintained by the ExploreASL community. Please cite the ExploreASL paper if you use this software in your research:

Mutsaerts, H.J.M.M., et al. (2021). ExploreASL: An image processing pipeline for multi-center ASL perfusion MRI studies. NeuroImage, 225, 117549. https://doi.org/10.1016/j.neuroimage.2020.117549

Previous Version

The original Electron-based ExploreASL GUI is preserved at MauricePasternak/ExploreASL-GUI (electron-v1 branch). This Tauri v2 rewrite supersedes it with a significantly smaller binary footprint, improved security, and a modernized tech stack.

Built With Open Source

• Tauri — Cross-platform desktop framework
• Mantine — React component library
• ExploreASL — The underlying pipeline

(back to top)