HKUDS/Vibe-Trading · critical · ValueError

delay requires n >= 1 (lookahead ban)

Error message

delay requires n >= 1 (lookahead ban)

What it means

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).

Source

Thrown at agent/src/factors/zoo/alpha101/alpha_008.py:62

    'extras_required': [],
    'requires_sector': False,
    'universe': ['equity_us', 'equity_in', 'equity_kr'],
    'frequency': ['1D'],
    'decay_horizon': 5,
    'min_warmup_bars': 15,
    'notes': '',
}


def _rolling_sum(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling window sum; warmup -> NaN."""
    return df.rolling(window=n, min_periods=n).sum()


def _delay(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Backward shift by n (lookahead-safe; n>=1 required)."""
    if n < 1:
        raise ValueError("delay requires n >= 1 (lookahead ban)")
    return df.shift(n)


def compute(panel: dict) -> pd.DataFrame:
    """Compute the alpha on the OHLCV+ panel and return a wide DataFrame."""
    close = panel["close"]
    open_ = panel["open"]

    returns = close.pct_change(fill_method=None)
    # Helper aliases (local closures keep the file standalone & purity-safe).
    rolling_sum = _rolling_sum
    delay = _delay
    s = rolling_sum(open_, 5) * rolling_sum(returns, 5)
    out = -1.0 * rank(s - delay(s, 10))
    return out

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Fix the delay argument to a positive integer per the formula spec
2. If 0-lag is intended, use the input directly instead of _delay(df, 0)
3. Assert n>=1 in tests sweeping delay parameters

Example fix

# before
_delay(close, -1)  # or 0
# after
_delay(close, 1)  # t-1 value, lookahead-safe

assert delay_n >= 1, 'lookahead ban'

def valid_delay(n: int) -> bool:
    return isinstance(n, int) and n >= 1

When it happens

Trigger: compute in alpha_008 calling _delay(df, 0) or _delay(df, -1) — usually a formula transcription typo or parametrized delay computed as 0.

Common situations: Porting WorldQuant Alpha101 formulas where a delay term like (-1) appears; parameterized lookbacks that can degenerate to 0 in tests/sweeps.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• delay requires n >= 1 (lookahead ban)
• delay requires n >= 1 (lookahead ban)
• delay requires n >= 1 (lookahead ban)
• delay requires n >= 1 (lookahead ban)
• delay requires n >= 1 (lookahead ban)

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/df46da1238d4cf8a. Report an issue: GitHub.