COVID19USFlows

[![MIT License][license-shield]][license-url]

<!-- PROJECT LOGO --> <br /> <p align="center"> <a href="https://geods.geography.wisc.edu/"> <img src="images/geods_safegraph_nsf_logo.jpg" alt="Logo" width="400"> <h2 align="center">Multiscale Dynamic Human Mobility Flow Dataset in the U.S. during the COVID-19 Epidemic</h2> <p align="center"> GeoDS Lab, Department of Geography, University of Wisconsin-Madison. <br /> <a href="https://geods.geography.wisc.edu/covid-19-physical-distancing">Website</a> · <a href="http://geods.geography.wisc.edu/covid19/King_WA.html">View Demo</a> </p> </p> <!-- TABLE OF CONTENTS -->

Table of Contents

• Citation
• About the Project
• Data Processing and Data Descriptor
• Dataset Structure
• How to Download Data?
• Field Descriptions
• License
• Contact
• Acknowledgements

<!-- Citation -->

Citation

If you use this dataset in your research or applications, please cite this source:

Kang, Y., Gao, S., Liang, Y. Li, M., Rao, J. and Kruse, J. Multiscale dynamic human mobility flow dataset in the U.S. during the COVID-19 epidemic. Scientific Data 7, 390 (2020). https://www.nature.com/articles/s41597-020-00734-5

@article{kang2020multiscale,
  title     = {Multiscale Dynamic Human Mobility Flow Dataset in the U.S. during the COVID-19 Epidemic},
  author    = {Kang, Yuhao and Gao, Song and Liang, Yunlei and Li, Mingxiao and Kruse, Jake},
  journal   = {Scientific Data},
  volumn    = {7},
  issue     = {390},
  pages     = {1--13},
  year = {2020}
}

<!-- ABOUT THE PROJECT -->

About The Project

Understanding dynamic human mobility changes and spatial interaction patterns at different geographic scales is crucial for monitoring and measuring the impacts of non-pharmaceutical interventions (such as stay-at-home orders) during the pandemic. In this data descriptor, we introduce an up-to-date multiscale dynamic human mobility flow dataset across the United States, with data starting from January 1st, 2019. By analyzing millions of anonymous mobile phone users’ visit trajectories to various places provided by SafeGraph, the daily and weekly dynamic origin-to-destination (O-D) population flows are computed, aggregated, and inferred at three geographic scales: census tract, county, and state. There is high correlation between our mobility flow dataset and openly available data sources, which shows the reliability of the produced data. Such a high spatiotemporal resolution human mobility flow dataset at different geographic scales over time may help monitor epidemic spreading dynamics, inform public health policy, and deepen our understanding of human behavior changes under the unprecedented public health crisis. This up-to-date O-D flow open data can support many other social sensing and transportation applications.

<!-- GETTING STARTED -->

Data Processing and Data Descriptor

The data processing framework for the mobility flow dataset production:

<p align="center"> <a href="https://geods.geography.wisc.edu/"> <img src="images/framework.png" alt="framework" > </a> </p>

Spatial distribution of places collected by SafeGraph across the whole United States.

<p align="center"> <a href="https://geods.geography.wisc.edu/"> <img src="images/safegraph_core_usa_eq_hist.png" alt="Core Places" > </a> </p>

Spatial patterns of mobility flows during March 2nd to March 8th at the county to county level.

<p align="center"> <a href="https://geods.geography.wisc.edu/"> <img src="images/County_03_02.jpg" alt="Weekly Flows" > </a> </p>

Spatial patterns of mobility flows during April 6th to April 12th at the county to county level.

<p align="center"> <a href="https://geods.geography.wisc.edu/"> <img src="images/County_04_06.jpg" alt="Weekly Flows" > </a> </p>

Temporal patterns of mobility flows in five metropolitan areas (just as examples; the data cover the whole US): New York, Los Angeles, Chicago, Seattle, and Houston. A: daily visitor flows; B: daily population flows; C: weekly visitor flows; D: weekly population flows. Date range: from March 2nd to May 31st, 2020.

<p align="center"> <a href="https://geods.geography.wisc.edu/"> <img src="images/temporal_patterns.jpg" alt="Temporal Patterns" > </a> </p>

A full description of the methodology used for this study can be found here: https://arxiv.org/abs/2008.12238.

<!-- Dataset Structure -->

Dataset Structure

Due to the data size restriction of GitHub, we have splitted our repository into a set of small data repositories. Each data repository follows the same folder structure but only contains part of the dataset. Here are the details about each repository:

