regul                package:pastecs                R Documentation

_R_e_g_u_l_a_t_i_o_n _o_f _o_n_e _o_r _s_e_v_e_r_a_l _t_i_m_e _s_e_r_i_e_s _u_s_i_n_g _v_a_r_i_o_u_s _m_e_t_h_o_d_s

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

     Regulate irregular time series or regular time series with gaps.
     Create a `regul' object from whose one or several regular time
     series can be extracted using `extract()' or `tseries()'. This is
     the function to apply most of the time to create regular time
     series ('rts' objects in Splus or 'ts' objects in R) that will be
     further analyzed by other functions that apply to regular time
     series.

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

     regul(x, y=NULL, xmin=min(x), n=length(x), units="days", frequency=NULL,
             deltat=1/frequency, datemin=NULL, dateformat="m/d/Y", tol=NULL,
             tol.type="both", methods="linear", rule=1, f=0, periodic=FALSE,
             window=(max(x) - min(x))/(n - 1), split=100, specs=NULL)
     summary(reg)
     plot(reg, series=1, col=c(1, 2), lty, plot.pts=TRUE,
             leg=FALSE, llab=c("initial", x$specs$methods[series]),
             lpos=c(1.5, 10), ...)
     lines(reg, series=1, col=3, lty=1, plot.pts=TRUE, ...)
     identify(reg, series=1, col=3, label="#", ...)
     hist(reg, nclass=30, col=c(4, 5, 2), plotit=TRUE, ...)
     extract(reg, n=ncol(reg$y), series=NULL)
     specs(reg)

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

       x: a vector containing times at which observations are sampled
          in the initial irregular time series. It can be expressed in
          any unit ("years", "days", "weeks", "hours", "min",
          "sec",...) as defined by the argument `units'. It is often
          expressed in "days" and the decimal part represents the part
          of the day, that is the time in hour:min:sec (dates coming
          from Excel, or even standard dates in S+ or R are expressed
          like that) 

       y: a vector (single series) or a matrix/data frame whose columns
          correspond to the various irregular time series to regulate.
          Rows are observations made at corresponding times in `x'. The
          number of rows must thus match the length of vector `x' 

    xmin: allows to respecify the origin of time in `x'. By default,
          the origin is not redefined and thus, the smallest value in
          `x' is used 

       n: the number of observations in the regular time series. By
          default, it is the same number than in the original irregular
          time series (i.e., `length(x)' 

   units: the time unit for the `x' vector. By default `units="days"'.
          A special value, `units="daystoyears"' indicates that `x' is
          expressed in "days" (1 unit = 1 day) but that we want to
          obtain the final regular time series expressed in "years" (1
          unit = 1 year). Give a correct value for `datemin' to make
          sure the right fraction of the year is computed for each
          observation (see example hereunder) 

frequency: the frequency of the regulated time series in the
          corresponding time unit. For instance, `frequency=12' with
          `units="years"' means montly sampled observations. Warning!
          When using `units="daystoyears"', specify `frequency' (or
          `deltat') in years! 

  deltat: the interval between two observations in the regulated time
          series. It is the inverse of `frequency'. If both `frequency'
          and `deltat' are provided, then `frequency' supersedes
          `deltat' 

 datemin: this is mostly useful for converting "days" in "years"
          time-scales (`units="daystoyears"'). If the `x' vector
          contains: 1, 3, 6,... (day #1, day #3, day #6,... of the
          experiment), one can give here the exact date of the first
          observation, allowing to define a correct origin in the
          "years" time scale. Provide a string in a format compatible
          with `dateformat'. For instance, if day #1 is the 21th March
          1998, give `datemin="03/21/1998"' with `dateformat="m/d/Y"' 

dateformat: indicate how `datemin' is formated. For instance:
          `"d/m/Y"', or `m/d/Y"' (by default), see `daystoyears()' for
          more info on date formatting 

     tol: the tolerance in the time-scale to determine if a measured
          value is used to approximate a regulated value. If `tol=0',
          observations in each respective series must match exactly,
          otherwise observations in the regulated series are
          interpolated. `tol' must be a round fraction of `deltat'
          (deltat, deltat/2, deltat/3, etc...), and cannot be larger
          than it, otherwise, `tol' is automatically adjusted to the
          closest allowed value. By default, `tol=NULL'. This is
          equivalent to `tol=0'. Warning! In the particular case of
          `units="daystoyears"', `tol' must be expressed in the
          original time-scale, that is "days", while `deltat' must be
          expressed in the fimal time-scale, that is "years"! 

tol.type: the type of adjustment to use for the time-tolerance:
          `"left"', `"right"', `"both"' (by default) or `"none"'. If
          `tol.type="left"', corresponding `x' values are seeked in a
          window ]xregul-tol, xregul]. If `tol.type="right"', they are
          seeked in the window [xregul, xregul+tol[. If
          `tol.type="both"', then they are seeked in the window
          ]xregul-tol, xregul+tol]. If several observations are in this
          window, the closest one is used. Finally, if
          `tol.type="none"', then all observations in the regulated
          time series are interpolated (even if exactly matching
          observations exist!) 

 methods: the method(s) to use to regulate the time series. Currently,
          it can be: `"constant"', `"linear"', `"spline"' or `"area"'
          (or a unique abbreviation of them). If several time series
          are provided (`y' is a matrix or a data frame), it is
          possible to define methods individually for each series. For
          instance, `methods=c("l", "a", "s")' defines the "linear"
          method for the first series, the "area" method for the second
          one, the "spline" method for the third one,... and again the
          "linear" for the fourth, the "area" for the fifth one, etc.
          (recycling rule). By default, the "linear" method is selected
          for all series 

    rule: the rule to use for extrapolated values (observations in the
          final regular time series that are outside the range of
          observed values in the initial time series). With `rule=1'
          (by default), these entries are not calculated and get NA;
          with `rule=2', these entries are extrapolated (avoid using
          this option, or use with extreme care!!!) 

       f: parameter for the `"constant"' regulation method. Coefficient
          giving more weight to the observation at left (`f=0', by
          default), to the observation at right (`f=1'), or give an
          intermediate weight to both of these observations (0 < f < 1)
          during the interpolation (see `reglin()' 

periodic: parameter for the `"spline"' regulation method. Indicate if
          the time series should be considered as periodic
          (`periodic=TRUE', first value must be equal to the last one).
          If this is the case, first and second derivates used to
          calculate spline segments around first and last observations
          use data in the other extreme of the series. In the other
          case (`periodic=FALSE', by default), derivates for extremes
          observations are considered to be equal to zero 

  window: parameter for the `"area"' regulation method. Size of the
          window to consider (see `regarea()'). By default, the mean
          interval between observations in the initial irregular time
          series is used. Give the same value as for deltat for working
          with adjacent windows 

   split: other parameter for the `"area"' method. To optimise
          calculation time and to avoid to saturate memory, very long
          time series are splitted into smaller subunits (see
          `regarea()'). This is transparent for the user. The default
          value of `split=100' should be rarely changed. Give a lower
          value if the program fails and reports a memory problem
          during calculation 

   specs: a `specs.regul' object returned by the function `specs()'
          applied to a `regul' object. Allows to collect
          parameterization of the `regul()' function and to apply them
          to another regulation 

     reg: A `regul' object as obtained after using the `regul()'
          function 

  series: the series to plot. By default, `series=1', corresponding to
          the first (or possibly the unique) series in the `regul'
          object 

     col: (1) for `plot()': the two colors to use to draw respectively
          the initial irregular series and the final regulated series.
          `col=c(1,2)' by default. (2) for `hist()': the three colors
          to use to represent respectively the fist bar (exact
          coincidence), the middle bars (coincidence in a certain
          tolerance window) and the last bar (values always
          interpolated). By default, `col=c(4,5,2)' 

     lty: the style to use to draw lines for the initial series and the
          regulated series, respectively. The default style is used for
          both lines if this argument is not provided 

plot.pts: if `plot.pts=TRUE' (by default) then points are also drawn
          for the regulated series (+). Those points that match
          observations in the initial irregular series, and are not
          interpolated, are further marked with a circle 

     leg: do we add a legend to the graph? By default, `leg=FALSE', no
          legend is added 

    llab: the labels to use for the initial irregular and the final
          regulated series, respectively. By default, it is `"initial"'
          for the first one and the name of the regulation method used
          for the second one (see `methods' argument) 

    lpos: the position of the top-left corner of the legend box (x,y),
          in the graph coordinates 

     ...: additional graph parameters 

   label: the character to use to mark points interactively selected on
          the graph. By default, `label="#"' 

  nclass: the number of classes to calculate in the histogram. This is
          indicative and this value is automatically adjusted to obtain
          a nicely-formatted histogram. By default, `nclass=30' 

  plotit: If `plotit=TRUE' then the histogram is plotted. Otherwise, it
          is only calculated 

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

     Several irregular time series (for instance, contained in a data
     frame) can be treated at once. Specify a vector with `"constant"',
     `"linear"', `"spline"' or `"area"' for the argument `methods' to
     use a different regulation method for each series. See
     corresponding fonctions (`regconst()', `reglin()', `regspline()'
     and `regarea()'), respectively, for more details on these methods.
     Arguments can be saved in a `specs' object and reused for other
     similar regulation processes. Functions `regul.screen()' and
     `regul.adj()' are useful to chose best time interval in the
     computed regular time series. If you want to work on seasonal
     effects in the time series, you will better use a "years"
     time-scale (1 unit = 1 year), or convert into such a scale. If
     initial time unit is "days" (1 unit = 1 day), a conversion can be
     operated at the same time as the regulation by specifying
     `units="daystoyears"'.

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

     An object of type 'regul' is returned. It has methods `print()',
     `summary()', `plot()', `lines()', `identify()', `hist()',
     `extract()' and `specs()'.

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

     Frdric Ibanez (ibanez@obs-vlfr.fr), Philippe Grosjean
     (phgrosjean@sciviews.org)

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

     Lancaster, P. & K. Salkauskas, 1986. Curve and surface fitting.
     Academic Press, England, 280 pp.

     Fox, W.T. & J.A. Brown, 1965. The use of time-trend analysis for
     environmental interpretation of limestones. J. Geol., 73:510-518.

     Ibanez, F., 1991. Treatment of the data deriving from the COST 647
     project on coastal benthic ecology: The within-site  analysis. In:
     B. Keegan (ed). Space and Time Series Data Analysis in Coastal
     Benthic Ecology. Pp 5-43.

     Ibanez, F. & J.C. Dauvin, 1988. Long-term changes (1977-1987) on a
     muddy fine sand Abra alba - Melinna palmata population community
     from the Western English Channel. J. Mar. Ecol. Prog. Ser.,
     49:65-81.

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

     `regul.screen', `regul.adj', `tseries', `is.tseries', `regconst',
     `reglin', `regspline', `regarea', `daystoyears'

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

     data(releve)
     # The series in this data frame are very irregularly sampled in time:
     releve$Day
     length(releve$Day)
     intervals <- releve$Day[2:61]-releve$Day[1:60]
     intervals
     range(intervals)
     mean(intervals)
     # The series must be regulated to be converted in a 'rts' or 'ts object
     rel.reg <- regul(releve$Day, releve[3:8], xmin=9, n=63, deltat=21,
             tol=1.05, methods=c("s","c","l","a","s","a"), window=21)
     rel.reg
     plot(rel.reg, 5)
     specs(rel.reg)
     # Now we can extract one or several regular time series
     melo.ts <- extract(rel.reg, series="Melosul")
     is.tseries(melo.ts)

     # One can convert time-scale from "days" to "years" during regulation
     # This is most useful for analyzing seasonal cycles in a second step
     melo.regy <- regul(releve$Day, releve$Melosul, xmin=6, n=87,
             units="daystoyears", frequency=24, tol=2.2, methods="linear",
             datemin="21/03/1989", dateformat="d/m/Y")
     melo.regy
     plot(melo.regy, main="Regulation of Melosul")
     # In this case, we have only one series in 'melo.regy'
     # We can use also 'tseries()' instead of 'extract()'
     melo.tsy <- tseries(melo.regy)
     is.tseries(melo.tsy)

