-
Notifications
You must be signed in to change notification settings - Fork 10
/
README.Rmd
146 lines (99 loc) · 6.65 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(npi)
library(tibble)
data("npis")
nyc <- npis
```
# npi <img src="man/figures/logo.png" align="right" height="139" />
> Access the U.S. National Provider Identifier Registry API
<!-- badges: start -->
[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/505_status.svg)](https://github.com/ropensci/software-review/issues/505)
[![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)
[![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![R-CMD-check](https://github.com/frankfarach/npi/workflows/R-CMD-check/badge.svg)](https://github.com/frankfarach/npi/actions)
[![Coverage status](https://codecov.io/gh/frankfarach/npi/branch/master/graph/badge.svg)](https://codecov.io/github/frankfarach/npi?branch=master)
[![DOI](https://zenodo.org/badge/122857655.svg)](https://zenodo.org/badge/latestdoi/122857655)
<!-- badges: end -->
Use R to access the U.S. National Provider Identifier (NPI) Registry API (v2.1) by the Center for Medicare and Medicaid Services (CMS): https://npiregistry.cms.hhs.gov/. Obtain rich administrative data linked to a specific individual or organizational healthcare provider, or perform advanced searches based on provider name, location, type of service, credentials, and many other attributes. `npi` provides convenience functions for data extraction so you can spend less time wrangling data and more time putting data to work.
## Installation
Install `npi` directly from Github using the `devtools` package:
```{r install, eval = FALSE}
devtools::install_github("frankfarach/npi")
library(npi)
```
## Usage
`npi` exports four functions, all of which match the pattern "npi_*":
* `npi_search()`: Search the NPI Registry and return the response as a [tibble](https://tibble.tidyverse.org/) with high-cardinality data organized into list columns.
* `npi_summarize()`: A method for displaying a nice overview of results from `npi_search()`.
* `npi_flatten()`: A method for flattening one or more list columns from a search result, joined by NPI number.
* `npi_is_valid()`: Check the validity of one or more NPI numbers using the official [NPI enumeration standard](https://www.cms.gov/Regulations-and-Guidance/Administrative-Simplification/NationalProvIdentStand/Downloads/NPIcheckdigit.pdf).
### Search the registry
`npi_search()` exposes nearly all of the NPPES API's [search parameters](https://npiregistry.cms.hhs.gov/registry/help-api). Let's say we wanted to find up to 10 organizational providers with primary locations in New York City:
```{r, eval = FALSE}
nyc <- npi_search(city = "New York City")
```
```{r print-nyc}
nyc
```
The full search results have four regular vector columns, `npi`, `provider_type`, `created_date`, and `last_updated_date` and seven list columns. Each list column is a collection of related data:
* `basic`: Basic profile information about the provider
* `other_names`: Other names used by the provider
* `identifiers`: Other provider identifiers and credential information
* `taxonomies`: Service classification and license information
* `addresses`: Location and mailing address information
* `practice_locations`: Provider's practice locations
* `endpoints`: Details about provider's endpoints for health information exchange
If you're comfortable [working with list columns](https://r4ds.had.co.nz/many-models.html), this may be all you need from the package. But let's not stop just yet, because `npi` provides convenience functions to summarize and extract the data you need.
## Working with search results
Run `npi_summarize()` on your results to see a more human-readable overview of what we've got:
```{r summarize-nyc}
npi_summarize(nyc)
```
Suppose we just want the basic and taxonomy information for each NPI in the result in a flattened data frame:
```{r flatten-two}
npi_flatten(nyc, c("basic", "taxonomies"))
```
Or we can flatten the whole thing and prune back later:
```{r flatten-all}
npi_flatten(nyc)
```
Now we're ready to do whatever else we need to do with this data. Under the hood, `npi_flatten()` has done a lot of data wrangling for us:
* unnested the specified list columns
* avoided potential naming collisions by prefixing the unnested names by their originating column name
* joined the data together by NPI
### Validating NPIs
Use `npi_is_valid()` to check whether each element of a vector of candidate numbers is a validly constructed NPI number:
```{r valid_npi_ex}
# Validate off NPIs
npi_is_valid(1234567893)
npi_is_valid(1234567898)
```
Note that this function doesn't check whether the NPI numbers are activated or deactivated (see [#22](https://github.com/frankfarach/npi/issues/22#issuecomment-787642817)).
## Set your own user agent
By default, all request headers include a user agent that references this repository. You can customize the user agent by setting the `npi_user_agent` option:
```{r, eval = FALSE}
options(npi_user_agent = "my_awesome_user_agent")
```
## Package Website
`npi` has a [website](https://frankfarach.github.io/npi/) with release notes, documentation on all user functions, and examples showing how the package can be used.
## Reporting Bugs
Did you spot a bug? I'd love to hear about it at the [issues page](https://github.com/frankfarach/npi/issues).
## Code of Conduct
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
## Contributing
Interested in learning how you can contribute to npi? Head over to the [contributor guide](CONTRIBUTING.md)—and thanks for considering!
## How to cite this package
For the latest citation, see the [Authors and Citation](https://frankfarach.github.io/npi/authors.html#citation) page on the package website.
## License
MIT (c) [Frank Farach](https://github.com/frankfarach)
This package's logo is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en) and co-created by [Frank Farach](https://github.com/frankfarach) and [Sam Parmar](https://github.com/parmsam). The logo uses a modified version of an [image](https://commons.wikimedia.org/wiki/File:Rod_of_Asclepius_(Search).svg) of the [Rod of Asclepius](https://en.wikipedia.org/wiki/Rod_of_Asclepius) and a magnifying glass that is attributed to Evanherk, GFDL.