Skip to content
exuber

Explosive time series

Detecting exuberance before the collapse.

Test a series for a bubble, date the episode, and monitor it as it forms. The tests allow for changing volatility and work on a single series, a panel, or a whole market.

> install.packages("exuber")

Python: pip install pyexuber. C++: from source

Get started GitHub
  • On CRAN
  • JSS 2022
  • 30+ methods
  • R · Python · C++
95% CRITICAL VALUE
Simulated series, illustrative BSADF reading stable explosive

01 · get started

One core, three ways in.

The costly part of a GSADF run is a recursive least-squares fit, updated with the Sherman-Morrison formula and repeated over O(T²) windows. It is written once, in C++. Each language binding wraps that core and adds the tools that users of that language expect.

exubercore

C++ / Armadillo

core

The recursive least-squares statistic itself. It has no R or Python dependency: it takes plain matrices and returns a statistic. Anything that needs random numbers (simulation, bootstrap, date-stamping) stays in the host language for now.

exuber

R · on CRAN

stable

The complete package: the statistic, Monte Carlo and wild-bootstrap critical values, date-stamping, plotting and panel methods.

install.packages("exuber")

pyexuber

Python · pybind11

early

Bindings to the same core, imported as exuber. The R functions are ported method by method (tests, bootstraps, dating, monitoring, multivariate methods and simulation) and cross-checked against R.

git clone …exuber/pyexuber && uv sync --dev

The same run

Three languages, one statistic.

The example simulates a series, tests it, calibrates the critical values and date-stamps the result. The R and Python versions differ only in spelling. The C++ core stops at the statistic, because anything that needs random numbers stays in the host language. 

library(exuber)

rsim <- radf(sim_data)               # adf, badf, sadf, gsadf, bsadf, ...
cv <- radf_mc_cv(n = NROW(sim_data)) # simulated 90/95/99% thresholds

summary(rsim, cv)   # rejects/does not reject H0 per series, per statistic
autoplot(rsim, cv)  # bsadf vs. its threshold, explosive spans shaded
datestamp(rsim, cv) # a Start/End/Duration row per detected episode

Install steps for each language are in the getting-started guide. Every function is listed in the reference index.

02 · the idea

Bubbles break the assumptions of standard tests.

Asset-price bubbles are rare, short and end abruptly, which are the features that standard time-series tests are built to ignore. The recursive right-tailed approach of Phillips, Wu, Shi and Yu made them testable.

Step 1

A bubble is a root above one.

Conventional unit-root tests are left-tailed, which means they ask whether a series is stationary. A bubble is the opposite alternative: prices grow faster than fundamentals can justify, and the autoregressive root is greater than one. Right-tailed tests put that question directly.

Step 2

Full-sample tests miss the ones that burst.

A bubble that inflates and then collapses averages out over a long sample and looks like an ordinary random walk (Evans, 1991). Running the test recursively restores its power. The SADF test uses expanding windows, and the GSADF test uses every feasible start and end point.

Step 3

The statistic becomes a calendar.

The backward sup-ADF sequence (BSADF) is compared with its critical value date by date, and the dates where it exceeds the critical value mark when an episode started and ended. An analyst or a central bank needs to know when a bubble occurred and whether it is still running, as well as whether one exists.

That was the 2015 answer. Later work has asked harder questions. Is a rejection a bubble or only volatility? How precisely are the dates pinned down? Can a bubble be caught as it happens? Is it confined to one market or spread across many? exuber follows that literature method by method.

03 · what it answers

Six questions that every bubble study meets.

The original PSY test answers the first question. The rest come from later literature, and exuber has a family of methods for each. Every card links to the notes and replications behind it.

Is there a bubble at all?

ADF, SADF, GSADF and the BSADF sequence all come from one recursive least-squares pass. Each series gets a summary that says whether the null is rejected.

radf()summary()autoplot()

Is my threshold right for my sample?

The null distribution has no closed form, so the critical values are simulated by Monte Carlo, wild bootstrap or sieve bootstrap. For lags 0–4 and n ≤ 4000 they can also be fetched precomputed.

radf_mc_cv()radf_wb_cv()radf_sb_cv()

When did it start, and when did it end?

These functions give origination, collapse and recovery dates, alternative dating estimators, and confidence intervals for the explosive root itself.

