timesias 0.0.1

A machine-learning framework for predicting outcomes from time-series history.

Timesias

Forcast outcomes from time-series history. This is the top-performing algorithm for DII National Data Science Challenge.

Installation

Clone this program to your local directory:

git clone https://github.com/GuanLab/sepsis.git

Dependency

• python (3.7.4)
• numpy (1.17.2)
• pandas (0.25.1)
• LightGBM (3.1.1)
• scikit-learn (0.19.0)
• shap (0.38.1)

For visualization:

• boken (2.3.0)

Input data format

The example data in the data/ are randomly generated data for the demonstration of the algorithm.

Two types of data is requied for model training and prediction:

• gs.file: .txt file two columns. The first column is file name index. The second column is the gold standard (0/1), representing the final outbreak of sepsis

0.psv,1
1.psv,1
2.psv,0
3.psv,1
4.psv,0
5.psv,1
6.psv,1

• *.psv: .psv table files separated by |, which is the time-series feature records. The header of psv file are the feature names. To note, the first column is the time index.

HR|feature_1|feature_2|...|feature_n-1|feature_n
0.0|1|0.0|...|1.3|0.0 
1.0|NaN|0.0|...|0.0|0.0
3.5|NaN|2.3|...|0.0|0.0

Model training and cross validation

timesias -g [GS_FILE_PATH] -t [LAST_N_RECORDS] -f [EXTRA_FEATURES] --shap

• GS_FILE_PATH: the path to the gold-standard file; for example, /data/gs.file;
• LAST_N_RECORDS: last n records to use for prediction. default: 16;
• EXTRA_FEATURES: addtional features used for prediction. default: ['norm', 'std', 'missing_portion', 'baseline'], which are all features we used in DII Data challenge.

also use

 timesias --help

to get instructions on the usage of our program.

This will generate models, which will be saved under a new directory ./models.

Evaluation results during five-fold cross validation will be stored in eva.tsv.

Top feature evaluation

if --shap is indicated, SHAP analysis will be carried out to show top contributing measurements and last nth time points. This will generate an html report (top_feature_report.html) like the following:

The corresponding shap values will be stored in shap_group_by_measurment.csv and shap_group_by_timeslot.csv.

Other applications of this method

This method can be generalized to be used on other hospitalization data. One application of this method is the COVID-19 DREAM Challenge, where this method also achieves top performance.

Reference

• For citation, please refer to our latest iScience paper: Assessment of the timeliness and robustness for predicting adult sepsis.
• For protocol(TBD)