"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(quantlib): add multi-asset group-purged cross-validation splits
santhreale68f94185dcf
diff --git a/agent/src/quantlib/crossvalidation.py b/agent/src/quantlib/crossvalidation.pyindex 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.pyindex 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.sizeassert 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))