Module risk 

Risk metrics: volatility, Sharpe, Sortino, max drawdown, beta, rolling drawdown, Calmar, Ulcer index, correlation, information ratio, and trade-PnL helpers.

Which ratio when?

Metric	Question it answers	Needs
sharpe_ratio	Return per unit total vol	Return series + RF
sortino_ratio	Return per unit downside vol	Returns + target
calmar_ratio	CAGR per unit peak–trough pain	Price path + years
ulcer_index	How deep/persistent were drawdowns?	Prices
information_ratio	Active return per tracking error	Asset + benchmark returns
correlation	Do two series move together?	Paired series
win_rate / profit_factor / expectancy	Trade list quality	Per-trade PnL

Calmar is path-level (prices + time); Sharpe/Sortino are return-series. Do not mix without aligning sampling frequency.

Error handling (v0.1+)

All public functions return FinanceResult. Short series, zero sample vol, empty prices, and length mismatches yield structured FinanceError values.

Functions

beta

OLS beta of asset returns vs market returns (same length series).

cagr_from_prices

CAGR from a positive price path over years years: (end/start)^(1/years) − 1.

cagr_from_prices_periods

CAGR using (prices.len()−1) / periods_per_year as the year fraction.

calmar_ratio

Calmar ratio: CAGR / |max drawdown| on a positive price series.

calmar_ratio_periods

Calmar with year fraction from sample length and periods_per_year.

correlation

Pearson correlation of two equal-length series.

drawdown_series

Running drawdown series (one value per price, starting at 0).

expectancy

Expectancy: mean trade P&L (including zeros).

information_ratio

Information ratio: mean(active) / stdev(active) where active[i] = asset[i] − benchmark[i].

max_drawdown

Maximum peak-to-trough drawdown over a positive price series (most negative fraction).

price_volatility

Volatility of simple returns computed from consecutive prices.

profit_factor

Profit factor: sum(positive pnl) / |sum(negative pnl)|.

rolling_max_drawdown

Running maximum drawdown magnitude observed up to each price index.

sharpe_ratio

Sharpe ratio: (mean - risk_free) / volatility over the return series.

sortino_ratio

Sortino ratio: (mean - target) / downside_deviation, using returns below target only.

ulcer_index

Ulcer index: sqrt(mean of squared percentage drawdowns) (Martin).

volatility

Sample standard deviation of a return series (population divisor n - 1).

volatility_annualized

Annualized volatility: volatility(returns) * sqrt(periods_per_year).

win_rate

Win rate over a trade P&L series: count(pnl > 0) / n (zeros count as non-wins).