Plugin

Central bank policy rates

Daily policy rates of the Fed, ECB, BoE, BoJ, SNB, BoC, RBA, RBNZ, Norges Bank and Riksbank, with the last change and the rate gap of your pair.

Data sourceNetwork: stats.bis.orgDesktop onlyv1.0.0

Get early access Plugin API documentation

About

The policy rate is the rate a central bank steers; it drives the carry of a currency pair and is the backdrop of most macro trades. The Bank for International Settlements collects the daily policy rates of central banks in one dataset, WS_CBPOL.

Before a run, the plugin downloads the rates of ten central banks and writes three feeds per currency: cbrate_usd (the rate in percent), cbrate_usd_days (days since the last change became known) and cbrate_usd_dir (1 when that change was a hike, -1 a cut). The currencies are usd (Fed), eur (ECB), gbp (Bank of England), jpy (Bank of Japan), chf (SNB), cad (Bank of Canada), aud (RBA), nzd (RBNZ), nok (Norges Bank) and sek (Riksbank).

When the run's instrument is a pair of two of these currencies, it also writes cbrate_gap_ plus the pair, for example cbrate_gap_audjpy: the base currency's rate minus the quote currency's, in percentage points. Positive means a long position in the pair earns the interest difference, before your broker's costs.

Configuration

Field	Type	Default	Description
`cache_days`Refetch after (days)	number	`1`	Days before the plugin downloads the rates again. Within that time a run reads the cached feeds and needs no network.

Use it in a strategy

pythonbars = ctx.bars(1)
if bars:
    gap = ctx.data("cbrate_gap_audjpy", bars[-1].ts)  # AUD rate minus JPY rate, in points
    if gap is not None and gap < 0:
        ctx.signal("EXIT")  # no carry left for a long AUDJPY

The gap feed exists for the pair of the run (here an AUDJPY run). The feeds are 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

`cbrate_<ccy>`Feed	The policy rate in percent per year for usd, eur, gbp, jpy, chf, cad, aud, nzd, nok and sek (cbrate_usd, cbrate_eur, ...), three business days after the day it applies.
`cbrate_<ccy>_days`Feed	Calendar days since the last change of that rate became known; starts at the first change in the data.
`cbrate_<ccy>_dir`Feed	The direction of that last change: 1 for a hike, -1 for a cut.
`cbrate_gap_<base><quote>`Feed	Only for a run on a pair of two covered currencies (AUDJPY gives cbrate_gap_audjpy): the base rate minus the quote rate in percentage points, on days both are known.

Data source and terms

Publisher	Bank for International Settlements, central bank policy rates (WS_CBPOL)
Terms	Read the terms
API key	None needed
Attribution	Source: BIS
Rate limit	One download of about 4 MB per refresh; the BIS publishes no limit.

Hosts it may reach: stats.bis.org

When values are known

The BIS dates a rate by the day it applies. Most changes are announced days earlier, but some took effect the morning they were announced (Bank of England on 11 March 2020, Bank of Canada on 4 March 2020), and the early history of some series is a market rate published the next business day. So each value is stored three business days after the day it applies and carried forward for at most 45 days: a change shows up a few days late, never early.

Limits

Not for trading the decision itself: a change appears days after the announcement. For the event, use the economic calendar (ctx.news_window).
The policy rate is not the swap or rollover your broker charges; the gap shows the direction and size of carry, not what a position would have earned.
Before a bank set a fixed policy rate, the BIS lists a market rate for some areas (the US effective federal funds rate in the early decades, for example); there it moves daily and the days and direction feeds mean little.
The BIS updates the dataset about weekly and some areas lag behind; a rate changed since the last update shows the old value until the BIS has it. The data stays on your machine; the BIS asks to be named as the source.

Preview

json{
  "2024-06-14": 4.25,
  "2024-06-15": 4.25,
  "2024-06-16": 4.25,
  "2024-06-17": 4,
  "_meta": {
    "delay_rule": "business_days:3",
    "source": "Made-up sample, not vendor data",
    "terms": "https://www.bis.org/terms_statistics.htm",
    "units": "percent per year"
  }
}

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"""Central bank policy rates: a data source on the plugin kit.

Before a run it downloads the daily policy rates of ten central banks from the
Bank for International Settlements (dataset WS_CBPOL) and writes, per currency:

    cbrate_usd         the policy rate in percent (Fed, ECB as eur, BoE as gbp, ...)
    cbrate_usd_days    days since the last change of that rate became known
    cbrate_usd_dir     direction of that change: 1 a hike, -1 a cut

and, when the run's instrument is a pair of two of these currencies, the rate
gap `cbrate_gap_<pair>` (base rate minus quote rate, in percentage points), the
carry a long position in the pair earns before costs:

    def on_market(self, ctx):
        bars = ctx.bars(1)
        if not bars:
            return
        gap = ctx.data("cbrate_gap_audjpy", bars[-1].ts)
        if gap is not None and gap < 0:
            ctx.signal("EXIT")       # no carry left for a long AUDJPY

When a value is known: the BIS dates a rate by the day it applies. Changes are
usually announced days before, but some take effect the morning they are
announced (the Bank of England on 11 March 2020, the Bank of Canada on 4 March
2020), and the early history of some series is a market rate published the next
business day. So each value is stored three business days after the day it
applies: conservative, a change shows up a few days late, never early.
"""

import json
import re

from orionquant_engine.plugins.kit import feeds, net

