| Title: | Local Partial Autocorrelation Function Estimation for Locally Stationary Wavelet Processes |
|---|---|
| Description: | Provides the method for computing the local partial autocorrelation function for locally stationary wavelet time series from Killick, Knight, Nason, Eckley (2020) <doi:10.1214/20-EJS1748>. |
| Authors: | Rebecca Killick [aut, cre], Guy Nason [aut], Marina Knight [aut], Matt Nunes [aut], Idris Eckley [ctb] |
| Maintainer: | Rebecca Killick <[email protected]> |
| License: | GPL-2 |
| Version: | 1.0.1 |
| Built: | 2024-11-24 06:26:17 UTC |
| Source: | https://github.com/cran/lpacf |
This package computes a localized partial autocorrelation of a time series assuming a locally stationary wavelet model.
| Package: | lpacf |
| Type: | Package |
| Version: | 1.0.1 |
| Date: | 2023-05-12 |
| License: | GPL-2 |
The lpacf function computes the localized partial autocorrelation
of a locally stationary time series. The resultant object can be printed using
print.lpacf or plotted by plot.lpacf.
Rebecca Killick, Marina Knight, Guy Nason and Matt Nunes
Maintainer: Rebecca Killick <[email protected]>
Killick, R., Knight, M. I., Nason, G.P. and Eckley, I. A. (2020) The local partial autocorrelation function and some applications. Electron. J. Statist. 14 (2), 3268-3314. DOI: 10.1214/20-EJS1748.
# # See examples in each of the functions' help pages linked above. ## # See examples in each of the functions' help pages linked above. #
Computes Epanechnikov kernel estimator closest to wavelet estimator of evolutionary wavelet spectrum. The idea is to obtain a good linear bandwidth.
AutoBestBW.Epan(x, filter.number = 1, family = "DaubExPhase", smooth.dev = var, AutoReflect = TRUE, tol = 0.1, maxits = 5, plot.it = FALSE, verbose = 0, ReturnAll = FALSE)AutoBestBW.Epan(x, filter.number = 1, family = "DaubExPhase", smooth.dev = var, AutoReflect = TRUE, tol = 0.1, maxits = 5, plot.it = FALSE, verbose = 0, ReturnAll = FALSE)
x |
Time series you want to analyze. |
filter.number |
The wavelet filter used to carry out smoothing operations. |
family |
The wavelet family used to carry out smoothing operations. |
smooth.dev |
The deviance estimate used for the smoothing (see ewspec help) |
AutoReflect |
Mitigate periodic boundary conditions of wavelet transforms by reflecting time series about RHS end before taking transforms (and is undone before returning the answer). |
tol |
Tolerance for golden section search for the best bandwidth |
maxits |
Maximum number of iterations for the golden section search |
plot.it |
Plot the values of the bandwidth and its closeness of the linear smooth to the wavelet smooth, if TRUE. |
verbose |
If nonzero prints out informative messages about the progress of the golden section search. Higher integers produce more messages. |
ReturnAll |
If TRUE then return the best bandwidth (in the ans component), the wavelet smooth (in EWS.wavelet) and the closest linear smooth (EWS.linear). If FALSE then just the bandwidth is returned. |
Tries to find the best running mean fit to an estimated spectrum obtained via wavelet shrinkage. The goal is to try and find a reasonable linear bandwidth.
If ReturnAll argument is FALSE then the best bandwidth is returned.
Guy Nason.
Nason, G.P. (2013) A test for second-order stationarity and approximate confidence intervals for localized autocovariances for locally stationary time series. J. R. Statist. Soc. B, 75, 879-904.
# # Generate synthetic data # x <- rnorm(256) # # Compute best linear bandwidth # tmp <- AutoBestBW(x=x) # # Printing it out in my example gives: # tmp # [1] 168# # Generate synthetic data # x <- rnorm(256) # # Compute best linear bandwidth # tmp <- AutoBestBW(x=x) # # Printing it out in my example gives: # tmp # [1] 168
This calculates the local partial autocorrelation function for data x. Up to lag.max lags are calculated.
lpacf(x, binwidth, lag.max=NULL, filter.number=10, family="DaubLeAsymm", smooth.dev=var, AutoReflect=TRUE, tol=0.1, maxits=5, ABBverbose=0, lapplyfn=lapply,allpoints=FALSE, verbose=FALSE, ...)lpacf(x, binwidth, lag.max=NULL, filter.number=10, family="DaubLeAsymm", smooth.dev=var, AutoReflect=TRUE, tol=0.1, maxits=5, ABBverbose=0, lapplyfn=lapply,allpoints=FALSE, verbose=FALSE, ...)
x |
The time series you wish to analyze |
binwidth |
The bandwidth for the
spectral smoothing. If the argument is missing or zero then the bandwidth
is chosen automatically using the |
lag.max |
The maximum lag of pacf required. If this argument is
|
filter.number |
The wavelet filter number for helping choose
the smoothing |
family |
The wavelet family for helping choose the smoothing
|
smooth.dev |
The type of deviance used by |
AutoReflect |
Mitigate periodic boundary conditions of wavelet transforms
by reflecting time series about RHS end before taking
transforms (and is undone before returning the answer).
Setting this to be |
tol |
Tolerance for golden section search for the best bandwidth used
only by |
maxits |
Maximum number of iterations for the golden section search used by
|
ABBverbose |
If nonzero prints out informative messages about the progress of the golden section search. Higher integers produce more messages. Setting it to zero suppresses messages. |
lapplyfn |
Function which applies a specified function to a vector. lapply is default but this argument can be used to replace this by something more efficient, e.g. a parallel version such as |
allpoints |
The lpacf is calculated using a window centered on a time point, if allpoints=TRUE then the edges of the data are also estimated (where a smaller, non-centered binwidth is used). Note, if |
verbose |
If |
... |
Other arguments for |
Calculates the local partial autocorrelation function (lpacf) for 1,...,lag.max lags. See paper in the references for more details.
NOTE: Often when local (windowed) estimates are created one assigns the estimated value to the central point in the window. This is the approach we take here when calculating the lacv and lpacf. This differs from the lpacf calculated for the forecastlpacf function which assign the estimated value to the last point in the window.
The function works by using the regular R pacf applied to carefully
chosen windows of the original series. Note: code in the
forecastlpacf from the forecastLSW package can compute a slightly different version of the
localized pacf using a wavelet method.
An object of class lpacf. This is a list with the following
components:
the.x |
the time coordinates of the localized partial autocorrelations. Call the length of this vector n. These coordinates can be non-integer (usually at halves) even if the original times are at the integers (which is assumed by this function). You can think of these indexing the value of the localized partial autocorrelation centred at these locations. |
lpacf |
The localized partical autocorrelations.
Matrix of dimension n x |
the.vacc |
This is |
the.x1 |
If |
the.x2 |
As for |
vacc |
A vector of length two containing the interval of time points for which the localized autocovariance is computed using the largest number of points in the calculation — ie the full binwidth. |
binwidth |
The smoothing binwidth that was used. |
AutoBinWidth |
This is |
Guy Nason and Rebecca Killick
Killick, R., Knight, M. I., Nason, G.P. and Eckley, I. A. (2020) The local partial autocorrelation function and some applications. Electron. J. Statist. 14 (2), 3268-3314. DOI: 10.1214/20-EJS1748.
lpacf.plot, forecastlpacf,
plot.lacf, print.lpacf, summary.lpacf
# first generate a time-varying process set.seed(1) x=tvar2sim() x.lpacf <- lpacf(x) # # There are two functions to plot lpacf class objects # # One is via the generic function plot which uses plot.lpacf # the other is a bespoke function lpact.plot. We'll look at # the generic function first which behaves similarly to the equivalent # function in the locits package: plot.lacf # # # This plot shows all of the localized partial autocovariances up to lag 27 # which is the default calculated value for this length of time series. plot(x.lpacf) # # In the previous plot, maybe there were too many lags. So, let's restrict to # five lags and colour them differently. # plot(x.lpacf, lags=1:5, lcol=1:5) # # By default, the lpacf is not computed for the whole time series range. # Let's do it for all the points now, and replot. # x.lpacf.all <- lpacf(x, allpoints=TRUE) plot(x.lpacf.all, lags=1:5, lcol=1:5) # # # Suppose we wanted to look at the localized partial autocorrelation at a # particular time point, using the regular acf-like plot. We can do this by: # # We will choose the time point to examine the localized pacf at as 150. # plot(x.lpacf, type="acf", the.time=150) # calculate the lpacf ans<-lpacf(x,lag.max=10,filter.number=2,family="DaubExPhase") # then maybe plot it by lag lpacf.plot(ans,atLag=1:10,atTime=150)# first generate a time-varying process set.seed(1) x=tvar2sim() x.lpacf <- lpacf(x) # # There are two functions to plot lpacf class objects # # One is via the generic function plot which uses plot.lpacf # the other is a bespoke function lpact.plot. We'll look at # the generic function first which behaves similarly to the equivalent # function in the locits package: plot.lacf # # # This plot shows all of the localized partial autocovariances up to lag 27 # which is the default calculated value for this length of time series. plot(x.lpacf) # # In the previous plot, maybe there were too many lags. So, let's restrict to # five lags and colour them differently. # plot(x.lpacf, lags=1:5, lcol=1:5) # # By default, the lpacf is not computed for the whole time series range. # Let's do it for all the points now, and replot. # x.lpacf.all <- lpacf(x, allpoints=TRUE) plot(x.lpacf.all, lags=1:5, lcol=1:5) # # # Suppose we wanted to look at the localized partial autocorrelation at a # particular time point, using the regular acf-like plot. We can do this by: # # We will choose the time point to examine the localized pacf at as 150. # plot(x.lpacf, type="acf", the.time=150) # calculate the lpacf ans<-lpacf(x,lag.max=10,filter.number=2,family="DaubExPhase") # then maybe plot it by lag lpacf.plot(ans,atLag=1:10,atTime=150)
This calculates the local partial autocorrelation function for data x based on spectral smoothing using the Epanechnikov kernel. Up to lag.max lags are calculated.
lpacf.Epan(x, binwidth, lag.max=NULL, filter.number=10, family="DaubLeAsymm", smooth.dev=var, AutoReflect=TRUE, tol=0.1, maxits=5, ABBverbose=0, lapplyfn=lapply, allpoints=FALSE, verbose=FALSE, ...)lpacf.Epan(x, binwidth, lag.max=NULL, filter.number=10, family="DaubLeAsymm", smooth.dev=var, AutoReflect=TRUE, tol=0.1, maxits=5, ABBverbose=0, lapplyfn=lapply, allpoints=FALSE, verbose=FALSE, ...)
x |
The time series you wish to analyze |
binwidth |
The bandwidth for the spectral smoothing. If the argument is missing or zero then the bandwidth
is chosen automatically using the |
lag.max |
The maximum lag of pacf required. If this argument is
|
filter.number |
The wavelet filter number for helping choose
the smoothing |
family |
The wavelet family for helping choose the smoothing
|
smooth.dev |
The type of deviance used by |
AutoReflect |
Mitigate periodic boundary conditions of wavelet transforms
by reflecting time series about RHS end before taking
transforms (and is undone before returning the answer).
Setting this to be |
tol |
Tolerance for golden section search for the best bandwidth used
only by |
maxits |
Maximum number of iterations for the golden section search used by
|
ABBverbose |
If nonzero prints out informative messages about the progress of the golden section search. Higher integers produce more messages. Setting it to zero suppresses messages. |
lapplyfn |
Function which applies a specified function to a vector. lapply is default but this argument can be used to replace this by something more efficient, e.g. a parallel version such as |
allpoints |
The lpacf is calculated using a window centered on a time point, if allpoints=TRUE then the edges of the data are also estimated (where a smaller, non-centered binwidth is used). Note, if |
verbose |
If |
... |
Other arguments for |
Calculates the local partial autocorrelation function (lpacf) for 1,...,lag.max lags. See paper in the references for more details.
NOTE: Often when local (windowed) estimates are created one assigns the estimated value to the central point in the window. This is the approach we take here when calculating the lacv and lpacf. This differs from the lpacf calculated for the forecastlpacf function which assign the estimated value to the last point in the window.
The function works by using the regular R pacf applied to carefully
chosen windows of the original series. Note: code in the
forecastlpacf from the forecastLSW package can compute a slightly different version of the
localized pacf using a wavelet method.
An object of class lpacf. This is a list with the following
components:
the.x |
the time coordinates of the localized partial autocorrelations. Call the length of this vector n. These coordinates can be non-integer (usually at halves) even if the original times are at the integers (which is assumed by this function). You can think of these indexing the value of the localized partial autocorrelation centred at these locations. |
lpacf |
The localized partical autocorrelations.
Matrix of dimension n x |
the.vacc |
This is |
the.x1 |
If |
the.x2 |
As for |
vacc |
A vector of length two containing the interval of time points for which the localized autocovariance is computed using the largest number of points in the calculation — ie the full binwidth. |
binwidth |
The smoothing binwidth that was used. |
AutoBinWidth |
This is |
Guy Nason and Rebecca Killick
Killick, R., Knight, M. I., Nason, G.P. and Eckley, I. A. (2020) The local partial autocorrelation function and some applications. Electron. J. Statist. 14 (2), 3268-3314. DOI: 10.1214/20-EJS1748.
lpacf, lpacf.plot, forecastlpacf,
plot.lacf, print.lpacf, summary.lpacf
# first generate a time-varying process set.seed(1) x=tvar2sim() x.lpacf <- lpacf(x) # # There are two functions to plot lpacf class objects # # One is via the generic function plot which uses plot.lpacf # the other is a bespoke function lpact.plot. We'll look at # the generic function first which behaves similarly to the equivalent # function in the locits package: plot.lacf # # # This plot shows all of the localized partial autocovariances up to lag 27 # which is the default calculated value for this length of time series. plot(x.lpacf) # # In the previous plot, maybe there were too many lags. So, let's restrict to # five lags and colour them differently. # plot(x.lpacf, lags=1:5, lcol=1:5) # # By default, the lpacf is not computed for the whole time series range. # Let's do it for all the points now, and replot. # x.lpacf.all <- lpacf(x, allpoints=TRUE) plot(x.lpacf.all, lags=1:5, lcol=1:5) # # # Suppose we wanted to look at the localized partial autocorrelation at a # particular time point, using the regular acf-like plot. We can do this by: # # We will choose the time point to examine the localized pacf at as 150. # plot(x.lpacf, type="acf", the.time=150) # calculate the lpacf ans<-lpacf.Epan(x,lag.max=10,filter.number=2,family="DaubExPhase") # then maybe plot it by lag lpacf.plot(ans,atLag=1:10,atTime=100)# first generate a time-varying process set.seed(1) x=tvar2sim() x.lpacf <- lpacf(x) # # There are two functions to plot lpacf class objects # # One is via the generic function plot which uses plot.lpacf # the other is a bespoke function lpact.plot. We'll look at # the generic function first which behaves similarly to the equivalent # function in the locits package: plot.lacf # # # This plot shows all of the localized partial autocovariances up to lag 27 # which is the default calculated value for this length of time series. plot(x.lpacf) # # In the previous plot, maybe there were too many lags. So, let's restrict to # five lags and colour them differently. # plot(x.lpacf, lags=1:5, lcol=1:5) # # By default, the lpacf is not computed for the whole time series range. # Let's do it for all the points now, and replot. # x.lpacf.all <- lpacf(x, allpoints=TRUE) plot(x.lpacf.all, lags=1:5, lcol=1:5) # # # Suppose we wanted to look at the localized partial autocorrelation at a # particular time point, using the regular acf-like plot. We can do this by: # # We will choose the time point to examine the localized pacf at as 150. # plot(x.lpacf, type="acf", the.time=150) # calculate the lpacf ans<-lpacf.Epan(x,lag.max=10,filter.number=2,family="DaubExPhase") # then maybe plot it by lag lpacf.plot(ans,atLag=1:10,atTime=100)
This function can produce plots of the lpacf at specified times and/or lags.
lpacf.plot(lpacf,atTime=NULL,atLag=NULL,SaveToFile=FALSE,alpha=0.95,...)lpacf.plot(lpacf,atTime=NULL,atLag=NULL,SaveToFile=FALSE,alpha=0.95,...)
lpacf |
An object produced by |
atTime |
Vector of the times of the |
atLag |
Vector of the lags (columns) of the |
SaveToFile |
If large numbers of plots are needed then set |
alpha |
alpha level for the confidence intervals, default 95% confidence. |
... |
Additional arguments can be supplied which will be passed to |
Produces the desired 1-d plots of the lpacf at times and lags as specified by atTime and atLag.
Silently returns the desired 1-d plots of the lpacf at times and lags as specified by atTime and atLag. If SaveToFile=TRUE then these are saved to a file in the current working directory rather than displayed.
Rebecca Killick
# first generate a time-varying process set.seed(879) x=tvar2sim() # calculate the lpacf ans<-lpacf(x,lag.max=10,filter.number=2,family="DaubExPhase") # then plot it at the first 10 lags at a couple of points in the data. lpacf.plot(ans,atLag=1:10,atTime=c(150,350))# first generate a time-varying process set.seed(879) x=tvar2sim() # calculate the lpacf ans<-lpacf(x,lag.max=10,filter.number=2,family="DaubExPhase") # then plot it at the first 10 lags at a couple of points in the data. lpacf.plot(ans,atLag=1:10,atTime=c(150,350))
lpacf object.
Plots information contained within a lpacf object.
Plot arrangement and options are similar to that in plot.lacf
in the locits package.
## S3 method for class 'lpacf' plot(x, type = "line", lags = 1:min(as.integer(10 * log10(nrow(x$lpacf))), ncol(x$lpacf) - 1), tcex = 1, lcol = 1, llty = 1, the.time = NULL, plot.it = TRUE, xlab, ylab, ...)## S3 method for class 'lpacf' plot(x, type = "line", lags = 1:min(as.integer(10 * log10(nrow(x$lpacf))), ncol(x$lpacf) - 1), tcex = 1, lcol = 1, llty = 1, the.time = NULL, plot.it = TRUE, xlab, ylab, ...)
x |
The |
type |
The type of plot you want. This can be |
lags |
A vector of integers containing the lags you wish to show. Note that, unlike regular autocorrelation, the smallest lag is lag one. |
tcex |
For the |
lcol |
A vector of colors, the same length as the |
llty |
As for |
the.time |
A time has to be specified for the |
plot.it |
If |
xlab |
A label for the x-axis. |
ylab |
A label for the y-axis |
... |
Other arguments to plot. |
Produces a graphical representation of localized partial autocorrelation.
The localized partial autocorrelation values are returned.
Essentially the ones that are, or would have been, plotted are
returned. The lags can be selected using the lags argument.
A matrix is returned: each row corresponds to a time point, each
column corresponds to a lag. All time points are returned.
Only the lags specified in the lags component are returned.
The dimnames component indicates which lags were returned.
This function was adapted from plot.lacf from the locits
package.
Guy Nason
Killick, R., Knight, M. I., Nason, G.P. and Eckley, I. A. (2020) The local partial autocorrelation function and some applications. Electron. J. Statist. 14 (2), 3268-3314. DOI: 10.1214/20-EJS1748.
# # Generate a test series # x.test <- tvar2sim() # # Compute its localized partial autocorrelation # x.lpacf <- lpacf(x.test) # # Perform a line plot of the localized partial autocorrelation of x # draw the lags in colours 1 thru 5 # # plot(x.lpacf, lags=1:5, lcol=1:5) # # Now produce the same plot, but omit lag 3 # plot(x.lpacf, lags=c(1,2,4,5), lcol=c(1,2,4,5)) # # Now plot localized autocovariance around time 175 using the regular acf # style plot. # plot(x.lpacf, type="acf", the.time=175)# # Generate a test series # x.test <- tvar2sim() # # Compute its localized partial autocorrelation # x.lpacf <- lpacf(x.test) # # Perform a line plot of the localized partial autocorrelation of x # draw the lags in colours 1 thru 5 # # plot(x.lpacf, lags=1:5, lcol=1:5) # # Now produce the same plot, but omit lag 3 # plot(x.lpacf, lags=c(1,2,4,5), lcol=c(1,2,4,5)) # # Now plot localized autocovariance around time 175 using the regular acf # style plot. # plot(x.lpacf, type="acf", the.time=175)
lpacf object.
Prints a lpacf object, basically telling you what's
there.
## S3 method for class 'lpacf' print(x, ...)## S3 method for class 'lpacf' print(x, ...)
x |
The |
... |
Other arguments |
Prints a lpacf object.
None
Guy Nason
Killick, R., Knight, M. I., Nason, G.P. and Eckley, I. A. (2020) The local partial autocorrelation function and some applications. Electron. J. Statist. 14 (2), 3268-3314. DOI: 10.1214/20-EJS1748.
# # Simulate an example # x.test <- tvar2sim() # # Compute the lpacf # x.lpacf <- lpacf(x.test) # # Print it out - note, can normally just type name of object # print(x.lpacf) #Class 'lpacf' : Localized Partial Autocorrelation Object: # ~~~~ : List with 5 components with names # the.x lpacf the.vacc binwidth AutoBinWidth # # #summary(.): #---------- #Number of times: 220 #Number of lags: 27 #Range of times from: 147 to 366 #Part series was analyzed (alltimes=FALSE) #Smoothing binwidth used was: 293 # Binwidth was chosen automatically# # Simulate an example # x.test <- tvar2sim() # # Compute the lpacf # x.lpacf <- lpacf(x.test) # # Print it out - note, can normally just type name of object # print(x.lpacf) #Class 'lpacf' : Localized Partial Autocorrelation Object: # ~~~~ : List with 5 components with names # the.x lpacf the.vacc binwidth AutoBinWidth # # #summary(.): #---------- #Number of times: 220 #Number of lags: 27 #Range of times from: 147 to 366 #Part series was analyzed (alltimes=FALSE) #Smoothing binwidth used was: 293 # Binwidth was chosen automatically
lpacf object.
Print out summary information about a lpacf object.
## S3 method for class 'lpacf' summary(object, ...)## S3 method for class 'lpacf' summary(object, ...)
object |
The |
... |
Other arguments |
Prints out number of times that we have localized partial autocorrelation for and the number of lags computed. The localized partial autocorrelation is computed at a number of time points that might not be identical to the times in the original series, this function prints out the min and max of the range of times and an indicator of whether the whole series' localized pacf was computed. The bandwidth associated with spectral smoothing is printed and a note made of whether it was computed automatically or supplied as an earlier argument.
None
Guy Nason
Killick, R., Knight, M. I., Nason, G.P. and Eckley, I. A. (2020) The local partial autocorrelation function and some applications. Electron. J. Statist. 14 (2), 3268-3314. DOI: 10.1214/20-EJS1748.
# # See example for print.lacf ## # See example for print.lacf #
Simulates a realization from a TVAR(2) model where
both parameters move from -1.1 to 0.5 in equal steps
over 512 time points. The realization is of length 512.
The innovations are normally distributed with mean zero and
standard deviation of sd.
tvar2sim(sd = 1)tvar2sim(sd = 1)
sd |
This is the standard deviation of the Gaussian innovation. |
This function is easily converted into one that does the same thing but for a different sample size.
A realization of the aforementioned TVAR(2) process.
Guy Nason.
# # Generate realization from the TVAR(2) process # x <- tvar2sim() # # Maybe plot it # ts.plot(x)# # Generate realization from the TVAR(2) process # x <- tvar2sim() # # Maybe plot it # ts.plot(x)