Skip to content

Commit

Permalink
Add files via upload
Browse files Browse the repository at this point in the history
  • Loading branch information
@evarol
evarol authored May 3, 2018
1 parent 9f0a06a commit fa0e6c2
Show file tree
Hide file tree
Showing 9 changed files with 1,878 additions and 0 deletions.
181 changes: 181 additions & 0 deletions COPYING.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
License

Section of Biomedical Image Analysis
Department of Radiology
University of Pennsylvania
3700 Hamilton Walk, Floor 7
Philadelphia, PA 19104

Web: http://www.med.upenn.edu/sbia/software.html
Email: software at cbica.upenn.edu



SBIA Contribution and Software License Agreement ("Agreement")
==============================================================

Version 1.1 (June 29, 2017)

This Agreement covers contributions to and downloads from Software maintained by
the Section of Biomedical Image Analysis ("SBIA"), Center for Biomedical Image
Computing and Analytics ("CBICA"), Department of Radiology at the University
of Pennsylvania. Part A of this Agreement applies to contributions of
software and/or data to the Software (including making revisions of or additions
to code and/or data already in this Software). Part B of this Agreement applies to
downloads of software and/or data from SBIA. Part C of this Agreement applies to
all transactions with SBIA. If you distribute Software (as defined below) downloaded
from SBIA, all of the paragraphs of Part B of this Agreement must be included with
and apply to such Software.

Your contribution of software and/or data to SBIA (including prior to the date
of the first publication of this Agreement, each a "Contribution") and/or
downloading, copying, modifying, displaying, distributing or use of any software
and/or data from SBIA (collectively, the "Software") constitutes acceptance of
all of the terms and conditions of this Agreement. If you do not agree to such
terms and conditions, you have no right to contribute your Contribution, or to
download, copy, modify, display, distribute or use the Software.

PART A. CONTRIBUTION AGREEMENT - LICENSE TO SBIA WITH RIGHT TO SUBLICENSE ("CONTRIBUTION AGREEMENT").
-----------------------------------------------------------------------------------------------------

1. As used in this Contribution Agreement, "you" means the individual contributing
the Contribution to the Software maintained by SBIA and the institution or entity
which employs or is otherwise affiliated with such individual in connection with
such Contribution.

2. This Contribution Agreement applies to all Contributions made to the Software
maintained by SBIA, including without limitation Contributions made prior to
the date of first publication of this Agreement. If at any time you make a
Contribution to the Software, you represent that (i) you are legally authorized
and entitled to make such Contribution and to grant all licenses granted in this
Contribution Agreement with respect to such Contribution; (ii) if your
Contribution includes any patient data, all such data is de-identified in
accordance with U.S. confidentiality and security laws and requirements,
including but not limited to the Health Insurance Portability and Accountability
Act (HIPAA) and its regulations, and your disclosure of such data for the purposes
contemplated by this Agreement is properly authorized and in compliance with all
applicable laws and regulations; and (iii) you have preserved in the Contribution
all applicable attributions, copyright notices and licenses for any third party
software or data included in the Contribution.

3. Except for the licenses granted in this Agreement, you reserve all right,
title and interest in your Contribution.

4. You hereby grant to SBIA, with the right to sublicense, a perpetual, worldwide,
non-exclusive, no charge, royalty-free, irrevocable license to use, reproduce,
make derivative works of, display and distribute the Contribution. If your
Contribution is protected by patent, you hereby grant to SBIA, with the right
to sublicense, a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable license under your interest in patent rights covering the Contribution,
to make, have made, use, sell and otherwise transfer your Contribution, alone
or in combination with any other code.

5. You acknowledge and agree that SBIA may incorporate your Contribution into
the Software and may make the Software available to members of the public
on an open source basis under terms substantially in accordance with the
Software License set forth in Part B of this Agreement. You further acknowledge
and agree that SBIA shall have no liability arising in connection with claims
resulting from your breach of any of the terms of this Agreement.

6. YOU WARRANT THAT TO THE BEST OF YOUR KNOWLEDGE YOUR CONTRIBUTION DOES NOT
CONTAIN ANY CODE THAT REQUIRES OR PRESCRIBES AN "OPEN SOURCE LICENSE" FOR
DERIVATIVE WORKS (by way of non-limiting example, the GNU General Public
License or other so-called "reciprocal" license that requires any derived
work to be licensed under the GNU General Public License or other
"open source license").

PART B. DOWNLOADING AGREEMENT - LICENSE FROM SBIA WITH RIGHT TO SUBLICENSE ("SOFTWARE LICENSE").
------------------------------------------------------------------------------------------------

