Tags a data frame with the admiral_df class and stores its metadata: the
key variables – the variables which uniquely identify its records – the
dataset name, and the ADaM dataset class. Call it on the finished dataset,
once it has been derived, e.g. just before summarizing it: the metadata is
not guaranteed to survive the derivations which build the dataset (see
Details). The metadata is read back with get_dataset_keys(),
get_dataset_name(), and get_dataset_class().
Called on a dataset which is already an admiral_df, it updates the
metadata rather than rebuilding it: an argument left as NULL keeps the
value stored by the previous call, so each item can be set on its own.
The keys describe the record structure the dataset is intended to have; they
are not checked against its records when they are stored. {admiral} never
infers the keys of a dataset: if they have not been set with this function,
functions which need them ask for them to be set. The class, by contrast, is
inferred from the dataset if it has not been set (see
infer_dataset_class()), but a class set here always takes precedence.
Arguments
- dataset
-
A data frame. It does not need to have the
admiral_dfclass already; the class is added if it is missing.- Permitted values
a data frame
- Default value
none
- dataset_keys
-
The key variables of
dataset, in key order, e.g.exprs(USUBJID, PARAMCD, AVISIT), stored in the"admiral_dataset_keys"attribute. They must be variables ofdataset: if any is not, a warning is issued and the keys are not set, so any keys set by a previous call are kept. An empty list,exprs(), records that the dataset has no key variables defined, which is distinct from its keys never having been set.NULLleaves keys stored by a previous call untouched.- Permitted values
list of variables created by
exprs()orNULL- Default value
NULL
- dataset_name
-
The name of the dataset, e.g.
"ADVS", stored in the"admiral_dataset_name"attribute. There are no restrictions on its casing: it is stored exactly as given.NULLleaves a name stored by a previous call untouched, so re-keying a dataset does not lose its name.- Permitted values
character scalar or
NULL- Default value
NULL
- dataset_class
-
The ADaM dataset class, stored in the
"admiral_dataset_class"attribute. This is the ADaM class of the dataset, not its R class (which isadmiral_df). It must be given in upper case, as listed below."TTE"is the time-to-event subclass of"BDS"."ADDL","MDBDS","MDTTE", and"MDOCCDS"are the medical device classes (device-level, and the device versions of"BDS","TTE", and"OCCDS"). The class is not checked against the variables ofdataset.NULLleaves a class stored by a previous call untouched.- Permitted values
"ADSL","BDS","OCCDS","TTE","ADDL","MDBDS","MDTTE","MDOCCDS", orNULL- Default value
NULL
Value
dataset with the admiral_df class, and the "admiral_dataset_keys",
"admiral_dataset_name", and "admiral_dataset_class" attributes for those of
dataset_keys, dataset_name, and dataset_class which were supplied (or had been
stored by a previous call).
Details
The keys can come from anywhere: the by_vars of the derivation which
produced the dataset, a dataset specification, or a hand-written list.
A specification provides them as a character vector, which chr2vars()
converts. {admiral} does not read specification objects itself; to use the
keys defined in a {metacore} specification, extract them in the calling
code, e.g. chr2vars(metacore::get_keys(spec, "ADVS")$variable).
All {admiral} dataset functions tag their output with the admiral_df
class, but they do not carry the metadata through. The core {dplyr} verbs
(mutate(), filter(), arrange(), select(), rename(), slice(),
distinct(), joins where dataset is x, ...) restore data frame
attributes, so the metadata survives those. It is not preserved by
operations which build a new data frame, in particular:
summarise(),tidyr::pivot_longer()/pivot_wider(),nest()/unnest(),complete(),bind_rows()whendatasetis not the first argument,joins where
datasetis they(rather than thex) argument,ungroup(), aftergroup_by()orrowwise()(which themselves keep the attributes but drop theadmiral_dfclass).
Many derivations use these internally, so metadata set at the start of a derivation pipeline is lost along the way. Set it once the dataset is finished, or re-apply this function if the dataset changes afterwards.
The keys are stored as plain variable names, so they are not updated by
rename() or removed by select(): a key which is no longer in the
dataset means it has changed since its keys were set.
See also
Utilities used within Derivation functions:
extract_unit(),
get_dataset_class(),
get_dataset_keys(),
get_dataset_name(),
get_flagged_records(),
get_not_mapped(),
get_vars_query()
Examples
Tagging a dataset with its metadata
library(tibble)
advs <- tribble(
~USUBJID, ~PARAMCD, ~AVISIT, ~AVAL,
"1", "DIABP", "BASELINE", 51,
"1", "SYSBP", "BASELINE", 121,
"2", "DIABP", "BASELINE", 79
)
advs <- admiral_df(
advs,
dataset_keys = exprs(USUBJID, PARAMCD, AVISIT),
dataset_name = "ADVS",
dataset_class = "BDS"
)
get_dataset_keys(advs)
#> [[1]]
#> USUBJID
#>
#> [[2]]
#> PARAMCD
#>
#> [[3]]
#> AVISIT
#>
get_dataset_name(advs)
#> [1] "ADVS"
get_dataset_class(advs)
#> [1] "BDS"
class(advs)
#> [1] "admiral_df" "tbl_df" "tbl" "data.frame"
Keys from a dataset specification
A dataset specification provides the keys as a character vector, which
chr2vars() converts. {admiral} does not read specification objects
itself, so they are extracted in the calling code; e.g. with a
{metacore} specification that is metacore::get_keys():
admiral_df(
advs,
dataset_keys = chr2vars(metacore::get_keys(spec, "ADVS")$variable),
dataset_name = "ADVS"
)
advs <- admiral_df(
advs,
dataset_keys = chr2vars(c("USUBJID", "PARAMCD", "AVISIT"))
)
# `dataset_name` was not repeated, so the name from the previous call stands
get_dataset_name(advs)
#> [1] "ADVS"
Declaring that a dataset has no key variables
An empty dataset_keys is stored all the same. It is not the same as leaving
the attribute unset: it records that no key variables are defined.
advs_no_keys <- admiral_df(advs, dataset_keys = exprs())
get_dataset_keys(advs_no_keys)
#> list()
