derive_vars_crit_flag {admiral} | R Documentation |
Derive Criterion Flag Variables CRITy
, CRITyFL
, and CRITyFN
Description
The function derives ADaM compliant criterion flags, e.g., to facilitate subgroup analyses.
If a criterion flag can't be derived with this function, the derivation is not ADaM compliant. It helps to ensure that:
the condition of the criterion depends only on variables of the same row,
the
CRITyFL
is populated with valid values, i.e, either"Y"
andNA
or"Y"
,"N"
, andNA
,the
CRITy
variable is populated correctly, i.e.,set to a constant value within a parameter if
CRITyFL
is populated with"Y"
,"N"
, andNA
andset to a constant value within a parameter if the criterion condition is fulfilled and to
NA
otherwise ifCRITyFL
is populated with"Y"
, andNA
Usage
derive_vars_crit_flag(
dataset,
crit_nr = 1,
condition,
description,
values_yn = FALSE,
create_numeric_flag = FALSE
)
Arguments
dataset |
Input dataset
|
crit_nr |
The criterion number, i.e., the
|
condition |
Condition for flagging records See description of the
|
description |
The description of the criterion The An expression can be specified to set the value depending on the parameter. Please note that the value must be constant within a parameter.
|
values_yn |
Should If set to Otherwise, the
|
create_numeric_flag |
Create a numeric flag? If set to
|
Value
The input dataset with the variables CRITy
, CRITyFL
, and
optionally CRITyFN
added.
Examples
Data setup
The following examples use the BDS dataset below as a basis.
library(tibble, warn.conflicts = FALSE) adbds <- tribble( ~PARAMCD, ~AVAL, "AST", 42, "AST", 52, "AST", NA_real_, "ALT", 33, "ALT", 51 )
Creating a simple criterion flag with values "Y"
and NA
(condition
, description
)
The following call is a simple application of derive_vars_crit_flag()
to derive a criterion flag/variable pair in a BDS dataset.
The new variables are named
CRIT1
/CRIT1FL
because the argumentcrit_nr
has not been passed.Since the argument
values_yn
has also not been passed and thus is set to its default ofFALSE
,CRIT1FL
is set toY
only ifcondition
evaluates toTRUE
. For example, in both the first and third records, wherecondition
is respectivelyFALSE
andNA
, we setCRIT1FL = NA_character_
. The fourth record also exhibits this behavior. Also, as per CDISC standards, in this caseCRIT1
is populated only for records wherecondition
evaluates toTRUE
.
derive_vars_crit_flag( adbds, condition = AVAL > 50, description = "Absolute value > 50" ) #> # A tibble: 5 × 4 #> PARAMCD AVAL CRIT1FL CRIT1 #> <chr> <dbl> <chr> <chr> #> 1 AST 42 <NA> <NA> #> 2 AST 52 Y Absolute value > 50 #> 3 AST NA <NA> <NA> #> 4 ALT 33 <NA> <NA> #> 5 ALT 51 Y Absolute value > 50
The description
argument also accepts expressions which depend
on other variables in the input dataset. This can be useful to
dynamically populate CRITx
, for instance in the case below where
we improve the CRIT1
text because the same flag/variable pair is
actually being used for multiple parameters.
derive_vars_crit_flag( adbds, condition = AVAL > 50, description = paste(PARAMCD, "> 50"), ) #> # A tibble: 5 × 4 #> PARAMCD AVAL CRIT1FL CRIT1 #> <chr> <dbl> <chr> <chr> #> 1 AST 42 <NA> <NA> #> 2 AST 52 Y AST > 50 #> 3 AST NA <NA> <NA> #> 4 ALT 33 <NA> <NA> #> 5 ALT 51 Y ALT > 50
Creating a criterion flag with values "Y"
, "N"
and NA
(values_yn
)
The next call builds on the previous example by using
value_yn = TRUE
to distinguish between the cases
where condition
is FALSE
and those where it is
not evaluable at all.
As compared to the previous example, for the first record
condition
evaluates toFALSE
and so we setCRIT1FL = "N"
, whereas for the third record,condition
evaluates toNA
becauseAVAL
is missing and so we setCRIT1FL
toNA
.Note also that because we are using the values
"Y"
,"N"
andNA
for the flag, as per CDISC standardsCRIT1
is now populated for all records rather than just for the"Y"
records.
derive_vars_crit_flag( adbds, condition = AVAL > 50, description = paste(PARAMCD, "> 50"), values_yn = TRUE ) #> # A tibble: 5 × 4 #> PARAMCD AVAL CRIT1FL CRIT1 #> <chr> <dbl> <chr> <chr> #> 1 AST 42 N AST > 50 #> 2 AST 52 Y AST > 50 #> 3 AST NA <NA> AST > 50 #> 4 ALT 33 N ALT > 50 #> 5 ALT 51 Y ALT > 50
If the user wishes to set the criterion flag to "N"
whenever
the condition is not fulfilled, condition
can be updated using
an if_else
call, where the third argument determines the behavior
when the condition is not evaluable.
derive_vars_crit_flag( adbds, condition = if_else(AVAL > 50, TRUE, FALSE, FALSE), description = paste(PARAMCD, "> 50"), values_yn = TRUE ) #> # A tibble: 5 × 4 #> PARAMCD AVAL CRIT1FL CRIT1 #> <chr> <dbl> <chr> <chr> #> 1 AST 42 N AST > 50 #> 2 AST 52 Y AST > 50 #> 3 AST NA N AST > 50 #> 4 ALT 33 N ALT > 50 #> 5 ALT 51 Y ALT > 50
Specifying the criterion variable/flag number and creating
a numeric flag (crit_nr
, create_numeric_flag
).
The user can manually specify the criterion variable/flag number
to use to name CRITy
/CRITyFL
by passing the crit_nr
argument. This
may be necessary if, for instance, other criterion flags already exist
in the input dataset.
The user can also choose to create an additional, equivalent numeric
flag CRITyFN
by setting create_numeric_flag
to TRUE
.
derive_vars_crit_flag( adbds, condition = AVAL > 50, description = paste(PARAMCD, "> 50"), values_yn = TRUE, crit_nr = 2, create_numeric_flag = TRUE ) #> # A tibble: 5 × 5 #> PARAMCD AVAL CRIT2FL CRIT2 CRIT2FN #> <chr> <dbl> <chr> <chr> <int> #> 1 AST 42 N AST > 50 0 #> 2 AST 52 Y AST > 50 1 #> 3 AST NA <NA> AST > 50 NA #> 4 ALT 33 N ALT > 50 0 #> 5 ALT 51 Y ALT > 50 1
See Also
BDS-Findings Functions that returns variable appended to dataset:
derive_basetype_records()
,
derive_var_analysis_ratio()
,
derive_var_anrind()
,
derive_var_atoxgr()
,
derive_var_atoxgr_dir()
,
derive_var_base()
,
derive_var_chg()
,
derive_var_ontrtfl()
,
derive_var_pchg()
,
derive_var_shift()