"""Portfolio construction: from signals or returns to weights, share targets and orders.
Pure functions over plain lists and dictionaries, so they work in a notebook, in a
model file's own environment (copy this module) and in an Agent's local tool.
- Weights: ``equal_weights``, ``inverse_volatility``, ``risk_parity``,
``minimum_variance`` (long only) and ``signal_weights`` (scale signals to a gross).
- Risk: ``volatility_target`` scales weights to a target annual volatility, and
``apply_limits`` caps each weight, the gross and the net exposure.
- Execution: ``target_shares`` turns weights into whole shares at given prices, and
``rebalance_orders`` lists the buys and sells that move holdings to the targets.
Money and prices are integers in ten-thousandths of a dollar, as everywhere in Market
Lab; returns are decimals per period.
"""
from __future__ import annotations
from math import sqrt
from typing import Dict, List, Mapping, Optional, Sequence
Weights = Dict[str, float]
def _covariance(returns: Mapping[str, Sequence[float]]) -> Dict[str, Dict[str, float]]:
names = list(returns)
length = min(len(returns[n]) for n in names)
if length < 2:
raise ValueError('need at least two returns per asset')
means = {n: sum(returns[n][:length]) / length for n in names}
return {
a: {
b: sum((returns[a][i] - means[a]) * (returns[b][i] - means[b]) for i in range(length))
/ (length - 1)
for b in names
}
for a in names
}
[docs]
def equal_weights(symbols: Sequence[str]) -> Weights:
"""1/n in each symbol."""
return {symbol: 1 / len(symbols) for symbol in symbols} if symbols else {}
[docs]
def inverse_volatility(returns: Mapping[str, Sequence[float]]) -> Weights:
"""Weights proportional to 1/volatility, summing to one."""
covariance = _covariance(returns)
inverse = {n: 1 / sqrt(covariance[n][n]) if covariance[n][n] > 0 else 0.0 for n in returns}
total = sum(inverse.values())
return {n: v / total for n, v in inverse.items()} if total else equal_weights(list(returns))
[docs]
def risk_parity(
returns: Mapping[str, Sequence[float]], *, iterations: int = 500, tolerance: float = 1e-10
) -> Weights:
"""Long-only weights where each asset contributes equally to portfolio variance.
Solved by the multiplicative fixed point w_i <- w_i * (1/n) / (w_i (Σw)_i / w'Σw),
started from inverse volatility.
"""
covariance = _covariance(returns)
names = list(returns)
weights = inverse_volatility(returns)
target = 1 / len(names)
for _ in range(iterations):
marginal = {a: sum(covariance[a][b] * weights[b] for b in names) for a in names}
variance = sum(weights[a] * marginal[a] for a in names)
if variance <= 0:
break
updated = {
a: (
weights[a] * sqrt(target / (weights[a] * marginal[a] / variance))
if weights[a] * marginal[a] > 0
else weights[a]
)
for a in names
}
total = sum(updated.values())
updated = {a: v / total for a, v in updated.items()}
if max(abs(updated[a] - weights[a]) for a in names) < tolerance:
return updated
weights = updated
return weights
[docs]
def minimum_variance(
returns: Mapping[str, Sequence[float]], *, iterations: int = 2000, step: Optional[float] = None
) -> Weights:
"""Long-only, fully invested minimum-variance weights by projected gradient descent."""
covariance = _covariance(returns)
names = list(returns)
weights = equal_weights(names)
largest = max(sum(abs(covariance[a][b]) for b in names) for a in names) or 1.0
rate = step if step is not None else 1 / largest
def project(values: Dict[str, float]) -> Dict[str, float]:
# Euclidean projection onto the simplex (weights >= 0 summing to one).
ordered = sorted(values.values(), reverse=True)
cumulative, theta = 0.0, 0.0
for index, value in enumerate(ordered, 1):
cumulative += value
candidate = (cumulative - 1) / index
if value - candidate > 0:
theta = candidate
return {a: max(v - theta, 0.0) for a, v in values.items()}
for _ in range(iterations):
gradient = {a: 2 * sum(covariance[a][b] * weights[b] for b in names) for a in names}
weights = project({a: weights[a] - rate * gradient[a] for a in names})
return weights
[docs]
def signal_weights(signals: Mapping[str, float], *, gross: float = 1.0) -> Weights:
"""Scale signals (any sign) so absolute weights sum to ``gross``; zeros stay zero."""
total = sum(abs(v) for v in signals.values())
return (
{s: gross * v / total for s, v in signals.items()} if total else dict.fromkeys(signals, 0.0)
)
[docs]
def portfolio_volatility(
weights: Mapping[str, float], returns: Mapping[str, Sequence[float]], periods_per_year: float
) -> float:
"""Annualised volatility of a weighted portfolio from per-period returns."""
covariance = _covariance({s: returns[s] for s in weights})
variance = sum(weights[a] * weights[b] * covariance[a][b] for a in weights for b in weights)
return sqrt(max(variance, 0.0) * periods_per_year)
[docs]
def volatility_target(
weights: Mapping[str, float],
returns: Mapping[str, Sequence[float]],
*,
target: float,
periods_per_year: float = 252,
max_leverage: float = 1.0,
) -> Weights:
"""Scale weights so the portfolio's annual volatility is ``target`` (capped leverage)."""
current = portfolio_volatility(weights, returns, periods_per_year)
if current <= 0:
return dict(weights)
gross = sum(abs(v) for v in weights.values())
scale = target / current
if gross * scale > max_leverage:
scale = max_leverage / gross
return {s: v * scale for s, v in weights.items()}
[docs]
def apply_limits(
weights: Mapping[str, float],
*,
max_weight: Optional[float] = None,
max_gross: Optional[float] = None,
max_net: Optional[float] = None,
) -> Weights:
"""Cap each absolute weight, then scale down to the gross and net limits."""
capped = {
s: (max(-max_weight, min(max_weight, v)) if max_weight is not None else v)
for s, v in weights.items()
}
gross = sum(abs(v) for v in capped.values())
if max_gross is not None and gross > max_gross:
capped = {s: v * max_gross / gross for s, v in capped.items()}
net = sum(capped.values())
if max_net is not None and abs(net) > max_net:
# Shrink the side that pushes the net beyond its limit.
side = 1 if net > 0 else -1
excess = abs(net) - max_net
exposure = sum(v for v in capped.values() if v * side > 0) * side
if exposure > 0:
factor = (exposure - excess) / exposure
capped = {s: v * factor if v * side > 0 else v for s, v in capped.items()}
return capped
[docs]
def target_shares(
weights: Mapping[str, float],
prices: Mapping[str, int],
equity: int,
*,
lot: int = 1,
) -> Dict[str, int]:
"""Whole shares (in multiples of ``lot``) closest below each weight of ``equity``."""
shares: Dict[str, int] = {}
for symbol, weight in weights.items():
price = prices[symbol]
if price <= 0:
raise ValueError(f'price of {symbol} must be positive')
raw = weight * equity / price
lots = int(abs(raw) // lot) * lot
shares[symbol] = lots if raw >= 0 else -lots
return shares
[docs]
def rebalance_orders(
current: Mapping[str, int],
target: Mapping[str, int],
*,
min_shares: int = 1,
) -> List[Dict[str, object]]:
"""Buys and sells that move ``current`` holdings to ``target``, sells first.
Each order is ``{'symbol', 'side', 'quantity'}``; changes smaller than
``min_shares`` are skipped to avoid paying costs for noise.
"""
orders = []
for symbol in sorted(set(current) | set(target)):
change = target.get(symbol, 0) - current.get(symbol, 0)
if abs(change) >= min_shares and change:
orders.append(
dict(symbol=symbol, side='buy' if change > 0 else 'sell', quantity=abs(change))
)
return sorted(orders, key=lambda order: order['side'] != 'sell')