--- a
+++ b/readme.md
@@ -0,0 +1,199 @@
+# HD-GLIO
+
+## Introduction
+
+This repository provides easy to use access to our HD-GLIO brain tumor segmentation tool. HD-GLIO is the result of a 
+joint project between the Department of Neuroradiology at the Heidelberg University Hospital, Germany and the 
+Division of Medical Image Computing at the German Cancer Research Center (DKFZ) Heidelberg, Germany. If you are using 
+HD-GLIO, please cite the following two publications:
+
+- Kickingereder P, Isensee F, Tursunova I, Petersen J, Neuberger U, Bonekamp D, Brugnara G, Schell M, Kessler T, 
+Foltyn M, Harting I, Sahm F, Prager M, Nowosielski M, Wick A, Nolden M, Radbruch A, Debus J, Schlemmer HP, Heiland S, 
+Platten M, von Deimling A, van den Bent MJ, Gorlia T, Wick W, Bendszus M, Maier-Hein KH. Automated quantitative tumour 
+response assessment of MRI in neuro-oncology with artificial neural networks: a multicentre, retrospective study. 
+Lancet Oncol. 2019 May;20(5):728-740. (https://doi.org/10.1016/S1470-2045(19)30098-1)
+- Isensee F, Petersen J, Kohl SAA, Jaeger PF, Maier-Hein KH. nnU-Net: Breaking the Spell on 
+Successful Medical Image Segmentation. arXiv preprint 2019 arXiv:1904.08128. (https://arxiv.org/abs/1904.08128)
+
+HD-GLIO was developed with 3220 MRI examinations from 1450 brain tumor patients (80% for training and 20% for testing). 
+Specifically the data included:
+1) a single-institutional retrospective dataset with 694 MRI examinations from 495 patients acquired at the 
+Department of Neuroradiology, Heidelberg University Hospital, Germany (corresponding to the “Heidelberg training 
+dataset and Heidelberg test dataset” described in Kickingereder et al. Lancet Oncol. 2019)
+2) a multicentric clinical trial dataset with 2034 MRI examinations from 532 patients acquired across 34 institutions 
+in Europe  (corresponding to the “EORTC-26101 test dataset” described in Kickingereder et al. Lancet Oncol. 2019)
+3) a single-institutional retrospective dataset with 492 MRI examinations from 423 patients (80% glial brain tumors, 
+20% other histological entities) undergoing routine MRI at different stages of the disease (including 79 early 
+postoperative MRI scans acquired <72h after surgery) at the Department of Neuroradiology, Heidelberg University 
+Hospital, Germany 
+ 
+Specifically, each MRI examination included precontrast T1-weighted, postcontrast T1-weighted, T2-weighted and FLAIR 
+sequences (all sequences brain extracted and co-registered) as well as corresponding ground-truth tumor segmentation 
+masks. HD-GLIO performs brain tumor segmentation for contrast-enhancing tumor and non-enhancing T2/FLAIR signal 
+abnormality. We applied a variant of the nnU-Net ('no-new-Net') framework (as described in Isensee et al. arXiv preprint 2019) 
+for training the HD-GLIO algorithm.
+
+HD-GLIO is very fast on GPU with <10s run time per MRI examination. 
+
+## Installation Instructions
+
+###  Installation Requirements
+Unlike HD-BET, HD-GLIO requires a GPU to perform brain tumor segmentation. Any GPU with 4 GB of VRAM and cuda/pytorch 
+support will do. 
+Running the prediction on CPU is not supported.
+
+### Installation with Pip
+Installation with pip is quick an easy, just run the following command and everything will be done for you:
+
+`pip install hd_glio`
+
+### Manual installation
+If you intend to modify HD-GLIO, you can also install is manually:
+
+1) Clone this repository:
+    
+    `git clone https://github.com/MIC-DKFZ/HD-GLIO`
+
+2) Go into the repository (the folder with the setup.py file) and install:
+
+    `cd HD-GLIO`
+
+    `pip install -e .`
+
+Per default, model parameters will be downloaded to ~/.hd_glio_params. If you wish to use a different folder, open 
+hd_glio/paths.py in a text editor and modify folder_with_parameter_files.
+
+
+Both manual and pip installation will install two commands with which you can use HD-GLIO from anywhere in your 
+system: `hd_glio_predict` and `hd_glio_predict_folder`.
+
+## How to use it
+Using HD_GLIO is straightforward. You can use it in any terminal on your linux system. The `hd_glio_predict` and 
+`hd_glio_predict_folder` commands were installed automatically. HD-GLIO requires a GPU with at least 4 GB of VRAM to run. 
+
+### Prerequisites
+HD-GLIO was trained with four MRI modalities: T1, constrast-enhanced T1, T2 and FLAIR. All these modalities must be present
+in order to run HD-GLIO. 
+
+All input files must be provided as nifti (.nii.gz) files containing 2D or 3D MRI image data. Sequences with 
+multiple temporal volumes (i.e. 4D sequences) are not supported (however can be splitted upfront into the individual 
+temporal volumes using fslsplit1). 
+
+- INPUT_T1 must be a T1-weighted sequence before contrast-agent administration (T1-w) acquired as 2D with axial 
+orientation (e.g. TSE) or as 3D (e.g. MPRAGE)
+- INPUT_CT1 must be a T1-weighted sequence after contrast-agent administration (cT1-w) acquired as 2D with axial 
+orientation (e.g. TSE) or as 3D (e.g. MPRAGE)
+- INPUT_T2 must be a T2-weighted sequence (T2-w) acquired as 2D 
+- INPUT_FLAIR must be a fluid attenuated inversion recovery (FLAIR) sequence acquired as 2D with axial orientation
+ (e.g. TSE). A 3D acquisition (e.g. 3D TSE/FSE) may work as well.
+ 
+(These specifications are in line with the consensus recommendations for a standardized brain tumor imaging protocol 
+in clinical trials - see Ellingson et al. Neuro Oncol. 2015 Sep;17(9):1188-98 - www.ncbi.nlm.nih.gov/pubmed/26250565)
+
+Input files must contain 3D images; Sequences with multiple temporal volumes (i.e. 4D sequences) are not supported 
+(however can be splitted upfront into the individual temporal volumes using fslsplit<sup>1</sup>).
+
+All input files must match the orientation of standard MNI152 template and must be brain extracted and co-registered. 
+All non-brain voxels must be 0.
+To ensure that these pre-processing steps are performed correctly you may adhere to the following example:
+
+##### Reorient MRI sequences to standard space
+
+```
+fslreorient2std T1.nii.gz T1_reorient.nii.gz
+fslreorient2std CT1.nii.gz CT1_reorient.nii.gz
+fslreorient2std T2.nii.gz T2_reorient.nii.gz
+fslreorient2std FLAIR.nii.gz FLAIR_reorient.nii.gz
+```
+
+##### The following is the recommended workflow for FSL5. There is a better way to do this but this requires FSL6 (see below)
+```
+# perform brain extraction using HD-BET (https://github.com/MIC-DKFZ/HD-BET)
+hd-bet -i T1_reorient.nii.gz
+hd-bet -i CT1_reorient.nii.gz
+hd-bet -i T2_reorient.nii.gz
+hd-bet -i FLAIR_reorient.nii.gz 
+
+# register all sequences to T1
+fsl5.0-flirt -in CT1_reorient_bet.nii.gz -ref T1_reorient_bet.nii.gz -out CT1_reorient_bet_reg.nii.gz -dof 6 -interp spline
+fsl5.0-flirt -in T2_reorient_bet.nii.gz -ref T1_reorient.nii.gz -out T2_reorient_bet_reg.nii.gz -dof 6 -interp spline
+fsl5.0-flirt -in FLAIR_reorient_bet.nii.gz -ref T1_reorient.nii.gz -out FLAIR_reorient_bet_reg.nii.gz -dof 6 -interp spline
+
+# reapply T1 brain mask (this is important because HD-GLIO expects non-brain voxels to be 0 and the registration 
+process can introduce nonzero values
+# T1_BRAIN_MASK.nii.gz is the mask (not the brain extracted image!) as obtained from HD-Bet
+fsl5.0-fslmaths CT1_reorient_bet_reg.nii.gz -mas T1_BRAIN_MASK.nii.gz CT1_reorient_bet_reg.nii.gz
+fsl5.0-fslmaths T2_reorient_bet_reg.nii.gz -mas T1_BRAIN_MASK.nii.gz T2_reorient_bet_reg.nii.gz
+fsl5.0-fslmaths FLAIR_reorient_bet_reg.nii.gz -mas T1_BRAIN_MASK.nii.gz FLAIR_reorient_bet_reg.nii.gz
+```
+
+##### This is how to do it with FSL6:
+```
+# run hd bet
+hd-bet -i T1_reorient.nii.gz -o t1_bet.nii.gz -s 1
+hd-bet -i CT1_reorient.nii.gz -o ct1_bet.nii.gz
+hd-bet -i T2_reorient.nii.gz -o t2_bet.nii.gz
+hd-bet -i FLAIR_reorient.nii.gz -o flair_bet.nii.gz
+
+# register brain extracted images to t1, save matrix
+flirt -in ct1_bet.nii.gz -out ct1_bet_reg.nii.gz -ref t1_bet.nii.gz -omat ct1_to_t1.mat -interp spline -dof 6 &
+flirt -in t2_bet.nii.gz -out t2_bet_reg.nii.gz -ref t1_bet.nii.gz -omat t2_to_t1.mat -interp spline -dof 6 &
+flirt -in flair_bet.nii.gz -out flair_bet_reg.nii.gz -ref t1_bet.nii.gz -omat flair_to_t1.mat -interp spline -dof 6 &
+wait
+
+# we are only interested in the matrices, delete the other output images
+rm ct1_bet.nii.gz t2_bet.nii.gz flair_bet.nii.gz
+rm ct1_bet_reg.nii.gz t2_bet_reg.nii.gz flair_bet_reg.nii.gz
+
+# now apply the transformation matrices to the original images (pre hd-bet)
+flirt -in CT1_reorient.nii.gz -out ct1_reg.nii.gz -ref t1_bet.nii.gz -applyxfm -init ct1_to_t1.mat -interp spline &
+flirt -in T2_reorient.nii.gz -out t2_reg.nii.gz -ref t1_bet.nii.gz -applyxfm -init t2_to_t1.mat -interp spline &
+flirt -in FLAIR_reorient.nii.gz -out flair_reg.nii.gz -ref t1_bet.nii.gz -applyxfm -init flair_to_t1.mat -interp spline &
+wait
+
+# now apply t1 brain mask to all registered images
+fslmaths ct1_reg.nii.gz -mas t1_bet_mask.nii.gz CT1_reorient_reg_bet.nii.gz & # t1_bet_mask.nii.gz was generated by hd-bet (see above)
+fslmaths t2_reg.nii.gz -mas t1_bet_mask.nii.gz T2_reorient_reg_bet.nii.gz & # t1_bet_mask.nii.gz was generated by hd-bet (see above)
+fslmaths flair_reg.nii.gz -mas t1_bet_mask.nii.gz FLAIR_reorient_reg_bet.nii.gz & # t1_bet_mask.nii.gz was generated by hd-bet (see above)
+wait
+
+# done
+```
+
+After applying this example you would use `T1_reorient.nii.gz`, `CT1_reorient_reg_bet.nii.gz`, `T2_reorient_reg_bet.nii.gz` 
+and `FLAIR_reorient_reg_bet.nii.gz` to proceed.
+
+
+### Run HD-GLIO
+HD-GLIO provides two main scripts: `hd_glio_predict` and `hd_glio_predict_folder`.
+
+#### Predicting a single case
+`hd_glio_predict` can be used to predict a single case. It is useful for exploration or if the number of cases to be 
+procesed is low. Here is how to use it:
+
+`hd_glio_predict -t1 T1_FILE -t1c CT1_FILE -t2 T2_FILE -flair FLAIR_FILE -o OUTPUT_FILE`
+
+T1_FILE, CT1_FILE, T2_FILE, FLAIR_FILE and OUTPUT_FILE must all be niftis (end with .nii.gz). The four input files must 
+be preprocesed as specified in *How to use it - Prerequisites* (ses above). 
+
+#### Predicting multiple cases
+`hd_glio_predict_folder` is useful for batch processing, especially if the number of cases to be processed is large. By 
+interleaving preprocessing, inference and segmentation export we can speed up the prediction significantly. Furthermore, 
+the pipeline is initialized only once for all cases, again saving a lot of computation time.  Here is how to use it:
+
+`hd_glio_predict_folder -i INPUT_FOLDER -o OUTPUT_FOLDER`
+
+INPUT_FOLDER hereby contains the T1, T1c, T2 and FLAIR images. In order to ensure that HD-GLIO correctly assigns 
+filenames to modalities, you **must** apply the following naming convention to your data
+
+- INPUT_T1: PATIENT_IDENTIFIER_0000.nii.gz
+- INPUT_CT1: PATIENT_IDENTIFIER_0001.nii.gz
+- INPUT_T2: PATIENT_IDENTIFIER_0002.nii.gz
+- INPUT_FLAIR: PATIENT_IDENTIFIER_0003.nii.gz
+
+Hereby, PATIENT_IDENTIFIER can be anything. You can use an arbitrary number of patients (by using a different 
+PATIENT_IDENTIFIER for each patient). Predicted segmentations will be saved as `PATIENT_IDENTIFIER.nii.gz` in the 
+OUTPUT_FOLDER
+
+
+<sup>1</sup>https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Fslutils