Home

Awesome

<div id="top"></div>

Contributors Forks Stargazers Issues MIT License LinkedIn GitHub Actions

"Buy Me A Coffee"

<!-- PROJECT LOGO --> <br /> <div align="center"> <a href="https://github.com/othneildrew/Best-README-Template"> <img src="./src/assets/appIcons/ExploreASLGUI_Logo_LightMode.png" fill="red" alt="Logo" width="100" height="100"> </a> <h3 align="center">ExploreASL GUI</h3> <p align="center"> Scanner To Publication User Interface for ASL Imaging <br /> <br /> <a href="https://github.com/MauricePasternak/ExploreASL-GUI/issues/new?assignees=MauricePasternak&labels=bug&template=bug_report.md&title=">Report Bug</a> · <a href="https://github.com/MauricePasternak/ExploreASL-GUI/issues/new?assignees=MauricePasternak&labels=enhancement&template=feature_request.md&title=">Request Feature</a> · <a href="https://mauricepasternak.github.io/ExploreASL-GUI-Docs/latest">Documentation</a> · <a href="https://github.com/MauricePasternak/ExploreASL-GUI/releases">Download</a> </p> </div> <!-- TABLE OF CONTENTS --> <details open> <summary>Table of Contents</summary> <ol> <li> <a href="#about-the-project">About The Project</a> <ul> <li><a href="#built-with">Built With</a></li> </ul> </li> <li> <a href="#download">Download</a> </li> <li> <a href="#documentation">Documentation</a> </li> <li> <a href="#download">Download</a> </li> <li> <a href="#workflow">Workflow</a> <ul> <li><a href="#1-import-your-dataset">1) Import Your Dataset</a></li> <li><a href="#2-verify-bids">2) Verify BIDS</a></li> <li><a href="#3-define-processing-parameters">3) Define Processing Parameters</a></li> <li><a href="#4-run-exploreasl">4) Run ExploreASL</a></li> <li><a href="#5-visualize-your-results">5) Visualize Your Results</a></li> </ul> </li> <li><a href="#roadmap">Roadmap</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li> <a href="#acknowledgments">Acknowledgments</a> <ul> <li><a href="#support">Support</a></li> <li><a href="#exploreasl-team">ExploreASL Team</a></li> </ul> </li> </ol> </details>
<!-- ABOUT THE PROJECT -->

About The Project

This project wraps around ExploreASL to provide users with a friendly and modern interface for analyzing their arterial spin labeling datasets, including:

Built With

Electron React MaterialUI

<p align="right">(<a href="#top">back to top</a>)</p>
<!-- RELEASES -->

Download

The latest downloadable releases for your operating system can be found here.

<p align="right">(<a href="#top">back to top</a>)</p>
<!-- DOCUMENTATION -->

Documentation

Complete documentation for this project is hosted on GitHub Pages. While it is recommended to give it a general read-through before using the application, most of the inputs within the application are accompanied by helper captions that provide additional information when completing a specific step.

<p align="right">(<a href="#top">back to top</a>)</p>
<!-- GETTING STARTED -->

Getting Started

Installation Instructions For Users

1) Get the pre-requisites

Depending on the type of ExploreASL installation you have, you will need either:

OR

2) Download the latest release of this project and install it on your local machine

Head on over to the Releases and download the appropriate version for your operating system

3) Run your OS-specific installer

Windows

Just double-click the installer. The application will be silently installed in the background and will finish when a Desktop shortcut is created.

Linux

Open a terminal, change the current working directory to the location of the .deb file and type in:

sudo apt install ./exploreasl-gui_0.5.0_amd64.deb

Where the version number within the filename may differ depending on the latest release.

The GUI will then be installed and a shortcut is automatically available from typing out exploreasl in your Super key search bar.

macOS

Open the .dmg file and drag the application to your Applications folder. The application will then be available from your Launchpad.

NOTE: The application is not signed, and in all likeliness you will receive an error message akin to the following the first time you run the application:

macOS 1st Unauthorized Message

Click on Cancel and then go to your Security & Privacy settings. Under the General tab, click on "Open Anyway" to allow the application to run.

macOS Security & Settings

The second time you run the application, you will be prompted with a similar message, but this time you will be able to click on "Open" to run the application.

macOS 2nd Warning Message

After this, you will be able to run the application without any issues and you will not be prompted with any more warning messages for subsequent attempts.

Uninstallation/Removal Instructions For Users

Windows

In your search bar, look for "Add or remove programs". Select the application and click uninstall.

Linux

Open a terminal and type in:

sudo apt remove exploreasl-gui

macOS

Go to the Applications folder and drag & drop the ExploreASL-GUI.app application to the Trash bin.

Installation Instructions For Developers

1) Ensure that you have NodeJS and NPM installed on your machine

Click here for more information on NodeJS installation.

2) Ensure that you have the yarn package manager installed on your machine

Simply install it via the command line:

npm install --global yarn

3) Clone the repo and install the dependencies

General Project Structure

