Introduction
The jumps package implements the method described in the
forthcoming Economic Modelling article “A Hodrick-Prescott
filter with automatically selected breaks”. The terms jumps and
breaks are used interchangeably in the package documentation.
Indeed, in the initial version of the article, we used the term jumps,
and one of the referees suggested that this term is generally devoted to
the jump processes used in mathematical finance, while breaks
is generally used in econometrics. We agreed with the referee and
decided to use the term breaks in the article’s final version. However,
we decided to keep the term jumps in the package name and in
the function names because we had already written most of it.
We introduced an innovation to the well-known Hodrick-Prescott filter
(HPF) that allows for a small number of discontinuities in the otherwise
smooth filter. The number, positions and magnitudes of these
discontinuities, which we name breaks or jumps, are
automatically estimated from the data. The method is based on the
minimization of the sum of squared residuals of the HPF subject to a
penalty on the number of breaks. The penalty is chosen by the user and
can be set to zero, in which case the method reduces to the standard
HPF. The technique is implemented in the hpj function,
which is the main function of the package. The function hpj
is a wrapper for other functions that implement various variations of
the technique.
For efficiency, the package’s computational engine is written in C++
through the Rcpp package. The engine implements the Kalman filter and
smoother for the state-space form underlying the HPF. All formulae can
be found in the article and in the vignette titled
Formulae.
Users needing higher control over the estimation process can use the
functions with names hpfj* and auto_hpfj*.
However, the wrapper function hpj makes the process simpler
and more stable. Indeed, good starting values are essential since the
technique is based on a complex numerical optimisation. Inside the
hpj function, we linearly transform the time series so that
the starting values in the hpfj* functions are expected to
work fine, and then we apply the anti-transform to all the results so
that they refer to the original time series. The functions
hpfj* and auto_hpfj* allow full control over
the starting values and penalties.
While hpfj* and auto_hpfj* accept only time
series stored in a numerical vector (any type of time series object is
cast to numerical vector), the hpj function accepts all the
main time series objects used in R (ts, zoo, xts, and timeSeries). All
the time series generated by the function receive the same class and
dates as the original time series.
Basic usage
The function is called as
hpj(y, maxsum = NULL, lambda = NULL, xreg = NULL, ic = c("bic", "hq", "aic", "aicc"))
where y is the time series to be filtered,
maxsum is inverse penalty, when zero no jumps are allowed,
the larger maxsum the more and larger breaks are allowed,
lambda is the smoothing parameter of the HPF,
xreg is a matrix of regressors (we are still woring on
this, so, at the moment it is not yet implemented), and ic
is the information criterion used to select the penalty when
maxsum = NULL. When lambda = NULL, the
smoothing parameter is estimated by quasi maximum likelihood. The
parameter lambda can be a positive number or one of the
following strings (in parenthesis the value of the smoothing parameter
corresponding to the string): daily (110,930,628,906), weekly
(45,697,600), monthly (129,600), quarterly (1,600), annual (6.25).
The function returns an object of class hpj, which is a
list with the following slots:
y the input time series;maxsum the maximum sum of additional standard
deviations;lambda the smoothing constant of the HP filter;pars vector of estimated parameters (sigma_slope,
sigma_noise, gamma);- hpj: the time series of the HP filter with
jumps;hpj_std the time series of the HP filter with jumps
standard deviations;std_devs vector of additional standard deviations of
the level disturbance;xreg matrix of regressors;df model’s degrees of freedom;loglik value of the log-likelihood at maximum;ic vector of information criteria (aic, aicc, bic,
hq);opt the output of the optimization function
(nloptr);call the call to the function.
The methods print and plot are available
for the hpj class. The plot method can be
customised:
plot(x, prob = NULL, show_breaks = TRUE, main = "original + filter", use_ggplot = TRUE, ...)
where x is the object of class hpj,
prob is the coverage of the confidence interval for the
filter, which is not plotted when prob = NULL,
show_breaks is a logical indicating whether to show the
breaks in the plot, main is the title of the plot,
use_ggplot is a logical indicating whether to use ggplot2,
and ... are additional arguments passed to the
plot function when the standard plot is used (that is when
use_ggplot = FALSE).
