fhircrackr (version 2.1.1)

fhir_crack: Flatten list of FHIR bundles

Description

Converts a fhir_bundle_list (the result of fhir_search() to a list of data.frames/data.tables, i.e. a fhir_df_list/fhir_dt_list if a fhir_design is given in the argument design. Creates a single data.frame/data.table, if only a fhir_table_description is given in the argument design.

There are two main output formats for the table: compact and wide. They differ regarding their handling of multiple entries for the same FHIR element (e.g. Patient.adress). In the compact format multiple entries are pasted together into one cell/column, in the wide format multiple entries 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 basic 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,
  remove_empty_columns = deprecated()
)
# S4 method for 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,
  remove_empty_columns = deprecated()
)
# S4 method for 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,
  remove_empty_columns = deprecated()
)

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.

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. Defaults to NULL.

remove_empty_columns

Use argument rm_empty_cols instead.

See Also

• Downloading bundles from a FHIR server: fhir_search()

• Creating designs/table_descriptions: fhir_table_description() and fhir_design()

• Dealing with multiple entries: fhir_melt(), fhir_cast(), fhir_rm_indices()

Examples

#unserialize example bundle
bundles <- fhir_unserialize(medication_bundles)


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

#define attributes to extract
medications <- fhir_table_description(
   resource = "MedicationStatement",
   cols     = c(
   	MS.ID              = "id",
   	STATUS.TEXT        = "text/status",
   	STATUS             = "status",
   	MEDICATION.SYSTEM  = "medicationCodeableConcept/coding/system",
   	MEDICATION.CODE    = "medicationCodeableConcept/coding/code",
   	MEDICATION.DISPLAY = "medicationCodeableConcept/coding/display",
   	DOSAGE             = "dosage/text",
    	PATIENT            = "subject/reference",
    	LAST.UPDATE        = "meta/lastUpdated"
  ),
  sep           = " ",
  brackets      = c("[", "]"),
  rm_empty_cols = FALSE
)

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

head(med_df) #data.frame


###Example 2###
#extract more resource types

patients <- fhir_table_description(
   resource = "Patient"
)

design <- fhir_design(medications, patients)

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

#list of data.frames/fhir_df_list
head(df_list$medications)
head(df_list$patients)

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