datestamp()rootstamp()dating_hlw()radf_recovery()

Is it a bubble, or just volatility?

Time-varying volatility can produce spurious bubbles. Time-transformed, weighted, sign-based and kernel-purged tests are designed to guard against this.

radf_tt()radf_sbz()radf_sign()radf_kp()

Is it happening right now?

Train on a stable window, then check each new observation as it arrives. The CUSUM, LBI and quantile detectors control the false-alarm rate.

monitor()monitor_cusum()monitor_lbi()monitor_quantile()

Is it one market, or many?

These tools look for common bubbles in large panels, co-explosive pairs, and contagion from one market to another.

radf_common()cobubble_test()contagion_reg()

To simulate your own bubbles, see the simulation DGPs.

04 · academic grounding

Every method is traced to its paper and checked against it.

Econometric software is only as credible as its agreement with the literature. The exuber package was peer-reviewed in the Journal of Statistical Software, and each method added since has a public replication record.

papers read from the primary source
52
papers read from the primary source
standalone replication scripts, R and Python
69
standalone replication scripts, R and Python
methods implemented beyond PSY
~30
methods implemented beyond PSY
replications behind every precomputed threshold
2,000
replications behind every precomputed threshold

Primary source first.

Every method is implemented from the paper that introduced it, using its formulas, tables and theorems rather than a later restatement.

Checked from scratch.

A separate script recomputes each statistic using brute-force regressions and hand-derived identities. Monte Carlo size and power are compared with the paper's own tables.

Shortfalls stated.

Where a published number could not be reproduced, the replication record says so.

Foundations

  • Phillips, P.C.B., Wu, Y. & Yu, J. (2011). Explosive behavior in the 1990s Nasdaq: when did exuberance escalate asset values? International Economic Review, 52(1), 201–226. doi:10.1111/j.1468-2354.2010.00625.x
  • Phillips, P.C.B., Shi, S. & Yu, J. (2015). Testing for multiple bubbles: historical episodes of exuberance and collapse in the S&P 500. International Economic Review, 56(4), 1043–1078. doi:10.1111/iere.12132
  • Phillips, P.C.B., Shi, S. & Yu, J. (2015). Testing for multiple bubbles: limit theory of real-time detectors. International Economic Review, 56(4), 1079–1134. doi:10.1111/iere.12131

The full bibliography, grouped by methodological family, is in references. The replication record shows what was reproduced and how.

Cite exuber

Vasilopoulos, K., Pavlidis, E. & Martínez-García, E. (2022). exuber: Recursive right-tailed unit root testing with R. Journal of Statistical Software, 103(10), 1–26. doi:10.18637/jss.v103.i10 

@Article{exuber,
  title   = {{exuber}: Recursive Right-Tailed Unit Root Testing with {R}},
  author  = {Kostas Vasilopoulos and Efthymios Pavlidis and Enrique Mart{'i}nez-Garc{'i}a},
  journal = {Journal of Statistical Software},
  year    = {2022},
  volume  = {103},
  number  = {10},
  pages   = {1--26},
  doi     = {10.18637/jss.v103.i10},
}

05 · progress

What is implemented, where, and what comes next.

The table below summarises the parity record, which lists each method against each implementation and is maintained by hand. The C++ core stops at the statistic, so everything that needs simulation lives in R and Python.

Method family C++ R Python
Recursive ADF / SADF / GSADF / BSADF done done done
Critical values: MC, wild & sieve bootstrap, shared store n/a done done
Date-stamping and root inference n/a done done
Volatility-robust tests n/a done done
Real-time monitoring n/a done done
Multivariate: common, co-, contagion n/a done done
Bubble simulation DGPs n/a done done
Summary and tidy layer n/a done done

Release status

  • exubercore v0.3.1 Tagged, and both bindings pin this version.
  • exuber 1.1.0 on CRAN Version 2.0.0, which includes every method above, is being prepared for CRAN.
  • pyexuber 0.1.0 on PyPI Install it with pip install pyexuber. Prebuilt wheels cover Linux, macOS and Windows.

Still open

  • Bootstrap critical values for quantile monitoring (QPWY/QPSY), in either package
  • Critical values beyond n = 4000 in the shared store