/---|
    |-> assets (media such as icons)
    |-> backend (logic executed by electron's IpcMain, i.e. spawning subprocesses to run ExploreASL)
    |-> common -|
    |           |-> schemas (form validators & form schemas)
    |           |-> types (reusable types & typescript declarations)
    |           |-> utilityFunctions (reusable functions for reducing code use)
    |           |-> GLOBALS.ts (global variables used throughout)
    |
    |-> components (reuseable React components)
    |-> ipc (logic for type-safe IpcMain <-> IpcRenderer communication)
    |-> pages (non-reuseable React components that make up the pages of the GUI)
    |-> stores (frontend-only collections of user-interface state)
    ... other files relate to project setup, package-handling, etc.
<p align="right">(<a href="#top">back to top</a>)</p>
<!-- USAGE EXAMPLES -->

Workflow

1) Import Your Dataset

To start off with, you'll have to convert the output from your DICOM scanner(s) into proper Brain Imaging Data Structure (BIDS) format.

This is accomplished via a 4-step procedure:

  1. Define the pieces of information found in the folder names leading to the DICOM files (i.e. does a folder name contain the subject ID, the session ID, etc.)
  2. Define which folders account for which type of scan (i.e. ASL, T1w, T2w, etc.) and whether you'd like to have any visits/sessions renamed.
  3. Define how the various scans present with the dataset were acquired (see image below). This includes parameters like Post Labeling Delay, Background Suppression, etc.
  4. Run ExploreASL's Import Module.
<p align="center"> <img src="./src/assets/img/READMEImages/ImportModule.png" style="width: 100%" /> </p> <p align="right">(<a href="#top">back to top</a>)</p>

2) Verify BIDS

Once a study has been imported to BIDS format, you can verify appropriate parameters are present for processing ASL by loading all BIDS sidecars into an interactive datagrid with built-in BIDS Validation (see below).

The datagrid allows for easy editing of BIDS fields with immediate feedback on whether the changes are valid or not. This is especially useful when dealing with anonymized datasets that lack certain fields.

<p align="center"> <img src="./src/assets/img/READMEImages/BIDSDatagridModule.png" style="width: 100%" /> </p> <p align="right">(<a href="#top">back to top</a>)</p>

3) Define Processing Parameters

There are a plethora of parameters tied to defining how an ASL-BIDS dataset should be processed. ExploreASL-GUI helps you define these parameters in a repeatable and reviewable manner.

Parameters are divided into 3 subsections:

  1. Study parameters (where is the study, what is its name, which subjects should be processed specifically, etc.)
  2. Modeling parameters (will a single or dual compartment model be used, what is the assumed T2* of the blood, etc.)
  3. ExploreASL pipeline parameters (which atlases to use when quantifying CBF ROIs, what should be the T-value for motion control, etc.)

Configurations can be easily saved with validation and re-loaded when tweaking settings.

<p align="center"> <img src="./src/assets/img/READMEImages/DefineDataParametersModule.png" style="width: 100%" /> </p> <p align="right">(<a href="#top">back to top</a>)</p>

4) Run ExploreASL

ExploreASL-GUI allows for multiprocessing of several studies and/or several subjects per study in parallel, making the most of your computer's resources.

Percent completion, text feedback, and visual QC images of processed structural and functional images are provided while the pipeline is running (see below).

<p align="center"> <img src="./src/assets/img/READMEImages/RunExploreASLModule.png" style="width: 100%" /> </p> <p align="right">(<a href="#top">back to top</a>)</p>

5) Visualize Your Results

ExploreASL-GUI allows for streamlined QC analysis and overall visualization of the processed datasets. Users are given the ability to merge their own demographics/clinical/neuropsyche ancillary data with the CBF data generated by ExploreASL and represented as interactive graphs of 2 flavors:

Emphasis on interactive. Clicking on datapoints will allow for the corresponding CBF volume to the loaded in for visual inspection across all dimensions and slices.

Plots with accompanying CBF volumes can be saved as PNGs for you publication purposes.

<p align="center"> <img src="./src/assets/img/READMEImages/DataVisualizationModule.png" style="width: 100%" /> </p> <p align="right">(<a href="#top">back to top</a>)</p>

<!-- ROADMAP -->

Roadmap

See the open issues for a full list of proposed features (and known issues).

<p align="right">(<a href="#top">back to top</a>)</p>

<!-- CONTRIBUTING -->

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.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request
<p align="right">(<a href="#top">back to top</a>)</p>

<!-- LICENSE -->

License

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

<p align="right">(<a href="#top">back to top</a>)</p>

<!-- CONTACT -->

Contact

Maurice Pasternak - maurice.pasternak@utoronto.ca

Project Link: https://github.com/MauricePasternak/ExploreASL-GUI

<p align="right">(<a href="#top">back to top</a>)</p>

<!-- ACKNOWLEDGMENTS -->

Acknowledgments

Support

For GUI-related questions, please don't hesitate to drop an email at: maurice.pasternak@utoronto.ca

For more information on the main program, click on the following: CLICK ME!

ExploreASL Team

For questions or concerns with the underlying ExploreASL program, the following individuals compromise the development team and may be contacted:

<p align="right">(<a href="#top">back to top</a>)</p>
<!-- MARKDOWN LINKS & IMAGES --> <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --> <!-- Badges -->