Developer documentation API v1

Deterministic quantitative methods

Explicit estimators, reproducible inputs and numerical preconditions.

Computation contract

A numerical artifact identifies the input snapshot, instrument universe, calculation revision, parameters, time range, sampling convention and units. Invalid-input and insufficient-history failures are explicit. Non-finite numeric output is rejected rather than serialized as NaN or infinity.

Quantitative services compute moving averages, Wilder RSI, returns, annualized volatility, drawdown and covariance. The definitions below specify estimator behavior, preconditions and interpretation.

Returns and sample volatility

P_t must be a positive, comparable price. n is the number of returns, so n+1 prices are required. A is the explicitly chosen observations-per-year convention. Square-root annualization assumes an appropriate variance-scaling model; autocorrelation, irregular spacing and regime changes can invalidate that interpretation. A price return is not a total return unless distributions are included consistently.

\begin{aligned}r_t&=\frac{P_t}{P_{t-1}}-1,&g_t&=\log\frac{P_t}{P_{t-1}}\\ \bar g&=\frac1n\sum_{t=1}^{n}g_t,&s^2&=\frac1{n-1}\sum_{t=1}^{n}(g_t-\bar g)^2\\ \sigma_{\mathrm{ann}}&=\sqrt A\,s\end{aligned}

Wilder relative strength index

The initial smoothed gains and losses are the arithmetic means of the first m changes, with m=14 for the standard indicator. A positive gain with zero loss returns 100; positive loss with zero gain returns 0. A flat series with both equal to zero returns 50. Wilder smoothing is recursive rather than a rolling simple average.

\begin{aligned}\Delta_t&=P_t-P_{t-1},&U_t&=\max(\Delta_t,0),&D_t&=\max(-\Delta_t,0)\\ \bar U_t&=\frac{(m-1)\bar U_{t-1}+U_t}{m},&\bar D_t&=\frac{(m-1)\bar D_{t-1}+D_t}{m}\\ \operatorname{RSI}_t&=100-\frac{100}{1+\bar U_t/\bar D_t}\end{aligned}

Drawdown and covariance

Drawdown is nonpositive under this convention; a reported positive maximum-loss magnitude is −MDD. Use net asset value instead of price for portfolio drawdown. Covariance requires synchronized return vectors and a documented missing-data policy. Pairwise deletion can produce a non-positive-semidefinite matrix; an optimizer needs a valid risk matrix and disclosed regularization.

\begin{aligned}\operatorname{Peak}_t&=\max_{0\le j\le t}P_j,&\operatorname{DD}_t&=\frac{P_t}{\operatorname{Peak}_t}-1\\ \operatorname{MDD}&=\min_t\operatorname{DD}_t,&\widehat\Sigma&=\frac1{n-1}\sum_t(r_t-\bar r)(r_t-\bar r)^\top\end{aligned}

Runnable volatility calculation

Synthetic observations. This code computes sample log-return volatility, not expected return or an Aura forecast. The downloadable examples include the same function.

python

from math import isfinite, log, sqrt
from statistics import stdev

def annualized_volatility(prices, periods_per_year=252):
    if len(prices) < 3 or any(not isfinite(p) or p <= 0 for p in prices):
        raise ValueError("Need at least three finite positive prices")
    if not isfinite(periods_per_year) or periods_per_year <= 0:
        raise ValueError("Invalid annualization convention")
    returns = [log(b) - log(a) for a, b in zip(prices, prices[1:])]
    return stdev(returns) * sqrt(periods_per_year)

print(round(annualized_volatility([100, 102, 101, 104]), 6))

Descriptive fits and predictive validity

An ordinary least-squares fit of log price against session index describes the selected sample. Its residual band is not automatically a predictive interval. Autocorrelation and conditional heteroskedasticity can invalidate independent-error standard errors.

Each artifact identifies its interpretation as descriptive, conditional or predictive, together with estimator revision, adjustment convention and input digest. A change in normalization is a method change even when the displayed indicator name stays the same.

Shrinkage of the risk matrix

S is the sample covariance matrix and F a structured target in the same units and asset order. Shrinkage trades sampling variance against target bias. The target and intensity selection belong to the risk-model revision; this formula does not prescribe a universal coefficient. F is positive semidefinite; a positive-definite target with nonzero shrinkage supplies positive curvature even when S is singular.

\widehat\Sigma_{\delta}=(1-\delta)S+\delta F,\qquad 0\le\delta\le1

Covariance structure before and after shrinkage

Two four-by-four synthetic unit-variance covariance matrices. Identity-target shrinkage at intensity 0.35 reduces off-diagonal correlations and the matrix condition number while retaining unit diagonal. — Synthetic standardized-return example with S = bbᵀ + diag(1 − b²), b = (0.90, 0.85, 0.35, −0.20), F = I and δ = 0.35. Both matrices are positive definite. The condition number is the ratio of largest to smallest eigenvalue. Better conditioning is a numerical property, not evidence of improved out-of-sample performance. View full size ↗

Conditioning and estimator stability

When the asset dimension is large relative to the number of observations, the sample covariance can be singular or poorly conditioned. A small eigenvalue makes an inverse-covariance allocation sensitive to small estimation changes. Shrinkage improves conditioning when the target supplies suitable positive curvature, but it does not remove regime shifts or incorrect input alignment.

The risk artifact records the observation count, universe, regularization method and matrix diagnostics. Optimization uses that exact revision so a result can be traced to its assumptions.

Mathematical and systems references

Ledoit and Wolf: covariance shrinkageBias-variance tradeoffs in covariance estimation for portfolio construction.