---
title: "Introduction to npi"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to npi}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(npi)
``` 

This vignette provides a brief introduction to the npi package.

`npi` is an R package that allows R users to access the [U.S. National Provider Identifier (NPI) Registry](https://npiregistry.cms.hhs.gov/) API by the Center for Medicare and Medicaid Services (CMS). 

The package makes it easy to obtain administrative data linked to a specific individual or organizational healthcare provider. Additionally, users can perform advanced searches based on provider name, location, type of service, credentials, and many other attributes.

## Search registry

To search for providers in New York City, use the `city` argument in `npi_search()`. By default, the search returns up to 10 records as a tibble organized into list columns.

The live search examples below are shown without execution so this vignette can be built without internet access. Run them in an interactive session to retrieve current registry data.

```{r, eval = FALSE}
nyc <- npi_search(city = "New York City")
nyc
```

Other search arguments for the function include `number`, `enumeration_type`, `taxonomy_description`, `first_name`, `last_name`, `use_first_name_alias`, `organization_name`, `address_purpose`, `state`, `postal_code`, `country_code`, and `limit`. 

Additionally, more than one search argument can be used at once.

```{r, eval = FALSE}
nyc_multi <- npi_search(city = "New York City", state = "NY", enumeration_type = "org")
nyc_multi
```

Visit the function's help page via `?npi_search` after installing and loading the package for more details.

## Increasing number of records returned

The `limit` argument of `npi_search()` lets you set the maximum records to return from 1 to 1200 inclusive, defaulting to 10 records if no value is specified.

```{r, eval = FALSE}
nyc_25 <- npi_search(city = "New York City", limit = 25)
nyc_25
```

When using `npi_search()`, searches with greater than 200 records (for example 300 records) may result in multiple API calls. This is because the API itself returns up to 200 records per request, but allows previously requested records to be skipped. `npi_search()` will automatically make additional API calls up to the API's limit of 1200 records for a unique set of query parameter values, and will still return a single tibble. However, to save time, the function only makes additional requests if needed. For example, if you request 1200 records, and 199 are returned in the first request, then the function does not need to make a second request because there are no more records to return.

```{r, eval = FALSE}
nyc_300 <- npi_search(city = "New York City", limit = 300)
nyc_300
```

The NPPES API documentation does not specify additional API rate limitations. However, if you need more than 1200 NPI records for a set of search terms, you will need to download the [NPPES Data Dissemination File](https://download.cms.gov/nppes/NPI_Files.html).

## Obtaining more human-readable output

`npi_summarize()` provides a more human-readable overview of search results. For the executable examples below, we use the bundled `npis` dataset: a saved sample of 10 provider records, not the output of the live searches above.

```{r}
nyc <- npi::npis
```

```{r}
npi_summarize(nyc)
```

Additionally, users can flatten all the list columns using `npi_flatten()`.

```{r}
npi_flatten(nyc)
```

Alternatively, individual columns can be flattened for each npi by using the `cols` argument. Only the columns specified will be flattened and returned with the npi column by default.

```{r}
npi_flatten(nyc, cols = c("basic", "taxonomies"))
```