Skip to contents

Convert a Date Character Vector into a Datetime Object

Source: R/derive_vars_dtm.R
convert_dtc_to_dtm.Rd

Convert a date character vector (usually --DTC) into a Date vector (usually *DTM).

Usage 

convert_dtc_to_dtm(
  dtc,
  highest_imputation = "h",
  date_imputation = "first",
  time_imputation = "first",
  min_dates = NULL,
  min_dates_strict = NULL,
  max_dates = NULL,
  max_dates_strict = NULL,
  preserve = FALSE
)

Arguments

dtc

The --DTC date to convert.

Permitted values

a character date vector

Default value

none

highest_imputation

Highest imputation level

The highest_imputation argument controls which components of the --DTC value are imputed if they are missing. All components up to the specified level are imputed.

If a component at a higher level than the highest imputation level is missing, NA is returned. For example, for highest_imputation = "D" "2020" results in NA because the month is missing.

If "n" is specified, no imputation is performed, i.e., if any component is missing, NA is returned.

If "Y" is specified, date_imputation should be "first" or "last" and min_dates or max_dates should be specified respectively. Otherwise, NA is returned if the year component is missing.

Permitted values

"Y" (year, highest level), "M" (month), "D" (day), "h" (hour), "m" (minute), "s" (second), "n" (none, lowest level)

Default value

"h"

date_imputation

The value to impute the day/month when a datepart is missing.

A character value is expected.

  • The"first" and "last" keywords allow imputation to the first/last day/month. They can also be used to impute the year if used in conjunction with the min_dates or max_dates arguments. Some examples of this are available here.

  • When highest_imputation is "M" or "D", the "mid" keyword can also be specified to impute missing components to the middle of the possible range:

    • If both month and day are missing, they are imputed as "06-30" (middle of the year).

    • If only day is missing, it is imputed as "15" (middle of the month).

  • "<dd>" can be specified only if highest_imputation = "D". Missing days are imputed by the specified day, e.g. "10" for the 10th day of the month. The specified day should be valid for all months as otherwise an error might be issued. For example, date_imputation = "30" results in an invalid date of "2024-02-30" for the partial date "2024-02".

  • "<mm>-<dd>" can be specified only if highest_imputation is "M", e.g. "06-15" for the 15th of June.

Permitted values

a key-word, i.e. "first", "mid", "last", or "<mm>-<dd>" or "<dd>"

Default value

"first"

time_imputation

The value to impute the time when a timepart is missing.

A character value is expected, either as a

  • format with hour, min and sec specified as "hh:mm:ss": e.g. "00:00:00" for the start of the day,

  • or as a keyword: "first","last" to impute to the start/end of a day.

The argument is ignored if highest_imputation = "n".

Permitted values

"first", "last", or user-defined

Default value

"first"

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 dtc value are considered. The possible dates are defined by the missing parts of the dtc date (see example below). This ensures that the non-missing parts of the dtc date are not changed. A date or date-time object is expected. For example

library(lubridate)
impute_dtc_dtm(
  "2020-11",
  min_dates = list(
   ymd_hm("2020-12-06T12:12"),
   ymd_hm("2020-11-11T11:11")
  ),
  highest_imputation = "M"
)
#> [1] "2020-11-11T11:11:00"

returns "2020-11-11T11:11:00" because the possible dates for "2020-11" range from "2020-11-01T00:00:00" to "2020-11-30T23:59:59". Therefore "2020-12-06T12:12:12" is ignored. Returning "2020-12-06T12:12:12" would have changed the month although it is not missing (in the dtc date).

For date variables (not datetime) in the list the time is imputed to "00:00:00". Specifying date variables makes sense only if the date is imputed. If only time is imputed, date variables do not affect the result.

Permitted values

a list of dates, e.g. list(ymd_hms("2021-07-01T04:03:01"), ymd_hms("2022-05-12T13:57:23"))

Default value

NULL

min_dates_strict

Minimum dates (strict)

The argument works like the min_dates argument but it affects the behavior of the min_dates and max_dates arguments. The range that is used to determine which of the min_dates and max_dates are considered is restricted by the dates specified for min_dates_strict (see example below and the example in the "Avoid Imputed Dates Before a Particular Date" section in vignette("imputation")).

This argument is useful if the max_dates argument is used and there are strict restrictions on the imputed date, like the event start date when the event end date is imputed.

For example

