| Signature | Description | Parameters |
|---|---|---|
template<arithmetic T, typename I = unsigned long, std::size_t A = 0> struct PairsSpreadVisitor; // --------------------------------- template<typename T, typename I = unsigned long, std::size_t A = 0> using pairs_spread_v = PairsSpreadVisitor<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. Pairs trading: hedge ratio, spread and spread z-score of two price series. The spread is spread[i] = A[i] - hedge_ratio[i] * B[i] - intercept[i], where A is the first column (the "dependent" asset) and B is the second column (the "independent" asset). The hedge ratio and the intercept come from an OLS regression of A on B. If hedge_roll_count is 0, one static regression over the whole series is used for every bar. Be aware that this is a full-sample estimate and it has look-ahead bias. If hedge_roll_count is > 0 (and must be >= 3), the regression is rolled over the trailing hedge_roll_count bars (ending at and including the current bar), so there is no look-ahead bias. The first hedge ratio is available at bar (first valid bar + hedge_roll_count - 1). The z-score is (spread[i] - mean) / stdev. If zscore_roll_count is 0, mean and stdev are those of the whole spread series (look-ahead bias again). Otherwise (must be >= 2), they are the trailing zscore_roll_count bars of the spread, ending at and including the current bar. The first z-score is available zscore_roll_count - 1 bars after the first available spread. So, with both rolling, the first z-score is at bar (first valid bar + hedge_roll_count + zscore_roll_count - 2). If log_prices is true, the regression and the spread are in terms of natural log of prices (non-positive prices become NaN). If biased is true, stdev uses n as its divisor, otherwise n - 1. NaN pairs are skipped in the regressions and the z-score statistics. The result is NaN wherever the spread, mean, stdev or the hedge ratio is not available, or when stdev is zero. get_result(): The z-score of the spread, (spread[i] - mean) / stdev. get_spread(): The spread, A[i] - hedge[i] * B[i] - intercept[i] (in log terms if log_prices is true). get_hedge_ratio(): The hedge ratio (the regression slope) for each bar. It is the same value on every bar when hedge_roll_count is 0. get_intercept(): The regression intercept for each bar. It is the same value on every bar when hedge_roll_count is 0.
explicit
PairsSpreadVisitor(size_type hedge_roll_count = 0,
size_type zscore_roll_count = 0,
bool log_prices = false,
bool biased = false);
hedge_roll_count: Window length (in bars) of the regression of A on B. 0 (default) means one static
regression over the whole series, used for every bar. Otherwise it must be at
least 3 and at most the column size. Longer windows give a more stable hedge
ratio but adapt more slowly to a changing relationship.
zscore_roll_count: Window length (in bars) used for the mean and standard deviation of the spread.
0 (default) means the mean and standard deviation of the whole spread series.
Otherwise it must be at least 2 and at most the column size. Shorter windows
make the z-score react to recent behavior; a common heuristic is to relate it
to the half-life of the spread (see HalfLifeVisitor).
log_prices: If true, regress and build the spread on natural logs of the prices. Default is false
(raw prices).
biased: If true, the standard deviation of the spread uses n as its divisor (population).
If false (default), it uses n - 1 (sample).
|
T: Column data type. I: Index type. A: Memory alignment boundary for vectors. Default is system default alignment |
static void test_PairsSpreadVisitor() { std::cout << "\nTesting PairsSpreadVisitor{ } ..." << 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(20); std::iota(idxvec.begin(), idxvec.end(), 0UL); // B is the independent asset and A is roughly 2 * B + 5 + mean reverting // noise. The expected values were calculated by an independent brute // force implementation of OLS and rolling statistics. // StlVecType<double> a = { 103.0966, 103.3874, 99.3161, 102.4687, 103.9124, 103.6243, 103.8741, 103.7796, 103.7974, 102.1705, 103.9823, 104.4696, 105.3045, 105.4812, 106.3169, 103.9437, 103.2873, 104.0997, 103.4713, 100.5303 }; StlVecType<double> b = { 49.0483, 49.3369, 47.0613, 48.7363, 49.5022, 49.1518, 48.7774, 49.142, 48.8208, 48.5497, 49.4138, 50.0315, 49.9545, 49.852, 50.0451, 49.3082, 48.8237, 49.4816, 49.3251, 47.6758 }; StlVecType<double> a_nan = { 103.0966, 103.3874, 99.3161, nval, 103.9124, 103.6243, 103.8741, 103.7796, 103.7974, 102.1705, 103.9823, 104.4696, 105.3045, 105.4812, 106.3169, nval, 103.2873, 104.0997, 103.4713, 100.5303 }; StlVecType<double> b_nan = { 49.0483, 49.3369, 47.0613, 48.7363, 49.5022, 49.1518, 48.7774, 49.142, 48.8208, nval, 49.4138, 50.0315, 49.9545, 49.852, 50.0451, nval, 48.8237, 49.4816, 49.3251, 47.6758 }; StlVecType<double> b_lead = { nval, nval, nval, nval, 49.5022, 49.1518, 48.7774, 49.142, 48.8208, 48.5497, 49.4138, 50.0315, 49.9545, 49.852, 50.0451, 49.3082, 48.8237, 49.4816, 49.3251, 47.6758 }; StlVecType<double> lin_a; StlVecType<double> lin_b; for (int i = 1; i <= 10; ++i) { lin_b.push_back(double(i)); lin_a.push_back(3.0 * double(i) + 1.0); } df.load_data(std::move(idxvec), std::make_pair("A", a), std::make_pair("B", b), std::make_pair("A_nan", a_nan), std::make_pair("B_nan", b_nan), std::make_pair("B_lead", b_lead)); // Static hedge ratio and static z-score // { pairs_spread_v<double> ps; df.single_act_visit<double, double>("A", "B", ps); assert(ps.get_result().size() == 20); assert(ps.get_spread().size() == 20); assert(ps.get_hedge_ratio().size() == 20); assert(ps.get_intercept().size() == 20); assert(near(ps.get_hedge_ratio()[0], 1.996802)); assert(near(ps.get_hedge_ratio()[19], 1.996802)); assert(near(ps.get_intercept()[0], 5.468905)); assert(near(ps.get_intercept()[19], 5.468905)); assert(near(ps.get_spread()[0], -0.312066)); assert(near(ps.get_spread()[11], -0.902322)); assert(near(ps.get_spread()[19], -0.137755)); assert(near(ps.get_result()[0], -0.617493)); assert(near(ps.get_result()[11], -1.785447)); assert(near(ps.get_result()[19], -0.272579)); } // Rolling hedge ratio (8) and rolling z-score (5). The first hedge ratio // is at index 7 and the first z-score is at index 7 + 5 - 1 = 11. // { pairs_spread_v<double> ps { 8, 5 }; df.single_act_visit<double, double>("A", "B", ps); assert(std::isnan(ps.get_hedge_ratio()[6])); assert(std::isnan(ps.get_spread()[6])); assert(near(ps.get_hedge_ratio()[7], 1.905081)); assert(near(ps.get_intercept()[7], 9.879607)); assert(near(ps.get_spread()[7], 0.280486)); assert(near(ps.get_hedge_ratio()[19], 2.239100)); assert(near(ps.get_intercept()[19], -6.351751)); assert(near(ps.get_spread()[19], 0.131157)); for (std::size_t i = 0; i < 11; ++i) assert(std::isnan(ps.get_result()[i])); assert(near(ps.get_result()[11], -0.527821)); assert(near(ps.get_result()[12], 0.694730)); assert(near(ps.get_result()[19], 0.653011)); // Chain the spread into the half-life visitor. The first spread is at // index 7, so the first half-life with a 12 bar window is at index // 7 + 12 - 1 = 18. // df.load_column("rolling_spread", std::move(ps.get_spread())); half_life_v<double> hl { 12 }; df.single_act_visit<double>("rolling_spread", hl); for (std::size_t i = 0; i < 18; ++i) assert(std::isnan(hl.get_result()[i])); assert(near(hl.get_ar_coefficient()[18], 0.129776)); assert(near(hl.get_result()[18], 0.339454)); assert(near(hl.get_ar_coefficient()[19], 0.062132)); assert(near(hl.get_result()[19], 0.249469)); } // Static hedge ratio and rolling z-score (6) // { pairs_spread_v<double> ps { 0, 6 }; df.single_act_visit<double, double>("A", "B", ps); assert(near(ps.get_hedge_ratio()[0], 1.996802)); assert(std::isnan(ps.get_result()[4])); assert(near(ps.get_result()[5], 1.413042)); assert(near(ps.get_result()[10], -0.815611)); assert(near(ps.get_result()[19], -0.436606)); } // Rolling hedge ratio (8) and static z-score // { pairs_spread_v<double> ps { 8, 0 }; df.single_act_visit<double, double>("A", "B", ps); assert(std::isnan(ps.get_result()[6])); assert(near(ps.get_result()[7], 0.312660)); assert(near(ps.get_result()[10], -0.486192)); assert(near(ps.get_result()[19], -0.038217)); } // Biased (population) standard deviation // { pairs_spread_v<double> ps { 8, 5, false, true }; df.single_act_visit<double, double>("A", "B", ps); assert(near(ps.get_result()[11], -0.590122)); assert(near(ps.get_result()[19], 0.730088)); } // Log prices // { pairs_spread_v<double> ps { 0, 0, true }; df.single_act_visit<double, double>("A", "B", ps); assert(near(ps.get_hedge_ratio()[0], 0.947184)); assert(near(ps.get_intercept()[0], 0.951478)); assert(near(ps.get_spread()[0], -0.003017)); assert(near(ps.get_result()[0], -0.621754)); assert(near(ps.get_result()[11], -1.769655)); assert(near(ps.get_result()[19], -0.276442)); } // NaNs in the middle: Pairs with a NaN are skipped // { pairs_spread_v<double> ps_stat; pairs_spread_v<double> ps_roll { 6, 4 }; df.single_act_visit<double, double>("A_nan", "B_nan", ps_stat); df.single_act_visit<double, double>("A_nan", "B_nan", ps_roll); assert(near(ps_stat.get_hedge_ratio()[0], 1.969178)); assert(near(ps_stat.get_intercept()[0], 6.858460)); assert(near(ps_stat.get_spread()[0], -0.346672)); assert(std::isnan(ps_stat.get_spread()[3])); assert(std::isnan(ps_stat.get_spread()[9])); assert(std::isnan(ps_stat.get_spread()[15])); assert(std::isnan(ps_stat.get_result()[3])); assert(near(ps_stat.get_result()[0], -0.641810)); assert(near(ps_stat.get_result()[11], -1.684295)); assert(near(ps_stat.get_result()[19], -0.389293)); assert(std::isnan(ps_roll.get_hedge_ratio()[4])); assert(near(ps_roll.get_hedge_ratio()[5], 1.888481)); assert(near(ps_roll.get_intercept()[5], 10.471512)); assert(std::isnan(ps_roll.get_spread()[9])); assert(near(ps_roll.get_spread()[19], 0.127604)); for (std::size_t i = 0; i < 8; ++i) assert(std::isnan(ps_roll.get_result()[i])); assert(near(ps_roll.get_result()[10], 1.106335)); assert(near(ps_roll.get_result()[19], 1.073855)); } // Leading NaNs: The first window starts at the first valid bar, so there // are no partially filled windows. First hedge ratio is at 4 + 5 - 1 = 8. // First spread is at 8 and first z-score is at 8 + 3 - 1 = 10. // { pairs_spread_v<double> ps { 5, 3 }; df.single_act_visit<double, double>("A", "B_lead", ps); for (std::size_t i = 0; i < 8; ++i) { assert(std::isnan(ps.get_hedge_ratio()[i])); assert(std::isnan(ps.get_spread()[i])); } for (std::size_t i = 0; i < 10; ++i) assert(std::isnan(ps.get_result()[i])); assert(near(ps.get_hedge_ratio()[8], 0.034140)); assert(near(ps.get_intercept()[8], 102.122009)); assert(near(ps.get_hedge_ratio()[9], 1.855644)); assert(near(ps.get_result()[10], 0.104707)); assert(near(ps.get_result()[11], 0.656370)); assert(near(ps.get_hedge_ratio()[19], 1.928733)); assert(near(ps.get_intercept()[19], 8.707309)); assert(near(ps.get_spread()[19], -0.130876)); assert(near(ps.get_result()[19], 1.130290)); } // Perfect linear relationship: A = 3 * B + 1 // { ULDataFrame df_lin; StlVecType<unsigned long> lin_idx(10); std::iota(lin_idx.begin(), lin_idx.end(), 0UL); df_lin.load_data(std::move(lin_idx), std::make_pair("A", lin_a), std::make_pair("B", lin_b)); pairs_spread_v<double> ps; df_lin.single_act_visit<double, double>("A", "B", ps); for (std::size_t i = 0; i < 10; ++i) { assert(std::abs(ps.get_hedge_ratio()[i] - 3.0) < 0.000000001); assert(std::abs(ps.get_intercept()[i] - 1.0) < 0.000000001); assert(std::abs(ps.get_spread()[i]) < 0.000000001); } // B constant: there is no slope // ULDataFrame df_flat; df_flat.load_data(StlVecType<unsigned long>{ 0, 1, 2, 3, 4 }, std::make_pair("A", StlVecType<double>{ 1, 2, 3, 4, 5 }), std::make_pair("B", StlVecType<double>{ 7, 7, 7, 7, 7 })); pairs_spread_v<double> ps_flat; df_flat.single_act_visit<double, double>("A", "B", ps_flat); for (std::size_t i = 0; i < 5; ++i) { assert(std::isnan(ps_flat.get_hedge_ratio()[i])); assert(std::isnan(ps_flat.get_spread()[i])); assert(std::isnan(ps_flat.get_result()[i])); } } // Re-using a visitor must not leak the previous run // { pairs_spread_v<double> ps; df.single_act_visit<double, double>("A", "B", ps); df.single_act_visit<double, double>("A_nan", "B_nan", ps); assert(ps.get_result().size() == 20); assert(near(ps.get_hedge_ratio()[0], 1.969178)); } #ifdef HMDF_SANITY_EXCEPTIONS { pairs_spread_v<double> bad_hedge { 2, 0 }; pairs_spread_v<double> big_hedge { 21, 0 }; pairs_spread_v<double> bad_z { 0, 1 }; bool thrown { false }; try { df.single_act_visit<double, double>("A", "B", bad_hedge); } catch (const DataFrameError &) { thrown = true; } assert(thrown); thrown = false; try { df.single_act_visit<double, double>("A", "B", big_hedge); } catch (const DataFrameError &) { thrown = true; } assert(thrown); thrown = false; try { df.single_act_visit<double, double>("A", "B", bad_z); } catch (const DataFrameError &) { thrown = true; } assert(thrown); } #endif // HMDF_SANITY_EXCEPTIONS }