\HeaderA{kzs}{Kolmogorov-Zurbenko Spline}{kzs}
\keyword{smooth}{kzs}
\keyword{ts}{kzs}
\keyword{nonparametric}{kzs}
\begin{Description}\relax
This is a one-dimensional iterative smoothing algorithm based on convolutions of rectangular kernels.
\end{Description}
\begin{Usage}
\begin{verbatim}
kzs(y, x, smooth, scale, k = 1, edges = TRUE, plot = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{y}] a one-dimensional vector of real values representing the response variable to be smoothed.

\item[\code{x}] a one-dimensional vector of real values representing the input variable.

\item[\code{smooth}] a real number defining the width of the smoothing window, i.e., the width of the rectangular kernel.   

\item[\code{scale}] for an irregularly spaced \code{x}, \code{scale} is a positive real number that will define a uniform
scale along \code{x}.

\item[\code{k}] an integer specifying the number of iterations \code{kzs} will execute; \code{k} may also be 
interpreted as the order of smoothness (as a polynomial of degree \code{k-1}). By default, \code{k = 1}.

\item[\code{edges}] a logical indicating whether or not to display the outcome data beyond the initial range of \code{x}. By 
default, \code{edges = TRUE}. 

\item[\code{plot}] a logical indicating whether or not to produce a plot of the \code{kzs} outcome. This is \code{TRUE}
by default.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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 \code{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 \code{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.
\end{Details}
\begin{Value}
a two-column data frame of paired values \code{(xk, yk)}:
\begin{ldescription}
\item[\code{xk }] \code{x} values in increments of \code{scale} 
\item[\code{yk }] smoothed response values resulting from \code{k} iterations of \code{kzs} 
\end{ldescription}
\end{Value}
\begin{Note}\relax
Data set (Xi, Yi) must be provided, usually as some observations that occur at certain times; \code{kzs}
is designed for the general situation, including time series data. In many applications where the input 
variable, \code{x}, can be time, \code{kzs} is resolving the problem of missing values in time series or 
irregularly observed values in longitudinal data analysis.\\ 

\code{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 \code{delta} and \code{d}, consult \code{\LinkA{kzs.params}{kzs.params}}.
\end{Note}
\begin{Author}\relax
Derek Cyr \email{cyr.derek@gmail.com} and Igor Zurbenko \email{igorg.zurbenko@gmail.com}
\end{Author}
\begin{References}\relax
Zurbenko, I.G. (1986). \emph{The Spectral Analysis of Time Series}. North Holland Series in 
Statistics and Probability, Elsevier Science, Amsterdam.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{kzs.params}{kzs.params}}, \code{\LinkA{kzs.2d}{kzs.2d}}, \code{\LinkA{kzs.md}{kzs.md}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

# 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")  
\end{ExampleCode}
\end{Examples}

