Plugin

VIX close

The daily Cboe VIX close from FRED as a feed, so a strategy can stand aside when volatility is high.

Data sourceNetwork: fred.stlouisfed.orgDesktop onlyv1.1.0

Get early access Plugin API documentation

About

The VIX is the market's expectation of 30 day volatility in the S&P 500, read from option prices. Many traders use it as a filter: no new positions while it is above a threshold, or smaller ones.

Before a run, the plugin downloads the series from FRED and writes the feed vix. Set another FRED series id to cache that series under the same feed name instead, for example VXNCLS for the Nasdaq 100 volatility index.

Configuration

Field	Type	Default	Description
`cache_days`Refetch after (days)	number	`1`	Days before the plugin downloads the series again. Within that time a run reads the cached feed and needs no network.
`series_id`FRED series id	string	`"VIXCLS"`	The FRED series to download, VIXCLS by default. Whatever it is, it is stored as the feed vix.

Use it in a strategy

pythonbars = ctx.bars(1)
if bars:
    vix = ctx.data("vix", bars[-1].ts)
    if vix is not None and vix > 30:
        ctx.signal("EXIT")

The feed is refreshed before a run whose strategy reads ctx.data, or when "Fetch external data (news and plugin feeds)" is ticked. A run on the server never fetches.

What it provides

vixFeed The close of the series, a number, under each day from the day after the first observation.

Data source and terms

Publisher	FRED, Federal Reserve Bank of St. Louis (series VIXCLS, data by Cboe)
Terms	Read the terms
API key	None needed
Attribution	Source: Cboe via FRED, Federal Reserve Bank of St. Louis
Rate limit	One download per refresh; FRED asks for moderate use.

Hosts it may reach: fred.stlouisfed.org

When values are known

A close is published after the market closes, so each value is stored under the next calendar day and carried forward over weekends and holidays, for at most 7 days. A bar on Monday reads Friday's close.

Limits

Daily closes only: an intraday strategy sees yesterday's VIX all day.
The VIX index data belongs to Cboe; FRED passes it on for personal use. The data stays on your machine.

Preview

json{
  "2024-03-02": 14.1,
  "2024-03-03": 14.1,
  "2024-03-04": 14.1,
  "2024-03-05": 14.6,
  "_meta": {
    "delay_rule": "next_day",
    "source": "Made-up sample, not vendor data",
    "terms": "https://fred.stlouisfed.org/legal/"
  }
}

A made-up sample that shows the shape of the output. Not vendor data and not a result.

The code

main.py, the file the app installs.

python"""VIX data plugin: a data source on the plugin kit.

Before a run (with external data fetching on) it downloads a FRED series, the
Cboe VIX close by default, and writes the feed "vix" that a strategy reads:

    def on_market(self, ctx):
        bars = ctx.bars(1)
        if not bars:
            return
        vix = ctx.data("vix", bars[-1].ts)
        if vix is not None and vix > 30:
            ctx.signal("EXIT")

A VIX close for a day is published after that day's close, so each value is
stored under the next day and carried forward over weekends and holidays: a
bar on Monday reads Friday's close, never Monday's. The download is skipped
while the feed is younger than cache_days, and a failed download leaves the
feed that was there.

The kit does the network (HTTPS to fred.stlouisfed.org only), the atomic
write and the day shift; this file is what is particular to the source.
"""

import re

from orionquant_engine.plugins.kit import feeds, net

HOSTS = ("fred.stlouisfed.org",)
FRED_CSV = "https://fred.stlouisfed.org/graph/fredgraph.csv"
FEED = "vix"
DELAY_RULE = "next_day"

_API = {"api": None}


def _log(message):
    if _API["api"] is not None:
        _API["api"].log(message)


def _config(key, default):
    api = _API["api"]
    return api.get_config(key, default) if api is not None else default


def parse(rows, series):
    """FRED's CSV rows to {observed day: value}. FRED marks a day without a
    value with "." and has named the date column DATE and observation_date."""
    out = {}
    for row in rows:
        cells = list(row.values())
        day = row.get("observation_date") or row.get("DATE") or (cells[0] if cells else "")
        raw = row.get(series)
        if raw is None and len(cells) > 1:
            raw = cells[1]
        if not day or raw in (None, "", "."):
            continue
        try:
            out[feeds.day_key(day)] = float(raw)
        except ValueError:
            continue
    return out


def data_fetch(context):
    """Lifecycle hook: refresh the feed before the backtest runs."""
    series = str(_config("series_id", "VIXCLS")).strip().upper()
    if not re.fullmatch(r"[A-Z0-9_]{1,40}", series):
        _log("series_id {!r} is not a FRED series id".format(series))
        return
    max_age = float(_config("cache_days", 1)) * 86400
    meta = feeds.read_meta(FEED) or {}
    if meta.get("series") == series and feeds.fresh(FEED, max_age):
        return
    try:
        rows = net.get_csv(FRED_CSV, hosts=HOSTS, params={"id": series})
    except net.NetError as exc:
        _log("fetch failed, the cached feed stays: {}".format(exc))
        return
    observed = parse(rows, series)
    if not observed:
        _log("FRED returned no values for {}, the cached feed stays".format(series))
        return
    known = feeds.shift(observed, DELAY_RULE)
    feeds.write_feed(
        FEED,
        feeds.fill_forward(known, until=feeds.today(), max_gap_days=7),
        meta={
            "source": "FRED, Federal Reserve Bank of St. Louis, series {}".format(series),
            "terms": "https://fred.stlouisfed.org/legal/",
            "delay_rule": DELAY_RULE,
            "series": series,
            "attribution": "Source: Cboe via FRED, Federal Reserve Bank of St. Louis",
        },
    )
    _log("cached {} {} values".format(len(observed), series))


def register(api):
    _API["api"] = api
    api.register_data_fetch(data_fetch)