TurningPointsResult#

class cultivars.spectral.cycles.TurningPointsResult(*, peaks, troughs, contraction, phases, window, min_phase, min_cycle, nobs)[source]#

A dated chronology: peaks, troughs, the contraction indicator, and the phase table.

A peak at \(t\) is a local maximum over \(\pm\texttt{window}\) observations, a trough a local minimum, with the two alternating and every phase at least min_phase and every cycle at least min_cycle observations long. Each completed phase from one turn to the next carries Harding and Pagan’s three numbers: its duration \(D\), its amplitude \(A = y_{\text{end}} - y_{\text{start}}\), and its excess

\[E = \frac{\displaystyle \int_{\text{start}}^{\text{end}} \bigl(y_t - \ell_t\bigr)\, dt}{\tfrac{1}{2} D\, |A|},\]

the area between the path and the straight line \(\ell\) joining its ends, relative to the triangle that line closes, positive when the path bows above the line. A contraction with positive excess fell fast and then flattened; an expansion with negative excess started slowly and accelerated.

Variables:

  • peaks – Indices of the peaks, in time order.

  • troughs – Indices of the troughs, in time order.

  • contraction – (T,) flags, True from the observation after a peak through the following trough. Before the first turn and after the last the state is carried from the nearest turn.

  • phases – One row per phase (start, end, is_contraction, duration, amplitude, excess): the change in the series over the phase, and Harding-Pagan’s excess – the area between the path and the straight line joining its ends, divided by the triangle’s area, positive when the path bows above the line.

  • window – Half-width of the local-extremum test.

  • min_phase – Shortest phase allowed.

  • min_cycle – Shortest peak-to-peak or trough-to-trough cycle allowed.

  • nobs – Observations.

Note

The chronology is a statement about the sample’s shape under the stated rules, not a test: no turn carries a p-value, and a turn near either end of the sample is provisional in the same way a Christiano-Fitzgerald cycle is, since the local-extremum window cannot look past the last observation. The first and last window observations can never be turns, so a series that ends mid-phase has that phase open and absent from phases, while contraction still carries the last known state to the end.

See also

  • TurningPoints – the producer, with the quarterly and monthly rule sets.

  • concordance() – the agreement of two chronologies, also reachable as concordance().

  • MSAR – the model-based alternative, whose smoothed regime probabilities this chronology can be compared against.

References

Harding, D., & Pagan, A. (2002). Dissecting the cycle: A methodological investigation. Journal of Monetary Economics, 49(2), 365-381.

Bry, G., & Boschan, C. (1971). Cyclical Analysis of Time Series: Selected Procedures and Computer Programs. NBER.

Example

A 24-period cycle on a slow upward trend; the quarterly rules find every turn, and the asymmetry of the trend shows in the amplitudes:

>>> import numpy as np
>>> t = np.arange(120.0)
>>> y = 0.01 * t + 0.5 * np.sin(2 * np.pi * t / 24)
>>> res = TurningPoints().date(y)
>>> res.peaks, res.troughs
(array([  6,  30,  54,  78, 102]), array([ 18,  42,  66,  90, 114]))
>>> res.n_cycles, res.nobs, float(res.contraction.mean())
(4, 120, 0.5)
>>> start, end, is_contraction, duration, amplitude, excess = res.phases[0]
>>> (start, end, is_contraction, duration), round(amplitude, 2), round(abs(excess), 3)
((6, 18, True, 12), -0.88, 0.0)
>>> res.concordance(np.roll(res.contraction, 6))
0.5

Attributes#

peaks

Indices of the peaks, ascending; a peak at t starts a contraction at t + 1.

troughs

Indices of the troughs, ascending; a trough at t starts an expansion at t + 1.

contraction

(T,) flags, True on every date in a contraction phase.

phases

Completed phases as (start, end, is_contraction, duration, amplitude, excess).

window

Half-width of the local-extremum test, in observations.

min_phase

Shortest phase the rules allowed, in observations.

min_cycle

Shortest peak-to-peak or trough-to-trough cycle the rules allowed.

nobs

Observations in the dated series, \(T\).

n_cycles

Completed peak-to-peak cycles, one fewer than the number of peaks.

Methods#

concordance(other)

Harding-Pagan concordance with another chronology.

summary()

The estimation summary, renderable as text, HTML, or a dataframe.