library(lubridate)
impute_dtc_dtm(
  c("2020-11", "2020-11"),
  min_dates_strict = list(
   c(ymd_hm("2020-11-24T00:00"), ymd_hm("2020-11-11T11:11"))
  ),
  max_dates = list(
    c(ymd_hm("2020-11-22T12:12"), ymd_hm("2020-11-22T12:12"))
  ),
  highest_imputation = "M",
  date_imputation = "last",
  time_imputation = "last"
)
#> [1] "2020-11-30T23:59:59" "2020-11-22T12:12:00"

returns ("2020-11-30T23:59:59", "2020-11-22T12:12:00"). The possible dates for "2020-11" range from "2020-11-01T00:00:00" to "2020-11-30T23:59:59".

For the first element, the min_dates_strict argument restricts this range to "2020-11-24T00:00:00" to "2020-11-30T23:59:59". Therefore "2020-11-22T12:12:00" (from the max_dates argument) is ignored as it is not within the restricted range.

For the second element, the min_dates_strict argument restricts this range to "2020-11-11T11:11:00" to "2020-11-30T23:59:59". In this case "2020-11-22T12:12:00" (from the max_dates argument) is within the restricted range and is considered.

Permitted values

a list of dates, e.g. list(ymd_hms("2021-07-01T04:03:01"), ymd_hms("2022-05-12T13:57:23"))

Default value

NULL

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.

For date variables (not datetime) in the list the time is imputed to "23:59:59". Specifying date variables makes sense only if the date is imputed. If only time is imputed, date variables do not affect the result.

Permitted values

a list of dates, e.g. list(ymd_hms("2021-07-01T04:03:01"), ymd_hms("2022-05-12T13:57:23"))

Default value

NULL

max_dates_strict

Maximum dates (strict)

The argument works like the max_dates argument but it affects the behavior of the min_dates and max_dates arguments. The range that is used to determine which of the min_dates and max_dates are considered is restricted by the dates specified for max_dates_strict (see example below).

This argument is useful if the min_dates argument is used and there are strict restrictions on the imputed date, like date of death or the event end date when the event start date is imputed.

For example

library(lubridate)
impute_dtc_dtm(
  c("2020-11", "2020-11"),
  max_dates_strict = list(
   c(ymd_hm("2020-11-24T00:00"), ymd_hm("2020-11-11T11:11"))
  ),
  min_dates = list(
    c(ymd_hm("2020-11-22T12:12"), ymd_hm("2020-11-22T12:12"))
  ),
  highest_imputation = "M",
  date_imputation = "first",
  time_imputation = "first"
)
#> [1] "2020-11-22T12:12:00" "2020-11-01T00:00:00"

returns ("2020-11-22T12:12:00", "2020-11-01T00:00:00"). The possible dates for "2020-11" range from "2020-11-01T00:00:00" to "2020-11-30T23:59:59".

For the first element, the max_dates_strict argument restricts this range to "2020-11-01T00:00:00" to "2020-11-24T00:00:00". The date "2020-11-22T12:12:00" (from the min_dates argument) is within the restricted range and is therefore considered.

For the second element, the max_dates_strict argument restricts this range to "2020-11-01T00:00:00" to "2020-11-11T11:11:00". In this case "2020-11-22T12:12:00" (from the max_dates argument) is outside the restricted range and thus it is ignored.

Permitted values

a list of dates, e.g. list(ymd_hms("2021-07-01T04:03:01"), ymd_hms("2022-05-12T13:57:23"))

Default value

NULL

preserve

Preserve lower level date/time part when higher order part is missing, e.g. preserve day if month is missing or preserve minute when hour is missing.

For example "2019---07" would return "2019-06-07 if preserve = TRUE (and date_imputation = "mid").

Permitted values

TRUE, FALSE

Default value

FALSE

Value

A datetime object

Details

This is a vector-oriented helper and is not usually called directly on a data frame with %>%.

See also

Date/Time Computation Functions that returns a vector: compute_age_years(), compute_dtf(), compute_duration(), compute_tmf(), convert_date_to_dtm(), convert_dtc_to_dt(), convert_xxtpt_to_hours(), impute_dtc_dt(), impute_dtc_dtm()

Examples 

convert_dtc_to_dtm("2019-07-18T15:25:00")
#> [1] "2019-07-18 15:25:00 UTC"
convert_dtc_to_dtm("2019-07-18T00:00:00") # note Time = 00:00:00 is not printed
#> [1] "2019-07-18 UTC"
convert_dtc_to_dtm("2019-07-18")
#> [1] "2019-07-18 UTC"