Package 'fracdist'

Numerical CDFs for Fractional Unit Root and Cointegration Tests

Description

A package for calculating numerical distribution functions of fractional unit root and cointegration test statistics. The included functions calculate critical values and P-values used in unit root tests, cointegration tests, and rank tests in the Fractionally Cointegrated Vector Autoregression (FCVAR) model (see Johansen and Nielsen, 2012).

Details

Simple tabulation is not a feasible approach for obtaining critical values and P-values because these distributions depend on a real-valued parameter b that must be estimated. Instead, response surface regressions are used to obtain the numerical distribution functions and combined by model averaging across values taken from a series of tables. As a function of the dimension of the problem, q, and a value of the fractional integration order b, this approach provides either a set of critical values or the asymptotic P-value for any value of the likelihood ratio statistic. The P-values and critical values are calculated by interpolating from the quantiles on a grid of probabilities and values of the fractional integration order, with separate tables for a range of values of cointegrating rank.

The functions in this package are based on the functions and subroutines in the Fortran program fracdist.f to accompany an article by MacKinnon and Nielsen (2014). This program is available from the archive of the Journal of Applied Econometrics at http://qed.econ.queensu.ca/jae/datasets/mackinnon004/. Alternatively, a C++ implementation of this program is also available; see https://github.com/jagerman/fracdist/blob/master/README.md for details.

Value

Returns NULL. Object included for description only.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

Johansen, S. and M. Ø. Nielsen (2012). "Likelihood inference for a fractionally cointegrated vector autoregressive model," Econometrica 80, pp.2667-2732.

---

Interpolate Critical Values Local to Fractional Integration Parameter

Description

blocal calculates an approximation to the CDF for a particular value of the fractional integration parameter b.

Usage

blocal(nb = 31, bb, estcrit, bval)

Arguments

nb	The integer number of values of the fractional integration parameter $b$. The default is 31, which is the number of gridpoints between 0.5 and 2.0 in the lookup tables.
bb	The fractional integration parameter, which can take on values between 0.5 and 2.0.
estcrit	A numeric scalar that is an estimate of the critical value, a quantile, corresponding to a particular probability.
bval	A numeric vector of the fractional integration parameter $b$ ranging between 0.5 and 2.0 to match those in the lookup tables.

Value

A numeric scalar that is the sum of regression coefficients from a response surface regression.

Note

The fractional integration parameter b must lie within the interval $[0.50, 2]$. If b is less than 0.5, the relevant distribution is chi-squared. A value above 2 is less common but might be avoided by differencing the data before estimating the model under consideration.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

Examples

frtab <- get_fracdist_tab(iq = 3, iscon = 0)
bval <- unique(frtab[, 'bbb'])
probs <- unique(frtab[, 'probs'])
estcrit <- frtab[frtab[, 'probs'] == probs[201], 'xndf']
bedf_i <- blocal(nb = 31, bb = 0.75, estcrit, bval)

---

Verify that fracdist parameters are valid parameter values

Description

This is a helper function for error handling in the fracdist package. It is not intended to be used externally but might help diagnose error messages from improperly chosen arguments.

Usage

check_fracdist_params(fracdist_params)

Arguments

fracdist_params

a list that may have the following elements: iq An integer scalar rank parameter for the test, from 1 through 12. This is often the difference in cointegration rank. iscon An indicator that there is a constant intercept term in the model. clevel The numeric scalar level of significance. bb The fractional integration parameter, which can take on values between 0.0 and 2.0.

Value

No return value when checks pass, otherwise execution halts and an error message is printed.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

Examples

# Test with iscon = 7 to see error message:
check_fracdist_params(list(iq = 2, iscon = 1))
# Test with iq = 13 to see error message:
check_fracdist_params(list(iq = 12, iscon = 1))
# Test with bb = -0.5 to see error message:
check_fracdist_params(list(iq = 12, iscon = 1, bb = 0.75))
# Test with bb = 2.5 to see error message:
check_fracdist_params(list(iq = 12, iscon = 1, bb = 1.5))
# Test with clevel = 2.5 to see error message:
check_fracdist_params(list(iq = 1, iscon = 1, clevel = 0.05))

