---
title: "Introduction to makicoint"
author: "Dr. 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
)
```

## Introduction

The `makicoint` package implements the Maki (2012) cointegration test, which extends traditional cointegration tests by allowing for an unknown number of structural breaks. This is particularly important in econometric analysis where structural changes can affect long-run relationships between variables.

## Installation

```{r installation, eval=FALSE}
# From CRAN
install.packages("makicoint")

# Development version
devtools::install_github("merwanroudane/makicoint")
```

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

## Basic Concept

Traditional cointegration tests (e.g., Engle-Granger, Johansen) assume parameter stability. However, economic relationships often experience structural breaks due to:

- Policy changes
- Economic crises
- Technological shifts
- Regime changes

The Maki test addresses this by:

1. Searching for optimal break point locations
2. Computing test statistics for each configuration
3. Selecting the minimum (most negative) statistic
4. Comparing against break-specific critical values

## Example 1: Single Structural Break

Let's generate two cointegrated series with one structural break:

```{r example1}
set.seed(123)
n <- 100
e1 <- rnorm(n)
e2 <- rnorm(n)

# Generate I(1) processes
x <- cumsum(e1)
y <- 0.5 * x + cumsum(e2)

# Add structural break at observation 50
y[51:100] <- y[51:100] + 2

# Plot the data
oldpar <- par(mfrow = c(2, 1), mar = c(4, 4, 2, 1))
plot(y, type = 'l', col = 'blue', main = 'Dependent Variable (Y) with Break',
     xlab = 'Time', ylab = 'Y')
abline(v = 50, col = 'red', lty = 2)
plot(x, type = 'l', col = 'darkgreen', main = 'Independent Variable (X)',
     xlab = 'Time', ylab = 'X')
par(oldpar)
```

Now perform the Maki test:

```{r test1}
# Prepare data matrix (Y first, then X)
data1 <- cbind(y, x)

# Run test with m=1 (one break), model=0 (level shift)
result1 <- coint_maki(data1, m = 1, model = 0)
print(result1)
```

**Interpretation:**
- The test correctly detects cointegration
- The break point is identified near observation 50
- The test statistic is more negative than the 5% critical value

## Example 2: Multiple Breaks

Generate data with two structural breaks:

```{r example2}
set.seed(456)
n <- 150
e1 <- rnorm(n)
e2 <- rnorm(n)

x2 <- cumsum(e1)
y2 <- 0.6 * x2 + cumsum(e2)

# Add two breaks
y2[51:100] <- y2[51:100] + 1.5
y2[101:150] <- y2[101:150] + 3

# Plot
plot(y2, type = 'l', col = 'blue', main = 'Series with Two Breaks',
     xlab = 'Time', ylab = 'Y')
abline(v = c(50, 100), col = 'red', lty = 2)

# Test
data2 <- cbind(y2, x2)
result2 <- coint_maki(data2, m = 2, model = 0)
print(result2)
```

## Example 3: Regime Shift (Model 2)

Regime shifts involve changes in both the intercept and slope:

```{r example3}
set.seed(789)
n <- 120
e1 <- rnorm(n)
e2 <- rnorm(n)

x3 <- cumsum(e1)
y3 <- 0.4 * x3 + cumsum(e2)

# Regime shift: change slope after observation 60
y3[61:120] <- y3[61:120] + 0.3 * x3[61:120]

# Plot
plot(y3, type = 'l', col = 'blue', main = 'Regime Shift',
     xlab = 'Time', ylab = 'Y')
abline(v = 60, col = 'red', lty = 2)

# Test with model=2
data3 <- cbind(y3, x3)
result3 <- coint_maki(data3, m = 1, model = 2)
print(result3)
```

## Model Selection Guide

Choose the model based on your application:

| Model | Description | Use When |
|-------|-------------|----------|
| 0 | Level shift | You expect only intercept changes |
| 1 | Level shift + trend | Data has deterministic trend |
| 2 | Regime shift | Both intercept and slopes may change |
| 3 | Trend + regime | Most general specification |

## Parameter Settings

### Trimming Parameter (`trimm`)

- Default: 0.15 (15% of sample)
- Determines minimum distance between breaks
- Smaller values allow breaks closer together
- Larger values impose more separation

### Lag Selection (`lagoption`)

- `lagoption = 0`: No lags (assumes white noise residuals)
- `lagoption = 1`: Automatic selection using t-sig criterion (recommended)

## Practical Tips

1. **Start Simple**: Begin with m=1 and model=0, then increase complexity
2. **Visual Inspection**: Plot your data to identify potential break points
3. **Sample Size**: Larger samples provide more reliable break detection
4. **Multiple Variables**: Extend to more than one regressor by adding columns

## Accessing Results

```{r results}
# Access specific components
result1$statistic        # Test statistic
result1$breakpoints      # Break locations
result1$critical_values  # Critical values [1%, 5%, 10%]
result1$reject_5         # Reject at 5% level?
```

## References

Maki, D. (2012). Tests for cointegration allowing for an unknown number of breaks. *Economic Modelling*, 29(5), 2011-2015.

## Session Info

```{r session}
sessionInfo()
```