HOSTS = ("stats.bis.org",)
#: BIS area code to the currency the feeds are named by. XM is the euro area.
AREAS = {
    "AU": "AUD", "CA": "CAD", "CH": "CHF", "GB": "GBP", "JP": "JPY",
    "NO": "NOK", "NZ": "NZD", "SE": "SEK", "US": "USD", "XM": "EUR",
}
BIS_DATA = "https://stats.bis.org/api/v1/data/WS_CBPOL/D.{areas}/all"
ATTRIBUTION = "Source: BIS"
DELAY_RULE = "business_days:3"
#: The BIS updates the series about once a week and some areas lag by weeks. A
#: rate is carried at most this long past its last observation, so an area the
#: BIS stopped updating ends instead of showing an old rate for ever.
MAX_GAP_DAYS = 45

_PAIR = re.compile(r"^([A-Z]{3})/?([A-Z]{3})$")

_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 source_terms():
    """The BIS terms link from this plugin's docs.json, where the source is
    written down once. It is on www.bis.org, a host the plugin never fetches
    from, so it is not repeated here as a URL."""
    try:
        with open(__plugin_dir__ + "/docs.json", encoding="utf-8") as fh:  # noqa: F821  # set by the loader
            return json.load(fh)["sources"][0]["terms"]
    except (OSError, ValueError, KeyError, IndexError, NameError):
        return "BIS terms of use for statistics (see the plugin's docs)"


def feed_name(currency, suffix=""):
    return "cbrate_" + currency.lower() + suffix


def run_pair(instrument):
    """(base, quote) when the run's instrument is a pair of two covered
    currencies (AUDJPY, EUR/USD), else None."""
    m = _PAIR.fullmatch(str(instrument or "").strip().upper())
    covered = set(AREAS.values())
    if not m or m.group(1) == m.group(2) or not {m.group(1), m.group(2)} <= covered:
        return None
    return m.group(1), m.group(2)


def parse(rows):
    """The BIS CSV rows to {currency: {day the rate applies: rate}}. The BIS
    writes NaN on days without an observation (weekends for some areas)."""
    out = {}
    for row in rows:
        ccy = AREAS.get((row.get("REF_AREA") or "").strip().upper())
        day = (row.get("TIME_PERIOD") or "").strip()
        raw = (row.get("OBS_VALUE") or "").strip()
        if ccy is None or not day or raw in ("", "NaN"):
            continue
        try:
            out.setdefault(ccy, {})[feeds.day_key(day)] = float(raw)
        except ValueError:
            continue
    return out


def changes(daily):
    """From a filled daily feed {day: rate}, the two derived feeds: days since
    the last change and its direction. Both start at the first change in the
    data; before it nothing is known about a last change."""
    days_since, direction = {}, {}
    last_change, last_dir, prev = None, None, None
    for day in sorted(daily):
        rate = daily[day]
        if prev is not None and abs(rate - prev) > 1e-9:
            last_change, last_dir = feeds.as_date(day), (1 if rate > prev else -1)
        prev = rate
        if last_change is not None:
            days_since[day] = (feeds.as_date(day) - last_change).days
            direction[day] = last_dir
    return days_since, direction


def _meta(**extra):
    meta = {
        "source": "Bank for International Settlements, central bank policy rates (WS_CBPOL)",
        "terms": source_terms(),
        "delay_rule": DELAY_RULE,
        "attribution": ATTRIBUTION,
    }
    meta.update(extra)
    return meta


def write_gap(base, quote):
    """cbrate_gap_<base><quote>: the base rate minus the quote rate on every
    day both are known. Returns the number of days written."""
    a, b = feeds.read_feed(feed_name(base)), feeds.read_feed(feed_name(quote))
    rows = {day: round(a[day] - b[day], 6) for day in set(a) & set(b)}
    if not rows:
        _log("no policy rate feeds for {} and {}, so no gap".format(base, quote))
        return 0
    feeds.write_feed("cbrate_gap_" + (base + quote).lower(), rows, meta=_meta(
        units="percentage points, {} rate minus {} rate".format(base, quote)))
    return len(rows)


def data_fetch(context):
    """Lifecycle hook: refresh the feeds before the backtest runs."""
    pair = run_pair(getattr(context, "instrument", ""))
    gap_name = "cbrate_gap_" + "".join(pair).lower() if pair else None
    max_age = float(_config("cache_days", 1)) * 86400
    if feeds.fresh(feed_name("USD"), max_age):
        if gap_name and not feeds.exists(gap_name):
            write_gap(*pair)
        return

    url = BIS_DATA.format(areas="+".join(sorted(AREAS)))
    try:
        rows = net.get_csv(url, hosts=HOSTS, params={"format": "csv", "detail": "dataonly"}, timeout=120.0)
    except net.NetError as exc:
        _log("fetch failed, the cached feeds stay: {}".format(exc))
        return
    observed = parse(rows)
    if "USD" not in observed:
        _log("the BIS answer had no US policy rate, the cached feeds stay")
        return

    until = feeds.today()
    for ccy in sorted(observed):
        known = feeds.shift(observed[ccy], DELAY_RULE)
        daily = feeds.fill_forward(known, until=until, max_gap_days=MAX_GAP_DAYS)
        feeds.write_feed(feed_name(ccy), daily, meta=_meta(currency=ccy, units="percent per year"))
        days_since, direction = changes(daily)
        if days_since:
            feeds.write_feed(feed_name(ccy, "_days"), days_since, meta=_meta(currency=ccy, units="days"))
            feeds.write_feed(feed_name(ccy, "_dir"), direction, meta=_meta(currency=ccy, units="1 hike, -1 cut"))
    if gap_name:
        write_gap(*pair)
    _log("cached policy rates for {}".format(", ".join(sorted(observed))))


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