[optional] categorical vector (character or factor) for stratifying
x
min.date
[optional] minimum calendar date for plotting x-axis of an epidemic
curve; should be of the form of "2004-08-10"; if no date is
specified, then several days are subtracted from the minimum date in
x as specified by the before option
max.date
[optional] maximum calendar date for plotting x-axis of an epidemic
curve; should be of the form of "2004-08-10"; if no date is
specified, then several days are added to the maximum date in
x as specified by the after option
before
if min.date is not specified, then these number of days are
subtracted from the minimum date in x for plotting minimum
calendar date for epidemic curve
after
if max.date is not specified, then these number of days are
added to the maximum date in x for plotting maximum calendar
date for epidemic curve
mindt
[required] Date-time object in standard format that will form the
lower boundary of the hour or half-hour time categories. The
mindt option must less than or equal to the minimum value in
x, and must be rounded off to the nearst hour for hour
categories (e.g., HH:00:00) or rounded off to the nearest half-hour
for half-hour categories (e.g., HH:30:00).
maxdt
[required] Date-time object in standard format that will form the
upper boundary of the hour or half-hour time categories. The
maxdt option must greater than or equal to the minimum value
in x, and must be rounded off to the nearst hour for hour
categories (e.g., HH:00:00) or rounded off to the nearest half-hour
for half-hour categories (e.g., HH:30:00).
half.hour
Set to TRUE for half-hour categories in epicurve.hours.
width
width of bars in the epidemic curve; this value is passed to
barplot function
space
space between bars in the epidemic curve; this value is passed to
barplot function
tick
adds tick marks to the x-axis (default = TRUE)
tick.offset
offsets tick marks so that they plotted between the bars
segments
segments bars so that each box represents one case
origin
allows user to specify an alternative origin for Julian dates that
are generated by this function (default = "1970-01-01")
sunday
First day of the week is Sunday (default = TRUE); setting to FALSE
makes Monday the first day of the week
...
options are passed to the barplot function
Details
These functions makes plotting epidemic curves much easier in
R. Normally, to plot an epidemic curve in R, one must do the
following: (1) have disease onset dates in some calendar date format,
(2) convert these onset dates into a factor with the levels specified
by the range of calendar dates for the x-axis of the epidemic curve,
(3) convert this factor into a table (with or without stratification),
(4) use this table as an argument in the barplot function to plot the
epidemic curve, and (5) make final adjustments (labels, titles, etc.).
Why use the barplot function? Strictly speaking, an epidemic
curve is a histogram displaying the distribution of onset times which
are categorized into, for example, dates. However, histogram functions
seems to work better for measurements that our continuous (e.g.,
height, weight). In contrast, epidemic curves are constructed from
onset time data that has been categorized into days, weeks, or
months. For this type of categorical data, the barplot does a
better job. The caveat, however, is that we need to specify the range
of possible calendar dates, weeks, or months in order to construct an
appropriate plot. To do this we convert the data into a factor with
the levels specified by the possible calendar date values.
To make this whole process much easier, and to generate additional
data that can be use for labeling your epidemic curve, the
epicurve functions were created.
Value
epicurve.dates
returns list:
$dates
input dates are converted to standard calendar date format
$dates2
input dates are also converted to a factor with levels determined by
the calendar dates ($cdates) used to plot the epidemic curve
$xvals
x-axis numeric values used for plotting the epidemic curve; this
comes from the barplot function
$cdates
the calendar dates used for plotting the epidemic curve
$cmday
the day of the mon (1-31) for the calendar dates used for plotting
the x-axis of the epidemic curve
$cmonth
the months (Jan, Feb, Mar, ...) for the calendar dates used for
plotting the x-axis of the epidemic curve
$cyear
the years (e.g., 1996, 2001, ...) for the calendar dates used for
plotting the x-axis of the epidemic curve
epicurve.weeks
returns list:
$dates
input dates are converted to standard calendar date format
$firstday
first day of the week is reported
$week
week of the year (1-53); note that week 52 or 53 can represent both
last week of a year but also the first few days at the beginning of
the year
$stratum
the Julian date for the mid-week day of the $week value
$stratum2
the Julian date for the mid-week day of the $week value
converted to a factor with levels determined by the Julian dates
($cstratum) used to plot the epidemic curve
$stratum3
the mid-week day of the $week value converted to standard
calendar dates
$xvals
x-axis numeric values used for plotting the epidemic curve; this
comes from the barplot function
$cweek
the week of the year used for plotting the x-axis of the epidemic
curve
$cstratum
the Julian date for the mid-week day of the $cweek value used
for plotting the x-axis of the epidemic curve
$cstratum2
the standard calendar date for the mid-week day of the $cweek
value used for plotting the x-axis of the epidemic curve
$cmday
the day of the mon (1-31) for the calendar dates used for plotting
the x-axis of the epidemic curve
$cmonth
the months (Jan, Feb, Mar, ...) for the calendar dates used for
plotting the x-axis of the epidemic curve
$cyear
the years (e.g., 1996, 2001, ...) for the calendar dates used for
plotting the x-axis of the epidemic curve
epicurve.months
returns list:
$dates
input dates are converted to standard calendar date format
$mon
month of the year (1-12)
$month
month of the year (Jan, Feb, Mar, ...)
$stratum
the Julian date for the mid-month day of the $mon value
$stratum2
the Julian date for the mid-month day of the $mon value
converted to a factor with levels determined by the Julian dates
($cstratum)used to plot the epidemic curve
$stratum3
the mid-month day of the $mon value converted to standard
calendar dates
$xvals
x-axis numeric values used for plotting the epidemic curve; this
comes from the barplot function
$cmon
the month of the year (1-12) used for plotting the x-axis of the
epidemic curve
$cmonth
the months (Jan, Feb, Mar, ...) for the calendar dates used for
plotting the x-axis of the epidemic curve
$cstratum
the Julian date for the mid-month day of the $cmonth value
used for plotting the x-axis of the epidemic curve
$cstratum2
the standard calendar date for the mid-month day of the
$cmonth value used for plotting the x-axis of the epidemic
curve
$cmday
the day of the mon (1-31) for the calendar dates used for plotting
the x-axis of the epidemic curve
$cyear
the years (e.g., 1996, 2001, ...) for the calendar dates used for
plotting the x-axis of the epidemic curve
epicurve.hours
returns list:
$ct
Date-time object that contains the number of seconds since the
beginning of 1970 as a numeric vector and produced by
as.POSIXct. You can use as.POSIXlt to
convert this output in human legible (already done by this
function).
$sec
seconds
$min
minutes
$hour
hours (0-23)
$hour12
hours (1-12)
$stratum
number of hours or 1/2 hours since beginning of 1970
$stratum2
factor (categorical variable) with number of hours of 1/2 hours
since beginning of 1970 using $cstratum as the levels
$stratum3
factor (categorical variable) in standard date-time format
indicating number of hours or 1/2 hours since beginning of 1970
using
$xvals
$cstratum
levels for creating $stratum2 factor
$cstratum2
levels for creating $stratum3 factor
$csec
seconds from $cstratum2
$cmin
minutes from $cstratum2
$chour
hours from $cstratum2 in 24-hour format
$chour12
hours from $cstratum2 in 12-hour format
$campm
corresponding 'AM' or 'PM' for $chour12
$campm2
corresponding 'am' or 'pm' for $chour12
$cweekday
day of the week for $cstratum2
$cwkday
abbreviated day of the week for $cstratum2
$cmday
day of the month for $cstratum2
$cmonth
month for $cstratum2
$cmon
abbreviated month for $cstratum2
$cyear
year for $cstratum2
$half.hour
FALSE (default) for 1-hour categories; TRUE for 1/2-hour categories
epicurve.table
returns numeric vector:
xvals
x-axis numeric values used for plotting the epidemic curve; this
comes from the barplot function