Added README file and image files it references (#541)

* Added README files links and lfs tracking to some images not already in .gitattributes.

.gitattributes

@@ -15,3 +15,10 @@ model_zoo/ECG2AF/km.jpg filter=lfs diff=lfs merge=lfs -text
 model_zoo/ECG2AF/study_design.jpg filter=lfs diff=lfs merge=lfs -text
 model_zoo/ECG2AF/architecture.png filter=lfs diff=lfs merge=lfs -text
 model_zoo/ECG2AF/salience.jpg filter=lfs diff=lfs merge=lfs -text
+model_zoo/cardiac_mri_derived_left_ventricular_mass/Lseg.png filter=lfs diff=lfs merge=lfs -text
+model_zoo/cardiac_mri_derived_left_ventricular_mass/Lreg.png filter=lfs diff=lfs merge=lfs -text
+model_zoo/left_ventricular_mass_from_ecg_student_and_mri_teacher/TrainingAndTestSets.jpg filter=lfs diff=lfs merge=lfs -text
+model_zoo/liver_fat_from_mri_ukb/liver_fat_from_echo_teacher_model.png filter=lfs diff=lfs merge=lfs -text
+model_zoo/liver_fat_from_mri_ukb/liver_fat_from_ideal_student_model.png filter=lfs diff=lfs merge=lfs -text
+model_zoo/ECG_PheWAS/ukb_phewas.png filter=lfs diff=lfs merge=lfs -text
+model_zoo/dropfuse/overview.png filter=lfs diff=lfs merge=lfs -text

model_zoo/cardiac_mri_derived_left_ventricular_mass/README.md

@@ -0,0 +1,26 @@
+# Deep learning to estimate cardiac magnetic resonance–derived left ventricular mass
+This folder contains models and code supporting the work described in <a href= "https://www.sciencedirect.com/science/article/pii/S2666693621000232?ref=pdf_download&fr=RR-2&rr=80df2c704c374cd4">this paper</a> published in the Cardiovascular Digital Health Journal.
+
+Within participants of the UK Biobank prospective cohort undergoing CMR, 2 convolutional neural networks were trained to estimate LV mass. The first (ML4H<sub>reg</sub>) performed regression informed by manually labeled LV mass (available in 5065 individuals), while the second (ML4Hseg) performed LV segmentation informed by InlineVF (version D13A) contours. All models were optimized using the Adam variant of stochastic gradient descent with initial learning rate 1 × 10-3, exponential learning rate decay, and batch size of 4 on K80 graphical processing units. 
+# ML4H<sub>reg</sub>
+The first model is a 3D convolutional neural network regressor ML4H<sub>reg</sub> trained with the manually annotated LV mass estimates provided by Petersen and colleagues to optimize the log cosh loss function, which behaves like L2 loss for small values and L1 loss for larger values: 
+
+![Loss of ML4Hregs](Lreg.png) 
+
+Here batch size, N, was 4 random samples from the training set of 3178 after excluding testing and validation samples from the total 5065 CMR images with LV mass values included in P.
+# ML4H<sub>seg</sub>
+ML4H<sub>seg</sub>, is a 3D semantic
+segmenter. To facilitate model development in the absence of hand-labeled segmentations, the models were trained with the InlineVF contours to minimize Lseg; the per-pixel cross-entropy between the label and the model’s prediction. 
+
+![Loss of ML4Hseg](Lseg.png)
+
+Here the batch size, N, was 4 from the total set of 33,071. Height, H, and width, W, are 256 voxels and there was a maximum of 13 Z slices along the short axis. There is a channel for each of the 3 labels, which were one-hot encoded in the training data, InlineVF (IVF), and probabilistic values from the softmax layer of ML4H<sub>seg</sub>. Segmentation architectures used U-Net-style long-range connections between early convolutional layers and deeper layers. Since not all CMR images used the same pixel dimensions, models were built to incorporate pixel size values with their fully connected layers before making predictions. 
+# Results
+The accuracy of both deep learning approaches wwere compared to LV mass obtained using InlineVF within an independent holdout set using manually labeled LV mass as the gold standard.
+![Overview of left ventricular (LV) mass algorithms.](https://ars.els-cdn.com/content/image/1-s2.0-S2666693621000232-gr1.jpg) 
+
+Within 33,071 individuals who underwent CMR, models were trained to derive CMR-based LV mass using deep learning regression (ML4Hreg) and segmentation (ML4Hseg).
+![Distributions of cardiac magnetic resonance (CMR)-derived left ventricular (LV) mass obtained using each estimation method.](https://ars.els-cdn.com/content/image/1-s2.0-S2666693621000232-gr2.jpg)
+
+In an independent holdout set of 891 individuals with manually labeled LV mass estimates available, ML4Hseg had favorable correlation with manually labeled LV mass (r = 0.864, 95% confidence interval 0.847–0.880; MAE 10.41 g, 95% CI 9.82–10.99) as compared to ML4Hreg (r = 0.843, 95% confidence interval 0.823–0.861; MAE 10.51, 95% CI 9.86–11.15, P = .01) and centered InlineVF (r = 0.795, 95% confidence interval 0.770–0.818; MAE 14.30, 95% CI 13.46–11.01, P < .01)
+![Correlation between manually labeled left ventricular (LV) mass and derived left ventricular mass estimated using each model. ](https://ars.els-cdn.com/content/image/1-s2.0-S2666693621000232-gr3.jpg)

model_zoo/dropfuse/README.md

@@ -1,5 +1,5 @@
 ## A Cross-Modal Autoencoder Framework Learns Holistic Representations of Cardiovascular State
-This directory contains code and instructions to create the models and results from [this paper](https://www.nature.com/articles/s41467-023-38125-0).
+This directory contains code and instructions to create the models and results from [this paper](https://www.nature.com/articles/s41467-023-38125-0) published in Nature Communications.
 
 In the paper, using the heart as a model system, we develop a cross-modal autoencoder framework for integrating distinct data modalities and constructing a holistic representation of cardio-vascular state. 
 In particular, we use our framework to construct such cross-modal representations from cardiac magnetic resonance images (MRIs), containing structural information, and electrocardiograms (ECGs), containing myoelectric information.
@@ -63,6 +63,7 @@ Having trained the two unimodal autoencoders above with encoders and decoders se
 ${HOME}/ml4h/scripts/tf.sh ${HOME}/ml4h/ml4h/recipes.py \
   --mode train \
   --tensors ${TENSORS} \
+  --tensormap_prefix ml4h.tensormap.ukb \
   --input_tensors ecg.ecg_rest_median_raw_10 mri.lax_4ch_heart_center \
   --output_tensors ecg.ecg_rest_median_raw_10 mri.lax_4ch_heart_center \
   --encoder_blocks ${HOME}/results/hypertuned_ecg_median_raw_10_autoencoder_256d/encoder_ecg_rest_median_raw_10.h5 \
@@ -81,6 +82,7 @@ ${HOME}/ml4h/scripts/tf.sh ${HOME}/ml4h/ml4h/recipes.py \
 ${HOME}/ml4h/scripts/tf.sh ${HOME}/ml4h/ml4h/recipes.py \
   --mode infer_encoders \
   --tensors ${TENSORS} \
+  --tensormap_prefix ml4h.tensormap.ukb \
   --input_tensors ecg.ecg_rest_median_raw_10 mri.lax_4ch_heart_center \
   --output_tensors ecg.ecg_rest_median_raw_10 mri.lax_4ch_heart_center \
   --id dropfuse_256d \

model_zoo/left_ventricular_mass_from_ecg_student_and_mri_teacher/README.md

@@ -1,4 +1,16 @@
 # Deep Learning to Predict Cardiac Magnetic Resonance-Derived Left Ventricular Mass and Hypertrophy from 12-Lead Electrocardiograms
-Three pre-trained models are included here. The model `ecg_rest_raw_age_sex_bmi_lvm_asymmetric_loss.h5` takes as input a 12 Lead resting ECG, as well as age, sex and BMI and has two outputs: one which regresses the left ventricular mass, and a second which gives a probability of left ventricular hypertrophy. 
-This model was trained with the asymmetric loss described in the paper.  The model `ecg_rest_raw_lvm_asymmetric_loss.h5` takes only an ECG as input and regresses left ventricular mass, this model was also trained with the asymmetric loss.
-The third model, `ecg_rest_raw_lvm_symmetric_loss.h5` takes only an ECG as input and regresses left ventricular mass, this model was trained with the symmetric logcosh loss.  The raw voltage values from the ECG are normalized by dividing by 2000 prior to being input to the model.
+
+This folder contains models and code supporting the work described in [this paper](https://www.ahajournals.org/doi/10.1161/CIRCIMAGING.120.012281?url_ver=Z39.88-2003&rfr_id=ori:rid:crossref.org&rfr_dat=cr_pub%20%200pubmed) published in the journal Circulation: Cardiovascular Imaging. 
+
+# LVM-AI
+Left Ventricular Mass-Artificial Intelligence (LVM-AI) is a one-dimensional convolutional neural network trained to predict CMR-derived LV mass using 12-lead ECGs. LVM-AI was trained within 32239 individuals from the UK Biobank with paired CMR and 12-lead ECG. It was provided with the entire 10 seconds of the 12-lead ECG waveform as well as participant age, sex, and BMI. 
+LVM-AI was evaluated in a UK Biobank test set as well as an external health care–based Mass General Brigham (MGB) dataset. In both test sets, LVM-AI was compared to with traditional ECG-based rules for diagnosing CMR-derived left ventricular hypertrophy. Associations between LVM-AI predicted LV mass index and incident cardiovascular events were tested in the UK Biobank and a separate MGB-based ambulatory cohort (MGB outcomes)
+![Overview of the training and test samples](TrainingAndTestSets.jpg)
+When compared with any ECG rule, LVM-AI demonstrated similar LVH discrimination in the UK Biobank (LVM-AI c-statistic 0.653 [95% CI, 0.608 -0.698] versus any ECG rule c-statistic 0.618 [95% CI, 0.574 -0.663], P=0.11) and superior discrimination in MGB (0.621; 95% CI, 0.592 -0.649 versus 0.588; 95% CI, 0.564 -0.611, P=0.02). 
+
+
+# Models 
+Three pre-trained models are included here:
+The model `ecg_rest_raw_age_sex_bmi_lvm_asymmetric_loss.h5` takes as input a 12 Lead resting ECG, as well as age, sex and BMI and has two outputs: one which regresses the left ventricular mass, and a second which gives a probability of left ventricular hypertrophy. This model was trained with the asymmetric loss described in the paper.  
+The model `ecg_rest_raw_lvm_asymmetric_loss.h5` takes only an ECG as input and regresses left ventricular mass. This model was also trained with the asymmetric loss.
+The third model, `ecg_rest_raw_lvm_symmetric_loss.h5` takes only an ECG as input and regresses left ventricular mass. This model was trained with the symmetric logcosh loss.  The raw voltage values from the ECG are normalized by dividing by 2000 prior to being input to the model.

model_zoo/liver_fat_from_mri_ukb/README.md

@@ -1,15 +1,17 @@
 # Machine learning enables new insights into clinical significance of and genetic contributions to liver fat accumulation
 
+This folder contains models and code supporting the work described in [this paper](https://www.sciencedirect.com/science/article/pii/S2666979X21000823) published in Cell Genomics.
+
 Here we host two models for estimating liver fat from abdominal MRI. 
-The liver fat percentage training data is from the returned liver fat values in the [UK Biobank field ID 22402](https://biobank.ctsu.ox.ac.uk/crystal/field.cgi?id=22402).  These values were only calculated for the echo protocol, so to infer liver fat from the ideal protocl we used a teacher/student modeling approach.
+The liver fat percentage training data is from the returned liver fat values in the [UK Biobank field ID 22402](https://biobank.ctsu.ox.ac.uk/crystal/field.cgi?id=22402).  These values were only calculated for the echo protocol, so to infer liver fat from the ideal protocol we used a teacher/student modeling approach.
 
 ## Teacher Model
 The teacher model was trained with abdominal MRIs acquired using the [echo protocol, UK Biobank field ID 20203](https://biobank.ctsu.ox.ac.uk/crystal/field.cgi?id=20203).  
 This model takes input of shape 160 x 160 x 10 and emits a scalar representing estimated liver fat percentage.
 The input TensorMap is defined at `tensormap.ukb.mri.gre_mullti_echo_10_te_liver`.
 The output TensorMap associated with these values is defined at `tensormap.ukb.mri.liver_fat`.
 The keras model file is at [liver_fat_from_echo.h5](liver_fat_from_echo.h5) and the model architecture is shown below.  The "?" in the input dimension represents the batch size of the input, which can be determined at runtime.  When training the teacher model we used a batch size of 8.
-![](liver_fat_from_echo_teacher_model.png)
+![https://www.medrxiv.org/content/10.1101/2020.09.03.20187195v1](liver_fat_from_echo_teacher_model.png)
 
 
 ## Student Model
@@ -19,4 +21,4 @@ This model takes input of shape 232 x 256 x 36 and also emits a scalar represent
 The input TensorMap is defined at `tensormap.ukb.mri.lms_ideal_optimised_low_flip_6dyn`.
 The output TensorMap associated with these values is defined at `tensormap.ukb.mri.liver_fat_echo_predicted`. 
 The keras model file is at [liver_fat_from_ideal.h5](liver_fat_from_ideal.h5) and the model architecture is shown below. The "?" in the input dimension represents the batch size of the input, which can be determined at runtime.  When training the student model we used a batch size of 5.
-![](liver_fat_from_ideal_student_model.png)
+![Architecture Diagram](liver_fat_from_ideal_student_model.png)

model_zoo/mi_feature_selection/README.md

@@ -44,5 +44,5 @@ xxx = pickle.load(open('models/coxnet_survival_05_final.pickle', 'rb'))
 
 ### Citation
 
-**Selection of 51 predictors from 13,782 candidate multimodal features using machine learning improves coronary artery disease prediction**, Saaket Agrawal, BS*, Marcus D. R. Klarqvist, PhD,  MSc, MSc*, Connor Emdin, DPhil, MD, Aniruddh P. Patel, MD, Manish D. Paranjpe, BA, Patrick T. Ellinor, MD, PhD, Anthony Philippakis, MD, PhD, Kenney Ng, PhD, Puneet Batra, PhD, Amit V. Khera, MD, MSc
+**[Selection of 51 predictors from 13,782 candidate multimodal features using machine learning improves coronary artery disease prediction](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC8672148/)**, Saaket Agrawal, BS*, Marcus D. R. Klarqvist, PhD,  MSc, MSc*, Connor Emdin, DPhil, MD, Aniruddh P. Patel, MD, Manish D. Paranjpe, BA, Patrick T. Ellinor, MD, PhD, Anthony Philippakis, MD, PhD, Kenney Ng, PhD, Puneet Batra, PhD, Amit V. Khera, MD, MSc
 

model_zoo/silhouette_mri/README.md

@@ -17,4 +17,4 @@ Several files are provided:
 
 ### Citation
 
-**Estimating body fat distribution - a driver of cardiometabolic health - from silhouette images**, Marcus D. R. Klarqvist, PhD*, Saaket Agrawal, BS*, Nathaniel Diamant, BS, Patrick T. Ellinor, MD, PhD, Anthony Philippakis, MD, PhD,  Kenney Ng, PhD, Puneet Batra, PhD, Amit V. Khera, MD
+**[Estimating body fat distribution - a driver of cardiometabolic health - from silhouette images](https://www.medrxiv.org/content/10.1101/2022.01.14.22269328v2)**, Marcus D. R. Klarqvist, PhD*, Saaket Agrawal, BS*, Nathaniel Diamant, BS, Patrick T. Ellinor, MD, PhD, Anthony Philippakis, MD, PhD,  Kenney Ng, PhD, Puneet Batra, PhD, Amit V. Khera, MD