Skip to the page
GUIDES/RUN A SCENARIO

Run a scenario

A scenario is a set of changes to the economy or the market on given days, such as a liquidity crisis. Every target, operation and shape is in the reference, Scenarios. The code blocks on this page run in order in one Python session.

Load a scenario and read it

A scenario lists what happened to the market (its shocks) separately from what its author assumes that caused (its transmission). Read describe(), which prints the two under separate headings, before you run anything. tf.Scenario.available() names every scenario that ships.

import tradefloor as tf

crisis = tf.Scenario.load("liquidity_crisis")
print(crisis.describe())
SCENARIO  liquidity_crisis

A funding event with an earnings shock: quoted depth collapses to 40 per
cent and the VIX goes three-and-a-half-fold for twenty-five days, credit
widens 50 basis points, and earnings fall 15 per cent over two months
and recover over the next four. Volatility is then released back to the
endogenous chain, and depth is written back, because nothing in the
engine writes that column. Example experimental assumptions, not a
forecast.

Schema      v1
Fingerprint sha256:7d8c8cc86e74bf02bcf800b3733a774b18fcada9b44ec47d69e84014489f8461
Source      liquidity_crisis.yml

Exogenous shocks
----------------------------------------------------------
  day 50-74          market.liquidity         x0.4
  day 50-74          macro.vix                x3.5
  day 50..91 ramp    market.earnings          x0.85
  day 92..175 ramp   market.earnings          x1.17647

Assumed transmission
----------------------------------------------------------
  day 50-74          macro.corporate_yield    +0.50pp

The transmission entries are ASSUMPTIONS made by whoever wrote this
scenario. Nothing here derives them, and nothing here is a forecast of
how a real market would respond.

Days count from the day the scenario is first applied, which for tf.evaluate is the run's first day. This crisis starts on day 50, so a run has to be longer than 50 days to see it.

Score an agent with and without it

Run the agent on each seed with scenario= and without it. Both runs on a seed are the same market up to day 50, so the difference in P&L is what the scenario did to this agent.

market = tf.Universe.random(10, seed=101)

def score(seed, scenario=None):
    # buy-and-hold's P&L over 60 days, with the scenario or without it
    agents = {"buy_and_hold": tf.reference_agents(seed=3)["buy_and_hold"]}
    card = tf.evaluate(agents, seed=seed, universe=market, days=60,
                       scenario=scenario)["buy_and_hold"]
    return card.pnl

gaps = []
for seed in (1, 2, 3):
    calm, hit = score(seed), score(seed, crisis)
    gaps.append(hit - calm)
    print(f"seed {seed}: {calm:+10,.0f} without  {hit:+10,.0f} with  "
          f"{hit - calm:+10,.0f} difference")
print(f"mean difference {sum(gaps) / len(gaps):+,.0f}")
seed 1:    -42,974 without    -362,212 with    -319,238 difference
seed 2:    +70,956 without    -181,626 with    -252,583 difference
seed 3:     +3,558 without    -284,745 with    -288,303 difference
mean difference -286,708

Buy-and-hold trades on its first step only, so the thinner book costs it nothing and the difference is what prices did in the first ten days of the crisis. Three seeds show a direction but are too few to quote a size. For several agents across many seeds, pass scenario= to tf.rank, as in Compare strategies.

Write your own

A scenario built in Python takes shock for an event from outside the market and assume for an effect you are assuming it has. This one halves quoted depth for twenty days and assumes credit widens 150 basis points over the same days.

squeeze = (tf.Scenario(name="credit_squeeze")
           .shock("market.liquidity", operation="multiply", value=0.5,
                  at=10, duration=20)
           .assume("macro.corporate_yield", operation="add", value=0.015,
                   at=10, duration=20))
print(squeeze.fingerprint)
sha256:1022f79ec4d397f352f46ada50d3abfddd500b863a24b536fa3f7c8c01d7c848

The fingerprint is a sha256 of the resolved scenario, and a manifest records it with each run that used the scenario. Written in YAML, the scenario resolves to the same document and has the same fingerprint.

text = """
version: 1
scenario:
  name: credit_squeeze
  shocks:
    - target: market.liquidity
      operation: multiply
      value: 0.5
      at: 10
      duration: 20
  transmission:
    - target: macro.corporate_yield
      operation: add
      value: 0.015
      at: 10
      duration: 20
"""
print(tf.Scenario.from_yaml(text).fingerprint == squeeze.fingerprint)
True

Changing a value, a day or the order of two interventions changes the fingerprint. Comments, key order and formatting in the YAML do not. Pass squeeze as scenario= to run it, as with a shipped one.

Next steps