stratiq-backtest 0.3.0__tar.gz

stratiq_backtest-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StratIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stratiq_backtest-0.3.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: stratiq-backtest
+Version: 0.3.0
+Summary: A tiny, honest backtesting engine: long-only signal backtests with full trade logs and buy-and-hold comparison.
+Author: StratIQ
+License: MIT
+Project-URL: Homepage, https://stratiqai.app/track-record
+Project-URL: Repository, https://github.com/germygrimes/stratiq-backtest
+Keywords: backtest,trading,quant,systematic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stratiq-backtest
+
+A tiny, honest backtesting engine. Long-only signal backtests with full trade logs — and every result shown next to the do-nothing alternative, because a strategy that beats nothing is a hobby.
+
+This is the engine behind [StratIQ's public track record](https://stratiqai.app/track-record), where every backtest is published with wins and losses.
+
+## Install
+
+```bash
+pip install stratiq-backtest
+```
+
+Or from source: `pip install .` — zero dependencies, stdlib only.
+
+## Quickstart
+
+```python
+from stratiq_backtest import CrossoverStrategy, run, summarize, synthetic_bars
+
+data = synthetic_bars(n=1500, seed=42)   # reproducible demo data (NOT real market data)
+strat = CrossoverStrategy(fast=50, slow=200)   # golden cross
+result = run(data, strat, warmup=strat.warmup)
+stats = summarize(data, result)
+
+print(stats["strategy_total_return_pct"], "vs buy-and-hold",
+      stats["buyhold_total_return_pct"])
+for t in stats["trades"]:
+    print(t)
+```
+
+Run the bundled example (golden cross on synthetic data):
+
+```bash
+python3 examples/golden_cross_synthetic.py
+```
+
+## Execution semantics (read this before trusting a number)
+
+- **Trades print at the close of the bar that generates the signal.** The strategy sees bar *i*'s close; the trade executes at bar *i*'s close.
+- **No look-ahead, ever.** A position entered on bar *i* does **not** earn bar *i*'s return — that move already happened before the trade printed. It starts earning on bar *i+1*. A position exited on bar *i* **does** earn bar *i*'s return (it was exposed during the bar, sold at its close).
+- Long-only, fully invested-or-cash. No leverage, no shorting. No commissions, no slippage, no taxes — real trading will do worse by roughly those costs.
+- Use dividend/split-adjusted closes or your returns will be wrong.
+
+> **Correction note (v0.2.0):** v0.1.0 credited each new position with the signal bar's own price move. That is look-ahead bias — the signal only exists after the bar closes — so v0.1.0 results were biased and unreliable, and must be re-run. (Note: "biased" does not always mean "overstated" — the old loop also dropped exit-bar returns, so on some datasets the corrected run comes out higher.) v0.2.0 fixes the execution timing and adds regression tests pinning the corrected behavior. If you published numbers computed with v0.1.0, re-run them.
+
+## Data
+
+The repo ships **no real market data**. `synthetic_bars()` generates a deterministic seeded random walk for examples and tests — reproducible forever, and clearly labeled synthetic. Never publish performance numbers computed on it as if they were real.
+
+For real data:
+- `fetch_yahoo(symbol)` — free daily bars from Yahoo Finance's chart API, adjusted close (dividend- and split-adjusted). Unofficial endpoint; fails loudly.
+- `fetch_stooq(symbol)` — free daily bars from Stooq, no API key. **Split-adjusted but NOT dividend-adjusted**: fine for experimenting, not for publishing numbers. (As of 2026-11 Stooq serves a JavaScript browser check to plain HTTP clients, so this path currently fails live; `fetch_yahoo` is the working one.)
+- `load_json()` / `load_csv()` — bring your own dividend/split-adjusted closes.
+
+## Use it inside your AI assistant (MCP)
+
+The engine ships an [MCP](https://modelcontextprotocol.io) server, so Claude, Claude Code, Cursor, and other MCP clients can backtest inside the conversation — every result arrives with buy-and-hold next to it, the full trade log, the data caveats, and a link to test your own rule.
+
+```bash
+python3 -m stratiq_backtest.mcp_server
+```
+
+MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "stratiq-backtest": {
+      "command": "stratiq-backtest-mcp"
+    }
+  }
+}
+```
+
+Tools:
+
+- `backtest_crossover` — `{ticker, fast=50, slow=200, start="2019-01-01"}`. Real daily bars via Yahoo Finance's adjusted-close series (dividend- and split-adjusted — the result carries its data caveats in the result).
+- `stratiq_track_record` — StratIQ's live graded record, fetched from stratiqai.app at call time. If the feed is unreachable it returns the page link and **no numbers** — a stale record is worse than none.
+
+## Write your own strategy
+
+```python
+from stratiq_backtest import Strategy
+
+class MyStrategy(Strategy):
+    def on_bar(self, i, data, position):
+        # i: current bar index, data.closes / data.dates available.
+        # Return 1 to be long, 0 for cash. The new position takes
+        # effect AFTER bar i's close (see execution semantics above).
+        ...
+```
+
+Warm up indicators with `warmup=` so signals only fire on fully-formed values.
+
+## Tests
+
+```bash
+python3 -m pytest tests/
+```
+
+Happy paths, failure modes, edge cases — including regression tests that pin the no-look-ahead contract above.

stratiq_backtest-0.3.0/README.md

@@ -0,0 +1,101 @@
+# stratiq-backtest
+
+A tiny, honest backtesting engine. Long-only signal backtests with full trade logs — and every result shown next to the do-nothing alternative, because a strategy that beats nothing is a hobby.
+
+This is the engine behind [StratIQ's public track record](https://stratiqai.app/track-record), where every backtest is published with wins and losses.
+
+## Install
+
+```bash
+pip install stratiq-backtest
+```
+
+Or from source: `pip install .` — zero dependencies, stdlib only.
+
+## Quickstart
+
+```python
+from stratiq_backtest import CrossoverStrategy, run, summarize, synthetic_bars
+
+data = synthetic_bars(n=1500, seed=42)   # reproducible demo data (NOT real market data)
+strat = CrossoverStrategy(fast=50, slow=200)   # golden cross
+result = run(data, strat, warmup=strat.warmup)
+stats = summarize(data, result)
+
+print(stats["strategy_total_return_pct"], "vs buy-and-hold",
+      stats["buyhold_total_return_pct"])
+for t in stats["trades"]:
+    print(t)
+```
+
+Run the bundled example (golden cross on synthetic data):
+
+```bash
+python3 examples/golden_cross_synthetic.py
+```
+
+## Execution semantics (read this before trusting a number)
+
+- **Trades print at the close of the bar that generates the signal.** The strategy sees bar *i*'s close; the trade executes at bar *i*'s close.
+- **No look-ahead, ever.** A position entered on bar *i* does **not** earn bar *i*'s return — that move already happened before the trade printed. It starts earning on bar *i+1*. A position exited on bar *i* **does** earn bar *i*'s return (it was exposed during the bar, sold at its close).
+- Long-only, fully invested-or-cash. No leverage, no shorting. No commissions, no slippage, no taxes — real trading will do worse by roughly those costs.
+- Use dividend/split-adjusted closes or your returns will be wrong.
+
+> **Correction note (v0.2.0):** v0.1.0 credited each new position with the signal bar's own price move. That is look-ahead bias — the signal only exists after the bar closes — so v0.1.0 results were biased and unreliable, and must be re-run. (Note: "biased" does not always mean "overstated" — the old loop also dropped exit-bar returns, so on some datasets the corrected run comes out higher.) v0.2.0 fixes the execution timing and adds regression tests pinning the corrected behavior. If you published numbers computed with v0.1.0, re-run them.
+
+## Data
+
+The repo ships **no real market data**. `synthetic_bars()` generates a deterministic seeded random walk for examples and tests — reproducible forever, and clearly labeled synthetic. Never publish performance numbers computed on it as if they were real.
+
+For real data:
+- `fetch_yahoo(symbol)` — free daily bars from Yahoo Finance's chart API, adjusted close (dividend- and split-adjusted). Unofficial endpoint; fails loudly.
+- `fetch_stooq(symbol)` — free daily bars from Stooq, no API key. **Split-adjusted but NOT dividend-adjusted**: fine for experimenting, not for publishing numbers. (As of 2026-11 Stooq serves a JavaScript browser check to plain HTTP clients, so this path currently fails live; `fetch_yahoo` is the working one.)
+- `load_json()` / `load_csv()` — bring your own dividend/split-adjusted closes.
+
+## Use it inside your AI assistant (MCP)
+
+The engine ships an [MCP](https://modelcontextprotocol.io) server, so Claude, Claude Code, Cursor, and other MCP clients can backtest inside the conversation — every result arrives with buy-and-hold next to it, the full trade log, the data caveats, and a link to test your own rule.
+
+```bash
+python3 -m stratiq_backtest.mcp_server
+```
+
+MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "stratiq-backtest": {
+      "command": "stratiq-backtest-mcp"
+    }
+  }
+}
+```
+
+Tools:
+
+- `backtest_crossover` — `{ticker, fast=50, slow=200, start="2019-01-01"}`. Real daily bars via Yahoo Finance's adjusted-close series (dividend- and split-adjusted — the result carries its data caveats in the result).
+- `stratiq_track_record` — StratIQ's live graded record, fetched from stratiqai.app at call time. If the feed is unreachable it returns the page link and **no numbers** — a stale record is worse than none.
+
+## Write your own strategy
+
+```python
+from stratiq_backtest import Strategy
+
+class MyStrategy(Strategy):
+    def on_bar(self, i, data, position):
+        # i: current bar index, data.closes / data.dates available.
+        # Return 1 to be long, 0 for cash. The new position takes
+        # effect AFTER bar i's close (see execution semantics above).
+        ...
+```
+
+Warm up indicators with `warmup=` so signals only fire on fully-formed values.
+
+## Tests
+
+```bash
+python3 -m pytest tests/
+```
+
+Happy paths, failure modes, edge cases — including regression tests that pin the no-look-ahead contract above.

