---
output: rmarkdown::github_document
editor_options: 
  chunk_output_type: console
---
```{r message=FALSE, warning=FALSE, error=FALSE, include=FALSE}
knitr::opts_chunk$set(message=FALSE, warning=FALSE, fig.retina=2)
options(width=120)
```
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/cdcfluview)](https://cran.r-project.org/package=cdcfluview)
[![Travis-CI Build Status](https://travis-ci.org/hrbrmstr/cdcfluview.svg?branch=master)](https://travis-ci.org/hrbrmstr/cdcfluview)
[![Coverage Status](https://img.shields.io/codecov/c/github/hrbrmstr/cdcfluview/master.svg)](https://codecov.io/github/hrbrmstr/cdcfluview?branch=master)

# I M P O R T A N T

The CDC migrated to a new non-Flash portal and back-end APIs changed. This is a complete reimagining of the package and --- as such --- all your code is going to break...eventually. Older functions have been deprecated with warnings and will be removed at some point.

All folks providing feedback, code or suggestions will be added to the DESCRIPTION file. Please include how you would prefer to be cited in any issues you file.

If there's a particular data set from https://www.cdc.gov/flu/weekly/fluviewinteractive.htm that you want and that isn't in the package, please file it as an issue and be as specific as you can (screen shot if possible).

# :mask: cdcfluview

Retrieve Flu Season Data from the United States Centers for Disease Control and Prevention ('CDC') 'FluView' Portal

## Description

The U.S. Centers for Disease Control (CDC) maintains a portal <http://gis.cdc.gov/grasp/fluview/fluportaldashboard.html> for accessing state, regional and national influenza statistics as well as Mortality Surveillance Data. The Flash interface makes it difficult and time-consuming to select and retrieve influenza data. This package provides functions to access the data provided by the portal's underlying API.

## What's Inside The Tin

The following functions are implemented:

- `age_group_distribution`:	Age Group Distribution of Influenza Positive Tests Reported by Public Health Laboratories
- `cdc_basemap`:	Retrieve CDC U.S. Basemaps
- `geographic_spread`:	State and Territorial Epidemiologists Reports of Geographic Spread of Influenza
- `get_weekly_flu_report`:	Retrieves (high-level) weekly (XML) influenza surveillance report from the CDC
- `hospitalizations`:	Laboratory-Confirmed Influenza Hospitalizations
- `ilinet`:	Retrieve ILINet Surveillance Data
- `ili_weekly_activity_indicators`:	Retrieve weekly state-level ILI indicators per-state for a given season
- `pi_mortality`:	Pneumonia and Influenza Mortality Surveillance
- `state_data_providers`:	Retrieve metadata about U.S. State CDC Provider Data
- `surveillance_areas`:	Retrieve a list of valid sub-regions for each surveillance area.
- `who_nrevss`:	Retrieve WHO/NREVSS Surveillance Data

MMWR ID Utilities:

- `mmwrid_map`:	MMWR ID to Calendar Mappings
- `mmwr_week`:	Convert a Date to an MMWR day+week+year
- `mmwr_weekday`:	Convert a Date to an MMWR weekday
- `mmwr_week_to_date`:	Convert an MMWR year+week or year+week+day to a Date object

Deprecated functions:

- `get_flu_data`:	Retrieves state, regional or national influenza statistics from the CDC (deprecated)
- `get_hosp_data`:	Retrieves influenza hospitalization statistics from the CDC (deprecated)
- `get_state_data`:	Retrieves state/territory-level influenza statistics from the CDC (deprecated)


The following data sets are included:

- `hhs_regions`:	HHS Region Table (a data frame with 59 rows and 4 variables)
- `census_regions`:	Census Region Table (a data frame with 51 rows and 2 variables)
- `mmwrid_map`:	MMWR ID to Calendar Mappings (it is exported & available, no need to use `data()`)

## NOTE

All development happens in branches now with only critical fixes being back-ported to the master branch when necessary.

## Installation

```{r eval=FALSE}
# CRAN
install.packages("cdcfluview")
# master branch
devtools::install_git("https://sr.ht/~hrbrmstr/cdcfluview")
devtools::install_git("https://gitlab.com/hrbrmstr/cdcfluview")
devtools::install_github("hrbrmstr/cdcfluview")
```

## Usage

```{r libs}
library(cdcfluview)
library(hrbrthemes)
library(tidyverse)

# current verison
packageVersion("cdcfluview")
```

### Age Group Distribution of Influenza Positive Tests Reported by Public Health Laboratories

```{r age-group-dist}
glimpse(age_group_distribution(years=2015))
```

### Retrieve CDC U.S. Coverage Map

```{r cdc-basemaps}
plot(cdc_basemap("national"))
plot(cdc_basemap("hhs"))
plot(cdc_basemap("census"))
plot(cdc_basemap("states"))
plot(cdc_basemap("spread"))
plot(cdc_basemap("surv"))
```

### State and Territorial Epidemiologists Reports of Geographic Spread of Influenza

```{r geographic-spread, message=FALSE, warning=FALSE}
glimpse(geographic_spread())
```

### Laboratory-Confirmed Influenza Hospitalizations

```{r surveillance-areas, fig.width=10, fig.height=7.5}
surveillance_areas()

glimpse(fs_nat <- hospitalizations("flusurv"))

ggplot(fs_nat, aes(wk_end, rate)) + 
  geom_line(aes(color=age_label, group=age_label)) +
  facet_wrap(~sea_description, scales="free_x") +
  scale_color_ipsum(name=NULL) +
  labs(x=NULL, y="Rates per 100,000 population",
       title="FluSurv-NET :: Entire Network :: All Seasons :: Cumulative Rate") +
  theme_ipsum_rc()

glimpse(hospitalizations("eip", years=2015))

glimpse(hospitalizations("eip", "Colorado", years=2015))

glimpse(hospitalizations("ihsp", years=2015))

glimpse(hospitalizations("ihsp", "Oklahoma", years=2015))
```

### Retrieve ILINet Surveillance Data

```{r ili-df}
walk(c("national", "hhs", "census", "state"), ~{
  
  ili_df <- ilinet(region = .x)
  
  print(glimpse(ili_df))
  
  ggplot(ili_df, aes(week_start, unweighted_ili, group=region, color=region)) +
    geom_line() +
    viridis::scale_color_viridis(discrete=TRUE) +
    labs(x=NULL, y="Unweighted ILI", title=ili_df$region_type[1]) +
    theme_ipsum_rc(grid="XY") +
    theme(legend.position = "none") -> gg
  
  print(gg)
  
})
```

### Retrieve weekly state-level ILI indicators per-state for a given season

```{r ili-weekly-activity, fig.width=10, fig.height=5}
ili_weekly_activity_indicators(2017)

xdf <- map_df(2008:2017, ili_weekly_activity_indicators)

count(xdf, weekend, activity_level_label) %>% 
  complete(weekend, activity_level_label) %>% 
  ggplot(aes(weekend, activity_level_label, fill=n)) + 
  geom_tile(color="#c2c2c2", size=0.1) +
  scale_x_date(expand=c(0,0)) +
  viridis::scale_fill_viridis(name="# States", na.value="White") +
  labs(x=NULL, y=NULL, title="Weekly ILI Indicators (all states)") +
  coord_fixed(100/1) +
  theme_ipsum_rc(grid="") +
  theme(legend.position="bottom")
```

### Pneumonia and Influenza Mortality Surveillance

```{r nat-pi-mortality}
(nat_pi <- pi_mortality("national"))

select(nat_pi, wk_end, percent_pni, baseline, threshold) %>% 
  gather(measure, value, -wk_end) %>% 
  ggplot(aes(wk_end, value)) + 
  geom_line(aes(group=measure, color=measure)) + 
  scale_y_percent() +
  scale_color_ipsum(name = NULL, labels=c("Baseline", "Percent P&I", "Threshold")) +
  labs(x=NULL, y="% of all deaths due to P&I",
       title="Percentage of all deaths due to pneumonia and influenza, National Summary") +
  theme_ipsum_rc(grid="XY") +
  theme(legend.position="bottom")

(st_pi <- pi_mortality("state", years=2015))

(reg_pi <- pi_mortality("region", years=2015))
```

### Retrieve metadata about U.S. State CDC Provider Data

```{r state-data-providers}
state_data_providers()
```

### Retrieve WHO/NREVSS Surveillance Data

```{r who-vrevss}
glimpse(xdat <- who_nrevss("national"))

mutate(xdat$combined_prior_to_2015_16, 
       percent_positive = percent_positive / 100) %>% 
  ggplot(aes(wk_date, percent_positive)) +
  geom_line() +
  scale_y_percent(name="% Positive") +
  labs(x=NULL, title="WHO/NREVSS Surveillance Data (National)") +
  theme_ipsum_rc(grid="XY")

who_nrevss("hhs", years=2016)

who_nrevss("census", years=2016)

who_nrevss("state", years=2016)
```

## cdcfluview Metrics

```{r echo=FALSE}
cloc::cloc_pkg_md()
```

## Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.