Risk Dimensions

Calculations We Use rd_metrics v0.1

One source of truth so every analyst, notebook, and agent computes the same metric the same way. Each row is a calculation in the rd_metrics library. Cite rd_metrics v0.1 on any deliverable. Risk V2 (downside-only) is reality; V1 (total-vol) is kept for comparison.

V2 — reality V1 — comparison relative / vs benchmark

House conventions

Total return. Performance uses adjusted close / a total-return index, never raw price.

Inputs. Functions take periodic returns (decimal, 0.012 = 1.2%) unless the row says "prices".

Annualization. ppy = periods per year: 252 daily · 52 weekly · 12 monthly · 4 quarterly · 1 annual.

Rates. Risk-free rf and MAR (minimum acceptable return) are annual decimals, default 0.

Stats. Sample standard deviation (ddof=1). NaNs dropped (pairwise for two-series metrics).

Core — return & growth

Metric	What it means	Formula (essence)	Function
Periodic returns	Per-period return from a price / TR series	`p_t / p_{t-1} − 1` (or log)	`to_returns(prices, kind)`
Total return	Compounded return over the window	`∏(1+r) − 1`	`total_return(r)`
Annualized return	Geometric annual rate of the return stream	`(1+TR)^(ppy/n) − 1`	`ann_return(r, ppy)`
CAGR	Compound annual growth from a price series	`(last/first)^(ppy/(n−1)) − 1`	`cagr(prices, ppy)`

Risk — V2 (the real measures)

Metric	What it means	Formula (essence)	Function
Downside deviation	Annualized dispersion of shortfalls vs MAR — only bad moves count	`√(mean(min(r−MAR,0)²)) · √ppy`	`downside_deviation(r, mar, ppy)`	V2
Max drawdown	Worst peak-to-trough of the equity curve (negative)	`min(equity/peak − 1)`	`max_drawdown(r)`	V2
Sortino	Return per unit of bad vol	`mean(excess) / downside_dev · √ppy`	`sortino(r, mar, rf, ppy)`	V2
Calmar	Return per unit of worst pain	`ann_return / \|max_drawdown\|`	`calmar(r, ppy)`	V2

Risk — V1 (kept for comparison)

Metric	What it means	Formula (essence)	Function
Volatility	Annualized total volatility — treats up and down the same	`std(r, ddof=1) · √ppy`	`ann_vol(r, ppy)`	V1
Sharpe	Return per unit of total vol	`mean(excess)/std(excess) · √ppy`	`sharpe(r, rf, ppy)`	V1

Relative — vs a market or benchmark

Metric	What it means	Formula (essence)	Function
Correlation	Pearson correlation of two return streams	`corr(a, b)`	`correlation(a, b)`	rel
Beta	Sensitivity to a market series	`cov(asset, mkt) / var(mkt)`	`beta(r, market)`	rel
Alpha	Annualized CAPM excess over what beta predicts	`ann_ret − [rf + β(ann_ret_mkt − rf)]`	`alpha(r, market, rf, ppy)`	rel
Tracking error	Annualized std of active return (vs benchmark)	`std(r − bench) · √ppy`	`tracking_error(r, bench, ppy)`	rel
Information ratio	Active return per unit of tracking error	`mean(active)/std(active) · √ppy`	`information_ratio(r, bench, ppy)`	rel

Distribution shape

Metric	What it means	Formula (essence)	Function
Skew	Asymmetry of returns (sample skewness)	`bias-corrected`	`skew(r)`
Excess kurtosis	Tail heaviness (normal = 0)	`Fisher`	`kurtosis(r)`
Tear-sheet bundle	All of the above as one dict — the standard summary	—	`summary(r, rf, mar, ppy)`

How to use it

Point Claude or any agent at rd_metrics.sortino() instead of letting it freelance a formula. One import, every calculation house-standard:

import rd_metrics as m

s = m.summary(returns, ppy=252)     # full tear sheet
m.sortino(returns, mar=0.0)         # one metric
m.cagr(prices, ppy=252)             # from a price series

Why this exists

Uniformity — everyone computes Sortino the same way. Auditable trail — versioned, tested calcs any deliverable can cite. Agent-ready — a named function beats a re-derived formula. The framing (Risk V1 vs V2, good vol vs bad vol) is in docs/first_principles.md.

Risk Dimensions · rd_metrics v0.1 · source lib/rd_metrics/ · tests test_rd_metrics.py (all pass) · glossary docs/rd_metrics_glossary.md