| Data Repository | Data Type | Scale | Time Range |
| --- | ----------- | --- | ----------- |
|COVID19USFlows-WeeklyFlows|weekly data|state, county|2019-2021|
|COVID19USFlows-WeeklyFlows-Ct2019|weekly data|census tract|2019|
|COVID19USFlows-WeeklyFlows-Ct2020|weekly data|census tract|2020|
|COVID19USFlows-WeeklyFlows-Ct2021|weekly data|census tract|2021|
|COVID19USFlows-DailyFlows|daily data|state, county|2019-2021|
|COVID19USFlows-DailyFlows-Ct2019-1|daily data|census tract|01/2019-04/2019|
|COVID19USFlows-DailyFlows-Ct2019-2|daily data|census tract|05/2019-08/2019|
|COVID19USFlows-DailyFlows-Ct2019-3|daily data|census tract|09/2019-12/2019|
|COVID19USFlows-DailyFlows-Ct2020-1|daily data|census tract|01/2020-04/2020|
|COVID19USFlows-DailyFlows-Ct2020-2|daily data|census tract|05/2020-08/2020|
|COVID19USFlows-DailyFlows-Ct2020-3|daily data|census tract|09/2020-12/2020|
|COVID19USFlows-DailyFlows-Ct2021|daily data|census tract|01/2021-04/2021|

Data provided in this repository are separated into two folders <em>daily_flows</em> and <em>weekly_flows</em> to store daily flow data and weekly flow data. The two folders are organized according to the geographic scale, where <em>ct2ct</em> indicates flows between census tract to census tract, <em>county2county</em> refers to flows between county to county, and <em>state2state</em> contains flow data originate from one state to others. All files are stored in a csv format, which has been widely used for storing, transferring, and sharing data in multiple domains. File names are formatted as <em>{data_type} _ {spatial_scale}_ {date}.csv</em>, e.g. <em>weekly_county2county_2020_03_02.csv</em> and <em>daily_state2state_2020_04_19.csv</em>. Specifically, for weekly flow data, the dates in file name refers to the date of the Monday in that week but summarize all mobility flows in that week from Monday to Sunday. Since the file size of flow data at census tract level exceeds the GitHub disk limit, each flow data file is split into 20 files, e.g. <em>weekly_ct2ct_2020_03_02_01.csv</em>.

The folders and files are organized as follows.

project
|-- codes
|-- daily_flows
|   |-- state2state
|   |   |-- daily_state2state_2020_03_01.csv
|   |   |-- daily_state2state_2020_03_02.csv
|   |   `-- ...
|   |-- county2county
|   |   |-- daily_county2county_2020_03_01.csv
|   |   |-- daily_county2county_2020_03_02.csv
|   |   `-- ...
|   `-- ct2ct
|       |-- 2020_03_01
|       |   |-- daily_ct2ct_2020_03_01_01.csv
|       |   |-- daily_ct2ct_2020_03_01_02.csv
|       |   `-- ...
|       |-- 2020_03_02
|       |   |-- daily_ct2ct_2020_03_02_01.csv
|       |   |-- daily_ct2ct_2020_03_02_02.csv
|       |   `-- ...
|       `-- ...
`-- weekly_flows
|   |-- state2state
|   |   |-- weekly_state2state_2020_03_02.csv
|   |   |-- weekly_state2state_2020_03_09.csv
|   |   `-- ...
|   |-- county2county
|   |   |-- weekly_county2county_2020_03_02.csv
|   |   |-- weekly_county2county_2020_03_09.csv
|   |   `-- ...
|   `-- ct2ct
|       |-- 2020_03_02
|       |   |-- weekly_ct2ct_2020_03_02_01.csv
|       |   |-- weekly_ct2ct_2020_03_02_02.csv
|       |   `-- ...
|       |-- 2020_03_09
|       |   |-- weekly_ct2ct_2020_03_09_01.csv
|       |   |-- weekly_ct2ct_2020_03_09_02.csv
|       |   `-- ...
|       `-- ...
`-- weekly_country_flows
    |-- country2state
    |   |-- weekly_country2state_2020_03_02.csv
    |   |-- weekly_country2state_2020_03_09.csv
    |   `-- ...
    |-- country2county
    |   |-- weekly_country2county_2020_03_02.csv
    |   |-- weekly_country2county_2020_03_09.csv
    |   `-- ...
    `-- country2ct
        |-- weekly_country2ct_2020_03_02.csv
        |-- weekly_country2ct_2020_03_09.csv
        `-- ...

<!--code usage-->

Code Usage

How to Download Data?

We provide a set of tools for downloading data.

Command Line

If you are Linux/Mac users, you can use wget/curl to download data files.

wget https://raw.githubusercontent.com/GeoDS/COVID19USFlows{repo_url}/master/{data_type}_flows/{spatial_scale}/{data_type}_{spatial_scale}_{date}.csv

curl https://raw.githubusercontent.com/GeoDS/COVID19USFlows{repo_url}/master/{data_type}_flows/{spatial_scale}/{data_type}