Awesome Open Source
Awesome Open Source

RIDDLE: Race and ethnicity Imputation from Disease history with Deep LEarning (RIDDLE) Build Status License

RIDDLE (Race and ethnicity Imputation from Disease history with Deep LEarning) is an open-source Python2 library for using deep learning to impute race and ethnicity information in anonymized electronic medical records (EMRs). RIDDLE provides the ability to (1) build models for estimating race and ethnicity from clinical features, and (2) interpret trained models to describe how specific features contribute to predictions. The RIDDLE library implements the methods introduced in "RIDDLE: Race and ethnicity Imputation from Disease history with Deep LEarning" (PLOS Computational Biology, 2018).

Compared to alternative methods (e.g., scikit-learn/Python, glm/R), RIDDLE is designed to handle large and high-dimensional datasets in a performant fashion. RIDDLE trains models efficiently by running on a parallelized TensorFlow/Theano backend, and avoids memory overflow by preprocessing data in conjunction with batch-wise training.

RIDDLE uses Keras to specify and train the underlying deep neural networks, and DeepLIFT to compute feature-to-class contribution scores. The current RIDDLE Python module works with both TensorFlow and Theno as the backend to Keras. The default architecture is a deep multi-layer perceptron (deep MLP) that takes binary-encoded features and targets. However, you can specify any neural network architecture (e.g., LSTM, CNN) and data format by writing your own model_module files!


Please visit


Python Libraries:

  • Keras (keras)
  • DeepLIFT (deeplift, available on GitHub)
  • TensorFlow (tensorflow) or Theano (theano)
  • scikit-learn (sklearn)
  • NumPy (numpy)
  • SciPy (scipy)
  • Matplotlib (matplotlib)
  • h5py (h5py)


  • HDF5

Unit testing

Execute the following command in the outer repository folder (not riddle/riddle):

% PYTHONPATH=. pytest


What's the easiest way to install RIDDLE?

You can clone the GitHub repo and go from there:

% git clone --recursive git://
% cd riddle
% pip install -r requirements.txt

How can I run the RIDDLE pipeline?

Execute the following scripts.

% python  # run parameter tuning
% python            # train and evaluate the model
% python  # interpret the traiend model

What is the default format for data files?

Please refer to the example data file dummy.txt and the accompanying README in the _data directory.


Ji-Sung Kim
Princeton University
hello (at) (technical inquiries)

Xin Gao, Associate Professor
King Abdullah University of Science and Technology

Andrey Rzhetsky, Edna K. Papazian Professor
University of Chicago
andrey.rzhetsky (at) (research inquiries)

License & Attribution

All media (including but not limited to designs, images and logos) are copyrighted by Ji-Sung Kim (2017).

Project code (explicitly excluding media) is licensed under the Apache License 2.0. If you would like use or modify this project or any code presented here, please include the notice and license files, and cite:

    author = {Kim, Ji-Sung AND Gao, Xin AND Rzhetsky, Andrey},
    journal = {PLOS Computational Biology},
    publisher = {Public Library of Science},
    title = {RIDDLE: Race and ethnicity Imputation from Disease history with Deep LEarning},
    year = {2018},
    month = {04},
    volume = {14},
    url = {},
    pages = {1-15},
    number = {4},
    doi = {10.1371/journal.pcbi.1006106}
Alternatives To Riddle
Select To Compare

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (808,235
Learning (76,209
Machine Learning (37,158
Deep Learning (36,543
Deep (36,543
Neural Network (15,516
Keras (10,450
Bioinformatics (4,555
Biology (1,231
Computational Biology (448
Epidemiology (255
Imputation (94