Skip to content

Books

A signal says which stocks look good and bad. A book is the weights you would actually hold: restricted to a universe, traded with a delay, neutral to the market or to sectors, scaled to a fixed size and capped per stock. build_book turns one into the other; Backtest uses it when given BookSettings.

Book settings

BookSettings and build_book turn a signal into the book Finding Alphas and WorldQuant BRAIN simulate: restricted to a universe, delayed, neutralized, scaled to a gross of one and truncated.

from qex import qex, BookSettings, build_book

settings = BookSettings(delay=1, universe='member', neutralize='market', truncation=0.05)
w = build_book(qex("rank(-returns(5))"), data, settings)
Setting Default Description
delay 1 Day t's weights use data up to day t − delay
universe None A universe: a field's name, a mask, or a universe expression (Universes from Python); None is every name with a price
neutralize "market" "market", a group field such as "sector", or None
truncation 0.05 Largest absolute weight of one name, as a fraction of the book; None for no cap
rounds 1000 Most neutralize, scale and clip rounds per day
mask_cross_section True With a universe, cross-sectional operators in the signal compare only the day's universe (details); False applies the universe to the finished signal only, as before 0.5

Untradable names

A name with no close that day can't be traded. Backtest holds its previous weight until it trades again, for at most MAX_PRICE_GAP (10) days, and then drops it (a delisting). hold_untradable applies the same rule to any weights:

from qex import hold_untradable, forward_returns

held = hold_untradable(w, data['close'])                 # what Backtest holds
pnl = (held * forward_returns(data['close']).reindex_like(held).fillna(0)).sum(axis=1)

Backtest books P&L daily, on forward_returns(close, 1). QuantileAnalysis measures forward_returns(close, holding_period). Both are NaN when the end price is missing, and measured from the last valid price when the start price is.

Book statistics

from qex import turnover, fitness, margin_bps

to = turnover(w)          # sum(|w_t - w_{t-1}|) each day
fitness(pnl, to)          # Sharpe * sqrt(|annual return| / max(mean turnover, 0.125))
margin_bps(pnl, to)       # total P&L / total traded, in basis points

Returns and forward returns

The returns behind every P&L and every forward-looking statistic follow one rule (Halts, Delistings and Gaps), and are available directly:

from qex import price_returns, forward_returns, MAX_PRICE_GAP

r = price_returns(data['close'], 5)       # what returns(5) gives: p[t] / p[last price at or before t-5] - 1
f = forward_returns(data['close'], 1)     # day t's return to day t+1, as Backtest books P&L

Both take max_gap (default MAX_PRICE_GAP, 10): the most rows a last price is carried over a gap.

Never compute returns with pandas' pct_change on prices: how it fills gaps changed between pandas 2 and 3.

API reference

BookSettings dataclass

Simulation settings for turning a signal into daily weights.

Attributes:

Name Type Description
delay int

Weights for day t use data up to day t - delay. Delay 1 trades at day t's close on what was known at day t-1's close; delay 0 trades at the same close the signal saw.

universe Optional[Union[str, Signal]]

Name of a data field that is 1 (or any finite value) for names in the universe that day and NaN otherwise, or a universe expression (qex text or a Signal) that is nonzero for a member, evaluated over every name (see qex.universe). None means every name with a price.

neutralize Optional[str]

"market" demeans across all names each day, a group field name (e.g. "sector") demeans within each group, None leaves the book unneutralized.

truncation Optional[float]

Largest absolute weight of any one name, as a fraction of the book. None means no cap.

rounds int

Neutralize, scale and clip are repeated, day by day, until all three hold, at most this many times (clipping alone breaks neutrality and book size). Most days need a few rounds; a heavy-tailed signal on a small cross-section can need a few hundred. A day still short of the cap after the last round is neutralized and scaled once more, so neutrality and book size always hold exactly and the cap is the one that may be exceeded, slightly.

mask_cross_section bool

