This function executes the function calls stored in the output tibble from [build_def()] with data objects supplied through a named list and returns the results as a list. It is intended to facilitate re-use of pre-defined calls with different data.
Usage
execute_def(
def,
with_data,
bind = FALSE,
force_proceed = getOption("healthdb.force_proceed")
)Arguments
- def
A tibble created by [build_def()].
- with_data
A named list which the elements are in the form of src_lab = data, where 'src_lab' corresponds to the src_labs argument from [build_def()] and 'data' is the data object that will be passed to calls stored in def. The names (and length) of `with_data` must match the unique values of src_labs in `def`.
- bind
A logical for whether row-binding records from multiple sources into one table. Note that the binding may fail in ways that are difficult to anticipate in advance, such as data type conflict (e.g., Date vs. character) between variables in the same name from different sources. The default is FALSE. If TRUE, the behavior is to try and return the unbinded result when failed.
- force_proceed
A logical for whether to ask for user input in order to proceed when remote tables are needed to be collected for binding. The default is FALSE to let user be aware of that the downloading process may be slow. Use options(healthdb.force_proceed = TRUE) to suppress the prompt once and for all.
Examples
# toy data
sample_size <- 30
df <- data.frame(
clnt_id = rep(1:3, each = 10),
service_dt = sample(seq(as.Date("2020-01-01"), as.Date("2020-01-31"), by = 1),
size = sample_size, replace = TRUE
),
diagx = sample(letters, size = sample_size, replace = TRUE),
diagx_1 = sample(c(NA, letters), size = sample_size, replace = TRUE),
diagx_2 = sample(c(NA, letters), size = sample_size, replace = TRUE)
)
# make df a database table
db <- dbplyr::tbl_memdb(df)
# use build_def to make a toy definition
sud_def <- build_def("SUD", # usually a disease name
src_lab = c("src1", "src2"), # identify from multiple sources, e.g., hospitalization, ED visits.
# functions that filter the data with some criteria
def_fn = define_case,
fn_args = list(
vars = starts_with("diagx"),
match = "start", # "start" will be applied to all sources as length = 1
vals = list(c("304"), c("305")),
clnt_id = "clnt_id", # list()/c() could be omitted for single element
# c() can be used in place of list
# if this argument only takes one value for each source
n_per_clnt = c(2, 3)
)
)
# save the definition for re-use
# saveRDS(sud_def, file = some_path)
sud_def %>% execute_def(with_data = list(src1 = df, src2 = db), force_proceed = TRUE)
#>
#> Actions for definition SUD using source df:
#> → --------------Inclusion step--------------
#> ℹ Identify records with condition(s):
#> • where at least one of the diagx, diagx_1, diagx_2 column(s) in each record
#> • contains a value satisfied regular expression: ^304
#>
#> All unique value(s) and frequency in the result (as the conditions require just one of the columns containing target values; irrelevant values may come from other vars columns):
#> integer(0)
#> → --------------No. rows restriction--------------
#> ℹ Of the 0 clients in the input, 0 were flagged as 0 by restricting that each client must have at least 2 records
#> → -------------- Output all records--------------
#>
#> Actions for definition SUD using source db:
#> → --------------Inclusion step--------------
#> ℹ Identify records with condition(s):
#> • where at least one of the diagx, diagx_1, diagx_2 column(s) in each record
#> • contains a value satisfied SQL LIKE pattern: 305%
#> ℹ To see the final query generated by 'dbplyr', use dplyr::show_query() on the output.
#> To extract the SQL string, use dbplyr::remote_query().
#>
#> This message is displayed once per session.
#> → --------------No. rows restriction--------------
#> ℹ Apply restriction that each client must have at least 3 records. Records that met the condition were flagged.
#> → -------------- Output all records--------------
#> $SUD.src1
#> [1] def src clnt_id service_dt
#> [5] diagx diagx_1 diagx_2 flag_restrict_n
#> <0 rows> (or 0-length row.names)
#>
#> $SUD.src2
#> # Source: SQL [0 x 8]
#> # Database: sqlite 3.45.2 [:memory:]
#> # ℹ 8 variables: def <lgl>, src <lgl>, clnt_id <int>, service_dt <dbl>,
#> # diagx <chr>, diagx_1 <chr>, diagx_2 <chr>, flag_restrict_n <lgl>
#>