fhir_sample_resources: Randomly sample resources from a FHIR server

Description

Downloads a random sample of resources of a given resource type from a FHIR server. The resources can be further constrained using FHIR search parameters.

Usage

fhir_sample_resources(
  base_url,
  resource,
  parameters = NULL,
  username = NULL,
  password = NULL,
  token = NULL,
  add_headers = NULL,
  sample_size = 20,
  seed = 1,
  verbose = 1
)

Value

A fhir_bundle_list containing randomly 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".
parameters: Optional. Either a length 1 character vector containing properly formatted FHIR search parameters, e.g. "gender=male&_summary=count" or a named list or named character vector e.g. list(gender="male", "_summary"="count") or c(gender="male", "_summary"="count"). Note that parameter names beginning with _ have to be put in quotation marks!
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 performs three steps to draw a random sample of resources from a FHIR server:

Count how many resources matching the type resource and the search parameters in parameters are found on the server. This is done to assert that the desired sample_size is bigger than the number of resources it is drawn from. This step can also be performed individually using fhir_count_resource().
Extract the resource (aka logical) IDs of all requested resources (without downloading the resources completely). This step can be also be performed individually using fhir_get_resource_ids()
Draw a random sample of size sample_size from the vector of resource IDs and download the corresponding set of resources from the server. This can also be done individually using fhir_sample_resources_by_ids()

The actual 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({

#how many resources are on the server?
count <- fhir_count_resource(
  base_url    = 'https://hapi.fhir.org/baseR4',
  resource    = "Patient",
  parameters  = "gender=female")

#randomly sample 30 of them
bundles <- fhir_sample_resources(
  base_url    = 'https://hapi.fhir.org/baseR4',
  resource    = "Patient",
  parameters  = "gender=female",
  sample_size = 30,
  seed        = 1)

bundles

}, silent = TRUE)
# }