open-source toolbox for clinical-translational mri research€¦ · “mode” = chain of...

Open-Source Toolbox for

Clinical-Translational MRI Research

Center for Advanced Imaging Innovation and Research (CAI2R)

New York University School of Medicine

Klinik für Radiologie und Nuklearmedizin

Universitätsspital Basel

Agenda

▪ Demo will only cover the Offline Reconstruction Pipeline

▪ Information on Raw-Data Collection & Workflow Monitoring:

http://yarraframework.com

Agenda

1. Overview & server requirements

2. Developing Yarra modules

3. How to integrate Matlab-written algorithms

4. How to integrate a BART module

5. How to package and share your algorithm

Overview

Yarra Offline Reconstruction Pipeline

▪ Aim: Run demanding algorithms on external Linux server(s)

PACS

Network

Share

MR Scanner

Workstation

ORT

Client

SAC

Client

Linux Server

YarraServer

Processing Modules

Raw Data (Twix)

+Task Definition

Queue

▪ On scanner: “ORT Client”

▪ Select patient scan

▪ On workstation: “SAC Client”

▪ Select saved Twix file



▪ YarraServer executes one “Reconstruction Mode” per task

▪ “Mode” = Chain of processing modules + Settings

▪ Modes configured centrally on server

▪ Yarra Client assigns mode during submission of task

(via protocol name or manual selection)

PreprocessingPreprocessingPre-Processing Reconstruction PreprocessingPreprocessingPost-ProcessingggTransfer

0 – 20 1 0 – 20 1 – 20


▪ “Module” can be any program running on Linux

▪ Server organizes data and executes modules in right order

▪ Server monitors modules to ensure high server availability

▪ Termination if unreasonable behavior detected

1. Excessive memory usage (to avoid “swap-to-death”)

2. Too long processing duration

3. No output for too long time

▪ Thresholds can be configured / disabled


▪ Terminated tasks moved to “Failed Folder”

▪ Successful tasks moved to “Completed Folder”

▪ Can be restarted by user, or archived for later processing

▪ Output of all modules captured in log file

▪ Facilitates debugging of modules

▪ Email notification service

(log-file attached)

Yarra Server Requirements

▪ Ubuntu Linux (16.04 or newer recommended)

▪ Server process running as daemon

▪ Incoming tasks received via Samba share

▪ Step-by-step installation instructions: http://yarraframework.com

▪ Configuration & server control done via Yarra WebGUI

Yarra WebGUI

▪ Typically running on port :8080

▪ Also works on smartphones

▪ User login with different access:

Level 1 = View task status

Level 2 = Modify or restart tasks

Level 3 = Control server and

configure modes

Yarra WebGUI – Demo

Open Browser

Developing Yarra Modules

What is a Yarra Module?

▪ Can be any program that runs on Linux

▪ Task information passed to module as command-line arguments

▪ Arguments for binary calls defined in “Reconstruction Mode”

▪ Simple “helper macros” to write module calls

▪ Interpreted by YarraServer when executing modules

Different Module Types

▪ Reconstruction Modules

▪ Transfer Modules

▪ Post-Processing Modules

▪ Pre-Processing Modules

PreprocessingPreprocessingPre-Processing Reconstruction PreprocessingPreprocessingPost-ProcessingggTransfer

0 – 20 1 0 – 20 1 – 20

Reconstruction Modules

▪ Purpose: Perform reconstruction of submitted raw data

▪ Duties: 1. Read given raw-data file

2. Run algorithm

3. Write results into given output folder (as DICOMs)

▪ Not necessary to fill DICOM tags (done by “SetDCMTags”)

▪ Can use given temporary folder if needed

▪ One reconstruction module per modeReconstruction

Transfer Modules

▪ Purpose: Transfer results to storage location (e.g. PACS)

▪ Duties: 1. Process files in given transfer folder

▪ Files in folder must not be deleted or modified

▪ One to 20 transfer modules per mode (executed sequentially)

ggTransfer

Post-Processing Modules

PreprocessingPreprocessingPost-Processing

