---
title: "Introduction to cms"
author: "Vigneshwar Subramanian & Raoul R. Wadhwa"
date: "20 May 2020"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{get-mpfs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The cms package implements a set of tools to download and clean publically available Medicare data, published on <https://www.cms.gov>, for analysis in R.
This vignette provides an overview of the key features of the package.

## Medicare Physician Fee Schedule (MPFS)

The `get_mpfs` function returns national payment files for the Medicare Physician Fee Schedule (MPFS).
All revisions for a specified year between 2014 and 2020, inclusive (specified as 2-digit integer, 14 through 20) are downloaded from [the CMS website](https://www.cms.gov/Medicare/Medicare-Fee-for-Service-Payment/PhysicianFeeSched/PFS-National-Payment-Amount-File) to a user-specified path. 

```{r get_mpfs, eval = FALSE, echo = TRUE}
# Example, code not run within vignette itself. 
# Result is hardcoded and displayed for illustrative purposes.

library(cms)

# download and view first few rows of 2020 MPFS database
mpfs20 <- get_mpfs(20, storage_path = 'storage', keep_downloads = TRUE)
head(mpfs20, 3)
```

```{r head(mpfs20), echo = FALSE}
structure(list(Year = c(2020, 2020, 2020), `Carrier Number` = c("01112", 
"01112", "01112"), Locality = c("05", "06", "07"), `HCPCS Code` = c("G0076", 
"G0076", "G0076"), Modifier = structure(c(1L, 1L, 1L), .Label = c("none", 
"26", "53", "TC"), class = "factor"), `PCTC Indicator` = c("0", 
"0", "0"), `Status Code` = c("A", "A", "A"), `Multiple Surgery Indicator` = c("0", 
"0", "0"), `50% Therapy Reduction Amount (non-institutional)` = c("0000000.00", 
"0000000.00", "0000000.00"), `50% Therapy Reduction Amount (institutional)` = c("0000000.00", 
"0000000.00", "0000000.00"), `OPPS Indicator` = c("9", "9", "9"
), `Facility Fee` = c(63.64, 63.64, 63.64), `Non-Facility Fee` = c(63.64, 
63.64, 63.64), `OPPS Facility Fee` = c(0, 0, 0), `OPPS Non-Facility Fee` = c(0, 
0, 0)), row.names = c(NA, -3L), class = c("tbl_df", "tbl", "data.frame"
))
```
By default, `get_mpfs` will store downloaded `.zip` files so that subsequent calls to `get_mpfs` with the same year and storage path will not require redownloading the raw data to import the database.
`get_mpfs` will instead delete downloaded files by passing the argument `keep_downloads = FALSE`.

Optionally, users can specify a valid 7-digit locality code (5-digit carrier number + 2-digit locality, passed as a single string) to instruct `get_mpfs` to return only the data corresponding to that locality:

```{r get_mpfs locality, eval = FALSE, echo = TRUE}
# Example, code not run within vignette itself. 
# Result is hardcoded and displayed for illustrative purposes.

mpfs20_ohio <- get_mpfs(20, storage_path = 'storage', locality = '1520200')
head(mpfs20_ohio, 3)
```

```{r head(mpfs20_ohio), echo = FALSE}
structure(list(Year = c(2020, 2020, 2020), `Carrier Number` = c("15202", 
"15202", "15202"), Locality = c("00", "00", "00"), `HCPCS Code` = c("G0076", 
"G0077", "G0078"), Modifier = structure(c(1L, 1L, 1L), .Label = c("none", 
"26", "53", "TC"), class = "factor"), `PCTC Indicator` = c("0", 
"0", "0"), `Status Code` = c("A", "A", "A"), `Multiple Surgery Indicator` = c("0", 
"0", "0"), `50% Therapy Reduction Amount (non-institutional)` = c("0000000.00", 
"0000000.00", "0000000.00"), `50% Therapy Reduction Amount (institutional)` = c("0000000.00", 
"0000000.00", "0000000.00"), `OPPS Indicator` = c("9", "9", "9"
), `Facility Fee` = c(55.71, 79.54, 131.29), `Non-Facility Fee` = c(55.71, 
79.54, 131.29), `OPPS Facility Fee` = c(0, 0, 0), `OPPS Non-Facility Fee` = c(0, 
0, 0)), row.names = c(NA, -3L), class = c("tbl_df", "tbl", "data.frame"
))
```

## Medicare Locality Key

The `locality_dict` dataset contains the locality definitions used by the MPFS, updated for 2020.  

```{r locality_dict}
mpfs20_locality <- cms::locality_dict
head(mpfs20_locality, 3)
```