stratiq_backtest-0.3.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stratiq-backtest"
+version = "0.3.0"
+description = "A tiny, honest backtesting engine: long-only signal backtests with full trade logs and buy-and-hold comparison."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "StratIQ" }]
+keywords = ["backtest", "trading", "quant", "systematic"]
+
+[project.scripts]
+stratiq-backtest-mcp = "stratiq_backtest.mcp_server:main"
+
+[project.urls]
+Homepage = "https://stratiqai.app/track-record"
+Repository = "https://github.com/germygrimes/stratiq-backtest"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stratiq_backtest*"]

stratiq_backtest-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stratiq_backtest-0.3.0/stratiq_backtest/__init__.py

@@ -0,0 +1,35 @@
+"""stratiq_backtest — a tiny, honest backtesting engine.
+
+Long-only signal backtests with full trade logs and a buy-and-hold
+comparison. No hidden assumptions: the methodology is documented in
+the README and every number the engine prints can be traced to a trade.
+"""
+
+from .backtest import BarData, BacktestResult, Strategy, Trade, run
+from .data import fetch_stooq, fetch_yahoo, load_csv, load_json
+from .indicators import atr_series, ema_series, rsi_series, sma
+from .stats import max_drawdown, summarize
+from .strategy import CrossoverStrategy
+from .synthetic import synthetic_bars
+
+__all__ = [
+    "BarData",
+    "BacktestResult",
+    "CrossoverStrategy",
+    "Strategy",
+    "Trade",
+    "atr_series",
+    "ema_series",
+    "fetch_stooq",
+    "fetch_yahoo",
+    "load_csv",
+    "load_json",
+    "max_drawdown",
+    "rsi_series",
+    "run",
+    "sma",
+    "summarize",
+    "synthetic_bars",
+]
+
+__version__ = "0.3.0"

