Installation Guide

  1. To begin, first checkout the code from GitLab:

git clone

2. Next set up the enviroment required to run the model, first making sure Anaconda is installed. .. note:: Anaconda can be downloaded from

Included in the repository are two yaml formatted Anaconda enviroment specs:

  • enviroment.yml: Contains the standard packages required to run the model

  • enviroment_gpu.yml: Standard enviroment + CUDA/CuPy for GPU acceleration. CuPy will be used to replace all references to numpy in the model itself.


CuPy requires an NVIDIA GPU and will only increase performance for model runs over large geographic area (e.g. the whole US)

To install and activate the appropriate enviroment:

cd bucky
conda env create --file enviroment.yml
conda activate bucky


cd bucky
conda env create --file enviroment_gpu.yml
conda activate bucky_gpu
  1. Finally, if you wish to use custom paths to store the data associated with the model (either inputs or outputs), simply edit the contents of config.yml in the root of the repository


It is recommended to use high speed storage for <raw_output_dir> if possible as that will have an impact on runtimes.

Downloading Input Datasets

The model depends on a number of input datasets being available in the <data_dir> specified in config.yml. To automatically download them just using the script provided in the root of the repository (this will take some time for the initial download):

chmod +x ./

The following datasets will be automatically downloaded:

  • COVID-19 Data Repository by the Center for Systems Science and Engineering at Johns Hopkins University
    • COVID-19 Case and death data on the county level

    • GitHub

  • Descartes Labs: Data for Mobility Changes in Response to COVID-19
    • State and county-level mobility statistics

    • GitHub

  • COVID Exposure Indices from PlaceIQ movement data
    • State and county-level location exposure indices

    • Reference: Measuring movement and social contact with smartphone data: a real-time application to COVID-19 by Couture, Dingel, Green, Handbury, and Williams Link

    • GitHub

  • The COVID Tracking Project at The Atlantic
    • COVID-19 case and death data at the state level

    • GitHub

  • US TIGER shapefiles from the US Census
  • US Census Bridged-Race Population estimates
  • Social Contact Matrices for 152 Countries
    • Projecting social contact matrices in 152 countries using contact surveys and demographic data, Prem et al.

    • Paper

  • USAFacts Coronavirus Stats and Data
    • County-level coronavirus cases and deaths

    • Link