forked from pharmaverse/admiral
-
Notifications
You must be signed in to change notification settings - Fork 0
/
convert_date_to_dtm.Rd
155 lines (127 loc) · 5.5 KB
/
convert_date_to_dtm.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/derive_date_vars.R
\name{convert_date_to_dtm}
\alias{convert_date_to_dtm}
\title{Convert a Date into a Datetime Object}
\usage{
convert_date_to_dtm(
dt,
highest_imputation = "h",
date_imputation = "first",
time_imputation = "first",
min_dates = NULL,
max_dates = NULL,
preserve = FALSE
)
}
\arguments{
\item{dt}{The date to convert.
A date or character date is expected in a format like \code{yyyy-mm-ddThh:mm:ss}.}
\item{highest_imputation}{Highest imputation level
The \code{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, \code{NA_character_} is returned. For example, for \code{highest_imputation = "D"} \code{"2020"} results in \code{NA_character_} because the month is missing.
If \code{"n"} is specified, no imputation is performed, i.e., if any component is
missing, \code{NA_character_} is returned.
If \code{"Y"} is specified, \code{date_imputation} should be \code{"first"} or \code{"last"}
and \code{min_dates} or \code{max_dates} should be specified respectively. Otherwise,
\code{NA_character_} is returned if the year component is missing.
\emph{Default}: \code{"h"}
\emph{Permitted Values}: \code{"Y"} (year, highest level), \code{"M"} (month), \code{"D"}
(day), \code{"h"} (hour), \code{"m"} (minute), \code{"s"} (second), \code{"n"} (none, lowest
level)}
\item{date_imputation}{The value to impute the day/month when a datepart is
missing.
A character value is expected, either as a
\itemize{
\item format with month and day specified as \code{"mm-dd"}: e.g. \code{"06-15"} for the
15th of June (The year can not be specified; for imputing the year
\code{"first"} or \code{"last"} together with \code{min_dates} or \code{max_dates} argument can
be used (see examples).),
\item or as a keyword: \code{"first"}, \code{"mid"}, \code{"last"} to impute to the first/mid/last
day/month.
}
The argument is ignored if \code{highest_imputation} is less then \code{"D"}.
\emph{Default}: \code{"first"}.}
\item{time_imputation}{The value to impute the time when a timepart is
missing.
A character value is expected, either as a
\itemize{
\item format with hour, min and sec specified as \code{"hh:mm:ss"}: e.g. \code{"00:00:00"}
for the start of the day,
\item or as a keyword: \code{"first"},\code{"last"} to impute to the start/end of a day.
}
The argument is ignored if \code{highest_imputation = "n"}.
\emph{Default}: \code{"first"}.}
\item{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 \code{dtc} value are considered. The possible dates
are defined by the missing parts of the \code{dtc} date (see example below). This
ensures that the non-missing parts of the \code{dtc} date are not changed.
A date or date-time object is expected.
For example
\if{html}{\out{<div class="sourceCode r">}}\preformatted{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"
)
}\if{html}{\out{</div>}}
returns \code{"2020-11-11T11:11:11"} because the possible dates for \code{"2020-11"}
range from \code{"2020-11-01T00:00:00"} to \code{"2020-11-30T23:59:59"}. Therefore
\code{"2020-12-06T12:12:12"} is ignored. Returning \code{"2020-12-06T12:12:12"} would
have changed the month although it is not missing (in the \code{dtc} date).
For date variables (not datetime) in the list the time is imputed to
\code{"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.}
\item{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
\code{"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.}
\item{preserve}{Preserve day if month is missing and day is present
For example \code{"2019---07"} would return \verb{"2019-06-07} if \code{preserve = TRUE}
(and \code{date_imputation = "mid"}).
Permitted Values: \code{TRUE}, \code{FALSE}
\emph{Default}: \code{FALSE}}
}
\value{
A datetime object
}
\description{
Convert a date (datetime, date, or date character) into a Date vector (usually \code{'--DTM'}).
}
\details{
Usually this computation function can not be used with \verb{\%>\%}.
}
\examples{
convert_date_to_dtm("2019-07-18T15:25:00")
convert_date_to_dtm(Sys.time())
convert_date_to_dtm(as.Date("2019-07-18"), time_imputation = "23:59:59")
convert_date_to_dtm("2019-07-18", time_imputation = "23:59:59")
convert_date_to_dtm("2019-07-18")
}
\seealso{
Date/Time Computation Functions that returns a vector:
\code{\link{compute_dtf}()},
\code{\link{compute_duration}()},
\code{\link{compute_tmf}()},
\code{\link{convert_dtc_to_dtm}()},
\code{\link{convert_dtc_to_dt}()},
\code{\link{impute_dtc_dtm}()},
\code{\link{impute_dtc_dt}()}
}
\author{
Samia Kabi
}
\concept{com_date_time}
\keyword{com_date_time}