Censor <Date>
columns in line list output from sim_linelist()
to a
specified time interval.
This function is similar to incidence2::incidence()
but does not aggregate
events into an <incidence2>
object, instead it returns the same line list
<data.frame>
as input but with modified event dates.
Arguments
- linelist
Line list
<data.frame>
output fromsim_linelist()
.- interval
An
integer
orcharacter
string for the size of the time interval for censoring. Validcharacter
options are:"daily
"weekly"
"epiweek"
"montly"
"yearly"
See details for information of the date/period objects that are returned for each interval type.
- reporting_artefact
A
character
string, either"none"
(default) or"weekend_effect"
. By default none of the dates are altered in other ways during censoring, however ifreporting_artefact = "weekend_effect"
then all the dates in the$date_reporting
column that fall on a weekend are shifted to the following Monday. This artefact is commonly referred to as the "weekend effect" (see doi:10.1186/s13104-025-07145-y ).- offset
An
integer
or<Date>
for the value to start counting the period from (0 is the start of the Unix epoch). Only applicable ifinterval
is specified as aninteger
.Default date used to start counting from for the
<grates_period>
is the earliest symptom onset date ($date_onset
). Seegrates::as_period()
for more information.If setting
reporting_artefact = "weekend_effects"
the period may start or end on a weekend.
Details
The line list columns that contain <Date>
objects are stored at double
point precision by default. In other words, they are not integer
values,
so can be part way through a day. The exact numeric value of the <Date>
can be seen if you unclass()
it.
Censoring line list dates reduces the time precision (window) of the event.
Often dates of events, such as symptom onset or hospital admission are only
known to the nearest day, not hour or minute. Other events may be more
coarsely censored, for example to the nearest week or month.
censor_linelist()
converts the exact double point precision event
<Date>
to the time interval
specified.
Depending on the interval
specified, the date columns will be returned
as different objects. Here is a list of the valid input interval
and the
resulting class of the date column.
integer
-><grates_period>
(seegrates::as_period()
)"daily"
-><Date>
(see Date)"weekly"
-><grates_isoweek>
(seegrates::as_isoweek()
)"epiweek"
-><grates_epiweek>
(seegrates::as_epiweek()
)"monthly"
-><grates_yearmonth>
(seegrates::as_yearmonth()
)"yearly"
-><grates_year>
(seegrates::as_year()
)
Examples
set.seed(1)
linelist <- sim_linelist()
linelist_cens <- censor_linelist(linelist, interval = "daily")
# censor to a 3-day period
linelist_cens <- censor_linelist(linelist, interval = 3)
# no reporting of events on weekends
linelist_cens <- censor_linelist(
linelist,
interval = "daily",
reporting_artefact = "weekend_effects"
)