Perelman School of Medicine at the University of Pennsylvania

Section for Biomedical Image Analysis (SBIA)

MOE - Mixture of Experts


In many studies, the main objective is to compare two groups of individuals, i.e. between normal controls and patients, with the assumption that disease affects all subjects in a uniform, homogeneous fashion. In other words, each affected individual is assumed to possess the same pattern of abnormality. This approach conflicts with what is observed in clinical assessments, which point to inherently multi-dimensional symptoms or cognitive changes that reflect a broad “spectrum” of changes associated with disease or developmental and maturational processes. To address this issue, present Mixture of Experts (MOE), a method that explicitly models and captures heterogeneous patterns of change in the affected group relative to a reference group of controls.

This software can be used for datasets where the reference group ("controls") and the affected group ("patients") cannot be separated by a single line ("hyperplane") in the high dimensional feature space. MOE combines multiple hyperplanes along with a clustering objective, to split the affected group into multiple sub-groups. This is done in such a manner that each of the resulting sub-group is separable from the reference group by a single line.

See Figure below for four simple 2D examples. The reference group is denoted by circles, and the affected group by triangles. In Case1, the affected group is not heterogeneous, as it is separable from the reference group with a single line. Cases 2, 3, 4 require multiple lines to separate the affected group from the reference group.

This software works with data saved in comma-separated value format. Input features can be based on any type of data - volumes, density, connectivity, diffusion, clinical scores, cognitive data etc.

Download

Software License

MOE software is freely available under a BSD-style open source license that is compatible with the Open Source Definition by The Open Source Initiative and contains no restrictions on use of the software. The full license text is included with the distribution package and available online.

 

To download please visit our NITRC page

Close


Documentation

1. Introduction

This software can be used for datasets where the reference group ("controls") and the affected group ("patients") cannot be separated by a single line ("hyperplane"). MOE combines multiple hyperplanes along with a clustering objective, to split the affected group into multiple sub-groups. This is done in such a manner that each of the resulting sub-group is separable from the reference group by a single line.

See Figure in test/All_test_results.png, where the reference group is denoted by circles, and the affected group by triangles. In Case1, the affected group is not heterogeneous, as it is seperable from the reference group with a single line. Cases 2, 3, 4 require multiple lines to separate the affected group from the reference group.

This software works with data saved in comma-separated value format. Input features can be based on any type of data - volumes, density, connectivity, diffusion, clinical scores, cognitive data etc.

For more details, please read UserManual.pdf

2. Testing & Installation

This software has been primarily implemented for Linux operating systems. It is implemented in Python.

Dependencies
  • Python 2.7.9
  • Python library numpy 1.7.2
  • Python library scipy 0.15.1
  • Python library pandas 0.16.2
  • Python library sklearn 0.15
  • Python library matplotlib 1.4.3

Make sure all dependencies are met before proceeding with install.

From within the src/ folder, run:

1) ./make test

This runs test.py from within the src directory.

We have provided synthetic two dimensional data for four test cases. In each of these cases, data points denoted by circles are the reference (control) samples, while points denoted by triangles are the affected (patient) cases which are made up of heterogeneous sub-groups. These are located in src/test/Case∗.

Test cases are used to check if the cross-validation accuracy in four test cases is greater than that of linear-SVM.

Proceed to the install step only if test passes in all four cases.

2)./make install ${installDir}

Installation requires the installation directory as a user-input. This creates four folders within installDir - bin, libexec, share and doc. bin/ contains the main executible moe. libexec/ has all python scripts. share/ has the test data. doc/ has the doxygen documentation.

3) Add the binary folder to the system path:

export PATH=${PATH}:${installDir}/bin/

3. Usage

To run this software you will need:

  1. An input csv file, with the following mandatory fields: (a) Subject index in the first column (b) Header row in the first row (c) A column containing the binary group labels - the name of the column and the value of the patient group (of whose heterogeneous sub-groups you want to find) needs to be provided in the command line options.

For a csv file ROI_values.csv that looks like below:

Subject_id, ROI_1, ROI_2, ROI_3, ..., Label, ...
BLSA_0001, 0.234, 0.4545, 0.212,...., AD , ...
BLSA_0002, 0.122, 0.1213, 0.3434,..., CN, ...
...
…

Run the following command: moe -d ROI_values.csv -p ROI_results -l AD -n 3 -o ./ -v

In the output directory, the software returns:

  1. One python numpy file containing all the results, with file name <prefix>_results_allResults.npz
  2. A csv file containing the hyperplanes, indexed against feature name in the first row. Filename <prefix>_results_hyperplanes.csv
  3. A csv file containing the memberships, indexed against subject id in the first column. Filename <prefix>_results_memberships.csv

 

Close


Changes

Version 1.0.0 (April, 2016)
  • First public release of the MOE software.

Close


People

Advisor

  • Christos Davatzikos

Software Authors

  • Harini Eavani
    • Developed the algorithm, implemented the software.

 

Close


Publications

Please cite [NeuroImage2016] when you used MOE in your research:

 

[NeuroImage2016] Eavani, H., Hsieh, M. K., An, Y., Erus, G., Beason-Held, L., Resnick, S., & Davatzikos, C. (2016). Capturing heterogeneous group differences using mixture-of-experts: Application to a study of aging. NeuroImage, 125, 498-514.

Close