{"record":{"id":"df46da1238d4cf8a","repo":"HKUDS/Vibe-Trading","slug":"delay-requires-n-1-lookahead-ban","errorCode":null,"errorMessage":"delay requires n >= 1 (lookahead ban)","messagePattern":"delay requires n >= 1 \\(lookahead ban\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"agent/src/factors/zoo/alpha101/alpha_008.py","lineNumber":62,"sourceCode":"    'extras_required': [],\n    'requires_sector': False,\n    'universe': ['equity_us', 'equity_in', 'equity_kr'],\n    'frequency': ['1D'],\n    'decay_horizon': 5,\n    'min_warmup_bars': 15,\n    'notes': '',\n}\n\n\ndef _rolling_sum(df: pd.DataFrame, n: int) -> pd.DataFrame:\n    \"\"\"Rolling window sum; warmup -> NaN.\"\"\"\n    return df.rolling(window=n, min_periods=n).sum()\n\n\ndef _delay(df: pd.DataFrame, n: int) -> pd.DataFrame:\n    \"\"\"Backward shift by n (lookahead-safe; n>=1 required).\"\"\"\n    if n < 1:\n        raise ValueError(\"delay requires n >= 1 (lookahead ban)\")\n    return df.shift(n)\n\n\ndef compute(panel: dict) -> pd.DataFrame:\n    \"\"\"Compute the alpha on the OHLCV+ panel and return a wide DataFrame.\"\"\"\n    close = panel[\"close\"]\n    open_ = panel[\"open\"]\n\n    returns = close.pct_change(fill_method=None)\n    # Helper aliases (local closures keep the file standalone & purity-safe).\n    rolling_sum = _rolling_sum\n    delay = _delay\n    s = rolling_sum(open_, 5) * rolling_sum(returns, 5)\n    out = -1.0 * rank(s - delay(s, 10))\n    return out\n","sourceCodeStart":44,"sourceCodeEnd":78,"githubUrl":"https://github.com/HKUDS/Vibe-Trading/blob/80ffdda44c5c4db0dd84d70e051cca591cea67df/agent/src/factors/zoo/alpha101/alpha_008.py#L44-L78","documentation":"Alpha101 factor helper _delay guards against lookahead bias: shifting a DataFrame backward by n<1 would leak future data into past rows, so n must be >= 1. The ValueError is raised eagerly before df.shift(n).","triggerScenarios":"compute in alpha_008 calling _delay(df, 0) or _delay(df, -1) — usually a formula transcription typo or parametrized delay computed as 0.","commonSituations":"Porting WorldQuant Alpha101 formulas where a delay term like (-1) appears; parameterized lookbacks that can degenerate to 0 in tests/sweeps.","solutions":["Fix the delay argument to a positive integer per the formula spec","If 0-lag is intended, use the input directly instead of _delay(df, 0)","Assert n>=1 in tests sweeping delay parameters"],"exampleFix":"# before\n_delay(close, -1)  # or 0\n# after\n_delay(close, 1)  # t-1 value, lookahead-safe","handlingStrategy":"validation","validationCode":"assert delay_n >= 1, 'lookahead ban'","typeGuard":"def valid_delay(n: int) -> bool:\n    return isinstance(n, int) and n >= 1","tryCatchPattern":null,"preventionTips":["Treat negative signs in Alpha101 formulas as rank-direction, not delay","Sweep-test delay params >=1"],"tags":["lookahead-bias","validation","alpha101"],"backgroundTag":"invalid-argument-value","analyzedSha":"80ffdda44c5c4db0dd84d70e051cca591cea67df","analyzedAt":"2026-08-28T12:46:38.989Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}