
  Section of Biomedical Image Analysis
  Department of Radiology
  University of Pennsylvania
  3600 Market Street, Suite 380
  Philadelphia, PA 19104

  Web:   https://www.rad.upenn.edu/sbia/
  Email: sbia-software at uphs.upenn.edu



INTRODUCTION
============


This software implements Generative-Discriminative Basis Learning (GONDOLA), which is explained in detail in paper [1] and extended later on in paper [2]. Theoretical ideas are explained in these papers, but as a brief explanation, GONDOLA provides a generative method to reduce the dimensionality of medical images while using class labels. It produces basis vectors that are useful for classification and also clinically interpretable. 
  
When provided with two sets of labeled images as input, the software outputs features in .ARFF format (Weka Format [3]) and a .mat file (MATLAB file). The program can also save basis vectors in .nii format (NIFTI format). Scripts are provided to find and build an optimal classifier using the Weka APIs. Prior knowledge about basis vectors can be provided via "group-wise" regularization that divides voxels of an image into groups - or, in practice, a segmentation image. Currently, only non-overlapping groups are supported. The software can also be used for semi-supervised cases in which a number of subjects do not have class labels (for an example, please see [1]).


To install and use this software, you must first meet the requirements explained in the INSTALL.txt file. Note that all input images must first be registered to a common template, and that any image format supported by ITK [4] can be used. If you find this piece of software useful, please cite [1] and [2]. 
  
 
PACKAGE OVERVIEW
================

  Source Package
  --------------

  - CMakeLists.txt      Root CMake configuration file.
  - config/             Package configuration files.
  - data/               Auxiliary data required by the executables (optional).
  - doc/                Software documentation such as the user manual.
  - src/                Source files including public header files and scripts.

  - AUTHORS             Kayhan N. Batmanghelich (batmanghelich@gmail.com)
                        Andreas Schuh (Andreas.Schuh@uphs.upenn.edu)
  - README              This readme file.
  - COPYING             The copyright and license notices.
  - INSTALL             Build and installation instructions.

  
Main Binary Files
------------------
This package contains several binary and library files. Below, we have introduced the bare minimum binaries or scripts that you need to be familiar with in order to run the algorithm:

   - bin/gondola-config  :  This script accepts a list of files, a list of corresponding IDs and a set of experiment parameters, then generates an appropriate folder structure and the required config files. Read the help file for more detail.


   - bin/gondola-ExperimentLauncher  :  To find out how well how well we can generalize our results, the experiment must typically be repeated several times (i.e. learning the basis, extracting the features and performing classification). This script manages entire experiments (e.g. all folds of 10-fold cross validation) and provides correct arguments to GONDOLA in. It requires as input another .config file describing the experiment; please read the documentation of launchExperiment for more detail. 

   - /sgeExecLearning_withMOSEK  : This script is used to run experiments in parallel on servers equipped with Sun Grid Engine (SGE). It must be changed slightly to define the allocated memory, the number of CPU's required, and the e-mail address to use when reporting the experiment's progress.

   - bin/gondola   :    This is the main executable, and provides the following functions:
                        1. Learning: Perform optimized learning of the basis vectors (B) and other parameters.
                        2. Feature Extraction: Project the images onto the basis vectors
                        3. Show: Output each basis as an independent image file.
		
       Please see the gondola documentation for more detail.
                        For function 1, the program requires a .config file specifying the algorithm parameters and outputs a MATLAB file (.mat file) containing the optimization history and the values of B,C, and w. 
             ** NOTE **  It is not typically necessary to run GONDOLA directly. A more intuitive wrapper script (launchExperiment) is included that calls GONDOLA and provides the proper arguments.




  What Do I Need to Run the Program?
  ----------------------------------------------
  As a minimum, you need a list of image file names, a list of corresponding subject IDs, and the required parameters for the experiments. Use makeCrossValidationExperiment to design the experiment's folder structure. 
    

  Binary Package
  --------------

  For details on where the built executables and libraries, auxiliary data, and  documentation are installed, please refer to the INSTALL file.



LICENSING
=========

  See COPYING file in project root or 'doc' directory for details.



REFERENCES
==========

  [1]  K. N. Batmanghelich, B. Taskar, C. Davatzikos; Generative-Discriminative
        Basis Learning for Medical Imagin; IEEE Trans Med Imaging. 2012 Jan;31(1):51-69. 

  [2] K. N. Batmanghelich, B. Taskar, D. Ye, C. Davatzikos; Regularized Tensor
  factorization for multi-modality medical image classification, MICCAI 2011, 
  LNCS 6893, p17

  [3]  http://www.cs.waikato.ac.nz/ml/weka/
  
  [4]  www.itk.org

