mkseas                 package:seas                 R Documentation

_M_a_k_e _a _d_a_t_e _i_n_t_o _a _s_e_a_s_o_n_a_l _f_a_c_t_o_r

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

     Discretizes a date within a year into a bin (or 'factor') for
     analysis, such as 11-day groups or by month.

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

     mkseas(x, width = 11, start.day = 1, calendar, year)

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

       x: A 'data.frame' with a 'date' column (of 'Date' or 'POSIXct'
          class)

          It can also be an integer specifying the Julian day (specify
          'year' to determine the leap year)

          If it is omitted, the full number of days will be calculated
          for the year, determined by either 'year' or 'calendar'

   width: either 'numeric' or other 'character' value; if it is
          numeric, it specifies the number of days in each bin (default
          is 11 days); if character it specifies a common calendar
          usage, such as '"mon"' for months; see details below

start.day: this is the start of the season, specified as either a as a
          'Date' to specify a month and day (year is ignored; day of
          month is ignored if 'width' relates to a month), or as a
          'numeric' day of year, between 1 and the number of days for
          the calendarter a leap day)

calendar: used to determine the number of days per year and per bin; if
          not specified, a proleptic Gregorian calendar is assumed; see
          'year.length'

    year: required if 'x' is omitted, or if 'x' is a Julian day integer
          and 'width' is non-numeric; used to calculate leap year

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

     This useful date function groups _days_ of a year into discrete
     bins (or into a 'factor').  Statistical and plotting functions can
     be applied to a variable contained within each bin. An example of
     this would be to find the monthly temperature averages, where
     _month_ is the bin.

     If 'width' is 'integer', the width of each bin (except for the
     last) will be exactly 'width' days. Since the number of days in a
     year are not consistent, nor are always perfectly divisible by
     'width', the numbers of days in the last bin will vary. 'mkseas'
     determines that last bin must have at least 20% of the number of
     observations for a leap year, otherwise it is merged into the
     second to last bin (which will have extra numbers of days). If
     'width' is 'numeric' (i.e. '366/12'), the width of each bin varies
     slightly. Using 'width = 366/12' is slightly different than 'width
     = "mon"'. Leap years only affect the _last_ bin.

     Other common classifications based on the Gregorian calendar can
     be used if 'width' is given a 'character' array. All of these
     systems are arbitrary: having different numbers of days in each
     bin, and leap years affecting the number of days in February. The
     most common, of course, is by _month_ ('"mon"'). Meteorological
     quarterly seasons ('"DJF"') are based on grouping three months,
     starting with December.  This style of grouping is commonly used
     in climate literature, and is preferred over the season names
     'winter', 'spring', 'summer', and 'autumn', which apply to only
     one hemisphere.  The less common annual quarterly divisions
     ('"JFM"') are similar, except that grouping begins with January.
     Zodiac divisions ('"zod"') are included for demonstrative
     purposes, and are based on the Tropical birth dates (common in
     Western-culture horoscopes) starting with Aries (March 21).

     Here are the complete list of options for the 'width' argument:

        *  'numeric': the width of each bin (or group) in days

        *  '366/n': divide the year into 'n' sections

        *  '"mon"': month intervals (abbreviated month names)

        *  '"month"': month intervals (full month names)

        *  '"DJF"': meteorological quarterly divisions: DJF, MAM, JJA,
           SON

        *  '"JFM"': annual quarterly divisions: JFM, AMJ, JAS, OND

        *  '"JF"': annual six divisions: JF, MA, AJ, JA, SO, ND

        *  '"zod"': zodiac intervals (abbreviated symbol names)

        *  '"zodiac"': zodiac intervals (full zodiac names)

     If a non-Gregorian calendar is used (see 'year.length'), the
     number of days in a year can be set using 'calendar' attribute in
     the 'date' column (using 'attr'). For example,
     'attr(x$date,"calendar") <- "365_day"' will set the dates using a
     365-day per year calendar, where February is always 28-days in
     length. If this attribute is not set, it is assumed a normal
     Gregorian calendar is used. Calendars with 360-days per year (or
     30-days per month) are incorrectly handled, since February cannot
     have 30 days, however this can be forced by including a duplicate
     February date in 'x' for each year).

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

     Returns an array of 'factor's for each date given in 'x'. The
     factor also has four attributes: 'width', 'start.day', 'calendar'
     (assumed to be 366, unless from attribute set in 'Date'), and an
     array 'days' showing the maximum number of days in each bin.

     See examples for its application.