---

Calculate Critical Values for Fractional Unit Root and Cointegration Tests

Description

fcrit calculates critical values for a particular level of significance and a set of intermediate calculations that are output from other functions in the fracdist package.

Usage

fpcrit(npts = 9, iq, clevel, probs, bedf, ginv)

Arguments

npts	An integer number of points for local approximation of the EDF near the level of significance clevel. It is usually 9, unless near a boundary.
iq	An integer scalar rank parameter for the test, from 1 through 12. This is often the difference in cointegration rank.
clevel	The numeric scalar level of significance.
probs	A numeric vector of probabilities over which an approximating empirical distribution function is obtained, taken from precalculated tables.
bedf	A numeric vector of quantiles of numerical distribution for specified value of fractional integration order $b$ or values of $b$ and $d$, depending on the particular model. Each element is the output of the function blocal.
ginv	A numeric vector of quantiles of the approximating chi-squared distribution.

Value

A numeric scalar critical value, a quantile of the distribution.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

See Also

fracdist_values for the calculation of critical values and P-values including any intermediate calculations.

Examples

frtab <- get_fracdist_tab(iq = 3, iscon = 0)
bval <- unique(frtab[, 'bbb'])
probs <- unique(frtab[, 'probs'])
bedf <- rep(NA, length(probs))
for (i in 1:length(probs)) {
    estcrit <- frtab[frtab[, 'probs'] == probs[i], 'xndf']
    bedf[i] <- blocal(nb = 31, bb = 0.75, estcrit, bval)
}
fpcrit(npts = 9, iq = 3, clevel = 0.05, probs, bedf, ginv = qchisq(probs, df = 3^2))

---

Calculate P-values for Fractional Unit Root and Cointegration Tests

Description

fpval calculates P-values for a particular value of the observed statistic and a set of intermediate calculations that are output from other functions in the fracdist package.

Usage

fpval(npts = 9, iq, stat, probs, bedf, ginv)

Arguments

npts	An integer number of points for local approximation of the EDF near the observed value of stat. It is usually 9, unless near a boundary.
iq	An integer scalar rank parameter for the test, from 1 through 12. This is often the difference in cointegration rank.
stat	A numeric scalar value of the test statistic.
probs	A numeric vector of probabilities over which an approximating empirical distribution function is obtained, taken from precalculated tables.
bedf	A numeric vector of quantiles of numerical distribution for specified value of fractional integration order $b$ or values of $b$ and $d$, depending on the particular model. Each element is the output of the function blocal.
ginv	A numeric vector of quantiles of the approximating chi-squared distribution.

Value

A numeric scalar P-value.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

See Also

fracdist_pvalues for the calculation of P-values including any intermediate calculations.

Examples

frtab <- get_fracdist_tab(iq = 3, iscon = 0)
bval <- unique(frtab[, 'bbb'])
probs <- unique(frtab[, 'probs'])
bedf <- rep(NA, length(probs))
for (i in 1:length(probs)) {
    estcrit <- frtab[frtab[, 'probs'] == probs[i], 'xndf']
    bedf[i] <- blocal(nb = 31, bb = 0.75, estcrit, bval)
}
fpval(npts = 9, iq = 3, stat = 3.84, probs, bedf, ginv = qchisq(probs, df = 3^2))

---

Calculate P-values for Fractional Unit Root and Cointegration Tests

Description

fracdist_pvalues calculates P-values for a particular value of the observed statistic.

Usage

fracdist_pvalues(iq, iscon, dir_name = NULL, bb, stat)

Arguments

iq	An integer scalar rank parameter for the test, from 1 through 12. This is often the difference in cointegration rank.
iscon	An indicator that there is a constant intercept term in the model.
dir_name	A string name of directory in which the approximating tables are stored. This is not normally used, since sufficient tables are included in the package. However, a user might want to draw the tables from another location.
bb	The fractional integration parameter, which can take on values between 0.5 and 2.0.
stat	A numeric scalar value of the test statistic.

