<a href="https://covid19datahub.io"><img src="https://storage.covid19datahub.io/logo.svg" align="right" height="128"/></a>
# Python Interface to COVID-19 Data Hub
[](https://pypi.org/pypi/covid19dh/) [](https://pypi.org/pypi/covid19dh/) [](https://doi.org/10.21105/joss.02376) [](https://github.com/covid19datahub/Python)
Download COVID-19 data across governmental sources at national, regional, and city level, as described in [Guidotti and Ardia (2020)](https://www.doi.org/10.21105/joss.02376). Includes the time series of vaccines, tests, cases, deaths, recovered, hospitalizations, intensive therapy, and policy measures by [Oxford COVID-19 Government Response Tracker](https://www.bsg.ox.ac.uk/research/research-projects/coronavirus-government-response-tracker). Please agree to the [Terms of Use](https://covid19datahub.io/LICENSE.html) and cite the following reference when using it:
**Reference**
Guidotti, E., Ardia, D., (2020).
COVID-19 Data Hub
_Journal of Open Source Software_, **5**(51):2376
[https://doi.org/10.21105/joss.02376](https://doi.org/10.21105/joss.02376)
## Setup and usage
Install from [pip](https://pypi.org/project/covid19dh/) with
```python
pip install covid19dh
```
Importing the main function `covid19()`
```python
from covid19dh import covid19
x, src = covid19()
```
Package is regularly updated. Update with
```bash
pip install --upgrade covid19dh
```
## Return values
The function `covid19()` returns 2 pandas dataframes:
* the data and
* references to the data sources.
## Parametrization
### Country
List of country names (case-insensitive) or ISO codes (alpha-2, alpha-3 or numeric). The list of ISO codes can be found [here](https://github.com/covid19datahub/COVID19/blob/master/inst/extdata/db/ISO.csv).
Fetching data from a particular country:
```python
x, src = covid19("USA") # Unites States
```
Specify multiple countries at the same time:
```python
x, src = covid19(["ESP","PT","andorra",250])
```
If `country` is omitted, the whole dataset is returned:
```python
x, src = covid19()
```
### Raw data
Logical. Skip data cleaning? Default `True`. If `raw=False`, the raw data are cleaned by filling missing dates with `NaN` values. This ensures that all locations share the same grid of dates and no single day is skipped. Then, `NaN` values are replaced with the previous non-`NaN` value or `0`.
```python
x, src = covid19(raw = False)
```
### Date filter
Date can be specified with `datetime.datetime`, `datetime.date` or as a `str` in format `YYYY-mm-dd`.
```python
from datetime import datetime
x, src = covid19("SWE", start = datetime(2020,4,1), end = "2020-05-01")
```
### Level
Integer. Granularity level of the data:
1. Country level
2. State, region or canton level
3. City or municipality level
```python
from datetime import date
x, src = covid19("USA", level = 2, start = date(2020,5,1))
```
### Cache
Logical. Memory caching? Significantly improves performance on successive calls. By default, using the cached data is enabled.
Caching can be disabled (e.g. for long running programs) by:
```python
x, src = covid19("FRA", cache = False)
```
### Vintage
Logical. Retrieve the snapshot of the dataset that was generated at the `end` date instead of using the latest version. Default `False`.
To fetch e.g. US data that were accessible on *22th April 2020* type
```python
x, src = covid19("USA", end = "2020-04-22", vintage = True)
```
The vintage data are collected at the end of the day, but published with approximately 48 hour delay,
once the day is completed in all the timezones.
Hence if `vintage = True`, but `end` is not set, warning is raised and `None` is returned.
```python
x, src = covid19("USA", vintage = True) # too early to get today's vintage
```
```
UserWarning: vintage data not available yet
```
### Data Sources
The data sources are returned as second value.
```python
from covid19dh import covid19
x, src = covid19("USA")
print(src)
```
### Additional information
Find out more at https://covid19datahub.io
## Acknowledgements
Developed and maintained by [Martin Benes](https://pypi.org/user/martinbenes1996/).
## Cite as
*Guidotti, E., Ardia, D., (2020), "COVID-19 Data Hub", Journal of Open Source Software 5(51):2376, doi: 10.21105/joss.02376.*
A BibTeX entry for LaTeX users is
```latex
@Article{,
title = {COVID-19 Data Hub},
year = {2020},
doi = {10.21105/joss.02376},
author = {Emanuele Guidotti and David Ardia},
journal = {Journal of Open Source Software},
volume = {5},
number = {51},
pages = {2376}
}
```
Raw data
{
"_id": null,
"home_page": "https://www.covid19datahub.io",
"name": "covid19dh",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "2019-nCov,coronavirus,covid-19,covid-data,covid19-data",
"author": "Martin Bene\u0161",
"author_email": "martinbenes1996@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/58/4f/b9712f889f168cc38201f7b4118efe772a36aaeab1b3aa8eb557e61f9143/covid19dh-2.3.1.tar.gz",
"platform": null,
"description": "<a href=\"https://covid19datahub.io\"><img src=\"https://storage.covid19datahub.io/logo.svg\" align=\"right\" height=\"128\"/></a>\n\n# Python Interface to COVID-19 Data Hub\n\n[](https://pypi.org/pypi/covid19dh/) [](https://pypi.org/pypi/covid19dh/) [](https://doi.org/10.21105/joss.02376) [](https://github.com/covid19datahub/Python)\n\nDownload COVID-19 data across governmental sources at national, regional, and city level, as described in [Guidotti and Ardia (2020)](https://www.doi.org/10.21105/joss.02376). Includes the time series of vaccines, tests, cases, deaths, recovered, hospitalizations, intensive therapy, and policy measures by [Oxford COVID-19 Government Response Tracker](https://www.bsg.ox.ac.uk/research/research-projects/coronavirus-government-response-tracker). Please agree to the [Terms of Use](https://covid19datahub.io/LICENSE.html) and cite the following reference when using it:\n\n**Reference**\n\nGuidotti, E., Ardia, D., (2020). \nCOVID-19 Data Hub \n_Journal of Open Source Software_, **5**(51):2376 \n[https://doi.org/10.21105/joss.02376](https://doi.org/10.21105/joss.02376) \n\n## Setup and usage\n\nInstall from [pip](https://pypi.org/project/covid19dh/) with\n\n```python\npip install covid19dh\n```\n\nImporting the main function `covid19()` \n\n```python\nfrom covid19dh import covid19\nx, src = covid19() \n```\n\nPackage is regularly updated. Update with\n\n```bash\npip install --upgrade covid19dh\n```\n\n## Return values\n\nThe function `covid19()` returns 2 pandas dataframes:\n* the data and\n* references to the data sources.\n\n## Parametrization\n\n### Country\n\nList of country names (case-insensitive) or ISO codes (alpha-2, alpha-3 or numeric). The list of ISO codes can be found [here](https://github.com/covid19datahub/COVID19/blob/master/inst/extdata/db/ISO.csv).\n\nFetching data from a particular country:\n\n```python\nx, src = covid19(\"USA\") # Unites States\n```\n\nSpecify multiple countries at the same time:\n\n```python\nx, src = covid19([\"ESP\",\"PT\",\"andorra\",250])\n```\n\nIf `country` is omitted, the whole dataset is returned:\n\n```python\nx, src = covid19()\n```\n\n### Raw data\n\nLogical. Skip data cleaning? Default `True`. If `raw=False`, the raw data are cleaned by filling missing dates with `NaN` values. This ensures that all locations share the same grid of dates and no single day is skipped. Then, `NaN` values are replaced with the previous non-`NaN` value or `0`. \n\n```python\nx, src = covid19(raw = False)\n```\n\n### Date filter\n\nDate can be specified with `datetime.datetime`, `datetime.date` or as a `str` in format `YYYY-mm-dd`.\n\n```python\nfrom datetime import datetime\nx, src = covid19(\"SWE\", start = datetime(2020,4,1), end = \"2020-05-01\")\n```\n\n### Level\n\nInteger. Granularity level of the data:\n\n1. Country level\n2. State, region or canton level\n3. City or municipality level\n\n```python\nfrom datetime import date\nx, src = covid19(\"USA\", level = 2, start = date(2020,5,1))\n```\n\n### Cache\n\nLogical. Memory caching? Significantly improves performance on successive calls. By default, using the cached data is enabled.\n\nCaching can be disabled (e.g. for long running programs) by:\n\n```python\nx, src = covid19(\"FRA\", cache = False)\n```\n\n### Vintage\n\nLogical. Retrieve the snapshot of the dataset that was generated at the `end` date instead of using the latest version. Default `False`.\n\nTo fetch e.g. US data that were accessible on *22th April 2020* type\n\n```python\nx, src = covid19(\"USA\", end = \"2020-04-22\", vintage = True)\n```\n\nThe vintage data are collected at the end of the day, but published with approximately 48 hour delay,\nonce the day is completed in all the timezones.\n\nHence if `vintage = True`, but `end` is not set, warning is raised and `None` is returned.\n\n```python\nx, src = covid19(\"USA\", vintage = True) # too early to get today's vintage\n```\n\n```\nUserWarning: vintage data not available yet\n```\n\n### Data Sources\n\nThe data sources are returned as second value.\n\n```python\nfrom covid19dh import covid19\nx, src = covid19(\"USA\")\nprint(src)\n```\n\n### Additional information\n\nFind out more at https://covid19datahub.io\n\n## Acknowledgements\n\nDeveloped and maintained by [Martin Benes](https://pypi.org/user/martinbenes1996/).\n\n## Cite as\n\n*Guidotti, E., Ardia, D., (2020), \"COVID-19 Data Hub\", Journal of Open Source Software 5(51):2376, doi: 10.21105/joss.02376.*\n\nA BibTeX entry for LaTeX users is\n\n```latex\n@Article{,\n title = {COVID-19 Data Hub},\n year = {2020},\n doi = {10.21105/joss.02376},\n author = {Emanuele Guidotti and David Ardia},\n journal = {Journal of Open Source Software},\n volume = {5},\n number = {51},\n pages = {2376}\n}\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Unified data hub for a better understanding of COVID-19 https://covid19datahub.io",
"version": "2.3.1",
"project_urls": {
"Download": "https://github.com/covid19datahub/Python/archive/2.3.0.tar.gz",
"Homepage": "https://www.covid19datahub.io"
},
"split_keywords": [
"2019-ncov",
"coronavirus",
"covid-19",
"covid-data",
"covid19-data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "357b1466f26f890998fb33f80ebd11ab56600d79fecbe1b3a97578b6da60688b",
"md5": "0c811a0f9e6cf2f055175754b3b3864c",
"sha256": "a0d16916cd91c26ac58ae28d428da8088fd0f522e3b906a3226d692fecc063f8"
},
"downloads": -1,
"filename": "covid19dh-2.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c811a0f9e6cf2f055175754b3b3864c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9386,
"upload_time": "2024-01-30T11:20:24",
"upload_time_iso_8601": "2024-01-30T11:20:24.323840Z",
"url": "https://files.pythonhosted.org/packages/35/7b/1466f26f890998fb33f80ebd11ab56600d79fecbe1b3a97578b6da60688b/covid19dh-2.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "584fb9712f889f168cc38201f7b4118efe772a36aaeab1b3aa8eb557e61f9143",
"md5": "379b16df1813956c2988f99a8cbfcdd7",
"sha256": "593dc7b348e9e2be5341e6f826817329afdebac16218d5055d106766d3e8c0ec"
},
"downloads": -1,
"filename": "covid19dh-2.3.1.tar.gz",
"has_sig": false,
"md5_digest": "379b16df1813956c2988f99a8cbfcdd7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10544,
"upload_time": "2024-01-30T11:20:25",
"upload_time_iso_8601": "2024-01-30T11:20:25.558384Z",
"url": "https://files.pythonhosted.org/packages/58/4f/b9712f889f168cc38201f7b4118efe772a36aaeab1b3aa8eb557e61f9143/covid19dh-2.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-30 11:20:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "covid19datahub",
"github_project": "Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "covid19dh"
}
JSON
