financial-timeseries

Files (1)

• SKILL.md

SKILL.md (first lines)

# Financial Time-Series

Rules and patterns for financial signal research and backtesting. Builds on
`python-style.instructions.md` and the canonical
[pandas skill](../pandas/SKILL.md) (datetime index, I/O, cleaning, gap filling,
timezones, version-safe APIs); follow those rules without restating them.
Patterns are inlined; external references
are [tensorflow-patterns.md](../../catalogs/tensorflow-patterns.md) and the
`statsforecast-prepare-frame` entry in [pandas-solutions.md](../../catalogs/pandas-solutions.md).

---

## General Rules

- Keep price series ascending with a `DatetimeIndex`; cast prices to `float64` before
  indicator libraries (TA-Lib requires doubles).
- Drop resample/indicator warm-up NaNs explicitly with `dropna()`; never fill them.
- Parameterize thresholds, windows, and periods as named constants — no magic numbers.
- Simple returns: `pct_change(fill_method=None)`; log returns (additive over time):
  `np.log(price).diff()`.
- EMA matching the `ta` library: `ewm(span=n, adjust=False, min_periods=n).mean()`
  (seeded with the first value). TA-Lib's EMA is SMA-seeded and converges to it after
  warm-up. The default `adjust=True` weighting differs from both.
- Custom rolling stats: prefer built-ins (`mean`, `std`, `ewm`); otherwise
  `rolling(n).apply(fn, raw=True)` so `fn` gets ndarrays, not Series.
- Annualization — state assumptions next to the constant:
  - Periods per year = trading days × bars per day: 252 days for exchange-traded
    equities, 365 for 24/7 markets (crypto); e.g. hourly crypto bars → 365 × 24.
  - `sqrt(N)` volatility scaling assumes i.i.d. returns; Sharpe assumes risk-free
    rate 0 unless excess returns are passed.
  - Mixed calendars (crypto + equities): align to the common calendar before joint stats.

---

## Look-Ahead Bias

A value used at bar `t` may depend only on data available at the close of bar `t`.

- Trade on the next bar: `strategy_ret = signal.shift(1) * returns`.
- `shift(-k)` only builds labels/targets — never features or signals.
- No `bfill()`, `interpolate()`, `rolling(..., center=True)`, or full-sample
  scaling in feature/backtest code — all read later values. This overrides the
  `pandas` skill's gap-filling `bfill` and `interpolate`, including the
  `reindex-interpolate-to-regular-grid` catalog entry: use `ffill()` instead.
  Fit scalers and models on the training span only.
- Right-labeled bars (`closed="right", label="right"`) are stamped at their close.
  Left-labeled bars contain data after their label — `shift(1)` before joining them
  to point-in-time data.
- Exclude a still-forming last bar from live decisions.

---

## OHLC Resampling

Use when a tick or 1-min price series must become OHLC bars.

- Anchor bins at the first observation (`origin="start"`), not the epoch default.
- Multi-asset: pass one shared `origin` timestamp so bar edges align across assets.

```python
def make_ohlc_resample(
    col: pd.Series, period: str = "10min", origin: str | pd.Timestamp = "start"
) -> pd.DataFrame:
    """Resample a price series into right-labeled OHLC bars plus hl2.

    Args:
        col: Ascending DatetimeIndex price series.
        period: Offset alias, e.g. "5min", "1h", "1D".
        origin: Bin anchor; "start" = first timestamp.

    Returns:
        DataFrame with open, high, low, close, hl2; empty bins dropped.
    """
    ohlc = col.resample(period, origin=origin, closed="right", label="right").ohlc()
    ohlc["hl2"] = (ohlc["high"] + ohlc["low"]) / 2
    return ohlc.dropna()


# One close column per asset on aligned bars (outer join; NaN where an asset has no bar):
start = df.index[0]
closes = pd.concat(
    {
        code: make_ohlc_resample(df[f"{code.lower()}_b"], "1D", origin=start)["close"]
        for code in ASSET_CODES
    },
    axis=1,
)
```

---

## Mean Resampling with Forward-Fill

Use when downsampling a non-OHLC price series with expected gaps.

```python
resampled = series.resample(target_freq, closed="left", label="left").mean().ffill()
```

- `ffill` carries the last valid price — valid for prices, not volumes or returns
  (fill those with 0 or leave NaN).
- Left labels stamp bars at their open; see [Look-Ahead Bias](#look-ahead-bias).

---

## Multi-Timeframe Sub-Sampling

Use to derive a coarser series from a fine one without another fetch.

- Anchor on the newest sample; sub-sampling forward from the start misaligns the
  newest bar with "now".

```python
def subsample_from_latest(series: pd.Series, step: int) -> pd.Series:
    """Every `step`-th value counting back from the newest, in chronological order."""
    return series.iloc[::-step].iloc[::-1]
```

---

From mabrosim/aet-content-pack, MIT.

More from mabrosim/aet-content-pack