zooreg                  package:zoo                  R Documentation

_R_e_g_u_l_a_r _z_o_o _S_e_r_i_e_s

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

     'zooreg' is the creator for the S3 class '"zooreg"' for regular
     '"zoo"' series. It inherits from '"zoo"' and is the analogue to
     'ts'.

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

     zooreg(data, start = 1, end = numeric(), frequency = 1, 
       deltat = 1, ts.eps = getOption("ts.eps"), order.by = NULL)

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

    data: a numeric vector, matrix or a factor.

   start: the time of the first observation.  Either a single number or
          a vector of two integers, which specify a natural time unit
          and a (1-based) number of samples into the time unit.

     end: the time of the last observation, specified in the same way
          as 'start'.

frequency: the number of observations per unit of time.

  deltat: the fraction of the sampling period between successive
          observations; e.g., 1/12 for monthly data.  Only one of
          'frequency' or 'deltat' should be provided.

  ts.eps: time series comparison tolerance.  Frequencies are considered
          equal if their absolute difference is less than 'ts.eps'.

order.by: a vector by which the observations in 'x' are ordered. If
          this is specified the arguments 'start' and 'end' are ignored
          and 'zoo(data, order.by, frequency)' is called. See 'zoo' for
          more information.

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

     Strictly regular series are those whose time points are equally
     spaced. Weakly regular series are strictly regular time series in
     which some of the points may have been removed but still have the
     original underlying frequency associated with them. '"zooreg"' is
     a subclass of '"zoo"' that is used to represent both weakly and
     strictly regular series. Internally, it is the same as '"zoo"'
     except  it also has a '"frequency"' attribute. Its index class is
     more restricted  than '"zoo"'. The index: 1. must be numeric or a
     class which can be coerced via 'as.numeric' (such as 'yearmon',
     'yearqtr', 'Date', 'POSIXct' etc.). 2. when converted to numeric
     must be expressable as multiples of 1/frequency. 3. group generic
     functions 'Ops' should be defined, i.e., adding/substracting a
     numeric to/from the index class should produce the correct value
     of the index class again.

     'zooreg' is the 'zoo' analogue to 'ts'. The arguments are almost
     identical, only in the case where 'order.by' is specified, 'zoo'
     is called with 'zoo(data, order.by, frequency)'. It creates a
     regular series of class '"zooreg"' which inherits from '"zoo"'. It
     is essentially a '"zoo"' series with an additional '"frequency"'
     attribute. In the creation of '"zooreg"' objects (via 'zoo',
     'zooreg', or coercion functions) it is always check whether the
     index specified complies with the frequency specified.

     The class '"zooreg"' offers two advantages over code '"ts"': 1.
     The index does not have to be plain numeric (although that is the
     default), it just must be coercable to numeric, thus printing and
     plotting can be customized. 2. This class can not only represent
     strictly regular series, but also series with an underlying
     regularity, i.e., where some observations from a regular grid are
     omitted.

     Hence, '"zooreg"' is a bridge between '"ts"' and '"zoo"' and can
     be employed to coerce back and forth between the two classes. The
     coercion function 'as.zoo.ts' returns therefore an object of class
     '"zooreg"' inheriting from '"zoo"'. Coercion between '"zooreg"'
     and '"zoo"' is also available and drops or tries to add a
     frequency respectively.

     For checking whether a series is strictly regular or does have an
     underlying regularity the generic function 'is.regular' can be
     used.

     Methods to standard generics for regular series such as
     'frequency', 'deltat' and 'cycle' are available for both
     '"zooreg"' and '"zoo"' objects. In the latter case, it is checked
     first (in a data-driven way) whether the series is in fact regular
     or not.

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

     An object of class '"zooreg"' which inherits from '"zoo"'. It is
     essentially a '"zoo"' series with a '"frequency"' attribute.

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

     'zoo', 'is.regular'

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

     ## equivalent specifications of a quarterly series
     ## starting in the second quarter of 1959.
     zooreg(1:10, frequency = 4, start = c(1959, 2))
     as.zoo(ts(1:10, frequency = 4, start = c(1959, 2)))
     zoo(1:10, seq(1959.25, 1961.5, by = 0.25), frequency = 4)

     ## use yearqtr class for indexing the same series
     z <- zoo(1:10, yearqtr(seq(1959.25, 1961.5, by = 0.25)), frequency = 4)
     z
     z[-(3:4)]

     ## create a regular series with a "Date" index
     zooreg(1:5, start = Sys.Date())
     ## or with "yearmon" index
     zooreg(1:5, end = yearmon(2000))

     ## lag and diff (as diff is defined in terms of lag)
     ## act differently on zoo and zooreg objects!
     ## lag.zoo moves a point to the adjacent time whereas
     ## lag.zooreg moves a point by deltat
     x <- c(1, 4, 5, 6)
     zz <- zoo(x, x)
     zr <- as.zooreg(zz)
     lag(zz)
     lag(zr)
     diff(zz)
     diff(zr)

     ## standard methods available for regular series
     frequency(z)
     deltat(z)
     cycle(z)
     cycle(z[-(3:4)])

     zz  <-  zoo(1:6, as.Date(c("1960-01-29", "1960-02-29", "1960-03-31", "1960-04-29", "1960-05-31", "1960-06-30")))
     # this converts zz to "zooreg" and then to "ts" expanding it to a daily
     # series which is 154 elements long, most with NAs.
     ## Not run: 
     length(as.ts(zz)) # 154
     ## End(Not run)
     # probably a monthly "ts" series rather than a daily one was wanted.
     # This variation of the last line gives a result only 6 elements long.
     length(as.ts(aggregate(zz, as.yearmon, c))) # 6

     zzr <- as.zooreg(zz)

     dd <- as.Date(c("2000-01-01", "2000-02-01", "2000-03-01", "2000-04-01"))
     zrd <- as.zooreg(zoo(1:4, dd))