With a universe set, the signal's cross-sectional operators (rank, zscore, demean, regression_neut, the group operators, ...) compare only the names in the universe that day and give NaN outside it, while time-series operators still see every name's full history (see qex.universe). False compares every name with data and applies the universe only to the finished signal, which reproduces books from before 0.5. Without a universe there is nothing to mask and it has no effect.

build_book

build_book(signal: Signal, data: Union[Dict[str, DataFrame], LazyData], settings: BookSettings = BookSettings(), start: Optional[DateLike] = None, end: Optional[DateLike] = None) -> pd.DataFrame

Daily weights of the book a signal implies under the given settings.

Each day the weights sum to zero (within each group, if neutralized by group), their absolute values sum to exactly one, and none exceeds the truncation. A day with no tradable names, or where the signal is flat, has all-zero weights. A name gets no weight on a day it has no close (it cannot be traded), is outside the universe as of the signal's date, or has no group under group neutralization. This is the target book; Backtest keeps a name's previous weight on days it has no close (see hold_untradable), since a halted position cannot be closed.

Parameters:

Name Type Description Default
signal Signal

The alpha signal.

required
data Union[Dict[str, DataFrame], LazyData]

Dict or LazyData with at least 'close', plus the universe and group fields the settings name.

required
settings BookSettings

Simulation settings.

BookSettings()
start Optional[DateLike]

Optional first date, applied after the delay.

None
end Optional[DateLike]

Optional last date, applied after the delay.

None

Returns:

Type Description
DataFrame

DataFrame of weights, dates by names.

hold_untradable

hold_untradable(weights: DataFrame, prices: DataFrame, max_gap: Optional[int] = None) -> pd.DataFrame

Weights a book can actually hold: a name with no price that day keeps yesterday's weight.

A name with no price cannot be traded (it is halted, or has delisted), so the position from the last day it had one is held, marked at its last price, until it trades again. Without this, a missing signal on a halt day would silently close the position at a price that doesn't exist, and the move across the halt would never reach PnL.

A position is held for at most max_gap days with no price (default qex.primitives.MAX_PRICE_GAP, the same limit price_returns uses to bridge a gap). After that it is dropped with no PnL for the missing move, as for a delisting with no delisting return. Names before their first price get no weight.

Days a name has a price are left as they are (NaN becomes 0). Because held weights are not rescaled, a day with a held name can have gross weight slightly above or below 1.

Parameters:

Name Type Description Default
weights DataFrame

Target weights, dates x names.

required
prices DataFrame

Prices ('close'); names and dates missing from it count as untradable.

required
max_gap Optional[int]

Most consecutive days with no price a position is held for.

None

Returns:

Type Description
DataFrame

Held weights, with the shape of weights.

price_returns

price_returns(prices, period: int = 1, max_gap: int = None)

Simple returns over period rows, bridging missing prices without inventing any.

The return on day t is p[t] / p[last valid at or before t - period] - 1, and NaN when p[t] is missing. So:

  • during a halt, and after a delisting, the return is NaN (no fake 0% days);
  • the day a halted name reopens carries the whole move since its last price;
  • daily returns compound exactly to the period-day return.

A price older than max_gap rows (default MAX_PRICE_GAP) no longer counts, so a name that comes back after a long suspension gets NaN, not one enormous return.

This replaces pct_change, whose handling of missing prices depends on the pandas version (pandas 2 carried prices forward and gave 0% returns; pandas 3 does not bridge gaps at all). This function gives the same answer on both.

Parameters:

Name Type Description Default
prices

DataFrame (dates x names) or Series (dates) of prices.

required
period int

Number of rows the return spans.

1
max_gap int

Most rows a last valid price may be carried forward.

None

Returns:

Type Description

Returns, with the same shape as prices.

forward_returns

forward_returns(prices, period: int = 1, max_gap: int = None)

Return from day t to day t + period: price_returns(prices, period).shift(-period).

Day t's value is p[t + period] / p[last valid at or before t] - 1, NaN when p[t + period] is missing. A position held through a halt therefore gets the whole gap move on the row before the reopen, and nothing on the halt days.