fhir_sample_resources_by_ids: Download a random sample of resources from a vector of resource IDs.

Description

Download a random sample of resources from a vector of resource IDs.

Usage

fhir_sample_resources_by_ids(
  base_url,
  resource,
  ids,
  id_param = "_id",
  username = NULL,
  password = NULL,
  token = NULL,
  add_headers = NULL,
  sample_size = 20,
  seed = 1,
  verbose = 1
)

Value

A list of bundles containing sampled resources.

Arguments

base_url: A character vector of length one specifying the base URL of the FHIR server, e.g. "http://hapi.fhir.org/baseR4".
resource: A character vector of length one or fhir_resource_type object with the resource type to be downloaded e.g. "Patient".
ids: A character vector containing the IDs from which to sample.
id_param: A character vector of length one containing the FHIR Search parameter belonging to the ids in ids. Defaults to "_id" meaning ids is interpreted as containing resource (aka logical) ids. Could be changed to "identifier" if ids contains a vector of identifier values instead.
username: A character vector of length one containing the username for basic authentication.
password: A character vector of length one containing the password for basic authentication.
token: A character vector of length one or object of class httr::Token, for bearer token authentication (e.g. OAuth2). See fhir_authenticate() for how to create this.
add_headers: A named character vector of custom headers to add to the HTTP request, e.g. c(myHeader = "somevalue") or c(firstHeader = "value1", secondHeader = "value2").
sample_size: A integer of length 1 containing the number of resources to sample.
seed: A integer of length 1 containing the seed for the random generator.
verbose: An integer of length 1 containing the level of verbosity. Defaults to 1.

Details

This function takes a character vector ids containing logical Ids of resources of a given type (specified in resource) on a FHIR server (specified in base_url) and downloads a random sample of size sample_size of the corresponding resources from the server.

Internally, the download of the resources is done by fhir_get_resources_by_ids(). This function will attempt to download the resources using a FHIR search request via POST where the IDs are part of the body. See fhir_search() for details. If this fails (e.g. because the server doesn't allow POST operations), the function falls back on a GET request. If the set of IDs is too long to fit into one GET request (i.e. if the request gets longer than 2083 characters), it will be spread across several requests.

For more information on authentication options, please see the help page of `fhir_search()

Examples

Run this code

# \donttest{

#the try({}, silent = TRUE) statement is only there to catch errors when the server is down
#you can skip it when the server is reachable

try({

#find IDs of all resources representing Homer Simpson
ids <- fhir_get_resource_ids(
  base_url   = 'https://hapi.fhir.org/baseR4',
  resource   = "Patient",
  parameters = "name=Homer&name=Simpson")

#Sample 10 of them
bundles <- fhir_sample_resources_by_ids(
  base_url    = 'https://hapi.fhir.org/baseR4',
  resource    = "Patient",
  ids         = ids,
  sample_size = 10,
  seed        = 1)

#Have a look at the samples
fhir_crack(
  bundles,
  fhir_table_description(
    resource = "Patient",
    cols     = list(
      ID     = "id",
      given  = "name/given",
      family = "name/family")))

}, silent = TRUE)
# }