kzs                   package:kzs                   R Documentation

_K_o_l_m_o_g_o_r_o_v-_Z_u_r_b_e_n_k_o _S_p_l_i_n_e

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

     This is a one-dimensional iterative smoothing algorithm based on
     convolutions of rectangular kernels.

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

     kzs(y, x, smooth, scale, k = 1, edges = TRUE, plot = TRUE)

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

       y: a one-dimensional vector of real values representing the
          response variable to be smoothed. 

       x: a one-dimensional vector of real values representing the
          input variable. 

  smooth: a real number defining the width of the smoothing window,
          i.e., the width of the rectangular kernel.    

   scale: for an irregularly spaced 'x', 'scale' is a positive real
          number that will define a uniform scale along 'x'. 

       k: an integer specifying the number of iterations 'kzs' will
          execute; 'k' may also be  interpreted as the order of
          smoothness (as a polynomial of degree 'k-1'). By default, 'k
          = 1'. 

   edges: a logical indicating whether or not to display the outcome
          data beyond the initial range of 'x'. By  default, 'edges =
          TRUE'.  

    plot: a logical indicating whether or not to produce a plot of the
          'kzs' outcome. This is 'TRUE' by default. 

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

     The relation between variables Y and X as a function of a current
     value of X = x [namely, Y(x)] is  often desired as a result of
     practical research. Usually we search for some simple function,
     Y(x),  when given a data set of pairs (Xi, Yi). When plotted,
     these pairs frequently resemble a noisy plot,  and thus Y(x) is
     desired to be a smooth outcome that captures patterns or long-term
     trends in the  original data, while suppressing the noise. The
     'kzs' function is based on convolutions of the rectangular kernel,
     which is equilvalent to repeated applications of a moving average.
     According to  the Central Limit Theorem, repeated convolutions
     with rectangular kernels will converge to the Gaussian kernel; the
     resulting kernel will have finite support equal to 'smooth*k',
     which will result in a  smooth outcome with diminished noise
     leakage, which is a feature that the standard Gaussian kernel does
     not exhibit.

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

     a two-column data frame of paired values '(xk, yk)': 

     xk : 'x' values in increments of 'scale' 

     yk : smoothed response values resulting from 'k' iterations of
          'kzs' 

_N_o_t_e:

     Data set (Xi, Yi) must be provided, usually as some observations
     that occur at certain times; 'kzs' is designed for the general
     situation, including time series data. In many applications where
     the input  variable, 'x', can be time, 'kzs' is resolving the
     problem of missing values in time series or  irregularly observed
     values in longitudinal data analysis.


     'kzs' may take time to completely run depending on the size of the
     data set used and the number of  iterations specified.

     For more information on the restrictions imposed on 'delta' and
     'd', consult 'kzs.params'.

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

     Derek Cyr cyr.derek@gmail.com and Igor Zurbenko
     igorg.zurbenko@gmail.com

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

     Zurbenko, I.G. (1986). _The Spectral Analysis of Time Series_.
     North Holland Series in  Statistics and Probability, Elsevier
     Science, Amsterdam.

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

     'kzs.params', 'kzs.2d', 'kzs.md'

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

     # Total time t
     t <- seq(from = -round(400*pi), to = round(400*pi), by = .25) 

     # Construct the signal over time
     ts <- 0.5*sin(sqrt((2*pi*abs(t))/200))
     signal <- ifelse(t < 0, -ts, ts)

     # Bury the signal in noise [randomly, from N(0, 1)]
     et <- rnorm(length(t), mean = 0, sd = 1)
     yt <- et + signal

     # Data frame of (t, yt) 
     pts <- data.frame(cbind(t, yt))

     ### EXAMPLE 1 - Apply kzs to the signal buried in noise                 

     # Plot of the true signal
     plot(signal ~ t, xlab = "t", ylab = "Signal", main = "True Signal",
     type = "l")

     # Plot of signal + noise
     plot(yt ~ t, ylab = "yt", main = "Signal buried in noise", type = "p")

     # Apply 3 iterations of kzs
     kzs(y = pts[,2], x = pts[,1], smooth = 80, scale = .2, k = 3, edges = TRUE,
     plot = TRUE)
     lines(signal ~ t, col = "red")
     title(main = "kzs(smooth = 80, scale = .2, k = 3, edges = TRUE)")
     legend("topright", c("True signal","kzs estimate"), cex = 0.8,
     col = c("red", "black"), lty = 1:1, lwd = 2, bty = "n")

     ### EXAMPLE 2 - Irregularly observed data over time

     # Cancel a random 20 percent of (t, yt) leaving irregularly observed time points
     obs <- seq(1:length(t))
     t20 <- sample(obs, size = length(obs)/5)
     pts20 <- pts[-t20,]        

     # Plot of (t,yt) with 20 percent of the data removed
     plot(pts20$yt ~ pts20$t, main = "Signal buried in noise\n20 percent of 
     (t, yt) deleted", xlab = "t", ylab = "yt", type = "p")

     # Apply 3 iterations of kzs
     kzs(y = pts20[,2], x = pts20[,1], smooth = 80, scale = .2, k = 3, edges = TRUE, 
     plot = TRUE)
     lines(signal ~ t, col = "red")
     title(main = "kzs(smooth = 80, scale = .2, k = 3, edges = TRUE)")
     legend("topright", c("True signal","kzs estimate"), cex = 0.8, 
     col = c("red", "black"), lty = 1:1, lwd = 2, bty = "n")  

