Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(quantlib): add multi-asset group-purged cross-validation splits

santhreale68f94185dcf
diff --git a/agent/src/quantlib/crossvalidation.py b/agent/src/quantlib/crossvalidation.py
index 0ce932bcb..8000f2fdb 100644
--- a/agent/src/quantlib/crossvalidation.py
+++ b/agent/src/quantlib/crossvalidation.py
@@ -52,6 +52,7 @@ __all__ = [
"Split",
"combinatorial_purged_splits",
"detect_boundary_leakage",
+ "group_purged_kfold_splits",
"purged_kfold_splits",
"purged_walk_forward_splits",
]
@@ -269,6 +270,91 @@ def purged_kfold_splits(
)
+
+def group_purged_kfold_splits(
+ groups: Sequence[object] | pd.Series | np.ndarray,
+ n_folds: int = 5,
+ embargo_fraction: float = DEFAULT_EMBARGO_FRACTION,
+) -> Iterator[Split]:
+ """Purged and embargoed K-fold cross-validation for panel and multi-asset datasets.
+
+ Groups all observations sharing a time group identifier (e.g. date or bar timestamp)
+ so that simultaneous observations across different assets are never split across
+ train and test partitions.
+
+ Args:
+ groups: Group identifiers (e.g. dates or bar index) for each sample row in order.
+ n_folds: Number of folds, at least :data:`MIN_FOLDS`.
+ embargo_fraction: Fraction of unique ordered groups embargoed after each test block.
+
+ Yields:
+ One :class:`Split` per fold, with ``train`` and ``test`` containing row indices.
+
+ Raises:
+ ValueError: If ``n_folds`` is invalid, fewer unique groups than folds exist,
+ or ``embargo_fraction`` is out of bounds.
+ """
+ if n_folds < MIN_FOLDS:
+ raise ValueError(f"n_folds must be at least {MIN_FOLDS}, got {n_folds}")
+ if not 0.0 <= embargo_fraction < 1.0:
+ raise ValueError(f"embargo_fraction must be in [0, 1), got {embargo_fraction}")
+
+ grp_array = np.asarray(groups)
+ n_samples = len(grp_array)
+ if n_samples == 0:
+ raise ValueError("groups array cannot be empty")
+
+ # Find unique groups preserving chronological order of appearance
+ unique_groups, first_indices = np.unique(grp_array, return_index=True)
+ # Sort by appearance order
+ order = np.argsort(first_indices)
+ unique_groups = unique_groups[order]
+ n_groups = len(unique_groups)
+
+ if n_groups < n_folds:
+ raise ValueError(f"{n_groups} unique groups cannot make {n_folds} folds")
+
+ # Map each group to its member row indices
+ group_to_rows: dict[object, np.ndarray] = {}
+ for idx, g in enumerate(grp_array):
+ group_to_rows.setdefault(g, []).append(idx)
+ for g in group_to_rows:
+ group_to_rows[g] = np.array(group_to_rows[g], dtype=int)
+
+ embargo_groups = int(round(n_groups * embargo_fraction))
+ boundaries = np.linspace(0, n_groups, n_folds + 1).astype(int)
+
+ for fold in range(n_folds):
+ start_g, stop_g = int(boundaries[fold]), int(boundaries[fold + 1])
+ if stop_g <= start_g:
+ continue
+
+ test_groups = set(unique_groups[start_g:stop_g])
+ embargo_end_g = min(n_groups, stop_g + embargo_groups)
+ embargo_groups_set = set(unique_groups[stop_g:embargo_end_g])
+
+ test_rows_list = [group_to_rows[g] for g in unique_groups[start_g:stop_g]]
+ test_rows = np.concatenate(test_rows_list) if test_rows_list else np.array([], dtype=int)
+
+ train_rows_list = []
+ for g in unique_groups:
+ if g not in test_groups and g not in embargo_groups_set:
+ train_rows_list.append(group_to_rows[g])
+
+ train_rows = np.concatenate(train_rows_list) if train_rows_list else np.array([], dtype=int)
+ train_rows.sort()
+ test_rows.sort()
+
+ embargoed_count = sum(len(group_to_rows[g]) for g in embargo_groups_set)
+
+ yield Split(
+ train=train_rows,
+ test=test_rows,
+ purged=0,
+ embargoed=embargoed_count,
+ test_bounds=(int(test_rows.min()), int(test_rows.max())),
+ )
+
def purged_walk_forward_splits(
n_samples: int,
label_end_times: pd.Series | Sequence[int] | np.ndarray | None = None,
diff --git a/agent/tests/quantlib/test_crossvalidation.py b/agent/tests/quantlib/test_crossvalidation.py
index 7c7cf1198..96893c024 100644
--- a/agent/tests/quantlib/test_crossvalidation.py
+++ b/agent/tests/quantlib/test_crossvalidation.py
@@ -17,6 +17,7 @@ from src.quantlib.crossvalidation import (
Split,
combinatorial_purged_splits,
detect_boundary_leakage,
+ group_purged_kfold_splits,
purged_kfold_splits,
purged_walk_forward_splits,
)
@@ -311,3 +312,44 @@ def test_purge_counts_are_reported_not_hidden():
for split in purged_kfold_splits(n, labels, n_folds=5):
removed = n - split.train.size - split.test.size
assert split.purged + split.embargoed == removed
+
+# --------------------------------------------------------------------------
+# group_purged_kfold_splits
+# --------------------------------------------------------------------------
+
+
+def test_group_purged_kfold_splits_prevents_cross_sectional_leakage():
+ # 10 assets x 100 dates = 1000 observations
+ n_dates = 100
+ n_assets = 10
+ dates = np.repeat(np.arange(n_dates), n_assets)
+
+ splits = list(group_purged_kfold_splits(dates, n_folds=5, embargo_fraction=0.05))
+ assert len(splits) == 5
+
+ for split in splits:
+ # 1. No shared row indices
+ assert len(np.intersect1d(split.train, split.test)) == 0
+
+ # 2. No shared dates between train and test
+ train_dates = set(dates[split.train])
+ test_dates = set(dates[split.test])
+ assert train_dates.intersection(test_dates) == set()
+
+ # 3. Exactly n_assets * number of test dates in test set
+ assert len(split.test) == len(test_dates) * n_assets
+
+ # 4. Embargo is applied to subsequent dates
+ test_max_date = max(test_dates)
+ embargo_expected_end = test_max_date + int(round(n_dates * 0.05))
+ for d in range(test_max_date + 1, min(n_dates, embargo_expected_end)):
+ assert d not in train_dates
+
+
+def test_group_purged_kfold_splits_input_validation():
+ with pytest.raises(ValueError, match="at least 2"):
+ list(group_purged_kfold_splits([1, 1, 2, 2], n_folds=1))
+ with pytest.raises(ValueError, match="cannot make 5 folds"):
+ list(group_purged_kfold_splits([1, 1, 2, 2], n_folds=5))
+ with pytest.raises(ValueError, match="groups array cannot be empty"):
+ list(group_purged_kfold_splits([], n_folds=2))