▪ Purpose: Analyze or modify results (e.g. calculate subtractions)

▪ Duties: 1. Analyze files in given input folder

2. Create modified or additional results in output folder

3. Move other to-be-kept files to output folder

▪ Only files in output folder will be passed on

▪ Files in input folder will be discarded

▪ Zero to 20 post-processing modules (chain)

Pre-Processing Modules

▪ Purpose: Prepare information or settings for reconstruction

▪ Duties: 1. Analyze given raw-data file

2. Write information into given work folder

▪ Example: Convert raw data to ISMRMD format

▪ Created files accessible by all subsequent modules

▪ Zero to 20 pre-processing modules (sequential chain)

PreprocessingPreprocessingPre-Processing

Included Modules

Name Type Description

PACSTransfer Transfer Sends results to PACS or workstation

DriveTransfer Transfer Stores results on network share

SetDCMTags Post-Processing Fills DICOM tags of reconstructed images from Twix file

Subtraction Post-Processing Calculates subtractions from reconstructed images

IniPatch Pre-Processing Patches settings in configuration (ini) files

GRASP Reconstruction CS-based DCE-MRI reconstruction (available via C2P)

Defining Reconstruction Modes

▪ “Mode” defines which modules are executed + settings

▪ Edited in WebGUI or with external text editor

▪ Text file with “.ini format” (in folder /yarra/modes)

▪ Required sections:

[ClientConfig]

[Options]

[PreProcessing]

[Reconstruction]

[PostProcessing]

[Transfer]

Binary paths and arguments for

module calls

Client-related settings, e.g. readable name

Additional server processing options

Example: GRASP Reconstruction;## YarraServer -- Reconstruction Mode Definition

;##

[ClientConfig]

Name=GRASP Abdomen

Tag=_YB

[email protected]

SortIndex=10

[Options]

KeepRawdata=true

[Reconstruction]

Bin=%bu/GRASP/GraspR

Args=%rid/%rif %rid/settings.ini %rod %tmp %vacc

[Transfer]

Bin=%bd/DriveTransfer

Args=%mc %td %vuid

[DriveTransfer]

TargetPath=/home/yarraserver/output

Settings for the client

Options for the server

Selection of recon module

Selection of transfer module

Module-specific settings

Example: GRASP Reconstruction

[Transfer]

Bin=%bd/DriveTransfer

Args=%mc %td %vuid

Linux binary

to-be-executed

Command-line

arguments

Example: GRASP Reconstruction

[Transfer]

Bin1=%bd/DriveTransfer

Args1=%mc %td %vuid

Bin2=%bd/PACSTransfer

Args2=%mc %td

Linux binary

to-be-executed

Command-line

arguments

Helper macros

▪ Required arguments depend on the individual module

Helper Macros

▪ Used to pass file/folder names to modules

▪ Make mode definitions independent from installation paths

▪ Examples:

%rif = Name of raw-data (Twix) file to-be-reconstructed%rif → grasp_abdomen#SAvantoFit#F146888#M117#D240419#T082316.dat

%hmb = Installation path of Matlab binary%hmb → /usr/local/bin/matlab

Available Macros

▪ List of available

macros shown

in WebGUI by

pressing “Help”

button

▪ Information used by Yarra clients for task submission

[ClientConfig]

Name=GRASP Abdomen

Tag=_YB

[email protected]

SortIndex=10

RequiresACC=true

RequiresAdjScans=true

“ClientConfig“ Section

▪ Mode automatically assigned if “tag” found in protocol name:

GRASP ax_YB

User-Selected Parameters

▪ Client can ask for “parameter” during submission

▪ Enables user to manually select reconstruction setting

[ClientConfig]

Name=GRASP Abdomen

Tag=_YB

ParamLabel=Spokes

ParamDescription=Number of spokes per frame

ParamMin=5

ParamMax=9999

ParamDefault=21

▪ Value accessible via helper macro %vparam

How to Develop Yarra Module?

▪ Step 1: Choose language / framework (e.g. Matlab, BART)

▪ Step 2: Implement “entry function” as interface:

