Backtesting

backtest.sim(position) turns a table of what to hold each day into a full backtest report: the equity curve, risk figures and every trade. If you haven't written a position yet, start with Stock selection rules.

Run a backtest

from finlab import data
from finlab import backtest

data.set_market('us')
with data.us_universe(index='SP500'):
    close = data.get('price:adj_close')

# Hold the 20 S&P 500 stocks with the strongest 6-month return
position = (close / close.shift(126)).is_largest(20)

# Rebalance at each month end
report = backtest.sim(position, resample='M', name='S&P 500 momentum top 20')
report.display()

from finlab import data
from finlab import backtest

data.set_market('us_fund')
close = data.get('price:adj_close')
position = close[['SPY', 'QQQ']].pct_change(126).is_largest(1)

report = backtest.sim(position, resample='M', name='US ETF momentum')
report.display()

data.us_universe(index='SP500') uses today's S&P 500 members for the whole history, so past results are overstated (survivorship bias); see Historical index backtests for a point-in-time version.

report.display() draws this report; you can explore it right here:

When a backtest buys and sells

• Signal: a row of position uses only data published by that day. A financial statement is dated by its filing; volume and turnover after that day's close.
• Fill: trades fill on the next trading day after the signal, at trade_at_price, the close by default.
• Rebalancing: set by resample.

from finlab import data
from finlab.backtest import sim

data.set_market('us')
close = data.get('price:adj_close')
position = close > close.average(20)

report_daily = sim(position, name='Rebalance on any change')   # no resample
report_monthly = sim(position, resample='M', name='Monthly')

print(len(report_daily.get_trades()), report_daily.get_stats()['cagr'])
print(len(report_monthly.get_trades()), report_monthly.get_stats()['cagr'])

Hold stocks only when the market is up

To hold only in a bull market, combine the positions with a date-indexed True/False Series: on False dates the positions go to zero and sim() holds cash.

index = data.get('world_index:adj_close')
risk_on = (index > index.average(60))['^GSPC']
risk_on = risk_on.reindex(position.index, method='ffill').fillna(False).astype(bool)

filtered = position & risk_on
report = backtest.sim(filtered, resample='W', upload=False)

from finlab import data
from finlab.backtest import sim

sp500 = data.get('world_index:adj_close')['^GSPC']
timing = sp500 > sp500.rolling(20).mean()
position *= timing
report = sim(position, upload=False)   # no resample, so the timing applies daily

sim() needs at least one asset column and one date row. For an all-cash strategy, keep the assets and dates and set the positions to False or 0.

Read the report and every trade

report.get_stats() returns figures such as annual return, max drawdown and Sharpe ratio; report.get_trades() returns every trade:

report.get_trades()

How far each trade went for and against you (MAE/MFE)

report.display_mae_mfe_analysis()

Can it absorb more money (liquidity)

For US strategies, check capacity with dollar volume (price:adj_close × price:volume), or restrict the universe with etl:us_liquid_stock_filter (20-day average dollar volume above $1M). The built-in LiquidityAnalysis module covers the Taiwan market only. See Analysis modules for more.

Next period's holdings and when to rebalance

report.weights holds this period's target weights; report.next_weights the target for the next rebalance boundary, computed from the data available now. Before that boundary, next_weights and the rebalance enter/exit actions can change daily: they preview the next period and don't mean you should trade today.

Ask whether rebalancing is due instead of comparing dates yourself:

print(report.is_rebalance_due())   # True: rebalance is due
print(report.next_weights)
print(report.actions)

False means not yet. True only means the time has come; it doesn't guarantee fresh closing data or filled orders, so rerun sim() with current data when due. Check stop-loss and take-profit actions separately with report.is_stop_triggered().

Daily Taiwan strategies use the exchange trading calendar to set the rebalance window when a usable calendar is available. Run live PortfolioSyncManager.update() on every schedule, not only when rebalancing is due, so it can catch up on missed rebalances.

More examples

New highs

from finlab import data
from finlab import backtest

data.set_market('us')
with data.us_universe(index='SP500'):
    close = data.get('price:adj_close')

position = close == close.rolling(250).max()   # S&P 500 stocks at a 250-day high
report = backtest.sim(position, resample='M', name='S&P 500 new highs')
report.display()

The 20 highest RSI

from finlab import data
from finlab.backtest import sim

data.set_market('us')
with data.us_universe(index='SP500'):
    rsi = data.indicator('RSI')

position = rsi.is_largest(20)
report = sim(position, resample='W', name='High RSI strategy')   # weekly

Price momentum with a profitability filter

from finlab import data
from finlab.backtest import sim

data.set_market('us')
with data.us_universe(index='SP500'):
    close = data.get('price:adj_close')
    net_income = data.get('us_income_statement:net_income')
    equity = data.get('us_balance_sheet:total_stockholders_equity')

roe = net_income / equity   # quarterly ROE, aligned to each SEC filing date
position = (
    (close / close.shift(60)).is_largest(30)   # top 30 by 60-day price change
    & (roe > 0)                                 # positive ROE
)

report = sim(position, resample='M', name='Deviation + ROE filter')

Common problems

from finlab import data

data.set_market('us')
close = data.get('price:adj_close')
position = (close > 100) & (close < 110)

per_day = position.sum(axis=1)   # stocks qualifying each day
print(f'{per_day.mean():.2f} a day on average, at most {per_day.max()}')
print(f'days with a signal: {(per_day > 0).sum()} / {len(per_day)}')
print(f'stocks never held: {(position.sum(axis=0) == 0).sum()} / {len(position.columns)}')

ma20 = close.average(20)
position_fixed = (close > ma20).is_largest(30)   # always 30 stocks

from finlab import data
from finlab.backtest import sim

# 1. Start everything on the same date
data.truncate_start = '2020-01-01'   # backtest from 2020 only

data.set_market('us')
close = data.get('price:adj_close')
volume = data.get('price:volume')
print(close.index[0], close.index[-1], volume.index[0], volume.index[-1])

# 2. Align dates by hand
common_dates = close.index.intersection(volume.index)
close_aligned = close.loc[common_dates]
volume_aligned = volume.loc[common_dates]

# 3. Drop dates that are all NaN and treat the remaining NaN as not held
position = (close > close.average(20)) & (volume > 1000)
position_cleaned = position.dropna(how='all', axis=0).fillna(False)
report = sim(position_cleaned, resample='M')

missing = position.isna()
print(missing.sum().sum(), missing.all(axis=1).sum(), missing.all(axis=0).sum())   # total, empty dates, empty stocks

Next steps