stratiq_backtest-0.3.0/stratiq_backtest/backtest.py

@@ -0,0 +1,130 @@
+"""Core backtest loop.
+
+Methodology (documented so every number is auditable):
+- Long-only, fully invested-or-cash. No leverage, no shorting.
+- Trades execute AT the close of the bar that generates the signal:
+  the strategy sees bar i's close, the trade prints at bar i's close.
+- NO look-ahead: a position entered on bar i does NOT earn bar i's
+  return (that move already happened before the trade printed). It
+  starts earning on bar i+1. A position exited on bar i DOES earn
+  bar i's return (it was exposed during the bar, sold at its close).
+  NOTE: v0.1.0 credited the signal bar's own return to the new
+  position — that was a look-ahead error, fixed in v0.2.0.
+- No commissions, no slippage, no taxes are modeled. Real trading
+  will do worse than these numbers by roughly those costs.
+- Use dividend/split-adjusted closes or your returns will be wrong.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BarData:
+    dates: list  # ISO date strings, one per bar
+    closes: list  # floats, preferably dividend/split-adjusted
+
+    def __len__(self):
+        if len(self.dates) != len(self.closes):
+            raise ValueError("dates and closes must be the same length")
+        return len(self.dates)
+
+
+@dataclass
+class Trade:
+    entry_date: str
+    entry: float
+    exit_date: str
+    exit: float
+    return_pct: float
+    open_at_end: bool = False
+
+
+@dataclass
+class BacktestResult:
+    trades: list = field(default_factory=list)
+    equity: list = field(default_factory=list)  # starts at 1.0, one entry per bar + 1
+    in_market_bars: int = 0
+    warmup: int = 0
+
+
+class Strategy:
+    """Decide the position after seeing bar i's close.
+
+    on_bar(i, data, position) -> new position (0 = cash, 1 = long).
+    The returned position takes effect after bar i's close (see the
+    no-look-ahead rule above). Strategies may keep state between bars;
+    reset() is called before each run.
+    """
+
+    def reset(self):
+        pass
+
+    def on_bar(self, i: int, data: BarData, position: int) -> int:
+        raise NotImplementedError
+
+
+def run(data: BarData, strategy: Strategy, warmup: int) -> BacktestResult:
+    """Run a backtest. Signals are evaluated from bar `warmup` onward."""
+    n = len(data)
+    if warmup < 1 or warmup >= n:
+        raise ValueError("warmup must be >= 1 and < len(data)")
+    strategy.reset()
+    closes, dates = data.closes, data.dates
+    position = 0
+    entry_px = entry_date = None
+    trades: list[Trade] = []
+    equity = [1.0]
+    in_market = 0
+
+    for i in range(n):
+        # 1) The position held DURING bar i earns bar i's return.
+        if position == 1:
+            in_market += 1
+            equity.append(equity[-1] * (closes[i] / closes[i - 1] if i > 0 else 1.0))
+        else:
+            equity.append(equity[-1])
+        # 2) Then the strategy reacts to bar i's close. A change takes
+        # effect after the close: an entry printed at closes[i] starts
+        # earning on bar i+1 (no look-ahead); an exit printed at
+        # closes[i] keeps the return already earned during bar i.
+        if i >= warmup:
+            want = strategy.on_bar(i, data, position)
+            if want not in (0, 1):
+                raise ValueError("strategy must return 0 (cash) or 1 (long)")
+            if want != position:
+                if want == 1:
+                    position = 1
+                    entry_px = closes[i]
+                    entry_date = dates[i]
+                else:
+                    ret = closes[i] / entry_px - 1
+                    trades.append(
+                        Trade(
+                            entry_date=entry_date,
+                            entry=round(entry_px, 2),
+                            exit_date=dates[i],
+                            exit=round(closes[i], 2),
+                            return_pct=round(ret * 100, 2),
+                        )
+                    )
+                    position = 0
+                    entry_px = entry_date = None
+
+    # Close any open position at the final close so equity is comparable.
+    if position == 1:
+        ret = closes[-1] / entry_px - 1
+        trades.append(
+            Trade(
+                entry_date=entry_date,
+                entry=round(entry_px, 2),
+                exit_date=dates[-1],
+                exit=round(closes[-1], 2),
+                return_pct=round(ret * 100, 2),
+                open_at_end=True,
+            )
+        )
+
+    return BacktestResult(
+        trades=trades, equity=equity, in_market_bars=in_market, warmup=warmup
+    )

stratiq_backtest-0.3.0/stratiq_backtest/data.py

@@ -0,0 +1,111 @@
+"""Data loading. Prefer dividend/split-adjusted closes — unadjusted
+data makes every backtest a lie about the past (dividends vanish)."""
+import csv
+import datetime
+import json
+import urllib.request
+
+from .backtest import BarData
+
+
+def load_json(path) -> BarData:
+    """Load {"dates": [...], "closes": [...]} or the compact
+    {"ts": [unix timestamps], "adj": [adjusted closes]} format."""
+    with open(path) as f:
+        d = json.load(f)
+    if "ts" in d and "adj" in d:
+        dates = [
+            datetime.datetime.fromtimestamp(t, datetime.UTC).date().isoformat()
+            for t in d["ts"]
+        ]
+        closes = [float(x) for x in d["adj"]]
+    elif "dates" in d and "closes" in d:
+        dates = list(d["dates"])
+        closes = [float(x) for x in d["closes"]]
+    else:
+        raise ValueError("JSON must have {dates, closes} or {ts, adj}")
+    return BarData(dates=dates, closes=closes)
+
+
+def load_csv(path, date_col="date", close_col="close") -> BarData:
+    """Load a CSV with a date column and a close column."""
+    dates, closes = [], []
+    with open(path, newline="") as f:
+        for row in csv.DictReader(f):
+            if not row.get(date_col) or not row.get(close_col):
+                continue
+            try:
+                px = float(row[close_col])
+            except ValueError:
+                continue  # e.g. Stooq "N/D" rows
+            dates.append(row[date_col][:10])
+            closes.append(px)
+    if not dates:
+        raise ValueError(f"no usable rows in {path}")
+    return BarData(dates=dates, closes=closes)
+
+
+def fetch_yahoo(symbol: str, start: str = "2019-01-01", end: str | None = None) -> BarData:
+    """Free daily bars from Yahoo Finance's chart API (no API key), using
+    the ADJUSTED close series — dividend- and split-adjusted, the only
+    honest basis for a long-window backtest. Unofficial endpoint: it can
+    rate-limit or change without notice, so callers must fail loudly."""
+    if end is None:
+        end = datetime.date.today().isoformat()
+    p1 = int(datetime.datetime.fromisoformat(start).replace(tzinfo=datetime.UTC).timestamp())
+    p2 = int(datetime.datetime.fromisoformat(end).replace(tzinfo=datetime.UTC).timestamp()) + 86400
+    url = (
+        "https://query1.finance.yahoo.com/v8/finance/chart/"
+        f"{symbol.upper()}?period1={p1}&period2={p2}&interval=1d&events=div,split"
+    )
+    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0 stratiq-backtest/0.3"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        payload = json.loads(r.read().decode("utf-8"))
+    result = (payload.get("chart") or {}).get("result") or []
+    if not result:
+        raise ValueError(f"no data returned for {symbol}")
+    result = result[0]
+    stamps = result.get("timestamp") or []
+    adj = ((result.get("indicators") or {}).get("adjclose") or [{}])[0].get("adjclose")
+    if adj is None:  # fall back to raw closes rather than nothing
+        adj = ((result.get("indicators") or {}).get("quote") or [{}])[0].get("close")
+    if not stamps or not adj:
+        raise ValueError(f"no price series returned for {symbol}")
+    dates, closes = [], []
+    for t, px in zip(stamps, adj):
+        if px is None:
+            continue
+        dates.append(datetime.datetime.fromtimestamp(t, datetime.UTC).date().isoformat())
+        closes.append(float(px))
+    if not dates:
+        raise ValueError(f"no usable bars returned for {symbol}")
+    return BarData(dates=dates, closes=closes)
+
+
+def fetch_stooq(symbol: str, start: str = "2019-01-01", end: str | None = None) -> BarData:
+    """Free daily bars from Stooq (no API key). NOTE: Stooq's free CSV is
+    split-adjusted but NOT dividend-adjusted — fine for experimenting,
+    not for publishing numbers. NOTE 2: as of 2026-11 Stooq serves a
+    JavaScript browser-verification challenge to plain HTTP clients, so
+    this fetch currently fails against the live site; fetch_yahoo is the
+    working free path."""
+    if end is None:
+        end = datetime.date.today().isoformat()
+    url = (
+        "https://stooq.com/q/d/l/?s="
+        f"{symbol.lower()}.us&d1={start.replace('-', '')}"
+        f"&d2={end.replace('-', '')}&i=d"
+    )
+    req = urllib.request.Request(url, headers={"User-Agent": "stratiq-backtest/0.1"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        text = r.read().decode("utf-8")
+    dates, closes = [], []
+    for line in text.strip().splitlines()[1:]:  # skip header
+        parts = line.split(",")
+        if len(parts) < 5 or parts[4] in ("", "N/D"):
+            continue
+        dates.append(parts[0])
+        closes.append(float(parts[4]))
+    if not dates:
+        raise ValueError(f"no data returned for {symbol}")
+    return BarData(dates=dates, closes=closes)

stratiq_backtest-0.3.0/stratiq_backtest/indicators.py

@@ -0,0 +1,82 @@
+"""Classic technical indicators. All functions use only data available
+at or before the bar they are evaluated on — no lookahead."""
+
+
+def sma(values, n, i):
+    """Simple moving average of the n values ending at index i (inclusive)."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if i - n + 1 < 0:
+        raise ValueError(f"not enough data: need {n} values ending at {i}")
+    return sum(values[i - n + 1 : i + 1]) / n
+
+
+def ema_series(values, n):
+    """Exponential moving average over the whole series (seeded with SMA)."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    k = 2 / (n + 1)
+    out = []
+    ema = None
+    for i, v in enumerate(values):
+        if i < n - 1:
+            out.append(None)
+        elif i == n - 1:
+            ema = sum(values[:n]) / n
+            out.append(ema)
+        else:
+            ema = v * k + ema * (1 - k)
+            out.append(ema)
+    return out
+
+
+def rsi_series(values, n=14):
+    """Relative Strength Index (Wilder's smoothing). None for the first n bars."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    out = [None] * len(values)
+    if len(values) <= n:
+        return out
+    gains, losses = [], []
+    for i in range(1, n + 1):
+        chg = values[i] - values[i - 1]
+        gains.append(max(chg, 0))
+        losses.append(max(-chg, 0))
+    avg_gain = sum(gains) / n
+    avg_loss = sum(losses) / n
+    for i in range(n, len(values)):
+        if i > n:
+            chg = values[i] - values[i - 1]
+            avg_gain = (avg_gain * (n - 1) + max(chg, 0)) / n
+            avg_loss = (avg_loss * (n - 1) + max(-chg, 0)) / n
+        if avg_loss == 0:
+            out[i] = 100.0
+        else:
+            rs = avg_gain / avg_loss
+            out[i] = 100 - 100 / (1 + rs)
+    return out
+
+
+def atr_series(highs, lows, closes, n=14):
+    """Average True Range (Wilder's smoothing). None for the first n bars."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if not (len(highs) == len(lows) == len(closes)):
+        raise ValueError("highs, lows, closes must be the same length")
+    out = [None] * len(closes)
+    if len(closes) <= n:
+        return out
+    trs = []
+    for i in range(1, len(closes)):
+        tr = max(
+            highs[i] - lows[i],
+            abs(highs[i] - closes[i - 1]),
+            abs(lows[i] - closes[i - 1]),
+        )
+        trs.append(tr)
+    atr = sum(trs[:n]) / n
+    out[n] = atr
+    for i in range(n + 1, len(closes)):
+        atr = (atr * (n - 1) + trs[i - 1]) / n
+        out[i] = atr
+    return out