Finance.Returns (finance v1.2.0)

Performance and risk metrics for a price or return series.

For now this covers volatility/2; return metrics such as CAGR, payback, and time-weighted return will land here as the library grows.

Summary

Functions

volatility(prices, opts \\ [])

Annualised volatility of a price series — the standard deviation of its period-over-period returns, scaled up to a yearly figure.

volatility!(prices, opts \\ [])

Same as volatility/2, but hands back the value on its own and raises ArgumentError if it can't be computed.

Types

error()

@type error() :: Finance.error()

Functions

volatility(prices, opts \\ [])

@spec volatility(
  [number()],
  keyword()
) :: {:ok, float()} | {:error, error()}

Annualised volatility of a price series — the standard deviation of its period-over-period returns, scaled up to a yearly figure.

Give it a list of prices in time order (daily closes, say). It measures the return between each consecutive pair, takes their sample standard deviation, and annualises by √periods_per_year. At least three prices are needed, and every price must be positive.

iex> Finance.Returns.volatility([100, 102, 101, 103, 105])
{:ok, 0.234528}

Options

:periods_per_year (pos_integer/0) - number of periods in a year, used to annualise (252 trading days by default) The default value is 252.
:returns - how to measure each period's return: :simple (b - a) / a or :log ln(b / a) The default value is :simple.
:precision (non_neg_integer/0) - decimal places the result is rounded to The default value is 6.

volatility!(prices, opts \\ [])

@spec volatility!(
  [number()],
  keyword()
) :: float()

Same as volatility/2, but hands back the value on its own and raises ArgumentError if it can't be computed.