1. As used in this Software License, "you" means the individual downloading and/or
using, reproducing, modifying, displaying and/or distributing the Software and
the institution or entity which employs or is otherwise affiliated with such
individual in connection therewith. The Section of Biomedical Image Analysis,
Department of Radiology at the Universiy of Pennsylvania ("SBIA") hereby grants
you, with right to sublicense, with respect to SBIA's rights in the software,
and data, if any, which is the subject of this Software License (collectively,
the "Software"), a royalty-free, non-exclusive license to use, reproduce, make
derivative works of, display and distribute the Software, provided that:
(a) you accept and adhere to all of the terms and conditions of this Software
License; (b) in connection with any copy of or sublicense of all or any portion
of the Software, all of the terms and conditions in this Software License shall
appear in and shall apply to such copy and such sublicense, including without
limitation all source and executable forms and on any user documentation,
prefaced with the following words: "All or portions of this licensed product
(such portions are the "Software") have been obtained under license from the
Section of Biomedical Image Analysis, Department of Radiology at the University
of Pennsylvania and are subject to the following terms and conditions:"
(c) you preserve and maintain all applicable attributions, copyright notices
and licenses included in or applicable to the Software; (d) modified versions
of the Software must be clearly identified and marked as such, and must not
be misrepresented as being the original Software; and (e) you consider making,
but are under no obligation to make, the source code of any of your modifications
to the Software freely available to others on an open source basis.

2. The license granted in this Software License includes without limitation the
right to (i) incorporate the Software into proprietary programs (subject to
any restrictions applicable to such programs), (ii) add your own copyright
statement to your modifications of the Software, and (iii) provide additional
or different license terms and conditions in your sublicenses of modifications
of the Software; provided that in each case your use, reproduction or
distribution of such modifications otherwise complies with the conditions
stated in this Software License.

3. This Software License does not grant any rights with respect to third party
software, except those rights that SBIA has been authorized by a third
party to grant to you, and accordingly you are solely responsible for
(i) obtaining any permissions from third parties that you need to use,
reproduce, make derivative works of, display and distribute the Software,
and (ii) informing your sublicensees, including without limitation your
end-users, of their obligations to secure any such required permissions.

4. The Software has been designed for research purposes only and has not been
reviewed or approved by the Food and Drug Administration or by any other
agency. YOU ACKNOWLEDGE AND AGREE THAT CLINICAL APPLICATIONS ARE NEITHER
RECOMMENDED NOR ADVISED. Any commercialization of the Software is at the
sole risk of the party or parties engaged in such commercialization.
You further agree to use, reproduce, make derivative works of, display
and distribute the Software in compliance with all applicable governmental
laws, regulations and orders, including without limitation those relating
to export and import control.

5. The Software is provided "AS IS" and neither SBIA nor any contributor to
the software (each a "Contributor") shall have any obligation to provide
maintenance, support, updates, enhancements or modifications thereto.
SBIA AND ALL CONTRIBUTORS SPECIFICALLY DISCLAIM ALL EXPRESS AND IMPLIED
WARRANTIES OF ANY KIND INCLUDING, BUT NOT LIMITED TO, ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
IN NO EVENT SHALL SBIA OR ANY CONTRIBUTOR BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY ARISING IN ANY WAY RELATED
TO THE SOFTWARE, EVEN IF SBIA OR ANY CONTRIBUTOR HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT NOT PROHIBITED BY LAW OR
REGULATION, YOU FURTHER ASSUME ALL LIABILITY FOR YOUR USE, REPRODUCTION,
MAKING OF DERIVATIVE WORKS, DISPLAY, LICENSE OR DISTRIBUTION OF THE SOFTWARE
AND AGREE TO INDEMNIFY AND HOLD HARMLESS SBIA AND ALL CONTRIBUTORS FROM
AND AGAINST ANY AND ALL CLAIMS, SUITS, ACTIONS, DEMANDS AND JUDGMENTS ARISING
THEREFROM.

6. None of the names, logos or trademarks of CBICA/SBIA or any of CBICA/SBIA's affiliates
or any of the Contributors, or any funding agency, may be used to endorse
or promote products produced in whole or in part by operation of the Software
or derived from or based on the Software without specific prior written
permission from the applicable party.

7. Any use, reproduction or distribution of the Software which is not in accordance
with this Software License shall automatically revoke all rights granted to you
under this Software License and render Paragraphs 1 and 2 of this Software
License null and void.

8. This Software License does not grant any rights in or to any intellectual
property owned by SBIA or any Contributor except those rights expressly
granted hereunder.


PART C. MISCELLANEOUS
---------------------

This Agreement shall be governed by and construed in accordance with the laws
of The Commonwealth of Pennsylvania without regard to principles of conflicts
of law. This Agreement shall supercede and replace any license terms that you
may have agreed to previously with respect to Software from SBIA.
Binary file added Pre_computed_results/HYDRA_results_test.mat
View file
Binary file not shown.
143 changes: 143 additions & 0 deletions README.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
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
[email protected]

===============
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.

Loading

0 comments on commit fa0e6c2

Please sign in to comment.