XPRIZE Pandemic Response Challenge

Introduction

Welcome to the XPRIZE Pandemic Response Challenge! This repository contains what you need to get started in creating your submission for the contest.

Within this repository you will find:

Sample predictors and prescriptors provided by Cognizant, in the form of Jupyter notebooks and python scripts
Sample implementations of the "predict" API and the "prescribe" API, which you will be required to implement as part of your submission
Sample IP (Intervention Plan) data to test your submission

Pre-requisites

To run the examples, you will need:

A computer or cloud image running a recent version of OS X or Ubuntu (Using Microsoft Windows™ may be possible but the XPRIZE team and Cognizant will be unable to support you.)
Your machine must have sufficient resources in terms of memory, CPU, and disk space to train machine learning models and run Python programs.
An installed version of Python, version ≥ 3.6. To avoid dependency issues, we strongly recommend using a standard Python virtual environment with pip for package management. The examples in this repo assume you are using such an environment.

Having registered for the contest, you should also have:

A copy of the Competition Guidelines
Access to the Support Slack channel
A pre-initialized sandbox within the XPRIZE system

Examples

Under the covid_xprize/examples directory you will find some examples of predictors and prescriptors that you can inspect to learn more about what you need to do:

predictors/linear contains a simple linear model, using the Lasso algorithm.
predictors/lstm contains a more sophisticated LSTM model for making predictions.
prescriptors/zero contains a trivial prescriptor that always prescribes no interventions; prescriptors/random contains one that prescribes random interventions.
prescriptors/neat contains code for training prescriptors with NEAT

The instructions below assume that you are using a standard Python virtual environment, and pip for package management. Installations using other environments (such as conda) are outside the scope of these steps.

In order to run the examples locally:

Ensure your current working directory is the root folder of this repository (the same directory as this README resides in). The examples assume your working directory is set to the project root and all paths are relative to it.
Ensure your PYTHONPATH includes your current directory:
```
export PYTHONPATH="$(pwd):$PYTHONPATH"
```
Create a Python virtual environment
Activate the virtual environment

Install the necessary requirements:

pip install -r requirements.txt --upgrade

Start Jupyter services:
```
jupyter notebook
```
This causes a browser window to launch
Browse to and launch one of the examples (such as linear) and run through the steps in the associated notebook -- in the case of linear, Example-Train-Linear-Rollout-Model.ipynb.
The result should be a trained predictor, and some predictions generated by running the predictor on test data. Details are in the notebooks.

XPRIZE sandbox

Upon registering for the contest, you will have been given access to a "sandbox", a virtual area within the XPRIZE cloud within which you can submit your work.

Submitting a predictor

In order for the automated judging process to detect and evaluate your submission, you must follow the instructions below. If your script does not conform to the API in any way, your submission will be omitted from judging.

Within your sandbox, under your home directory you will find a pre-created work directory.
Under this work directory, you must provide a Python script with the name predict.py. Examples of such scripts are provided in this repository. This script will invoke your predictor model and save the predictions produced.
Your script must accept particular command line parameters, and generate a particular output, as explained below.
Whatever models and other data files your predictor requires must be uploaded to your sandbox and visible to your predict.py script, for example, by placing them in the work directory or subdirectories thereof.
Expect that the current working directory will be your sandbox work directory when your script is called. Therefore, references to other modules and resource files should be relative to that.

Expect your script to be called as follows (the dates and filenames are just examples and will vary):

python predict.py --start_date 2020-12-01 --end_date 2020-12-31 --interventions_plan ip_file.csv 
  --output_file 2020-12-01_2020_12_31.csv

It is the responsibility of your script to run your predictor for the dates requested (between start_date and end_date inclusive) and generate predictions in the path and file specified by output_file, using the provided intervention plan. Take careful note of the performance and timing requirements in the Competition Guidelines for running your predictor.

For more details on this API, consult the Competition Guidelines or the support Slack channel.

Submitting a prescriptor

Within your sandbox, under your home directory you will find a pre-created work directory.
Under this work directory, you must provide a Python script with the name prescribe.py. Examples of such scripts are provided in this archive. This script will invoke your prescriptions model and save the prescriptions produced.
Your script must accept particular command line parameters, and generate a particular output, as explained below.
Whatever models and other data files your prescriptor requires must be uploaded to your sandbox and visible to your prescribe.py script, for example, by placing them in the work directory or subdirectories thereof.
Expect that the current working directory will be your sandbox work directory when your script is called. Therefore, references to other modules and resource files should be relative to that.

Expect your script to be called as follows (the dates and filenames are just examples and will vary):

python prescribe.py --start_date 2020-12-01 --end_date 2020-12-31 --interventions_past ip_file.csv 
  --output_file 2020-12-01_2020_12_31.csv

It is the responsibility of your script to run your prescriptor for the dates requested (between start_date and end_date inclusive) and generate prescriptions in the path and file specified by output_file. Take careful note of the performance and timing requirements in the Competition Guidelines for running your prescriptor.

Example prescriptors can be found under covid_xprize/examples/prescriptors/.

For more details on this API, consult the Competition Guidelines or the support Slack channel.

Trained standard predictor

The repo also provides a trained standard predictor to train prescriptors against. To use it, call covid_xprize/standard_predictor/predict.py to make predictions. See get_predictions in covid_xprize/examples/prescriptors/neat/utils.py and generate_cases_and_stringency_for_prescriptions in prescriptor_robojudge.ipynb for examples of how to make this call.

More information/Support

For more information and support, refer to the competition guidelines or post your questions in the support Slack channel; you should have gained access to both of these when you created a login in the competition platform.

For a concrete visualization of what the competition is about, see Cognizant's COVID-19 intervention optimization demo. Using this dashboard you can select among different prescriptors from the Pareto Front to see the effect on prescriptions for intervention plans in various regions.

For more background information please see also the research paper From Prediction to Prescription: Evolutionary Optimization of Non-Pharmaceutical Interventions in the COVID-19 Pandemic.

ordovas/covid-xprize