epicurve {epitools}R Documentation

Construct an epidemic curve

Description

Construct an epidemic curve

Usage

epicurve.dates(x, format = "%Y-%m-%d", strata = NULL,
               min.date, max.date, before = 7, after = 7,
               width = 1, space = 0, tick = TRUE,
               tick.offset = 0.5, segments = FALSE, ...)

epicurve.weeks(x, format = "%Y-%m-%d", strata = NULL,
               min.date, max.date, before = 7, after = 7,
               width = 1, space = 0, tick = TRUE,
               tick.offset = 0.5, segments = FALSE,
               origin = as.Date("1970-01-01"), sunday = TRUE, ...)

epicurve.months(x, format = "%Y-%m-%d", strata = NULL,
                min.date, max.date, before = 31, after = 31,
                width = 1, space = 0, tick = TRUE,
                tick.offset = 0.5, segments = FALSE,
                origin = as.Date("1970-01-01"), ...)

epicurve.table(x, width = 1, space = 0, tick = TRUE,
               tick.offset = 0.5, segments = FALSE, ...)
  

Arguments

x character vector of dates
format date format of x; default is of form "2004-08-10"
strata [optional] categorical (character or factor) vector 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 ays 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
width width of bars in epidemic curve; this value is passed to barplot function
space space between bars in 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 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 specified the range of possible calendar dates, weeks, or months in order to construct and appropriate plot. To do this we convert the data into a factor with the levels specified by the possible calendar values.

To make this whole proces much easier, and to generate additional data that can be use for labeling your epidemic curve, the epicurve functions were created.

Value

epicurve.dates returms 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.table returns numeric vector:
xvals x-axis numeric values used for plotting the epidemic curve; this comes from the barplot function

Note

Visit http://www.epitools.net for the latest.

Author(s)

Tomas Aragon, aragon@berkeley.edu, http://www.medepi.net/aragon

References

none

See Also

barplot, strptime

Examples

##epicurve.dates
sampdates <- seq(as.Date("2004-07-15"), as.Date("2004-09-15"), 1)
x <- sample(sampdates, 100, rep=TRUE)
xs <- sample(c("Male","Female"), 100, rep=TRUE)
epicurve.dates(x)
epicurve.dates(x, strata = xs)
rr <- epicurve.dates(x, strata = xs, segments = TRUE,
                     axisnames = FALSE)
axis(1, at = rr$xvals, labels = rr$cmday, tick = FALSE, line = 0)
axis(1, at = rr$xvals, labels = rr$cmonth, tick = FALSE, line = 1)

##epicurve.weeks
sampdates <- seq(as.Date("2004-07-15"), as.Date("2004-09-15"), 1)
x <- sample(sampdates, 100, rep=TRUE)
xs <- sample(c("Male","Female"), 100, rep=TRUE)
epicurve.weeks(x)

epicurve.weeks(x, strata = xs)

rr <- epicurve.weeks(x, strata = xs, segments = TRUE)
rr

##epicurve.months
dates <- c("1/1/04", "1/2/04", "1/3/04", "1/4/04", "1/5/04",
"1/6/04", "1/7/04", "1/8/04", "1/9/04", "1/10/04", NA, "1/12/04",
"1/14/04", "3/5/04", "5/5/04", "7/6/04", "8/18/04", "12/13/05",
"1/5/05", "4/6/05", "7/23/05", "10/3/05")
aw <- as.month(dates, format = "%m/%d/%y")
aw
aw2 <- as.month(dates, format = "%m/%d/%y", min.date="2003-01-01")
aw2

##epicurve.table
##test function
xvec <- c(1,2,3,4,5,4,3,2,1)
epicurve.table(xvec)

names(xvec) <- 1991:1999
epicurve.table(xvec)

xmtx <- rbind(xvec, xvec)
rownames(xmtx) <- c("Male", "Female")
epicurve.table(xmtx)

epicurve.table(xmtx, seg = TRUE)


[Package Contents]