Module stocks 

Ordered price-path analytics (equities or any positive price series).

Layers

Layer	API	Purpose
Scalars	simple_return, volatility, beta, …	One-off metrics
Solution	price_path_solution	Summary stats + formulas for a full path
Series	PricePathSolution::series	Period detail (return, wealth, drawdown)
Tables	PricePathSeries::print_table	Terminal / copy-paste output

Error handling (v0.1+)

Public scalars and price_path_solution return crate::FinanceResult. Empty series, non-positive prices, length mismatches, and zero volatility cases are structured crate::FinanceError values — not panics. Prefer composing with ? when prices come from users or external data.

Modules

path

Price-path analysis: solution struct, period series, and pretty tables.

returns

Simple and logarithmic returns from prices.

risk

Risk metrics: volatility, Sharpe, Sortino, max drawdown, beta, rolling drawdown.

Structs

PricePathOptions

Options for price_path_solution.

PricePathPeriod

One step between consecutive prices.

PricePathSeries

Period series for a price path. Derefs to [PricePathPeriod].

PricePathSolution

Full analysis of an ordered price path.

Enums

ReturnKind

Kind of return used for mean / vol / Sharpe on the path.

Functions

beta

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

cagr

Compound annual growth rate: (end / start)^(1/years) - 1.

drawdown_series

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

log_return

Logarithmic return: ln(p1 / p0). Requires strictly positive prices.

log_returns

Log returns for consecutive prices: length prices.len() - 1.

max_drawdown

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

mean_return

Arithmetic mean of a return series.

price_path_solution

Build a PricePathSolution summarizing returns, risk, and period detail for a price path.

price_volatility

Volatility of simple returns computed from consecutive prices.

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.

simple_return

Simple return between two prices: (p1 - p0) / p0.

simple_returns

Simple returns for consecutive prices: length prices.len() - 1.

sortino_ratio

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

total_return

Total simple return from first to last price: (end - start) / start.

volatility

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

volatility_annualized

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