---
title: "Introduction to makicoint"
author: "Merwan Roudane"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to makicoint}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>",
                      fig.width = 7, fig.height = 5)
has_ggplot <- requireNamespace("ggplot2", quietly = TRUE)
```

## Overview

`makicoint` implements the Maki (2012) residual-based test for cointegration
that allows for an **unknown number of structural breaks**. It extends the
Gregory-Hansen (one break) and Hatemi-J (two breaks) tests to any feasible
number of breaks. The null hypothesis is *no cointegration*; the alternative is
*cointegration with up to `m` breaks*.

```{r load}
library(makicoint)
```

## How it works

Breaks are placed one at a time by a sequential Bai-Perron procedure. At each
candidate break the cointegrating regression is fitted and its residual is tested
with an augmented Dickey-Fuller (ADF) regression. The **test statistic is the
minimum ADF t-statistic** over all candidates and all steps; reject the null when
it falls below the critical value.

Four deterministic models are available: level shift (`model = 0`), level shift
with trend (`1`), regime shift (`2`), and regime shift with trend (`3`).

## Example: a single level break

```{r ex1}
set.seed(123)
n <- 100
x <- cumsum(rnorm(n))
y <- 0.5 * x + cumsum(rnorm(n))
y[51:100] <- y[51:100] + 2          # a level break at observation 50

res <- coint_maki(cbind(y, x), m = 1, model = 0)
res
```

The break is detected near observation 50 and, if the series are cointegrated
with that break, the statistic falls below the critical value.

### The diagnostic plot

If `ggplot2` is installed, `plot()` draws a two-panel dashboard: the series with
its break-adjusted long-run fit, and the cointegrating residual.

```{r ex1plot, eval = has_ggplot, fig.alt = "Two-panel Maki test dashboard"}
plot(res)
```

## Two engines

The break **dates** can be chosen two ways; both give the same test statistic.
The default reproduces the original 'GAUSS'/'tspdlib' implementation. With
`engine = "paper"`, each break minimises the cointegrating-regression sum of
squared residuals, the rule in Maki (2012, Steps 2 and 4).

```{r engines}
g <- coint_maki(cbind(y, x), m = 2, model = 2)                 # default (GAUSS)
p <- coint_maki(cbind(y, x), m = 2, model = 2, engine = "paper")
c(gauss = g$statistic, paper = p$statistic)
rbind(gauss = g$breakpoints, paper = p$breakpoints)
```

## Critical values

`cv_coint_maki()` returns the Maki (2012) Table 1 values, which depend on the
number of regressors (1-4), the number of breaks (1-5) and the model.

```{r cv}
cv_coint_maki(k = 2, m = 3, model = 2)
```

## More than five breaks

Maki's Table 1 stops at five breaks (his footnote 5 notes more are possible).
`makicoint` estimates the statistic and breaks for any feasible number, and for
more than five it can simulate the critical values by Maki's own Monte-Carlo
design. The simulation reruns the whole search every replication, so it is
heavy; use a few thousand replications for reported work.

```{r simcv, eval = FALSE}
# (not run here; can take minutes)
coint_maki(cbind(y, x), m = 7, simcv = 2000, simt = 500)
```

## Accessing results

```{r results}
res$statistic
res$breakpoints
res$critical_values
res$cv_source
```

## Reference

Maki, D. (2012). Tests for cointegration allowing for an unknown number of
breaks. *Economic Modelling*, 29, 2011-2015.
<https://doi.org/10.1016/j.econmod.2012.04.022>