function MyRecon(raw_file, output_folder, temp_folder)

▪ Step 3: Write mode file that calls function (using helper macros):

MyRecon(%rid/%rif, %rod, %tmp)

▪ Step 4: Package module & deploy

Integration of Matlab Code

Demo Algorithm

▪ Example: Simple FFT reconstruction for 3D GRE scans

▪ Step 1: Write Matlab function with algorithm

1. Load Twix data

2. Perform 3D FFT for each channel

3. Calculate sum-of-squares images

4. Crop center (to remove 2x readout oversampling)

5. Write images as DICOMs (without tags)

Demo Algorithm

▪ Step 2: Write mode definition that executes Matlab

1. Call Matlab function as reconstruction

2. Call SetDCMTags module to populate DICOM tags

3. Call DriveTransfer module to store images

Writing the Matlab Function

▪ “mapVBVD” package for reading Twix files

▪ Matlab “dicomwrite” function for saving images

Open Matlab Function

Writing the Mode File

▪ Matlab started in non-UI mode (“-nodesktop -nosplash -nojvm”)

▪ Function launched via “-r” argument

▪ Here: Matlab command wrapped in script “entrypoint.sh”

Open Mode File

Open Entry-Point Script

Testing it!

▪ YarraServer running in virtual machine (VirtualBox)

▪ Task submitted using Yarra SAC Client

▪ Reconstructed images stored on Samba share

Open SAC

Open Browser

Open DICOM Viewer

Integration of BART Modules

About BART

▪ MRI reconstruction toolbox developed by research groups of

Martin Uecker (Göttingen) and Michael Lustig (Berkeley)

▪ Implements many calibration and reconstruction algorithms

for parallel imaging and compressed sensing

▪ http://mrirecon.github.io/bart

▪ Yarra can be used to make BART algorithms

available on clinical scanners

BART Integration

▪ BART provides Linux command-line tools

▪ Scriptable using Bash shell scripts

▪ Script can be launched as Yarra reconstruction module

Open Recon Script

Open Entry Function

Open Mode File

Demo

Open SAC

Open Browser

Open DICOM Viewer

Module Packaging

Integrated Module Installer

▪ Installation & update of modules possible via WebGUI

▪ Similar to WordPress plugin installation

▪ Folder created in:

/yarra/modules_user

▪ Helper macro: %bu

Manifest File

▪ Packaged module = ZIP archive with manifest file

▪ Text file with extension .yml (.ini format)

▪ Used for version management & info display in WebGUI

[YarraModule]

Name=Matlab Sample

Description=Simple example that shows how to integrate Matlab

Version=1

Author=Roy Wiggins

Homepage=yarraframework.com

RequiresMatlab=true

Demo

Open Folder

Open Browser

Multi Server Operation

Load Balancing

▪ YarraServer processes 1 task per time (“max-out resources”)

▪ Many scans → tasks waiting in queue

▪ Distribution of tasks to multiple servers possible

▪ Simple load-balancer integrated in Yarra ORT client

▪ Server list read from “seed server”

▪ “Round robin” strategy for sending tasks to servers

Task Routing

▪ Servers can declare “features” (e.g. GPU) in server list

▪ Reconstruction modes can request server features

▪ Yarra client routes tasks to server with feature

▪ If multiple servers, load balancing within suited servers

Outlook: Cloud Processing

YarraCloud Reconstruction Service

▪ Cloud-driven reconstruction service running on AWS

▪ Eliminates need to purchase & install server

▪ Pay-per-use model → scales with institutional demand

▪ Containerized version of YarraServer

▪ PHI removal prior to cloud upload

▪ More information: http://yarracloud.com

▪ Documentation: http://yarraframework.com

▪ Source code: http://bitbucket.org/yarra-dev

▪ All code released under GNU Public License (GPL)

▪ Please contribute!

▪ Support chat: https://gitter.im/yarra-dev

▪ Please use instead of email

Support and Resources

h t t p : / / ya r r a f r a m e w o r k . c o m

open-source toolbox for clinical-translational mri research€¦ · “mode” = chain of...

Documents