fhir_crack-methods: Flatten list of FHIR bundles
In POLAR-fhiR/fhircrackr: Handling HL7 FHIR® Resources in R

fhir_crack

R Documentation

Flatten list of FHIR bundles

Description

Converts a fhir_bundle_list (the result of fhir_search()) to a data.frame/data.table or list of df/dt, if more than one resource type is extracted at once.

There are two main output formats for the table: compact and wide. They differ regarding their handling of multiple occurrences of the same FHIR element (e.g. Patient.adress). In the compact format multiple occurrences are pasted together into one cell/column, in the wide format multiple occurrences are distributed over several (indexed) columns. If none of the resources contains any multiple values on the extracted elements, the two formats will result in the same structure.

To increase speed with larger amounts of data the cracking process can be parallelised over a number of cores defined in the ncores argument.

Usage

fhir_crack(
  bundles,
  design,
  sep = NULL,
  brackets = NULL,
  rm_empty_cols = NULL,
  verbose = 2,
  data.table = FALSE,
  format = NULL,
  keep_attr = NULL,
  ncores = 1
)

## S4 method for signature 'ANY,fhir_table_description'
fhir_crack(
  bundles,
  design,
  sep = NULL,
  brackets = NULL,
  rm_empty_cols = NULL,
  verbose = 2,
  data.table = FALSE,
  format = NULL,
  keep_attr = NULL,
  ncores = 1
)

## S4 method for signature 'ANY,fhir_design'
fhir_crack(
  bundles,
  design,
  sep = NULL,
  brackets = NULL,
  rm_empty_cols = NULL,
  verbose = 2,
  data.table = FALSE,
  format = NULL,
  keep_attr = NULL,
  ncores = 1
)

Arguments

`bundles`	A FHIR search result as returned by `fhir_search()`.
`design`	A fhir_design or fhir_table_description object. See `fhir_design()`/`fhir_table_description()` and the corresponding vignette (`vignette("flattenResources", package ="fhircrackr")`) for a more detailed explanation and comprehensive examples of both.
`sep`	Optional. A character of length one containing the separator string used for separating multiple entries in cells when `format = "compact"`. Will overwrite the `sep` defined in `design`. If `sep = NULL`, it is looked up in `design`, where the default is `":::"`.
`brackets`	Optional. A character of length one or two used for the indices of multiple entries, which will overwrite the `brackets` defined in `design`. If `brackets = NULL`, it is looked up in `design`, where the default is `character(0)`,i.e. no indices are added to multiple entries. Empty strings (`""`) are not allowed.
`rm_empty_cols`	Optional. Remove empty columns? Logical scalar which will overwrite the `rm_empty_cols` defined in `design`. If `rm_empty_cols = NULL`, it is looked up in `design`, where the default is `FALSE`.
`verbose`	An integer vector of length one. If 0, nothing is printed, if 1, only finishing message is printed, if > 1, extraction progress will be printed. Defaults to 2.
`data.table`	A logical vector of length one. If it is set to `TRUE` the fhir_crack-function returns a data.table, otherwise a data.frame. Defaults to `FALSE`.
`format`	Optional. A character of length one indicating whether the resulting table should be cracked to a `wide` or `compact` format. Will overwrite the `format` defined in `design` which defaults to `compact`. `wide` means multiple entries will be distributed over several columns with indexed names. `compact` means multiple entries will be pasted into one cell/column separated by `sep`.
`keep_attr`	Optional. A logical of length one indicating whether the attribute name of the respective element (`⁠@value⁠` in most cases) should be attached to the name of the variable in the resulting table. Will overwrite `keep_attr` in `design` which defaults to `FALSE`.
`ncores`	Either `NULL` (no parallelisation) or an integer of length 1 containing the number of cpu cores that should be used for parallelised cracking. Parallelisation currently only works on linux systems. Defaults to `NULL`.

Value

If a fhir_design was used, the result is a list of data.frames, i.e. a fhir_df_list object, or a list of data.tables, i.e. a fhir_dt_list object. If a fhir_table_description was used, the result is a single data.frame/data.table.

Examples

#unserialize example bundle
bundles <- fhir_unserialize(medication_bundles)


###Example 1###
#Extract just one resource type

#define attributes to extract
med_desc <- fhir_table_description(
   resource = "MedicationStatement",
   cols     = c(
   	id              = "id",
   	status          = "status",
   	system          = "medicationCodeableConcept/coding/system",
   	code            = "medicationCodeableConcept/coding/code",
   	display         = "medicationCodeableConcept/coding/display"
  )
)

med_df <- fhir_crack(bundles = bundles, design = med_desc)

head(med_df) #data.frame


###Example 2###
#extract two resource types at once

pat_desc <- fhir_table_description(
   resource = "Patient"
)

design <- fhir_design(med_desc, pat_desc)

df_list <- fhir_crack(bundles = bundles, design = design)

#list of data.frames/fhir_df_list
head(df_list$med_desc)
head(df_list$pat_desc)

#The design that was used can be extracted from a fhir_df_list
fhir_design(df_list)


###Example 3###
#Filter values before extracting

#unserialize example bundle
b <- fhir_unserialize(bundles = example_bundles5)

#only extract codings with loinc system
table_desc <- fhir_table_description(
                    resource = "Observation",
                    cols = c(
                      id = "id",
		                 loinc = "code/coding[system[@value='http://loinc.org']]/code",
	                 display = "code/coding[system[@value='http://loinc.org']]/display"
	                 )
)

table <- fhir_crack(bundles = b,
				    design = table_desc)

table

POLAR-fhiR/fhircrackr documentation built on Dec. 24, 2024, 3:06 a.m.