fhir_sample_resources {fhircrackr} | R Documentation |
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
)
Arguments
base_url |
A character vector of length one specifying the base URL of the FHIR server, e.g. |
resource |
A character vector of length one or fhir_resource_type object with the resource type to be downloaded, e.g. |
parameters |
Optional. Either a length 1 character vector containing properly formatted FHIR search parameters, e.g.
|
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 |
add_headers |
A named character vector of custom headers to add to the HTTP request, e.g. |
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 inparameters
are found on the server. This is done to assert that the desiredsample_size
is bigger than the number of resources it is drawn from. This step can also be performed individually usingfhir_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 usingfhir_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()
Value
A fhir_bundle_list containing randomly sampled resources.
See Also
fhir_search()
, fhir_sample_resources_by_ids()
, fhir_get_resources_by_ids()
, fhir_count_resource()
Examples
#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)