psytest.bubbles module

psytest.bubbles module#

psytest.bubbles#

This module contains the main class for the PSY test (see psytest.bubbles.PSYBubbles). This class handles the frontend of the test, receiving the data and parameters, and providing methods to run the test and retrieve results. It also includes methods for parsing arguments, checking conditions, and finding bubble dates.

class psytest.bubbles.PSYBubbles(data: ndarray[tuple[int, ...], dtype[float64]], minwindow: int | None = None, minlength: int | None = None, lagmax: int | None = None, rstep: float | None = None, delta: float = 1.0)[source]#

Bases: Generic[IndexType]

Class to perform the Phillips, Shi & Yu (2015) test for bubbles in time series data.

Parameters:
Raises:

  • TypeError – If arguments are not of the expected type.

  • ValueError – If r0 and rstep are not in the range (0, 1) or if kmax is not a positive integer.

teststat(force: bool = False) → dict[float | IndexType, float][source]#

Retrieves the BSADF test statistic.

Parameters:

force (bool, optional) – If True, forces recalculation.

Returns:

teststat – Test statistics for each observation. If the object contains an index. It will be used as keys for the dictionary. Otherwise, the function returns the test statistic as a function of \(r_2\) in psytest.PSYBubbles.r2grid().

Return type:

dictionary with float keys and float values

Notes

The test statistic is defined as:

\[\text{BSADF}_{r_2} = \max_{r_1 \in [0, r_2 - r_0]} \text{ADF}(y_{r_1:r_2})\]

See the original paper for more details.

critval(alpha: float | list[float], fast: Literal[True]) → dict[float | IndexType, NDArray[float64]][source]#
critval(alpha: float | list[float], fast: Literal[False], nreps: int, nobs: int | None) → dict[float | IndexType, NDArray[float64]]

Retrieves BSADF critical values using Monte Carlo Simulations.

Parameters:

  • alpha (list[float] | float, optional) – Significance levels \(\alpha\). Defaults to ALPHA_LIST (see psytest.utils.defaults)

  • fast (bool, optional) – If True (Default), uses tabulated critical values. Otherwise, simulates them using nreps simulations of size nobs.

  • nreps (int, optional) – Number of simulations (required if fast is True).

  • nobs (int | None, optional) – Number of observations (used if fast is False). Defaults to None, setting it to psytest.PSYBubbles.nobs.

Returns:

critval – Dictionary with critical values for each \(r_2\) in psytest.PSYBubbles.r2grid(). The keys are the \(r_2\) values and the values are the critical values for the given significance level. If alpha is a list, the keys are the \(r_2\) values and the values are an array of critical values for each significance level. If alpha is a float, the keys are the \(r_2\) values and the values are the critical values for the given significance level.

Return type:

dict

Raises:

Notes

This function uses functools.lru_cache to cache the results for faster access. So after the first call, subsequent calls with the same parameters will utilize the cached results to reduce computation time.

find_bubbles(alpha: float, fast: Literal[True]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]#
find_bubbles(alpha: float, fast: Literal[False], nreps: int, nobs: int | None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Identifies the bubble periods in the time series.

Parameters:

  • alpha (float) – Significance level \(\alpha\). Defaults to 0.05.

  • fast (bool, optional) – If True (Default), uses tabulated critical values. Otherwise, simulates them using nreps simulations of size nobs.

  • nreps (int, optional) – Number of simulations (required if fast is True).

  • nobs (int | None, optional) – Number of observations (used if fast is False). Defaults to None, setting it to psytest.PSYBubbles.nobs.

Returns:

bubbles – Array with 2 columns. The first element contains the start time of the bubble, given by the index of the data. The second element contains the end time of the data. If the bubble has not ended by the end of the data, it is set to None.

Return type:

numpy.ndarray

Notes

The start of a bubble is defined as the point \(r_s\) where the test statistic exceeds the critical value:

\[\text{BSADF}_{r_s} > \text{CV}_{r_s, \alpha}\]

And the end of a bubble is defined as the point \(r_e > r_s\) where the test statistic falls below the critical value:

\[\text{BSADF}_{r_e} < \text{CV}_{r_e, \alpha}\]

Following the original paper, we require that the end period be at least \(\text{minlength}\) periods after the start period. Therefore, if a bubble start is detected at \(r_s\), but ends before \(r_s + \text{minlength}\), it is disregarded.

classmethod from_pandas(data: Series, minwindow: int | None = None, minlength: int | None = None, lagmax: int = 0, rstep: float | None = None) → PSYBubbles[source]#

Creates a PSYBubbles object from a pandas.Series.

Parameters:

  • data (pandas.Series of dtype numpy.float64) – Time series data.

  • minwindow (int | None, optional) – Minimum window size to calculate the test. Defaults to r0_default.

  • minlength (int | None, optional) – Minimum bubble length.

  • lagmax (int, optional) – Maximum lag \(k_{\max}\). Defaults to 0.

  • rstep (float | None, optional) – Step size \(r_{\text{step}}\). Defaults to \(1/n\).

Returns:

psybubbles – An instance of the PSYBubbles class with psytest.bubbles.PSYBubbles.index set to the provided pandas.Series.index.

Return type:

PSYBubbles

Raises:

TypeError – If data is not a pandas.Series or if data dtype is not of type numpy.float64.

Contents