finlab.backtest

finlab.backtest runs your position signal (a True/False table of which stocks to hold each day) through historical data and returns the equity curve, performance metrics and every trade. Use it to validate entry and exit logic and to evaluate annual return and drawdown; combine it with finlab.optimize to test parameter combinations or compare strategies.

Which function to use

Backtest a position signal

sim()

Simulates the equity curve of a position history and returns a backtest Report; report.display() draws it.

from finlab import data
from finlab.backtest import sim

# Load U.S. adjusted closing prices
data.set_market('us')
close = data.get('price:adj_close')

# Strategy logic: price breaks above 20-day moving average
ma20 = close.average(20)
position = close > ma20

# Backtest (monthly rebalancing, 10% max per stock)
report = sim(
    position,
    resample='M',  # Monthly rebalancing
    position_limit=0.1,  # 10% max weight per stock
)

# Display performance report
report.display()

sim() signals are always "generated today, executed tomorrow": each row's date is the day that data was available to you, and trade_at_price sets which price fills the next day. Every method on the report is in finlab.report.

end_date, metrics_only, notification_enable and line_access_token are keyword-only. Returns a Report, or a Metrics object when metrics_only=True.

Common parameter combinations

These continue from position, close and ma20 above.

Rebalance monthly (suits passive investors)

report = sim(
    position,
    resample='M',  # Monthly rebalancing
    position_limit=0.1,  # 10% max per stock
    upload=True,  # Upload to cloud (local runs do not upload by default)
)

Rebalance weekly (suits active investors)

report = sim(
    position,
    resample='W',  # Weekly rebalancing
    position_limit=0.05,  # 5% max per stock (diversified)
    trade_at_price='open',  # Trade at open price (more conservative)
)

Add a stop-loss and take-profit

Set them in sim() directly, or use hold_until() for more flexible exit rules:

# Method 1: Set in sim()
report = sim(
    position,
    resample='M',
    stop_loss=0.1,  # 10% stop-loss
    take_profit=0.2,  # 20% take-profit
)

# Method 2: Use hold_until() for more flexibility
exit_condition = close < ma20  # Exit when price drops below MA
position_with_exit = position.hold_until(
    exit=exit_condition,
    stop_loss=0.1,  # 10% stop-loss
    take_profit=0.2,  # 20% take-profit
)
report = sim(position_with_exit, resample='M')

Rebalance timing and stop basis

resample=None (the default) is not a fixed daily rebalance: whenever any symbol's row in position differs from the previous row, the whole portfolio is reallocated to the new row, so it rebalances every day only if position changes every day.

retain_cost_when_rebalance decides how stop-loss/take-profit is measured for symbols that stay held on the day a rebalance is executed:

• False (default): every holding's stop-loss/take-profit basis resets to that day's price, including symbols that stay held; the trail_stop peak and the trail_stop_activation state are recalculated too.
• True: symbols held in the same direction keep their original entry cost and peak; only new or reversed positions reset.

So with resample=None and the default False, another symbol entering or leaving also resets the stop line of a symbol you hold throughout. With stop_loss=0.15, position holding A every day, and close-price execution:

Under both settings A's return in report.trades is -19%: the reset changes the stop basis, not the trade return. With periodic settings such as resample='M', the same rule applies on every rebalance date.

stop_trading_next_period only decides whether a symbol exited by stop-loss/take-profit is bought back at the next rebalance; it does not affect whether symbols that stay held reset their basis.

Custom execution prices and portfolio valuation

For stock/ETF backtests, trade_at_price accepts a price name (such as 'close' or 'open') or a DataFrame of execution prices with dates as its index and stock IDs as columns. It determines trade fills; daily portfolio valuation and ordinary close-based stop checks (touched_exit=False) still use market.get_price('close', adj=True).

U.S. stocks and ETFs value holdings with us_price:adj_close / us_fund_price:adj_close, which include split and dividend adjustments, so dividend-paying ETFs such as SPY can use the default sim(position) directly; supplying custom prices is unnecessary to include those adjustments. Taiwan uses etl:adj_close the same way. This is an adjusted-price return convention, not a cash ledger simulating exact reinvestment of each cash dividend.

Custom execution prices must share the valuation prices' adjustment scale, as in this example using the U.S. position above:

data.set_market('us')
adj_close = data.get('price:adj_close')
report = sim(position, trade_at_price=adj_close, upload=False)

If only execution prices are doubled to adj_close * 2, the quantity bought is calculated at twice the price while holdings are valued on the original scale, distorting NAV. To use a custom price system, supply a custom Market with consistent execution, valuation and stop prices. With touched_exit=True, open, high and low prices must also share that scale.

Measure another engine's NAV

metrics_from_nav() accepts daily NAV from any engine or custom ledger and measures curve performance using the same definitions as sim(). Research/strategy management tools can register these results without rewriting the backtest:

import pandas as pd
from finlab.backtest import metrics_from_nav
from finlab.backtest.metrics import metrics_to_dict

nav = pd.Series([100, 102, 101], index=pd.date_range("2026-01-01", periods=3))
metrics = metrics_from_nav(nav)
print(metrics.annual_return(), metrics.sharpe_ratio(), metrics.max_drawdown())
print(metrics_to_dict(metrics))  # Non-finite measurements become None
print(metrics.provenance)  # Backend, period and observation count

Supply a numeric Series with a DatetimeIndex, at least two increasing dates, at most one observation per day, and finite positive values. Measurement uses the input's local calendar dates. The first value is normalized to 1; invalid rows are never sorted or dropped. NAV must include costs and neutralize deposits/withdrawals. Performance is not independently audited brokerage performance. The return value is standalone Metrics with curve-derived measurements; no Report, trade records, holdings or orders are created.

metrics_from_nav(nav) -> Metrics

Deploy any engine's program and required files with the existing ZIP deployment API. Put third-party dependencies in requirements.txt at the ZIP root and call metrics_from_nav after running the engine. Cloud Python, dependency and resource limits still apply:

python -m finlab cloud deploy external_nav --zip strategy.zip --entry-script main.py --time 09:30 --no-contest

This function does not create/upload a cloud Report or establish contest eligibility.

Common questions

report = sim(position, resample='M')
trades = report.get_trades()
if len(trades) == 0:
    print("Warning: Strategy has no trade records!")
    # Check entry frequency
    print(f"Average daily stocks in position: {position.sum(axis=1).mean():.1f}")
    print(f"Maximum stocks in position: {position.sum(axis=1).max()}")

data.truncate_start = '2020-01-01'  # Only backtest data after 2020
report = sim(position, resample='M')

report = sim(position)  # resample=None rebalances on any position change
report = sim(position, resample='M')  # Monthly rebalancing

report = sim(
    position,
    resample='M',
    fee_ratio=0.0005,  # 0.05% commission per trade
    tax_ratio=0,  # No transaction tax on U.S. stocks
)

position = (close > ma20).is_largest(30)  # Hold at most 30 stocks

# 1. Use a longer rebalancing period
report = sim(position, resample='Q')  # Quarterly rebalancing (3x faster than monthly)

# 2. Shorten backtest period
data.truncate_start = '2018-01-01'  # Only load data from 2018 onward

# 3. Reduce the number of stocks
position = (close > ma20).is_largest(50)  # Only test 50 stocks

Next steps

Source code is on GitHub; for worked examples, see the tests folder.