Skip to content

Commit fa0e6c2

Browse files
evarolevarol
authored
Add files via upload
1 parent 9f0a06a commit fa0e6c2

9 files changed

Lines changed: 1878 additions & 0 deletions

File tree

‎COPYING.txt‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
License
2+
3+
Section of Biomedical Image Analysis
4+
Department of Radiology
5+
University of Pennsylvania
6+
3700 Hamilton Walk, Floor 7
7+
Philadelphia, PA 19104
8+
9+
Web: http://www.med.upenn.edu/sbia/software.html
10+
Email: software at cbica.upenn.edu
11+
12+
13+
14+
SBIA Contribution and Software License Agreement ("Agreement")
15+
==============================================================
16+
17+
Version 1.1 (June 29, 2017)
18+
19+
This Agreement covers contributions to and downloads from Software maintained by
20+
the Section of Biomedical Image Analysis ("SBIA"), Center for Biomedical Image
21+
Computing and Analytics ("CBICA"), Department of Radiology at the University
22+
of Pennsylvania. Part A of this Agreement applies to contributions of
23+
software and/or data to the Software (including making revisions of or additions
24+
to code and/or data already in this Software). Part B of this Agreement applies to
25+
downloads of software and/or data from SBIA. Part C of this Agreement applies to
26+
all transactions with SBIA. If you distribute Software (as defined below) downloaded
27+
from SBIA, all of the paragraphs of Part B of this Agreement must be included with
28+
and apply to such Software.
29+
30+
Your contribution of software and/or data to SBIA (including prior to the date
31+
of the first publication of this Agreement, each a "Contribution") and/or
32+
downloading, copying, modifying, displaying, distributing or use of any software
33+
and/or data from SBIA (collectively, the "Software") constitutes acceptance of
34+
all of the terms and conditions of this Agreement. If you do not agree to such
35+
terms and conditions, you have no right to contribute your Contribution, or to
36+
download, copy, modify, display, distribute or use the Software.
37+
38+
PART A. CONTRIBUTION AGREEMENT - LICENSE TO SBIA WITH RIGHT TO SUBLICENSE ("CONTRIBUTION AGREEMENT").
39+
-----------------------------------------------------------------------------------------------------
40+
41+
1. As used in this Contribution Agreement, "you" means the individual contributing
42+
the Contribution to the Software maintained by SBIA and the institution or entity
43+
which employs or is otherwise affiliated with such individual in connection with
44+
such Contribution.
45+
46+
2. This Contribution Agreement applies to all Contributions made to the Software
47+
maintained by SBIA, including without limitation Contributions made prior to
48+
the date of first publication of this Agreement. If at any time you make a
49+
Contribution to the Software, you represent that (i) you are legally authorized
50+
and entitled to make such Contribution and to grant all licenses granted in this
51+
Contribution Agreement with respect to such Contribution; (ii) if your
52+
Contribution includes any patient data, all such data is de-identified in
53+
accordance with U.S. confidentiality and security laws and requirements,
54+
including but not limited to the Health Insurance Portability and Accountability
55+
Act (HIPAA) and its regulations, and your disclosure of such data for the purposes
56+
contemplated by this Agreement is properly authorized and in compliance with all
57+
applicable laws and regulations; and (iii) you have preserved in the Contribution
58+
all applicable attributions, copyright notices and licenses for any third party
59+
software or data included in the Contribution.
60+
61+
3. Except for the licenses granted in this Agreement, you reserve all right,
62+
title and interest in your Contribution.
63+
64+
4. You hereby grant to SBIA, with the right to sublicense, a perpetual, worldwide,
65+
non-exclusive, no charge, royalty-free, irrevocable license to use, reproduce,
66+
make derivative works of, display and distribute the Contribution. If your
67+
Contribution is protected by patent, you hereby grant to SBIA, with the right
68+
to sublicense, a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
69+
irrevocable license under your interest in patent rights covering the Contribution,
70+
to make, have made, use, sell and otherwise transfer your Contribution, alone
71+
or in combination with any other code.
72+
73+
5. You acknowledge and agree that SBIA may incorporate your Contribution into
74+
the Software and may make the Software available to members of the public
75+
on an open source basis under terms substantially in accordance with the
76+
Software License set forth in Part B of this Agreement. You further acknowledge
77+
and agree that SBIA shall have no liability arising in connection with claims
78+
resulting from your breach of any of the terms of this Agreement.
79+
80+
6. YOU WARRANT THAT TO THE BEST OF YOUR KNOWLEDGE YOUR CONTRIBUTION DOES NOT
81+
CONTAIN ANY CODE THAT REQUIRES OR PRESCRIBES AN "OPEN SOURCE LICENSE" FOR
82+
DERIVATIVE WORKS (by way of non-limiting example, the GNU General Public
83+
License or other so-called "reciprocal" license that requires any derived
84+
work to be licensed under the GNU General Public License or other
85+
"open source license").
86+
87+
PART B. DOWNLOADING AGREEMENT - LICENSE FROM SBIA WITH RIGHT TO SUBLICENSE ("SOFTWARE LICENSE").
88+
------------------------------------------------------------------------------------------------
89+
90+
1. As used in this Software License, "you" means the individual downloading and/or
91+
using, reproducing, modifying, displaying and/or distributing the Software and
92+
the institution or entity which employs or is otherwise affiliated with such
93+
individual in connection therewith. The Section of Biomedical Image Analysis,
94+
Department of Radiology at the Universiy of Pennsylvania ("SBIA") hereby grants
95+
you, with right to sublicense, with respect to SBIA's rights in the software,
96+
and data, if any, which is the subject of this Software License (collectively,
97+
the "Software"), a royalty-free, non-exclusive license to use, reproduce, make
98+
derivative works of, display and distribute the Software, provided that:
99+
(a) you accept and adhere to all of the terms and conditions of this Software
100+
License; (b) in connection with any copy of or sublicense of all or any portion
101+
of the Software, all of the terms and conditions in this Software License shall
102+
appear in and shall apply to such copy and such sublicense, including without
103+
limitation all source and executable forms and on any user documentation,
104+
prefaced with the following words: "All or portions of this licensed product
105+
(such portions are the "Software") have been obtained under license from the
106+
Section of Biomedical Image Analysis, Department of Radiology at the University
107+
of Pennsylvania and are subject to the following terms and conditions:"
108+
(c) you preserve and maintain all applicable attributions, copyright notices
109+
and licenses included in or applicable to the Software; (d) modified versions
110+
of the Software must be clearly identified and marked as such, and must not
111+
be misrepresented as being the original Software; and (e) you consider making,
112+
but are under no obligation to make, the source code of any of your modifications
113+
to the Software freely available to others on an open source basis.
114+
115+
2. The license granted in this Software License includes without limitation the
116+
right to (i) incorporate the Software into proprietary programs (subject to
117+
any restrictions applicable to such programs), (ii) add your own copyright
118+
statement to your modifications of the Software, and (iii) provide additional
119+
or different license terms and conditions in your sublicenses of modifications
120+
of the Software; provided that in each case your use, reproduction or
121+
distribution of such modifications otherwise complies with the conditions
122+
stated in this Software License.
123+
124+
3. This Software License does not grant any rights with respect to third party
125+
software, except those rights that SBIA has been authorized by a third
126+
party to grant to you, and accordingly you are solely responsible for
127+
(i) obtaining any permissions from third parties that you need to use,
128+
reproduce, make derivative works of, display and distribute the Software,
129+
and (ii) informing your sublicensees, including without limitation your
130+
end-users, of their obligations to secure any such required permissions.
131+
132+
4. The Software has been designed for research purposes only and has not been
133+
reviewed or approved by the Food and Drug Administration or by any other
134+
agency. YOU ACKNOWLEDGE AND AGREE THAT CLINICAL APPLICATIONS ARE NEITHER
135+
RECOMMENDED NOR ADVISED. Any commercialization of the Software is at the
136+
sole risk of the party or parties engaged in such commercialization.
137+
You further agree to use, reproduce, make derivative works of, display
138+
and distribute the Software in compliance with all applicable governmental
139+
laws, regulations and orders, including without limitation those relating
140+
to export and import control.
141+
142+
5. The Software is provided "AS IS" and neither SBIA nor any contributor to
143+
the software (each a "Contributor") shall have any obligation to provide
144+
maintenance, support, updates, enhancements or modifications thereto.
145+
SBIA AND ALL CONTRIBUTORS SPECIFICALLY DISCLAIM ALL EXPRESS AND IMPLIED
146+
WARRANTIES OF ANY KIND INCLUDING, BUT NOT LIMITED TO, ANY WARRANTIES OF
147+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
148+
IN NO EVENT SHALL SBIA OR ANY CONTRIBUTOR BE LIABLE TO ANY PARTY FOR
149+
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES
150+
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY ARISING IN ANY WAY RELATED
151+
TO THE SOFTWARE, EVEN IF SBIA OR ANY CONTRIBUTOR HAS BEEN ADVISED OF THE
152+
POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT NOT PROHIBITED BY LAW OR
153+
REGULATION, YOU FURTHER ASSUME ALL LIABILITY FOR YOUR USE, REPRODUCTION,
154+
MAKING OF DERIVATIVE WORKS, DISPLAY, LICENSE OR DISTRIBUTION OF THE SOFTWARE
155+
AND AGREE TO INDEMNIFY AND HOLD HARMLESS SBIA AND ALL CONTRIBUTORS FROM
156+
AND AGAINST ANY AND ALL CLAIMS, SUITS, ACTIONS, DEMANDS AND JUDGMENTS ARISING
157+
THEREFROM.
158+
159+
6. None of the names, logos or trademarks of CBICA/SBIA or any of CBICA/SBIA's affiliates
160+
or any of the Contributors, or any funding agency, may be used to endorse
161+
or promote products produced in whole or in part by operation of the Software
162+
or derived from or based on the Software without specific prior written
163+
permission from the applicable party.
164+
165+
7. Any use, reproduction or distribution of the Software which is not in accordance
166+
with this Software License shall automatically revoke all rights granted to you
167+
under this Software License and render Paragraphs 1 and 2 of this Software
168+
License null and void.
169+
170+
8. This Software License does not grant any rights in or to any intellectual
171+
property owned by SBIA or any Contributor except those rights expressly
172+
granted hereunder.
173+
174+
175+
PART C. MISCELLANEOUS
176+
---------------------
177+
178+
This Agreement shall be governed by and construed in accordance with the laws
179+
of The Commonwealth of Pennsylvania without regard to principles of conflicts
180+
of law. This Agreement shall supercede and replace any license terms that you
181+
may have agreed to previously with respect to Software from SBIA.

