{"id":18989858,"url":"https://github.com/cdcgov/ephtrackr","last_synced_at":"2025-04-22T11:11:11.808Z","repository":{"id":81711145,"uuid":"360220297","full_name":"CDCgov/EPHTrackR","owner":"CDCgov","description":"R interface to the CDC National Public Health Tracking Network API","archived":false,"fork":false,"pushed_at":"2024-07-21T14:04:00.000Z","size":1002,"stargazers_count":20,"open_issues_count":7,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-17T00:14:35.531Z","etag":null,"topics":["cdc","environmental-data","epidemiology","publichealth","r","rstats"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CDCgov.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-21T15:32:24.000Z","updated_at":"2025-03-21T19:15:36.000Z","dependencies_parsed_at":"2024-05-31T18:49:34.228Z","dependency_job_id":"a81c3287-932c-467c-9e36-b831d7ff0c26","html_url":"https://github.com/CDCgov/EPHTrackR","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":"CDCgov/template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2FEPHTrackR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2FEPHTrackR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2FEPHTrackR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2FEPHTrackR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CDCgov","download_url":"https://codeload.github.com/CDCgov/EPHTrackR/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250228637,"owners_count":21395958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdc","environmental-data","epidemiology","publichealth","r","rstats"],"created_at":"2024-11-08T17:08:09.554Z","updated_at":"2025-04-22T11:11:11.778Z","avatar_url":"https://github.com/CDCgov.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\neditor_options: \n  chunk_output_type: console\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit the README.Rmd file --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\"\n)\n```\n\n\u003c!-- badges: start --\u003e\n[![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) \n[![R build status](https://github.com/CDCgov/EPHTrackR/workflows/R-CMD-check/badge.svg)](https://github.com/CDCgov/EPHTrackR/actions?workflow=R-CMD-check)\n[![CRAN status](https://www.r-pkg.org/badges/version/sword)](https://CRAN.R-project.org/package=sword)\n[![Lifecycle: stable](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)\n\u003c!-- badges: end --\u003e\n\n\n\u003c!-- [![Travis-CI Build Status](https://travis-ci.org/cont-limno/LAGOSNE.svg?branch=master)](https://travis-ci.org/cont-limno/LAGOSNE) [![CRAN\\_Status\\_Badge](http://www.r-pkg.org/badges/version/LAGOSNE)](https://cran.r-project.org/package=LAGOSNE) [![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/LAGOSNE)](https://cran.r-project.org/package=LAGOSNE)\n[![Codecov test coverage](https://codecov.io/gh/tidyverse/dplyr/branch/master/graph/badge.svg)](https://codecov.io/gh/tidyverse/dplyr?branch=master)--\u003e\n\n\n# EPHTrackR \u003cimg src=\"man/figures/CDC_Tracking_Combined.jpg\" align=\"right\" height=140/\u003e\n\nThe `EPHTrackR` package provides an R interface to access and download publicly available data stored on the [CDC National Environmental Public Health Tracking Network](https://www.cdc.gov/nceh/tracking/about.htm) (Tracking Network) via a connection with the [Tracking Network Data API](https://ephtracking.cdc.gov/apihelp). A detailed user guide describing available API calls and associated outputs can be found at that link. Associated metadata for downloaded measure data can be found on the Tracking Network [Indicators and Data](https://ephtracking.cdc.gov/searchMetadata) page. Users might find it easier to view the online [Data Explorer](https://ephtracking.cdc.gov/DataExplorer/) to get a sense of the available datasets before or while using this package.\n\nThe purpose of the Tracking Network is to deliver information and data to protect the nation from health issues arising from or directly related to environmental factors. At the local, state, and national levels, the Tracking Network relies on a variety of people and information systems to deliver a core set of health, exposure, and hazards data; information summaries; and tools to enable analysis, visualization, and reporting of insights drawn from data.\n\n**Measures** are the core data product of the Tracking Network. Measures are organized into **indicators**, groups of highly related measures, and **content areas**, the highest level of categorization containing all the indicators related to a broad topic of interest. Using Tracking Network data, users can create customized maps, tables, and graphs of local, state, and national data. The Tracking Network contains data covering several focal areas: \u003cbr\u003e\n    — Health effects of exposures, such as asthma \u003cbr\u003e\n    — Hazards in the environment, such as air pollution \u003cbr\u003e\n    — Climate, such as extreme heat events \u003cbr\u003e\n    — Community design, such as access to parks \u003cbr\u003e\n    — Lifestyle risk factors, such as smoking \u003cbr\u003e\n    — Population characteristics, such as age and income \u003cbr\u003e\n\n\n## Installation\n\n```{r install,eval=FALSE, echo=T}\n#install development version from Github\n#install devtools first if you haven't previously - install.packages(\"devtools\")\ndevtools::install_github(\"CDCgov/EPHTrackR\", \n                         dependencies = TRUE)\n```\n \n\n## Load package\n\n```{r load_library, eval=T} \nlibrary(EPHTrackR)\n```\n\n\n## Saving a Tracking API token\n\nThe `tracking_api_token()` function adds a Tracking API token to your .Renviron file so it can be called securely without being stored in your code. After you have run this function, the token will be called automatically by all the other functions in this package. Leaving the default argument `install=T`, ensures that the token will be saved in future R sessions. A token can be acquired by emailing, trackingsupport(AT)cdc.gov. A token is not required to use this package, but you will experience less throttling and better API support if you have one. Further information is available at https://ephtracking.cdc.gov/apihelp. \n\n```{r save_token, eval=FALSE, echo=t}\n\ntracking_api_token(\"XXXXXXXXXXXXXXXXX\", \n                   install=T)\n\n#After you run this function, reload your environment so you can use the token without restarting R.\nreadRenviron(\"~/.Renviron\")\n\n\n#Token can be viewed by running:\nSys.getenv(\"TRACKING_API_TOKEN\")\n\n```\n\n## Full measure inventory\n\nRunning the `list_measures()` function without any additional inputs retrieves the latest inventory of content areas, indicators, and measures from the Tracking Network Data API.\n\n```{r full_data, eval=FALSE, echo=t}\nmeasures_inventory \u003c- list_measures()\n\nView(measures_inventory)\n\n```\n\n\n## Viewing content area, indicator, and measure names\nEach content area, indicator, and measure has a full name and a unique identifier. You can use this information to determine what data are available on the Tracking Network and make appropriate calls to download the data (see below).\n\n#### List content areas available\n```{r content areas, eval=T}\nca_df \u003c- list_content_areas()\n\nhead(ca_df)\n```\n\n#### List indicators in specified content area(s)\n\n```{r indicators, eval=T}\nind_df \u003c- list_indicators(content_area = \"Heat \u0026 Heat-related Illness (HRI)\")\n\nhead(ind_df)\n```\n\n#### List measures in specified indicator(s) and/or content area(s)\n\n```{r measures, eval=T}\nmeas_df \u003c- list_measures(content_area = 36)\n\nhead(meas_df)\n```\n\n\n## Viewing available geographic and temporal types and items for specified measures\n\nMeasures on the Tracking Network vary in their geographic resolution (e.g., state, county), geographic extent (e.g., Massachusetts, Michigan, Pennsylvania, California, Georgia), temporal resolution (e.g., year, month) and temporal extent (e.g., 2000-2010, 2010-2020). By becoming familiar with the geographies and temporal periods for which data are available using this function, you can make more targeted data downloads.\n\n#### List geographic types available for specified measures\n\nMeasures are typically available at the state, county, or census tract level.\n\n```{r geographic types, eval = T}\ngeog_type_df \u003c- list_GeographicTypes(measure= \"Number of Square Miles within FEMA Designated Flood Hazard Area\")\n\nhead(geog_type_df[[1]])\n```\n\n#### List geographic items available for specified measures\n\nThis function identifies the particular geographic items (e.g., Alabama) that are available for a specified measure. It will reveal both the lowest level geographic items available (e.g., a county or census tract) and an overarching items, like states (i.e., parent geographic item) that contains the lowest level geographic items you would like returned in the data.\n\n```{r geographic items, eval = T}\ngeog_item_df \u003c- list_GeographicItems(measure= \"Annual Number of Extreme Heat Days from May to September\",\n                                     geo_type=\"County\")\n\nhead(geog_item_df[[1]])\n```\n\n\n#### List temporal items available for specified measures\n\nMeasures are typically available at an annual scale, but also can be daily, monthly, or weekly. This function identifies the particular years, months, days etc. that are available for the specified measure (e.g., 2001, Aug 2020, etc.)\n\n```{r temporal items, eval = T}\ntemp_df \u003c- list_TemporalItems(measure= \"Annual Number of Extreme Heat Days from May to September\")\n\nhead(temp_df[[1]])\n```\n\n## Viewing available Advanced Options for data stratification\n\nIn addition to geographic and temporal specifications, some measures on the Tracking Network have a set of **Advanced Options** that allow users to access data stratified by other variables. For instance, data on asthma hospitalizations can be broken down by age and/or gender.\n\n#### List available stratification levels for a measure\n\n**Advanced Options** might only be available at a particular geographic scale (e.g., age-breakdown of asthma hospitalizations is only available at the state level). Therefore, results showing available stratification levels always include the geography type. The output of this function is a list with a separate element for each geography type available (e.g., state, county) for the specified measure. Each row in the data frame elements of the list shows a stratification available for the measure.\n\n```{r statification levels, eval = T}\nstrat_df \u003c- list_StratificationLevels(measure=99)\n\nhead(strat_df[[1]])\n```\n\n#### List available stratification types for a measure\n\nIf you'd like to query Tracking data by a specific stratification level (e.g., you'd like data for just males), then you need to run the `list_StratificationTypes()` function to identify the internal name for the stratification and the appropriate code for the stratification level of interest (e.g., 1 for male, 2 for female). The internal name can be found in the in the ColumnName column of the function output and codes can be found in the nested list found in the stratificationItem column of the function output. Refer back to these when constructing queries with with the `get_data()` function.\n\n```{r statification types, eval = T}\nstrat_df \u003c- list_StratificationTypes(measure=99,\n                                     geo_type=\"State\")\n\nstrat_df[[1]]\n\n#viewing the nested list in the stratificationItem column of the function output to identify stratification level codes\nstrat_df[[1]]$stratificationItem\n\n```\n\n\n## Accessing Tracking Network data\n\nYou can use the information from the functions listed above to request specific data from the Tracking Network Data API. Be careful when making queries. If you request data that include many years and/or data at a fine geographic scale, the dataset could be very large and take a long time to download (if it doesn't crash your session and bog down the entire  API).\n\nWe recommend that you include only one measure and one stratification level in a data query. Many geographies and temporal periods may be submitted. The function will likely still work if vectors of multiple measures or stratification levels are submitted, but the resulting object will be a multi-element list and distinguishing the element that applies to a particular measure or stratification might be difficult. The output of function calls with a single measure and stratification level is a list with one element containing the relevant data frame.\n\n#### Downloading state-level measure data\n\n```{r data download simple, eval = T}\n\ndata_st\u003c-get_data(measure=99,\n                  strat_level = \"ST\")\n\nhead(data_st[[1]])\n```\n\n#### Downloading measure data with advanced options\n\nThe advanced stratification options are submitted via the `strat_level` argument and the subset of stratification levels derived from the `list_StratificationTypes()` function can be submitted with the `stratItems` argument.\n\n```{r data download advanced, eval = T}\n\n\n\n\ndata_strat.item \u003c- get_data(measure=99,\n                  strat_level =  \"ST_AG_GN\",\n                  temporalItems = c(2005),\n                  geoItems = \"Arizona\",\n                  stratItems = c(\"GenderId=1\",\"AgeBandId=3\"))\n\nhead(data_strat.item[[1]])\n\n\n```\n\n#### Downloading measure data with advanced options and specific geographies\n\nYou can submit state names, abbreviations, or state FIPS codes with the `geoItems` argument. This will return data for either the specified state(s) or all the sub-state geographies within the state, depending on the geography type of the data (e.g., state, county). Individual sub-state geographies can also be submitted by FIPS code or name with this argument. For measures with sub-state geographies, a mix of state and sub-state entries can be submitted.\n\n```{r data download monthly, eval = T}\n\ndata_mo.geo\u003c-get_data(measure=99,  \n                      strat_level = \"State x County\", #this can be written by name or ID (i.e., \"ST_CT)\n                      geoItems = c(\"Massachusetts\",\n                                   \"Alameda, CA\", #county name should not include word 'county' and must have state\n                                   1001))\n\nhead(data_mo.geo[[1]])\n\n```\n\n#### Downloading measure data with specific geographies and temporal periods selected\n\n```{r data download the works, eval = T}\n\ndata_tpm.geo \u003c- get_data(measure=99, \n                      strat_level = \"ST\",\n                      geoItems = c(\"CO\", \"ME\", \"FL\"),\n                      temporalItems = c(2014:2018))\n\nhead(data_tpm.geo[[1]])\n\n```\n\n\n## Public Domain Standard Notice\nThis repository constitutes a work of the United States Government and is not\nsubject to domestic copyright protection under 17 USC § 105. This repository is in\nthe public domain within the United States, and copyright and related rights in\nthe work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).\nAll contributions to this repository will be released under the CC0 dedication. By\nsubmitting a pull request you are agreeing to comply with this waiver of\ncopyright interest.\n\n## License Standard Notice\nThe repository utilizes code licensed under the terms of the Apache Software\nLicense and therefore is licensed under ASL v2 or later.\n\nThis source code in this repository is free: you can redistribute it and/or modify it under\nthe terms of the Apache Software License version 2, or (at your option) any\nlater version.\n\nThis source code in this repository is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the Apache Software License for more details.\n\nYou should have received a copy of the Apache Software License along with this\nprogram. If not, see http://www.apache.org/licenses/LICENSE-2.0.html\n\nThe source code forked from other open source projects will inherit its license.\n\n## Privacy Standard Notice\nThis repository contains only non-sensitive, publicly available data and\ninformation. All material and community participation is covered by the\n[Disclaimer](https://github.com/CDCgov/EPHTrackR/blob/master/DISCLAIMER.md)\nand [Code of Conduct](https://github.com/CDCgov/EPHTrackR/blob/master/code-of-conduct.md).\nFor more information about CDC's privacy policy, please visit [http://www.cdc.gov/other/privacy.html](https://www.cdc.gov/other/privacy.html).\n\n## Contributing Standard Notice\nAnyone is encouraged to contribute to the repository by [forking](https://help.github.com/articles/fork-a-repo)\nand submitting a pull request. (If you are new to GitHub, you might start with a\n[basic tutorial](https://help.github.com/articles/set-up-git).) By contributing\nto this project, you grant a world-wide, royalty-free, perpetual, irrevocable,\nnon-exclusive, transferable license to all users under the terms of the\n[Apache Software License v2](http://www.apache.org/licenses/LICENSE-2.0.html) or\nlater.\n\nAll comments, messages, pull requests, and other submissions received through\nCDC including this GitHub page may be subject to applicable federal law, including but not limited to the Federal Records Act, and may be archived. Learn more at [http://www.cdc.gov/other/privacy.html](http://www.cdc.gov/other/privacy.html).\n\n## Records Management Standard Notice\nThis repository is not a source of government records, but is a copy to increase\ncollaboration and collaborative potential. All government records will be\npublished through the [CDC web site](http://www.cdc.gov).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdcgov%2Fephtrackr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdcgov%2Fephtrackr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdcgov%2Fephtrackr/lists"}