Statistics

finml_core.metrics.statistics

log_returns(prices, period=1)

Calculates the logarithmic (continuously compounded) returns.

Computes the log return as the difference between the natural logarithm of the price at time t and the natural logarithm of the price at time t-period.

\[r_t = \ln(P_t) - \ln(P_{t-n})\]

Parameters:

Name	Type	Description	Default
prices	Series	Time series of asset prices. Must be strictly positive.	required
period	int	The shift period to calculate returns. Defaults to 1 (daily returns if data is daily).	1

Returns:

Type	Description
Series	Series of log returns. The first 'period' values will be NaN.

Notes

Log returns are preferred in quantitative finance because:

1. Time Additivity: Sum of log returns equals the total period return.
2. Statistical Properties: They are often assumed to be normally distributed.

---

rolling_mean(prices, window)

Calculates the Simple Moving Average (SMA).

Computes the unweighted mean of the previous 'window' data points.

\[ \mu_t = \frac{1}{n} \sum_{i=0}^{n-1} P_{t-i} \]

Parameters:

Name	Type	Description	Default
prices	Series	Time series data.	required
window	int	The size of the moving window.	required

Returns:

Type	Description
Series	The rolling mean. The first 'window-1' values will be NaN.

---

rolling_std(prices, window)

Calculates the Moving Standard Deviation.

Computes the standard deviation of the previous 'window' data points. Often used as a measure of dynamic volatility (e.g., Bollinger Bands width).

\[\sigma_t = \sqrt{\frac{1}{n-1} \sum_{i=0}^{n-1} (P_{t-i} - \bar{x}_t)^2}\]

Where:

• \(\sigma_t\): Rolling standard deviation at time \(t\).
• \(n\): Lookback period (window size).
• \(P_{t-i}\): Observation at time \(t-i\).
• \(\bar{x}_t\): Moving average (mean) of the window at time \(t\).

Parameters:

Name	Type	Description	Default
prices	Series	Time series data.	required
window	int	The size of the moving window.	required

Returns:

Type	Description
Series	The rolling standard deviation.

---

simple_returns(prices, period=1)

Calculates the arithmetic (simple) returns.

\[R_t = \frac{P_t}{P_{t-n}} - 1\]

Parameters:

Name	Type	Description	Default
prices	Series	Time series of asset prices.	required
period	int	The shift period. Defaults to 1.	1

Returns:

Type	Description
Series	Series of simple returns.

---

volatility(returns, annualize=True, scale=252)

Calculates the volatility (sample standard deviation) of a return series.

Optionally applies an annualization factor.

\[ \sigma_{annual} = \sigma_{period} \times \sqrt{T} \]

Parameters:

Name	Type	Description	Default
returns	Series	Time series of asset returns (log or simple).	required
annualize	bool	If True, scales the volatility to an annual figure. Defaults to True.	True
scale	int	The annualization factor. Use 252 for daily data, 12 for monthly data. Defaults to 252.	252

Returns:

Type	Description
float	The standard deviation of the series.

Notes

This function uses N-1 degrees of freedom (sample standard deviation), which is the default behavior in pandas.std().