Public API / @insiderfinance/totalfinance
@insiderfinance/totalfinance/math/timeseries
import from '@insiderfinance/totalfinance/math/timeseries'
Every public export in this entry point, including type-only declarations. Search by name or concept.
Jump to an export (13)
AugmentedDickeyFullerOptions · EngleGrangerResult · KpssOptions · LjungBoxOptions · TestResult · acf · augmentedDickeyFullerTest · engleGranger · hurstExponent · kpssTest · ljungBox · ouHalfLife · pacf
interface
AugmentedDickeyFullerOptions
Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.
export interface AugmentedDickeyFullerOptions {
/** Deterministic terms: `'c'` = constant (default), `'ct'` = constant + linear trend. */
regression?: 'c' | 'ct';
/** Number of augmenting lagged differences (default 0 ⇒ plain Dickey–Fuller). */
lags?: number;
}
Fields, parameters & returned members (2)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
interface
EngleGrangerResult
Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.
export interface EngleGrangerResult {
/** Slope of the cointegrating regression `y = α + β·x + resid`. */
beta: number;
/** Intercept of the cointegrating regression. */
alpha: number;
/** ADF test on the regression residuals (the cointegration test statistic). */
residualAugmentedDickeyFuller: TestResult;
/** `true` when the residual ADF statistic falls below the 5% Engle–Granger critical value. */
cointegrated: boolean;
}
Fields, parameters & returned members (11)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
interface
KpssOptions
Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.
export interface KpssOptions {
/** `'c'` = level stationarity (default), `'ct'` = trend stationarity. */
regression?: 'c' | 'ct';
}
Fields, parameters & returned members (1)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
interface
LjungBoxOptions
Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.
// ───────────────────────── Ljung–Box ─────────────────────────
export interface LjungBoxOptions {
/**
* Number of parameters ESTIMATED from the same series before the test (e.g. `p + q` for the
* residuals of an ARMA(p, q) fit). The reference distribution loses one degree of freedom per
* fitted parameter: `Q ~ χ²(lags − fittedParameterCount)`. Default 0 — the raw white-noise null,
* which is the right reference only for a series that was NOT fitted.
*/
fittedParameterCount?: number;
}
Fields, parameters & returned members (1)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
interface
TestResult
Uniform result shape for every hypothesis test in this module.
/** Uniform result shape for every hypothesis test in this module. */
export interface TestResult {
/** The test statistic. */
statistic: number;
/** Approximate (or, for Ljung–Box, exact) p-value, when defined. */
pValue?: number;
/** Asymptotic critical values at the 1% / 5% / 10% levels, when the test tabulates them. */
criticalValues?: {
'1%': number;
'5%': number;
'10%': number;
};
/** Human-readable identifier of the test and its configuration. */
method: string;
}
Fields, parameters & returned members (7)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
acf
Sample autocorrelation function through `maxLag`, using the biased (÷N) estimator that guarantees a
positive-semidefinite sequence. Returns `[1, ρ₁, …, ρ_maxLag]` — index 0 is lag 0 and equals 1 exactly.
export declare function acf(series: number[], maxLag: number): number[];
Fields, parameters & returned members (2)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
augmentedDickeyFullerTest
Augmented Dickey–Fuller test for a unit root. Regresses `Δyₜ` on `y_{t−1}`, a constant (and a trend
for `'ct'`), and `lags` lagged differences; the statistic is the t-ratio on `y_{t−1}`. A very negative
statistic (below the critical value) rejects the unit-root null in favour of stationarity.
export declare function augmentedDickeyFullerTest(series: number[], options?: AugmentedDickeyFullerOptions): TestResult;
Fields, parameters & returned members (11)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
engleGranger
Engle–Granger two-step cointegration test. Step 1 regresses `y` on `x` (with intercept); step 2 runs
an ADF test on the residuals. Because the residuals are estimated, the decision uses the
residual-based Engle–Granger critical value (≈ −3.34 at 5% for one regressor), not the raw ADF table.
export declare function engleGranger(dependent: number[], independent: number[]): EngleGrangerResult;
Fields, parameters & returned members (6)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
hurstExponent
Hurst exponent via rescaled-range (R/S) analysis. For a geometric progression of window sizes the
mean rescaled range `⟨R/S⟩ₙ` scales as `nᴴ`; `H` is the slope of `log⟨R/S⟩` on `log n`. R/S is
computed on the input series AS GIVEN, so the usual reading — `H ≈ 0.5` random walk, `H > 0.5`
persistence/trending, `H < 0.5` mean reversion — assumes an INCREMENT (returns) series. Passing an
integrated level series (e.g. a price path) instead yields `H ≈ 1`.
BIAS CAVEAT — read this before calling 0.55 "persistence". This is PLAIN R/S with no Anis–Lloyd
(1976) small-sample correction, and plain R/S is biased UPWARD at every finite sample size: for
independent data `E[R/S]ₙ` is not `n^0.5`, so the slope is not 0.5 either. Measured on this
implementation over 20 seeds of iid normal input (mean, and the spread across seeds):
- `n = 512` → `H ≈ 0.565` (0.52 … 0.65)
- `n = 4096` → `H ≈ 0.538` (0.48 … 0.59)
- `n = 32768` → `H ≈ 0.534` (0.51 … 0.56)
The bias shrinks with `n` but is still ~0.03 at 32k points, and the seed-to-seed spread is wider
than the bias itself. So a lone `H = 0.55` on 4k observations is evidence of NOTHING. Compare
against a shuffled (or synthetic iid) version of your own series at the SAME length rather than
against the textbook 0.5, or use a corrected estimator. The ORDERING (anti-persistent < iid <
persistent, as the test suite asserts) is reliable; the absolute level is not.
export declare function hurstExponent(series: number[]): number;
Fields, parameters & returned members (1)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
kpssTest
Kwiatkowski–Phillips–Schmidt–Shin (KPSS) stationarity test. The null is (level or trend)
stationarity, so a LARGE statistic (above the critical value) rejects stationarity — the mirror image
of ADF. The bandwidth for the long-run variance defaults to `⌊4·(T/100)^¼⌋`.
export declare function kpssTest(series: number[], options?: KpssOptions): TestResult;
Fields, parameters & returned members (10)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
ljungBox
Ljung–Box portmanteau test for autocorrelation up to `lags`:
`Q = N(N+2) Σ_{k=1}^{h} ρ̂ₖ² / (N−k)`, distributed `χ²(h)` under the white-noise null. The p-value is
the exact chi-square survival function.
On ARMA RESIDUALS the white-noise null is the wrong reference: fitting `p + q` parameters to the
same data absorbs autocorrelation the statistic then fails to see, so `χ²(h)` is too conservative
and the test under-rejects. Pass `fittedParameterCount` to use the standard corrected reference
`χ²(h − p − q)` (Box–Jenkins); the returned `method` discloses the degrees of freedom actually
used. The statistic itself is unchanged — only the reference distribution moves.
export declare function ljungBox(series: number[], lags: number, options?: LjungBoxOptions): TestResult;
Fields, parameters & returned members (11)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
ouHalfLife
Half-life of mean reversion from an AR(1) fit `xₜ = a + b·x_{t−1} + εₜ`:
`halfLife = −ln 2 / ln b`. Defined (positive) only for a mean-reverting series with `0 < b < 1`;
returns `NaN` when `b ≤ 0` and a non-positive value when `b ≥ 1` (no reversion), by construction.
export declare function ouHalfLife(series: number[]): number;
Fields, parameters & returned members (1)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.
function
pacf
Partial autocorrelation function through `maxLag` via the Durbin–Levinson recursion on the sample
ACF. Returns `[1, φ₁₁, …, φ_maxLag,maxLag]` (index 0 = 1 by convention).
export declare function pacf(series: number[], maxLag: number): number[];
Fields, parameters & returned members (2)
Stability, warnings & conventions
stable-by-law (pre-1.0; not a 1.0 stability guarantee)
Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.