# fjohansen (R)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![R](https://img.shields.io/badge/R-%E2%89%A54.0-blue)](https://cran.r-project.org)
[![GitHub](https://img.shields.io/badge/repo-merwanroudane%2Ffjohansen-black)](https://github.com/merwanroudane/fjohansen)

**R implementation** of the **Johansen cointegration test with
Fourier-type smooth nonlinear deterministic trends restricted to
cointegrating relations** of

> **Kurita, T. & Shintani, M. (2025)**. *Johansen test with Fourier-type
> smooth nonlinear trends in cointegrating relations.* **Econometric
> Reviews**, 44(10), 1589–1616.
> [DOI: 10.1080/07474938.2025.2530640](https://doi.org/10.1080/07474938.2025.2530640)

The package also bundles the FGLS Wald test of

> **Perron, P., Shintani, M. & Yabu, T. (2017, 2021)**. *Testing for
> flexible nonlinear trends with an integrated or stationary noise
> component.* *OBES* 79, 822–850.

used as a frequency-selection pre-step.

> **Author:** Merwan Roudane — `merwanroudane920@gmail.com`
> **Repository:** <https://github.com/merwanroudane/fjohansen>

A sibling Python package with identical functionality is available on
[PyPI](https://pypi.org/project/fjohansen/).

---

## ✨ Features

* Six model variants — `CNR`, `LNR`, `CNU`, `LNU`, `constant`, `linear`.
* Bundled Table B1 critical values + pre-computed moments for all common
  cells (no Monte-Carlo cost on cold start).
* Sequential cointegrating-rank selection.
* Perron-Shintani-Yabu (2021) FGLS Wald test with general-to-specific
  frequency selection (univariate and multivariate panels).
* Publication-quality output: ASCII summary, LaTeX (booktabs), HTML, and
  `ggplot2` figures matching the paper's style.
* All paper DGPs (NF-DGP-1..4, F-DGP-1, F-DGP-2) + a synthetic JGB
  surrogate.

---

## 📦 Installation

```r
# Development version from GitHub
# install.packages("remotes")
remotes::install_github("merwanroudane/fjohansen", subdir = "fjohansenR")
```

Dependencies: `ggplot2`, `scales`, `knitr` (all available on CRAN).
Suggested extras: `testthat`, `kableExtra`, `patchwork`.

---

## 🚀 Quick start

```r
library(fjohansen)

# 1. Synthetic JGB-style dataset (Section 6 of the paper)
data <- sample_jgb_data(T = 108)

# 2. Pick the number of Fourier frequencies (PSY 2021)
sel <- select_frequencies(data, n_max = 5, p_d = 1, sig_level = 0.10)
print(sel)                          # n_selected, per_series, detail

# 3. Estimate the Johansen-Fourier (CNR) model
res <- johansen_fourier(data, k = 3, n = sel$n_selected, model = "CNR")

# 4. Pretty output
print(res)                           # Table-3 style ASCII
summary(res)                         # adds beta / alpha
cat(format_trace_latex(res))         # journal-ready LaTeX
cat(format_trace_html(res))          # styled HTML

# 5. ggplot2 figures
plot(res, which = "eigenvalues")
plot(res, which = "long_run")
plot(res, which = "risk_premium")
plot(res, which = "residuals")
```

---

## 🧩 Model variants

| Code        | $Z_1$ (cointegrating space)              | $Z_2$ (unrestricted)                 |
|-------------|-------------------------------------------|---------------------------------------|
| `CNR`       | `(X[t-1]', F[t,T]', 1)'`                  | DX-lags only                          |
| `LNR`       | `(X[t-1]', F[t,T]', t)'`                  | DX-lags + constant                    |
| `CNU`       | `(X[t-1]', 1)'`                           | DX-lags + `F[t,T]`                    |
| `LNU`       | `(X[t-1]', t)'`                           | DX-lags + constant + `F[t,T]`         |
| `constant`  | `(X[t-1]', 1)'`                           | DX-lags only (standard Johansen)      |
| `linear`    | `(X[t-1]', t)'`                           | DX-lags + constant (standard)         |

with `F[t,T] = [sin(2*pi*t/T), cos(2*pi*t/T), ..., sin(2*pi*n*t/T), cos(2*pi*n*t/T)]'`.

---

## 📚 Reference

Main public functions:

| Function                                | Purpose                                   |
|-----------------------------------------|-------------------------------------------|
| `johansen_fourier(data, k, n, model)`   | Reduced-rank regression + trace test.     |
| `select_frequencies(data, n_max, ...)`  | PSY 2021 general-to-specific selection.   |
| `psy_wald_test(y, k_freqs, p_d, ...)`   | Univariate FGLS Wald test.                |
| `jf_quantile(level, p_minus_r, n, model)` | Critical-value lookup / Gamma fallback. |
| `jf_p_value(stat, p_minus_r, n, model)` | Gamma-approximation p-value.              |
| `simulate_limit_distribution(...)`      | Limit-distribution sampler.               |
| `format_trace_table / _latex / _html`   | Table exports.                            |
| `plot.johansen_fourier`                 | `ggplot2` figures: eigenvalues, long-run, risk-premium, residuals. |
| `sample_jgb_data()`                     | JGB surrogate dataset.                    |
| `generate_f_dgp1 / _f_dgp2 / _nf_dgp1..4` | Paper DGPs.                             |

---

## 📑 Citation

```bibtex
@article{kurita_shintani_2025,
  author  = {Takamitsu Kurita and Mototsugu Shintani},
  title   = {Johansen test with Fourier-type smooth nonlinear trends in cointegrating relations},
  journal = {Econometric Reviews},
  year    = {2025},
  volume  = {44},
  number  = {10},
  pages   = {1589--1616},
  doi     = {10.1080/07474938.2025.2530640}
}

@misc{roudane_fjohansenR,
  author = {Merwan Roudane},
  title  = {fjohansen: Johansen test with Fourier-type smooth nonlinear trends (R)},
  year   = {2025},
  url    = {https://github.com/merwanroudane/fjohansen}
}
```

---

## 📜 License

MIT — © 2025 Merwan Roudane (`merwanroudane920@gmail.com`).