Value

A numeric scalar P-value.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

See Also

Calls fpval for the calculation of P-values after performing some intermediate calculations.

Examples

fracdist_pvalues(iq = 1, iscon = 0, bb = 0.73, stat = 3.84)

---

Calculate Critical Values or P-values for Fractional Unit Root and Cointegration Tests

Description

fracdist_values calculates either critical Values or P-values for for fractional unit root and cointegration tests

Usage

fracdist_values(
  iq,
  iscon,
  dir_name = NULL,
  bb,
  stat,
  ipc = TRUE,
  clevel = c(0.01, 0.05, 0.1)
)

Arguments

iq	An integer scalar rank parameter for the test, from 1 through 12. This is often the difference in cointegration rank.
iscon	An indicator that there is a constant intercept term in the model.
dir_name	A string name of directory in which the approximating tables are stored. This is not normally used, since sufficient tables are included in the package. However, a user might want to draw the tables from another location.
bb	The fractional integration parameter, which can take on values between 0.0 and 2.0.
stat	A numeric scalar value of the test statistic. This is only used if P-values are required.
ipc	A logical indicator to calculate a P-value. If ipc == FALSE critical values are calculated instead.
clevel	The numeric scalar level of significance. The default is to calculate critical values for the conventional levels of significance: clevel = c(0.01, 0.05, 0.10).

Value

Either a numeric scalar P-value, if ipc == TRUE, otherwise, a numeric vector of critical values, the same length as clevel.

Note

For fractional integration orders between 0 and 0.5, the chi-square distribution is used. See Johansen and Nielsen 2012 for details.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

Johansen, S. and M. Ø. Nielsen (2012). "Likelihood inference for a fractionally cointegrated vector autoregressive model," Econometrica 80, pp.2667-2732.

See Also

Calls fpval to calculate P-values or fpcrit to calculate critical values, after performing some intermediate calculations.

Examples

# Calculate P-values:
fracdist_values(iq = 1, iscon = 0, bb = 0.43, stat = 3.84)
fracdist_values(iq = 1, iscon = 0, bb = 0.73, stat = 3.84)
# Calculate critical values:
fracdist_values(iq = 1, iscon = 0, bb = 0.73, ipc = FALSE, clevel = 0.05)
fracdist_values(iq = 1, iscon = 0, bb = 0.43, ipc = FALSE, clevel = 0.05)
fracdist_values(iq = 1, iscon = 0, bb = 0.73, ipc = FALSE)

---

Obtain Lookup Tables of Probabilities and Quantiles

Description

get_fracdist_tab selects a table of probabilities and quantiles for a list of values of the fractional integration parameter, corresponding to a particular rank or dimension and the specification of a constant term.

Usage

get_fracdist_tab(iq, iscon, dir_name = NULL, file_ext = "rda")

Arguments

iq	An integer scalar rank parameter for the test, from 1 through 12. This is often the difference in cointegration rank.
iscon	An indicator that there is a constant intercept term in the model.
dir_name	A string name of directory in which the tables are stored. This is not normally used, however, a user might want to draw the tables from another location.
file_ext	A string extension indicating the file format of the tables. The default is 'rda', which is the format of the tables included in the package. The tables may also be stored in 'RData' format. The tables accompanying the original Fortran program, on which this package is based, can be obtained in 'txt' format. See the reference for details.

Value

A data frame with three columns: bbb is the fractional integration parameter, probs are the probability values, and xndf is the probs quantile of the distribution.

References

James G. MacKinnon and Morten Ørregaard Nielsen, "Numerical Distribution Functions of Fractional Unit Root and Cointegration Tests," Journal of Applied Econometrics, Vol. 29, No. 1, 2014, pp.161-171.

Examples

frtab <- get_fracdist_tab(iq = 1, iscon = 0)

---