Open-Source Toolbox for Clinical-Translational MRI Research€¦ · “Mode” = Chain of...
Transcript of 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
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
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
Yarra Offline Reconstruction Pipeline
Yarra Offline Reconstruction Pipeline
▪ 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
Yarra Offline Reconstruction Pipeline
▪ “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
Yarra Offline Reconstruction Pipeline
▪ 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
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
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
SortIndex=10
RequiresACC=true
RequiresAdjScans=true
“ClientConfig“ Section
▪ Mode automatically assigned if “tag” found in protocol name:
GRASP ax_YB
▪ Information used by Yarra clients for task submission
[ClientConfig]
Name=GRASP Abdomen
Tag=_YB
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
▪ 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