| Signature | Description | Parameters |
|---|---|---|
template<arithmetic T, typename I = unsigned long, std::size_t A = 0> struct HalfLifeVisitor; // --------------------------------- template<typename T, typename I = unsigned long, std::size_t A = 0> using half_life_v = HalfLifeVisitor<T, I, A>; |
This is a "single action visitor", meaning it is passed the whole data vector in one call and you must use the single_act_visit() interface. Half-life of mean reversion of a series (typically a pairs-trading spread, see PairsSpreadVisitor) in number of bars. It fits the discrete Ornstein-Uhlenbeck (AR(1)) model
s[t] = c + phi * s[t - 1] + e[t]
by OLS on s[t] - s[t - 1] = c + (phi - 1) * s[t - 1] + e[t] and the half-life is -ln(2) / ln(phi) for 0 < phi < 1. Note that this is the exact AR(1) half-life, not the -ln(2) / (phi - 1) approximation. If phi >= 1 the series does not mean revert and the half-life is +infinity. If phi <= 0 the series oscillates around its mean and the half-life is not defined (NaN).If roll_count is 0, one regression over the whole series is used and the same value is reported for every bar (full-sample, so look-ahead bias). Otherwise (must be >= 4), the regression is rolled over the trailing roll_count bars, ending at and including the current bar. The first result is available roll_count - 1 bars after the first valid value (e.g. the first available spread of PairsSpreadVisitor). NaN values are skipped (along with the pairs they are a part of). At least 3 valid (s[t - 1], s[t]) pairs are required, otherwise the result is NaN. get_result(): The half-life, in bars. +infinity when phi >= 1, NaN when phi <= 0 or when it cannot be estimated. get_ar_coefficient(): The estimated AR(1) coefficient phi for each bar. Use it if you want a different half-life definition, or to see how close the series is to a unit root.
explicit
HalfLifeVisitor(size_type roll_count = 0);
roll_count: Window length (in bars) of the regression. 0 (default) means one
regression over the whole series, with the same result on every bar.
Otherwise it must be at least 4 (that gives the minimum of 3 pairs)
and at most the column size.
|
T: Column data type. I: Index type. A: Memory alignment boundary for vectors. Default is system default alignment |
static void test_HalfLifeVisitor() { std::cout << "\nTesting HalfLifeVisitor{ } ..." << std::endl; const double nval = std::numeric_limits<double>::quiet_NaN(); auto near = [](double a, double b) -> bool { return (std::abs(a - b) < 0.000001); }; ULDataFrame df; StlVecType<unsigned long> idxvec(30); std::iota(idxvec.begin(), idxvec.end(), 0UL); // Noisy AR(1) with phi = 0.8. The expected values were calculated by an // independent brute force implementation of OLS. // StlVecType<double> s = { 1.5, 1.2412, 0.7608, 0.6339, 0.8502, -0.1982, 0.6836, 0.318, -0.0438, -0.5585, 0.0191, 0.3527, 0.9044, 1.1701, 1.0676, 1.0183, 1.2823, 0.587, 0.4467, 0.5483, 0.2123, 0.5307, 0.2485, 0.5352, 0.4985, 0.63, -0.2548, -0.634, 0.1651, 0.2211 }; StlVecType<double> s_nan = { 1.5, 1.2412, 0.7608, 0.6339, 0.8502, -0.1982, 0.6836, nval, nval, -0.5585, 0.0191, 0.3527, 0.9044, 1.1701, 1.0676, 1.0183, 1.2823, 0.587, 0.4467, 0.5483, 0.2123, 0.5307, 0.2485, 0.5352, 0.4985, 0.63, -0.2548, -0.634, 0.1651, 0.2211 }; StlVecType<double> half; // 64, 32, 16, ... exactly phi = 0.5 StlVecType<double> explosive; // 1.1 ^ t StlVecType<double> alternating; StlVecType<double> short_col { 1.0, 0.5, 0.25 }; for (int i = 0; i < 12; ++i) { half.push_back(64.0 * std::pow(0.5, i)); explosive.push_back(std::pow(1.1, i)); alternating.push_back((i % 2) ? -1.0 : 1.0); } df.load_data(std::move(idxvec), std::make_pair("s", s), std::make_pair("s_nan", s_nan)); // Full sample: The same value for every bar // { half_life_v<double> hl; df.single_act_visit<double>("s", hl); assert(hl.get_result().size() == 30); assert(hl.get_ar_coefficient().size() == 30); for (std::size_t i = 0; i < 30; ++i) { assert(near(hl.get_ar_coefficient()[i], 0.555125)); assert(near(hl.get_result()[i], 1.177694)); } half_life_v<double> hl_nan; df.single_act_visit<double>("s_nan", hl_nan); for (std::size_t i = 0; i < 30; ++i) { assert(near(hl_nan.get_ar_coefficient()[i], 0.496310)); assert(near(hl_nan.get_result()[i], 0.989428)); } } // Rolling. The first result is at index 12 - 1 = 11. // { half_life_v<double> hl { 12 }; df.single_act_visit<double>("s", hl); for (std::size_t i = 0; i < 11; ++i) { assert(std::isnan(hl.get_result()[i])); assert(std::isnan(hl.get_ar_coefficient()[i])); } assert(near(hl.get_ar_coefficient()[11], 0.462109)); assert(near(hl.get_result()[11], 0.897912)); assert(near(hl.get_ar_coefficient()[14], 0.488436)); assert(near(hl.get_result()[14], 0.967344)); assert(near(hl.get_ar_coefficient()[20], 0.546849)); assert(near(hl.get_result()[20], 1.148389)); assert(near(hl.get_ar_coefficient()[29], 0.347656)); assert(near(hl.get_result()[29], 0.656054)); // The same, but with a gap of two NaNs at indices 7 and 8. Windows // that don't include the gap are not affected. // half_life_v<double> hl_nan { 12 }; df.single_act_visit<double>("s_nan", hl_nan); for (std::size_t i = 0; i < 11; ++i) assert(std::isnan(hl_nan.get_result()[i])); assert(near(hl_nan.get_ar_coefficient()[11], 0.337889)); assert(near(hl_nan.get_result()[11], 0.638823)); assert(near(hl_nan.get_ar_coefficient()[14], 0.369196)); assert(near(hl_nan.get_result()[14], 0.695633)); assert(near(hl_nan.get_result()[20], hl.get_result()[20])); assert(near(hl_nan.get_result()[29], hl.get_result()[29])); } // Exact cases // { ULDataFrame df_ex; StlVecType<unsigned long> idx12(12); std::iota(idx12.begin(), idx12.end(), 0UL); df_ex.load_data(std::move(idx12), std::make_pair("half", half), std::make_pair("explosive", explosive), std::make_pair("alternating", alternating)); // phi = 0.5 --> half-life of exactly 1 bar // half_life_v<double> hl_half; df_ex.single_act_visit<double>("half", hl_half); for (std::size_t i = 0; i < 12; ++i) { assert(std::abs(hl_half.get_ar_coefficient()[i] - 0.5) < 1e-9); assert(std::abs(hl_half.get_result()[i] - 1.0) < 1e-9); } half_life_v<double> hl_half_roll { 6 }; df_ex.single_act_visit<double>("half", hl_half_roll); for (std::size_t i = 0; i < 5; ++i) assert(std::isnan(hl_half_roll.get_result()[i])); for (std::size_t i = 5; i < 12; ++i) assert(std::abs(hl_half_roll.get_result()[i] - 1.0) < 1e-9); // phi >= 1: it doesn't mean revert // half_life_v<double> hl_exp; df_ex.single_act_visit<double>("explosive", hl_exp); for (std::size_t i = 0; i < 12; ++i) { assert(std::abs(hl_exp.get_ar_coefficient()[i] - 1.1) < 1e-9); assert(std::isinf(hl_exp.get_result()[i])); assert(hl_exp.get_result()[i] > 0); } // phi <= 0: Oscillating, half-life is not defined // half_life_v<double> hl_alt; df_ex.single_act_visit<double>("alternating", hl_alt); for (std::size_t i = 0; i < 12; ++i) { assert(std::abs(hl_alt.get_ar_coefficient()[i] + 1.0) < 1e-9); assert(std::isnan(hl_alt.get_result()[i])); } } // phi = 0.9 --> half-life = -ln(2) / ln(0.9) = 6.578813 // { ULDataFrame df_slow; StlVecType<unsigned long> idx(15); std::iota(idx.begin(), idx.end(), 0UL); df_slow.load_data(std::move(idx), std::make_pair("slow", StlVecType<double>{ 100.0, 90.0, 81.0, 72.9, 65.61, 59.049, 53.1441, 47.82969, 43.046721, 38.7420489, 34.86784401, 31.381059609, 28.2429536481, 25.41865828329, 22.876792454961 })); half_life_v<double> hl; df_slow.single_act_visit<double>("slow", hl); for (std::size_t i = 0; i < 15; ++i) { assert(std::abs(hl.get_ar_coefficient()[i] - 0.9) < 1e-9); assert(std::abs(hl.get_result()[i] - 6.578813478960585) < 1e-6); } } // Too few valid pairs: All NaN // { ULDataFrame df_few; df_few.load_data(StlVecType<unsigned long>{ 0, 1, 2, 3, 4, 5 }, std::make_pair("s", StlVecType<double>{ nval, nval, nval, nval, 1.0, 2.0 })); half_life_v<double> hl; df_few.single_act_visit<double>("s", hl); for (std::size_t i = 0; i < 6; ++i) assert(std::isnan(hl.get_result()[i])); } // Re-using a visitor must not leak the previous run // { half_life_v<double> hl { 12 }; df.single_act_visit<double>("s", hl); df.single_act_visit<double>("s_nan", hl); assert(hl.get_result().size() == 30); assert(near(hl.get_result()[14], 0.695633)); } #ifdef HMDF_SANITY_EXCEPTIONS { half_life_v<double> bad_roll { 3 }; half_life_v<double> big_roll { 31 }; bool thrown { false }; try { df.single_act_visit<double>("s", bad_roll); } catch (const DataFrameError &) { thrown = true; } assert(thrown); thrown = false; try { df.single_act_visit<double>("s", big_roll); } catch (const DataFrameError &) { thrown = true; } assert(thrown); // Column too short for the full-sample regression // ULDataFrame df_short; df_short.load_data(StlVecType<unsigned long>{ 0, 1, 2 }, std::make_pair("s", short_col)); half_life_v<double> hl; thrown = false; try { df_short.single_act_visit<double>("s", hl); } catch (const DataFrameError &) { thrown = true; } assert(thrown); } #endif // HMDF_SANITY_EXCEPTIONS }