epicurve              package:epitools              R Documentation

_C_o_n_s_t_r_u_c_t _a_n _e_p_i_d_e_m_i_c _c_u_r_v_e

_D_e_s_c_r_i_p_t_i_o_n:

     Construct an epidemic curve

_U_s_a_g_e:

     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, ...)
       

_A_r_g_u_m_e_n_t_s:

       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 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

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  

_N_o_t_e:

     Visit <URL: http://www.epitools.net> for the latest.

_A_u_t_h_o_r(_s):

     Tomas Aragon, aragon@berkeley.edu, <URL: http://www.medepi.com>

_R_e_f_e_r_e_n_c_e_s:

     none

_S_e_e _A_l_s_o:

     'barplot', 'strptime'

_E_x_a_m_p_l_e_s:

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

