derive_vars_dt {admiral} | R Documentation |
Derive/Impute a Date from a Character Date
Description
Derive a date (*DT
) from a character date (--DTC
).
The date can be imputed (see date_imputation
argument)
and the date imputation flag (*DTF
) can be added.
Usage
derive_vars_dt(
dataset,
new_vars_prefix,
dtc,
highest_imputation = "n",
date_imputation = "first",
flag_imputation = "auto",
min_dates = NULL,
max_dates = NULL,
preserve = FALSE
)
Arguments
dataset |
Input dataset The variables specified by the
|
new_vars_prefix |
Prefix used for the output variable(s). A character scalar is expected. For the date variable (
|
dtc |
The A character date is expected in a format like
|
highest_imputation |
Highest imputation level The If a component at a higher level than the highest imputation level is
missing, If If
|
date_imputation |
The value to impute the day/month when a datepart is missing. A character value is expected.
The year can not be specified; for imputing the year
|
flag_imputation |
Whether the date imputation flag must also be derived. If If If Please note that CDISC requirements dictate the need for a date imputation
flag if any imputation is performed, so
|
min_dates |
Minimum dates A list of dates is expected. It is ensured that the imputed date is not
before any of the specified dates, e.g., that the imputed adverse event start
date is not before the first treatment date. Only dates which are in the
range of possible dates of the impute_dtc_dtm( "2020-11", min_dates = list( ymd_hms("2020-12-06T12:12:12"), ymd_hms("2020-11-11T11:11:11") ), highest_imputation = "M" ) returns
|
max_dates |
Maximum dates A list of dates is expected. It is ensured that the imputed date is not after any of the specified dates, e.g., that the imputed date is not after the data cut off date. Only dates which are in the range of possible dates are considered. A date or date-time object is expected.
|
preserve |
Preserve day if month is missing and day is present For example
|
Details
In {admiral}
we don't allow users to pick any single part of the date/time to
impute, we only enable to impute up to a highest level, i.e. you couldn't
choose to say impute months, but not days.
The presence of a *DTF
variable is checked and if it already exists in the input dataset,
a warning is issued and *DTF
will be overwritten.
Value
The input dataset with the date *DT
(and the date imputation flag *DTF
if requested) added.
Examples
Derive a date variable without imputation
In this example, we derive ASTDT
from MHSTDTC
with no imputation
done for partial dates.
library(tibble) library(lubridate) mhdt <- tribble( ~MHSTDTC, "2019-07-18T15:25:40", "2019-07-18T15:25", "2019-07-18", "2019-02", "2019", "2019---07", "" ) derive_vars_dt( mhdt, new_vars_prefix = "AST", dtc = MHSTDTC ) #> # A tibble: 7 × 2 #> MHSTDTC ASTDT #> <chr> <date> #> 1 "2019-07-18T15:25:40" 2019-07-18 #> 2 "2019-07-18T15:25" 2019-07-18 #> 3 "2019-07-18" 2019-07-18 #> 4 "2019-02" NA #> 5 "2019" NA #> 6 "2019---07" NA #> 7 "" NA
Impute partial dates (highest_imputation
)
Imputation is requested by the highest_imputation
argument. Here
highest_imputation = "M"
for month imputation is used, i.e. the highest
imputation done on a partial date is up to the month. By default, missing date
components are imputed to the first day/month/year. A date imputation flag variable, ASTDTF
,
is automatically created. The flag variable indicates if imputation was done
on the date.
derive_vars_dt( mhdt, new_vars_prefix = "AST", dtc = MHSTDTC, highest_imputation = "M", date_imputation = "first" ) #> # A tibble: 7 × 3 #> MHSTDTC ASTDT ASTDTF #> <chr> <date> <chr> #> 1 "2019-07-18T15:25:40" 2019-07-18 <NA> #> 2 "2019-07-18T15:25" 2019-07-18 <NA> #> 3 "2019-07-18" 2019-07-18 <NA> #> 4 "2019-02" 2019-02-01 D #> 5 "2019" 2019-01-01 M #> 6 "2019---07" 2019-01-01 M #> 7 "" NA <NA>
Impute to the last day/month (date_imputation = "last"
)
In this example, we derive ADT
impute partial dates to last day/month, i.e.
date_imputation = "last"
.
qsdt <- tribble( ~QSDTC, "2019-07-18T15:25:40", "2019-07-18T15:25", "2019-07-18", "2019-02", "2019", "2019---07", "" ) derive_vars_dt( qsdt, new_vars_prefix = "A", dtc = QSDTC, highest_imputation = "M", date_imputation = "last" ) #> # A tibble: 7 × 3 #> QSDTC ADT ADTF #> <chr> <date> <chr> #> 1 "2019-07-18T15:25:40" 2019-07-18 <NA> #> 2 "2019-07-18T15:25" 2019-07-18 <NA> #> 3 "2019-07-18" 2019-07-18 <NA> #> 4 "2019-02" 2019-02-28 D #> 5 "2019" 2019-12-31 M #> 6 "2019---07" 2019-12-31 M #> 7 "" NA <NA>
Impute to the middle (date_imputaton = "mid"
) and suppress
imputation flag (flag_imputation = "none"
)
In this example, we will derive TRTSDT
with date imputation flag
(*DTF
) suppressed. Since date_imputation = "mid"
, partial date imputation
will be set to June 30th for missing month and 15th for missing day only.
The flag_imputation = "none"
call ensures no date imputation flag is
created. In practice, as per CDISC requirements this option can only be
selected if the imputed variable is not part of the final ADaM dataset.
exdt <- tribble( ~EXSTDTC, "2019-07-18T15:25:40", "2019-07-18T15:25", "2019-07-18", "2019-02", "2019", "2019---07", "" ) derive_vars_dt( exdt, new_vars_prefix = "TRTS", dtc = EXSTDTC, highest_imputation = "M", date_imputation = "mid", flag_imputation = "none" ) #> # A tibble: 7 × 2 #> EXSTDTC TRTSDT #> <chr> <date> #> 1 "2019-07-18T15:25:40" 2019-07-18 #> 2 "2019-07-18T15:25" 2019-07-18 #> 3 "2019-07-18" 2019-07-18 #> 4 "2019-02" 2019-02-15 #> 5 "2019" 2019-06-30 #> 6 "2019---07" 2019-06-30 #> 7 "" NA
Impute to a specific date (date_imputation = "04-06"
)
In this example, we derive ASTDT
with specific date imputation, i.e.
date_imputation = "04-06"
. Note that day portion, "-06"
, is used in the
imputation of the record with "2019-02"
.
derive_vars_dt( mhdt, new_vars_prefix = "AST", dtc = MHSTDTC, highest_imputation = "M", date_imputation = "04-06" ) #> # A tibble: 7 × 3 #> MHSTDTC ASTDT ASTDTF #> <chr> <date> <chr> #> 1 "2019-07-18T15:25:40" 2019-07-18 <NA> #> 2 "2019-07-18T15:25" 2019-07-18 <NA> #> 3 "2019-07-18" 2019-07-18 <NA> #> 4 "2019-02" 2019-02-06 D #> 5 "2019" 2019-04-06 M #> 6 "2019---07" 2019-04-06 M #> 7 "" NA <NA>
Avoid imputation before a user-defined date (min_dates
)
In this example, we derive ASTDT
where AESTDTC
is all partial dates in
need of imputation. Using min_dates = exprs(TRTSDTM)
, we are telling the function
to not allow imputation dates to be before the treatment start date
via min_dates
argument. Note that the second record does not get imputed
as it is before TRTSDTM
.
adae <- tribble( ~AESTDTC, ~TRTSDTM, "2020-12", ymd_hms("2020-12-06T12:12:12"), "2020-11", ymd_hms("2020-12-06T12:12:12") ) derive_vars_dt( adae, dtc = AESTDTC, new_vars_prefix = "AST", highest_imputation = "M", min_dates = exprs(TRTSDTM) ) #> # A tibble: 2 × 4 #> AESTDTC TRTSDTM ASTDT ASTDTF #> <chr> <dttm> <date> <chr> #> 1 2020-12 2020-12-06 12:12:12 2020-12-06 D #> 2 2020-11 2020-12-06 12:12:12 2020-11-01 D
Preserve lower components if higher ones were imputed (preserve
)
The preserve
argument can be used to "preserve" information from the partial dates.
For example, "2019---07"
, will be displayed as "2019-06-07"
rather than
"2019-06-30"
with preserve = TRUE
and date_imputation = "mid"
.
derive_vars_dt( mhdt, new_vars_prefix = "AST", dtc = MHSTDTC, highest_imputation = "M", date_imputation = "mid", preserve = TRUE ) #> # A tibble: 7 × 3 #> MHSTDTC ASTDT ASTDTF #> <chr> <date> <chr> #> 1 "2019-07-18T15:25:40" 2019-07-18 <NA> #> 2 "2019-07-18T15:25" 2019-07-18 <NA> #> 3 "2019-07-18" 2019-07-18 <NA> #> 4 "2019-02" 2019-02-15 D #> 5 "2019" 2019-06-30 M #> 6 "2019---07" 2019-06-07 M #> 7 "" NA <NA>
Further examples
Further example usages of this function can be found in the Date and Time Imputation vignette.
See Also
Date/Time Derivation Functions that returns variable appended to dataset:
derive_var_trtdurd()
,
derive_vars_dtm()
,
derive_vars_dtm_to_dt()
,
derive_vars_dtm_to_tm()
,
derive_vars_duration()
,
derive_vars_dy()