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 |
price_returns ¶
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 |
forward_returns ¶
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.