_L_o_c_a_l_e _w_a_r_n_i_n_g:

     Month names generated using '"mon"' or '"months"' are locale
     specific, and depend on your operating system and system language
     settings. Normally, abbreviated month names should have exactly
     three characters or less, with no trailing decimals. However,
     Microsoft-based operating systems have an inconsistent set of
     abbreviated month names between locales. For example, abbreviated
     month names in English locales have three letters with no period
     at the end, while French locales have 3-4 letters with a decimal
     at the end. If your OS is POSIX, you should have consistent month
     names in any locale. This can be fixed by setting
     'options("seas.month.len") <- 3', which forces the length of the
     months to be three-characters in length.

     To avoid any issues supporting locales, or to use English month
     names, simply revert to a C locale: 'Sys.setlocale(loc="C")'.

_N_o_t_e:

     The phase of the Gregorian solar year (begins Julian day 1, or
     January 1st) is not in sync with the phase of '"DJF"' (begins
     Julian day 335/336) or '"zod"' (begins Julian day 80/81). If
     either of these systems are to be used, ensure that there are
     _several_ years of data, or that the phase of the data is the same
     as the beginning Julian day.

     For instance, if one years worth of data beginning on Julian day 1
     is factored into '"DJF"' bins, the first bin will mix data from
     the first three months, and from the last month. The last three
     bins will have a continuous set of data. If the values are not
     perfectly periodic, the first bin will have higher variance, due
     to the mixing of data separated by nearly a year.

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

     M.W. Toews

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

     <URL: http://en.wikipedia.org/wiki/Solar_calendar>

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

     'mkann', 'seas.sum'

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

     # Demonstrate the number of days in each category
     ylab <- "Number of days"

     barplot(table(mkseas(width="mon", year=2005)),
       main="Number of days in each month",ylab=ylab)

     barplot(table(mkseas(width="zod", year=2005)),
       main="Number of days in each zodiac sign",
       ylab=ylab)

     barplot(table(mkseas(width="DJF", year=2005)),
       main="Number of days in each meteorological season",
       ylab=ylab)

     barplot(table(mkseas(width=5, year=2004)),
       main="5-day categories", ylab=ylab)

     barplot(table(mkseas(width=11, year=2005)),
       main="11-day categories",ylab=ylab)

     barplot(table(mkseas(width=366/12, year=2005)),
       main="Number of days in 12-section year",
       sub="Note: not exactly the same as months")

     # Application using synthetic data
     dat <- data.frame(date=as.Date(paste(2005,1:365),"%Y %j"),
       value=(-cos(1:365*2*pi/365)*10+rnorm(365)*3+10))
     attr(dat$date,"calendar") <- "365_day"

     dat$d5 <- mkseas(dat,5)
     dat$d11 <- mkseas(dat,11)
     dat$month <- mkseas(dat,"mon")
     dat$DJF <- mkseas(dat,"DJF")

     plot(value ~ date, dat)
     plot(value ~ d5, dat)
     plot(value ~ d11, dat)
     plot(value ~ month, dat)
     plot(value ~ DJF, dat)

     head(dat)

     tapply(dat$value, dat$month, mean, na.rm=TRUE)
     tapply(dat$value, dat$DJF, mean, na.rm=TRUE)

     dat[which.max(dat$value),]
     dat[which.min(dat$value),]

     # start on a different day
     st.day <- as.Date("2000-06-01")

     dat$month <- mkseas(dat,"mon",start.day=st.day)
     dat$d11 <- mkseas(dat,11,start.day=st.day)
     dat$DJF <- mkseas(dat,"DJF",start.day=st.day)

     plot(value ~ d11, dat,
          main=.seasxlab(11,start.day=st.day))
     plot(value ~ month, dat,
          main=.seasxlab("mon",start.day=st.day))
     plot(value ~ DJF, dat,
          main=.seasxlab("DJF",start.day=st.day))

