linearSegmentation         package:ifultools         R Documentation

_P_i_e_c_e_w_i_s_e _l_i_n_e_a_r _s_e_g_m_e_n_t_a_t_i_o_n _o_f _a _t_i_m_e _s_e_r_i_e_s

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

     Locates the change-points of time series based on a piecewise
     linear segmentation algorithm. Given a window size ('n.fit') and
     an angle tolerance ('angle.tolerance'), the segmentation algorithm
     starts by finding the slope of the first 'n.fit' points of the
     series via least squares regression. The window is slid over one
     point to the right, the points within the new window are
     regressed, and the new slope is compared to the old slope. If the
     change in slope exceeds the specified 'angle.tolerance', a
     change-point is recorded as the rightmost point of the previous
     iteration's window. The routine then picks up again starting at
     the point just to the right of the change-point. If the change in
     slope does not exceed the specified 'angle.tolerance', then the
     old slope is updated (in a running average sense), and the
     algorithm continues as usual. The window is slid along the until
     its rightmost point reaches the edge of the time series.

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

     linearSegmentation(x, y, n.fit=5, angle.tolerance=5,
         aspect=TRUE, plot=FALSE, add=FALSE, ...)

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

       x: the independent variable of the time series.

       y: the dependent variable of the time series.

     ...: additional arguments sent unaltered to the 'abline' function
          used to draw the vertical divisions of the linear
          segmentation. Only used if 'plot=TRUE'.

     add: a logical value. If 'TRUE', the plot is added using the
          current plotting scheme. Default: 'FALSE'.

angle.tolerance: the maximum angle in degrees that the running average
          of the slopes in the current set of points can change
          relative to the slope of the data calculated in the most
          current (rightmost) window before a change-point is recorded.
          Default: 5.

  aspect: a logical value. If 'TRUE', the aspect ratio of the data
          (defined by 'range(y) / range(x)') is used to adjust the
          'angle.tolerance'. Specifically, the new angle tolerance
          becomes 'angle.tolerance / aspect.ratio'. Using the aspect
          ratio to dilate 'angle.tolerance' allows the user to specify
          the degree of variablity they wish to impose on the data
          vis-a-vis a standard plot of the data, i.e. what you would
          see if you issued 'plot(xdata, ydata)'. The idea is that when
          looking at such plots, one might decide (for example) that a
          5 degree variablity on the plot would be acceptable. But if
          that range of 'y' is vastly different from that of 'x', then
          the true change in angle from one section to the other will
          be much different than 5 degrees. Thus, 'aspect' can be used
          to compensate for aspect ratios far away from unity. Default:
          'TRUE'.

   n.fit: an integer denoting the window size, not to exceed the number
          of samples in the time series. Default: 5.

    plot: a logical value. If 'TRUE', a plot of the segmentation is
          displayed. Default: 'FALSE'.

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

     a vector containing the result.

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

     'lm'.

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

     ## obtain some data with approximately 
     ## piecewise-linear trends 
     x <- seq(0,2*pi,length=100)
     y <- sin(x)

     ## perform linear segmentation with aspect ratio 
     ## dilation using a 5 degree tolerance and 5 
     ## point windows 
     z <- linearSegmentation(x, y, n.fit=5, angle.tolerance=5, aspect=TRUE)

     ## plot the data and the estimated change-points 
     plot(x, y)
     abline(v=x[z], lty=2)

