1 Backend

`S7` Classes

`class_catalog`

class_catalog <- new_class(
  name = "class_catalog",
  properties = list(
    groups = class_list),
  validator = function(self) 
    if (!rlang::is_named(self@groups)) "all @groups must be named"
  )

class_catalog(groups = list(npi = 1, ccn = "clinicians"))

<class_catalog>
 @ groups:List of 2
 .. $ npi: num 1
 .. $ ccn: chr "clinicians"

try(class_catalog(groups = list(1, "clinicians")))

Error : <class_catalog> object is invalid:
- all @groups must be named

National Downloadable File

ndf_identifier <- \(x) {
  kit::nswitch(x,
    "affiliations", "27ea-46a8",
    "clinicians", "mj5m-pzi6",
    default = NA_character_,
    nThread = 4L)
}

httr2::url_parse("https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/")

url_tmp <- httr2::url_parse("https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/") |> 
  httr2::url_build() |> 
  httr2::request()

httr2::req_template(
  url_tmp, 
  "/{fname}?show-reference-ids=true", 
  fname = ndf_identifier("affiliations"))

httr2::url_parse("https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/") |> 
  httr2::url_build() |> 
  httr2::request() |> 
  httr2::req_url_path_append(ndf_identifier("affiliations")) |> 
  httr2::req_url_path_append("?show-reference-ids=true") |>
  httr2::req_perform() |>
  httr2::resp_body_json(check_type = FALSE, simplifyVector = TRUE)

$accessLevel
[1] "public"

$landingPage
[1] "https://data.cms.gov/provider-data/dataset/27ea-46a8"

$bureauCode
[1] "009:38"

$issued
[1] "2023-08-17"

$`@type`
[1] "dcat:Dataset"

$modified
[1] "2025-03-07"

$released
[1] "2025-03-20"

$keyword
                            identifier       data
1 f62da856-f3e0-565a-a6e0-f6aefcafde00 Clinicians

$contactPoint
$contactPoint$`@type`
[1] "vcard:Contact"

$contactPoint$fn
[1] "CMS"

$contactPoint$hasEmail
[1] "mailto:QPP@cms.hhs.gov"


$publisher
$publisher$identifier
[1] "4c1de1c4-f083-5877-8968-7ddc04756c49"

$publisher$data
$publisher$data$`@type`
[1] "org:Organization"

$publisher$data$name
[1] "Centers for Medicare & Medicaid Services (CMS)"



$identifier
[1] "27ea-46a8"

$description
[1] "This is the facility affiliations data publicly reported in the Provider Data Catalog."

$title
[1] "Facility Affiliation Data"

$programCode
[1] "009:000"

$distribution
                            identifier        data.@type
1 efbf0529-5062-5fc1-a233-66efcd087cfb dcat:Distribution
                                                                                                                       data.downloadURL
1 https://data.cms.gov/provider-data/sites/default/files/resources/b7c4080ae144663e43353a9c35cd3f53_1741377912/Facility_Affiliation.csv
  data.mediaType
1       text/csv
                                                                                                                                                                                                                                                                                                                                                                                                                                    data.%Ref:downloadURL
1 b7c4080ae144663e43353a9c35cd3f53__1741377912__source, b7c4080ae144663e43353a9c35cd3f53__1741377912__local_url, s3://211125755750-pdc-prod-dac-data/Facility_Affiliation.csv, https://h-o.st/provider-data/sites/default/files/resources/b7c4080ae144663e43353a9c35cd3f53_1741377912/Facility_Affiliation.csv, b7c4080ae144663e43353a9c35cd3f53, b7c4080ae144663e43353a9c35cd3f53, text/csv, text/csv, source, local_url, 1741377912, 1741377912, NA, NA

$theme
                            identifier                   data
1 2d4e6b14-abb6-5b27-8e8d-047c7832ac1d Doctors and clinicians

$archiveExclude
[1] FALSE

$`%modified`
[1] "2025-03-07T15:05:12-0500"

meta_ndf <- \(fname) {
  
  stopifnot(curl::has_internet())
  
  x <- request(
    paste0(
      "https://data.cms.gov/",
      "provider-data/api/1/",
      "metastore/schemas/",
      "dataset/items/",
      switch(fname, 
             affiliations = "27ea-46a8", 
             clinicians   = "mj5m-pzi6", 
             stop("Invalid argument")),
    "?show-reference-ids=true")) |>
       req_perform() |>
       resp_body_json(
         check_type     = FALSE,
         simplifyVector = TRUE)
  
  distro <- gelm(gelm(x, "distribution"), "identifier")
  
  y <- request(
    paste0(
    "https://data.cms.gov/", 
    "provider-data/api/1/",
    "datastore/query/", 
    distro, 
    "?limit=1&offset=100&",
    "count=true&results=true&", 
    "schema=true&keys=true&",
    "format=json&rowIds=true")) |>
       req_perform() |>
       resp_body_json(
         check_type     = FALSE,
         simplifyVector = TRUE)
  
  z <- gelm(gelm(gelm(y, "schema"), distro), "fields")
  
  list(
    title        = gelm(x, "title"),
    description  = gelm(x, "description"),
    identifier   = gelm(gelm(x, "identifier"), "identifier"),
    distribution = distro,
    issued       = gelm(x, "issued"),
    modified     = gelm(x, "modified")[[1]],
    released     = gelm(x, "released"),
    dimensions   = paste0(gelm(gelm(y, "count"), is.numeric), " x ", gelm(gelm(z, "record_number"), "length")),
    fields       = names(z),
    site         = gelm(x, "landingPage"),
    csv          = gelm(gelm(gelm(x, "distribution"), "data"), "downloadURL", m = "df"),
    dictionary   = paste0(
      "https://data.cms.gov/provider-data/sites/default/files/data_dictionaries/physician/DOC_Data_Dictionary.pdf"
    )
  )
  
}

