epicurve {epitools}

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.hours(x, mindt, maxdt, strata = NULL, half.hour = FALSE,
               width = 1, space = 0, tick = TRUE,
               tick.offset = 0.5, segments = FALSE, ...) 

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 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

Author(s)

Tomas Aragon, [e-mail], http://www.phdata.science

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.hours
data(oswego)
## create vector with meal date and time
mdt <- paste("4/18/1940", oswego$meal.time)
mdt[1:10]
## convert into standard date and time
meal.dt <- strptime(mdt, "%m/%d/%Y %I:%M %p")
meal.dt[1:10]
## create vector with onset date and time
odt <- paste(paste(oswego$onset.date,"/1940",sep=""), oswego$onset.time)
odt[1:10]
## convert into standard date and time
onset.dt <- strptime(odt, "%m/%d/%Y %I:%M %p")
onset.dt[1:10]      

##set colors
col3seq.d <- c("#43A2CA", "#A8DDB5", "#E0F3DB")

par.fin <- par()$fin
par(fin=c(5,3.4))

##1-hour categories
xv <- epicurve.hours(onset.dt, "1940-04-18 12:00:00", "1940-04-19 12:00:00",
                     axisnames = FALSE, axes = FALSE, ylim = c(0,11),
                     col = col3seq.d[1], segments =  TRUE,
                     strata = oswego$sex)

hh <- xv$chour12==3 | xv$chour12== 6 | xv$chour12== 9
hh2 <- xv$chour12==12
hh3 <- xv$chour12==1
hlab <- paste(xv$chour12,xv$campm2,sep="")
hlab2 <- paste(xv$cmonth,xv$cmday)
axis(1, at = xv$xval[hh], labels = xv$chour12[hh], tick = FALSE, line = -.2)
axis(1, at = xv$xval[hh2], labels = hlab[hh2], tick = FALSE, line = -.2)
axis(1, at = xv$xval[hh3], labels = hlab2[hh3], tick = FALSE, line = 1.0)
axis(2, las = 1)
title(main = "Figure 1. Cases of Gastrointestinal Illness
by Time of Onset of Symptoms (Hour Category)
Oswego County, New York, April 18-19, 2004",
      xlab = "Time of Onset",
      ylab = "Cases")

##1/2-hour categories
xv <- epicurve.hours(onset.dt, "1940-04-18 12:00:00", "1940-04-19 12:00:00",
                     axisnames = FALSE, axes = FALSE, ylim = c(0,11),
                     col = col3seq.d[1], segments =  TRUE,
                     half.hour = TRUE, strata = oswego$sex)
hh <- xv$chour12==3 | xv$chour12== 6 | xv$chour12== 9
hh2 <- xv$chour12==12
hh3 <- xv$chour12==1
hlab <- paste(xv$chour12,xv$campm2,sep="")
hlab2 <- paste(xv$cmonth,xv$cmday)
axis(1, at = xv$xval[hh], labels = xv$chour12[hh], tick = FALSE, line = -.2)
axis(1, at = xv$xval[hh2], labels = hlab[hh2], tick = FALSE, line = -.2)
axis(1, at = xv$xval[hh3], labels = hlab2[hh3], tick = FALSE, line = 1.0)
axis(2, las = 1)
title(main = "Figure 2. Cases of Gastrointestinal Illness
by Time of Onset of Symptoms (1/2 Hour Category)
Oswego County, New York, April 18-19, 2004",
      xlab = "Time of Onset",
      ylab = "Cases")

par(fin=par.fin)


##epicurve.table
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)