HYDRA Section of Biomedical Image Analysis Department of Radiology University of Pennsylvania Richard Building 3700 Hamilton Walk, 7th Floor Philadelphia, PA 19104 Web: https://www.med.upenn.edu/sbia/ Email: sbia-software at uphs.upenn.edu Copyright (c) 2018 University of Pennsylvania. All rights reserved. See https://www.med.upenn.edu/sbia/software-agreement.html or COPYING file. Author: Erdem Varol software@cbica.upenn.edu =============== 1. INTRODUCTION =============== This software performs clustering of heterogenous disease patterns within patient group. The clustering is based on seperating the patient imaging features from the control imaging features using a convex polytope classifier. Covariate correction can be performed optionally. =============== 2. TESTING & INSTALLATION =============== This software has been primarily implemented in MATLAB for Linux operating systems. ---------------- Requirements ---------------- - Matlab optimization toolbox - Matlab version >2014 ---------------- Installation ---------------- Hydra can be run directly in a matlab environment without compilation. OPTIONAL: If the user wants to run hydra as a standalone executable, then it must be compiled as following (using the additionally obtained matlab compiler "mcc"): Run the following command in a MATLAB environment: mcc -m hydra.m ----------------- Test ----------------- We provided a test sample in the test folder. To test in matlab enviroment, use the command: hydra('-i','test.csv','-o','.','-z','test_covar.csv','-k',3,'-f',3) To test in command line using the compiled executable, use the command: hydra -i test.csv -o . -z test_covar.csv -k 3 -f 3 This runs a HYDRA experiment which may take a few minutes. The test case contains a subset of a functional MRI study dataset by T. Satterwaithe comprising 100 subjects and their functional ROI's. The output is the clustering labels of the input subjects (only patients are clustered) at varying clustering levels. Also, the clustering stability at varying levels is output to show the rationale for choosing the clustering level. ----------------- Test Verification ----------------- Pre-computed HYDRA results have been included in directory "Pre_computed_test_results". The user may verify that their test results match the pre-computed results to confirm proper set-up. If the clustering occurred properly, ARI for clustering level k=3 should be greater than that of clustering level k=2. ========== 3. USAGE ========== I. Running "HYDRA": Here is a brief introduction to running HYDRA. For a complete list of parameters, see --help option. To run this software, you will need an input csv file, with the following mandatory fields in the following column order: (Column 1) ID: ID for subject (Column 2---(last minus 1)) features: features to be used for clustering (Column (last)) groups: label whether the subject is control (-1) or patient (1) NOTE: Controls must be strictly -1 and patients must be 1 label. NOTE: Label headers names are not strict. An example input csv file looks as following: ID, feature_1, feauture_2, feature_3, group subject_1, 5, 1, 79.3, -1 subject_2, 10, 1, 71.4, 1 subject_3, 3, 1, 82.7, -1 Optionally, you can provide a covariate file that will be used to remove covariate effects from imaging features before HYDRA analysis. The covariate file has the following format: (Column 1) ID: ID for subject (Column 2---(last)) covariates: covariates of subjects An example covariate csv file looks as following: ID, age, sex subject_1, 29, 1 subject_2, 35, 1 subject_3, 51, 0 If you install the package successfully, there will be two ways of running HYDRA: 1. Running HYDRA in a matlab environment, a simple example: hydra('-i','test.csv','-o','.','-z','test_covar.csv','-k',3,'-f',3) 2. Running matlab compiled HYDRA executables in the command line, a simple example: hydra -i test.csv -o . -z test_covar.csv -k 3 -f 3 The software returns: 1. HYDRA_results.mat in the specified output directory. This mat file stores the following variables CIDX - clustering indices for subjects (rows) at varying levels (columns) ARI - adjusted rand index of clustering at varying levels, clustering level at the highest ARI should be selected ID - subject ID of rows =========== 4. REFERENCE =========== If you find this software useful, please cite: Varol, Erdem, Aristeidis Sotiras, Christos Davatzikos, and Alzheimer's Disease Neuroimaging Initiative. "HYDRA: Revealing heterogeneity of imaging and genetic patterns through a multiple max-margin discriminative analysis framework." NeuroImage 145 (2017): 346-364. =========== 5. LICENSING =========== See https://www.med.upenn.edu/sbia/software-agreement.html or COPYING.txt file.