Examples

meta_ndf("affiliations") |> 
  purse()

- $title        c1  Facility Affiliation Data
- $description  c1  This is the facility affiliations data publicly reporte ...
- $identifier   c1  27ea-46a8
- $distribution c1  efbf0529-5062-5fc1-a233-66efcd087cfb
- $issued       c1  2023-08-17
- $modified     c1  2025-03-07
- $released     c1  2025-03-20
- $dimensions   c1  1565148 x 10
- $fields       c10 record_number npi ind_pac_id provider_last_name provide ...
- $site         c1  https://data.cms.gov/provider-data/dataset/27ea-46a8
- $csv          c1  https://data.cms.gov/provider-data/sites/default/files/ ...
- $dictionary   c1  https://data.cms.gov/provider-data/sites/default/files/ ...

meta_ndf("clinicians") |> 
  purse()

- $title        c1  National Downloadable File
- $description  c1  The Doctors and Clinicians national downloadable file i ...
- $identifier   c1  mj5m-pzi6
- $distribution c1  4d332c5c-900d-5b33-9e48-cc2dde7a6b5f
- $issued       c1  2023-08-17
- $modified     c1  2025-03-07
- $released     c1  2025-03-20
- $dimensions   c1  2667516 x 10
- $fields       c32 record_number npi ind_pac_id ind_enrl_id provider_last_ ...
- $site         c1  https://data.cms.gov/provider-data/dataset/mj5m-pzi6
- $csv          c1  https://data.cms.gov/provider-data/sites/default/files/ ...
- $dictionary   c1  https://data.cms.gov/provider-data/sites/default/files/ ...

# Backend {#sec-backend}

```{r}
#| label: setup-common-01
#| include: false
source("includes/_common.R")
```

## `S7` Classes

### `class_catalog`

```{r}
#| label: class_catalog
class_catalog <- new_class(
  name = "class_catalog",
  properties = list(
    groups = class_list),
  validator = function(self) 
    if (!rlang::is_named(self@groups)) "all @groups must be named"
  )

class_catalog(groups = list(npi = 1, ccn = "clinicians"))

try(class_catalog(groups = list(1, "clinicians")))
```

## National Downloadable File

```{r}
#| label: url_building
ndf_identifier <- \(x) {
  kit::nswitch(x,
    "affiliations", "27ea-46a8",
    "clinicians", "mj5m-pzi6",
    default = NA_character_,
    nThread = 4L)
}

httr2::url_parse("https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/")

url_tmp <- httr2::url_parse("https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/") |> 
  httr2::url_build() |> 
  httr2::request()

httr2::req_template(
  url_tmp, 
  "/{fname}?show-reference-ids=true", 
  fname = ndf_identifier("affiliations"))

httr2::url_parse("https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/") |> 
  httr2::url_build() |> 
  httr2::request() |> 
  httr2::req_url_path_append(ndf_identifier("affiliations")) |> 
  httr2::req_url_path_append("?show-reference-ids=true") |>
  httr2::req_perform() |>
  httr2::resp_body_json(check_type = FALSE, simplifyVector = TRUE)
```

```{r}
#| label: meta_ndf
meta_ndf <- \(fname) {
  
  stopifnot(curl::has_internet())
  
  x <- request(
    paste0(
      "https://data.cms.gov/",
      "provider-data/api/1/",
      "metastore/schemas/",
      "dataset/items/",
      switch(fname, 
             affiliations = "27ea-46a8", 
             clinicians   = "mj5m-pzi6", 
             stop("Invalid argument")),
    "?show-reference-ids=true")) |>
       req_perform() |>
       resp_body_json(
         check_type     = FALSE,
         simplifyVector = TRUE)
  
  distro <- gelm(gelm(x, "distribution"), "identifier")
  
  y <- request(
    paste0(
    "https://data.cms.gov/", 
    "provider-data/api/1/",
    "datastore/query/", 
    distro, 
    "?limit=1&offset=100&",
    "count=true&results=true&", 
    "schema=true&keys=true&",
    "format=json&rowIds=true")) |>
       req_perform() |>
       resp_body_json(
         check_type     = FALSE,
         simplifyVector = TRUE)
  
  z <- gelm(gelm(gelm(y, "schema"), distro), "fields")
  
  list(
    title        = gelm(x, "title"),
    description  = gelm(x, "description"),
    identifier   = gelm(gelm(x, "identifier"), "identifier"),
    distribution = distro,
    issued       = gelm(x, "issued"),
    modified     = gelm(x, "modified")[[1]],
    released     = gelm(x, "released"),
    dimensions   = paste0(gelm(gelm(y, "count"), is.numeric), " x ", gelm(gelm(z, "record_number"), "length")),
    fields       = names(z),
    site         = gelm(x, "landingPage"),
    csv          = gelm(gelm(gelm(x, "distribution"), "data"), "downloadURL", m = "df"),
    dictionary   = paste0(
      "https://data.cms.gov/provider-data/sites/default/files/data_dictionaries/physician/DOC_Data_Dictionary.pdf"
    )
  )
  
}
```

### Examples

```{r}
#| label: meta_affiliations
meta_ndf("affiliations") |> 
  purse()
```


```{r}
#| label: meta_clinicians
meta_ndf("clinicians") |> 
  purse()
```