‎Pre_computed_results/HYDRA_results_test.mat‎

686 Bytes
Binary file not shown.

‎README.txt‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
HYDRA
2+
3+
Section of Biomedical Image Analysis
4+
Department of Radiology
5+
University of Pennsylvania
6+
Richard Building
7+
3700 Hamilton Walk, 7th Floor
8+
Philadelphia, PA 19104
9+
10+
Web: https://www.med.upenn.edu/sbia/
11+
Email: sbia-software at uphs.upenn.edu
12+
13+
Copyright (c) 2018 University of Pennsylvania. All rights reserved.
14+
See https://www.med.upenn.edu/sbia/software-agreement.html or COPYING file.
15+
16+
Author:
17+
Erdem Varol
18+
software@cbica.upenn.edu
19+
20+
===============
21+
1. INTRODUCTION
22+
===============
23+
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.
24+
25+
26+
===============
27+
2. TESTING & INSTALLATION
28+
===============
29+
30+
This software has been primarily implemented in MATLAB for Linux operating systems.
31+
32+
----------------
33+
Requirements
34+
----------------
35+
- Matlab optimization toolbox
36+
- Matlab version >2014
37+
38+
39+
----------------
40+
Installation
41+
----------------
42+
43+
Hydra can be run directly in a matlab environment without compilation.
44+
45+
OPTIONAL:
46+
47+
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"):
48+
49+
Run the following command in a MATLAB environment:
50+
51+
mcc -m hydra.m
52+
53+
-----------------
54+
Test
55+
-----------------
56+
We provided a test sample in the test folder.
57+
58+
To test in matlab enviroment, use the command:
59+
60+
hydra('-i','test.csv','-o','.','-z','test_covar.csv','-k',3,'-f',3)
61+
62+
To test in command line using the compiled executable, use the command:
63+
64+
hydra -i test.csv -o . -z test_covar.csv -k 3 -f 3
65+
66+
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.
67+
68+
-----------------
69+
Test Verification
70+
-----------------
71+
72+
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.
73+
74+
==========
75+
3. USAGE
76+
==========
77+
78+
I. Running "HYDRA":
79+
80+
Here is a brief introduction to running HYDRA. For a complete list of parameters, see --help option.
81+
82+
To run this software, you will need an input csv file, with the following mandatory fields in the following column order:
83+
(Column 1) ID: ID for subject
84+
(Column 2---(last minus 1)) features: features to be used for clustering
85+
(Column (last)) groups: label whether the subject is control (-1) or patient (1)
86+
87+
NOTE: Controls must be strictly -1 and patients must be 1 label.
88+
NOTE: Label headers names are not strict.
89+
90+
An example input csv file looks as following:
91+
92+
ID, feature_1, feauture_2, feature_3, group
93+
subject_1, 5, 1, 79.3, -1
94+
subject_2, 10, 1, 71.4, 1
95+
subject_3, 3, 1, 82.7, -1
96+
97+
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:
98+
(Column 1) ID: ID for subject
99+
(Column 2---(last)) covariates: covariates of subjects
100+
101+
An example covariate csv file looks as following:
102+
103+
ID, age, sex
104+
subject_1, 29, 1
105+
subject_2, 35, 1
106+
subject_3, 51, 0
107+
108+
If you install the package successfully, there will be two ways of running HYDRA:
109+
110+
1. Running HYDRA in a matlab environment, a simple example:
111+
112+
hydra('-i','test.csv','-o','.','-z','test_covar.csv','-k',3,'-f',3)
113+
114+
2. Running matlab compiled HYDRA executables in the command line, a simple example:
115+
116+
hydra -i test.csv -o . -z test_covar.csv -k 3 -f 3
117+
118+
119+
The software returns:
120+
121+
122+
1. HYDRA_results.mat in the specified output directory.
123+
124+
This mat file stores the following variables
125+
126+
CIDX - clustering indices for subjects (rows) at varying levels (columns)
127+
ARI - adjusted rand index of clustering at varying levels, clustering level at the highest ARI should be selected
128+
ID - subject ID of rows
129+
130+
===========
131+
4. REFERENCE
132+
===========
133+
134+
If you find this software useful, please cite:
135+
136+
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.
137+
138+
===========
139+
5. LICENSING
140+
===========
141+
142+
See https://www.med.upenn.edu/sbia/software-agreement.html or COPYING.txt file.
143+

0 commit comments

Comments
 (0)