@insiderfinance/totalfinance/risk/research

interface

BacktestOverfittingProbabilityOptions

Options for {@link probabilityOfBacktestOverfitting}.

// ───────────────────────── PBO (combinatorially-symmetric cross-validation) ─────────────────────────
/** Options for {@link probabilityOfBacktestOverfitting}. */
export interface BacktestOverfittingProbabilityOptions {
    /**
     * Number of disjoint contiguous row-blocks `S` (even, `4 ≤ S ≤ 16`). Default `16` (Bailey & López de
     * Prado). The `C(S, S/2)` train/test splits grow fast in `S`; the observation count is trimmed to a
     * multiple of `S` (the oldest rows dropped).
     */
    splits?: number;
}

Fields, parameters & returned members (1)

Name / type	Meaning & unit	Optional / default
`splits` `number`	Number of disjoint contiguous row-blocks `S` (even, `4 ≤ S ≤ 16`). Default `16` (Bailey & López de Prado). The `C(S, S/2)` train/test splits grow fast in `S`; the observation count is trimmed to a multiple of `S` (the oldest rows dropped). unitless by name	Optional No @default declared; consult the signature and description.

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

BacktestOverfittingProbabilityResult

The result of a CSCV probability-of-backtest-overfitting analysis.

/** The result of a CSCV probability-of-backtest-overfitting analysis. */
export interface BacktestOverfittingProbabilityResult {
    /**
     * Probability of backtest overfitting: the fraction of the `C(S, S/2)` symmetric train/test splits on
     * which the in-sample-best configuration ranks **below the out-of-sample median** (logit `λ < 0`). Near
     * `0.5` for noise (selection is worthless out of sample), near `0` for a genuinely persistent edge.
     */
    backtestOverfittingProbability: number;
    /** Number of symmetric train/test splits evaluated: `C(S, S/2)`. */
    combinations: number;
    /** Blocks `S` actually used. */
    splits: number;
    /** Observations (rows) used after trimming to a multiple of `S`. */
    observations: number;
    /** Number of strategy configurations (columns) `N`. */
    trials: number;
    /** Median logit `λ = ln(r̄/(1−r̄))` across the splits (`r̄` = OOS relative rank of the IS-best); `< 0` ⇒ overfit-leaning. */
    medianLogit: number;
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        [k: string]: unknown;
    };
    /** Structured warnings; always present (possibly empty). */
    diagnostics: {
        warnings: QuantWarning[];
    };
}

Fields, parameters & returned members (10)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`backtestOverfittingProbability` `number`	Probability of backtest overfitting: the fraction of the `C(S, S/2)` symmetric train/test splits on which the in-sample-best configuration ranks below the out-of-sample median (logit `λ < 0`). Near `0.5` for noise (selection is worthless out of sample), near `0` for a genuinely persistent edge. unitless by name	Required / declared member No @default declared; consult the signature and description.
`combinations` `number`	Number of symmetric train/test splits evaluated: `C(S, S/2)`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`medianLogit` `number`	Median logit `λ = ln(r̄/(1−r̄))` across the splits (`r̄` = OOS relative rank of the IS-best); `< 0` ⇒ overfit-leaning. unitless by name	Required / declared member No @default declared; consult the signature and description.
`observations` `number`	Observations (rows) used after trimming to a multiple of `S`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`splits` `number`	Blocks `S` actually used. unitless by name	Required / declared member No @default declared; consult the signature and description.
`trials` `number`	Number of strategy configurations (columns) `N`. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

DeflatedSharpeResult

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface DeflatedSharpeResult {
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        [k: string]: unknown;
    };
    /** Structured warnings; always present (possibly empty). */
    diagnostics: {
        warnings: QuantWarning[];
    };
    /** Probability the true Sharpe beats the multiple-testing-adjusted benchmark `SR₀`. */
    /** `null` when the statistics carry no Sharpe (a zero-variance series). */
    deflatedSharpe: number | null;
    /** The un-deflated PSR (benchmark 0), for comparison. */
    probabilisticSharpe: number | null;
    /** Expected maximum Sharpe across `trialCount` under the null — the deflation benchmark `SR₀`. */
    expectedMaxSharpe: number;
    trialCount: number;
}

Fields, parameters & returned members (8)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`deflatedSharpe` `number \| null`	`null` when the statistics carry no Sharpe (a zero-variance series). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`expectedMaxSharpe` `number`	Expected maximum Sharpe across `trialCount` under the null — the deflation benchmark `SR₀`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`probabilisticSharpe` `number \| null`	The un-deflated PSR (benchmark 0), for comparison. unitless by name	Required / declared member No @default declared; consult the signature and description.
`trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

LeakageIssue

One leaking split found by {@link checkLeakage}.

// ───────────────────────── leakage & survivorship diagnostics ─────────────────────────
/** One leaking split found by {@link checkLeakage}. */
export interface LeakageIssue {
    /** Index of the leaking split. */
    split: number;
    /** How many indices appear in both train and test. */
    overlapCount: number;
    /** Up to 10 of the overlapping indices, as a sample. */
    sample: number[];
}

Fields, parameters & returned members (3)

Name / type	Meaning & unit	Optional / default
`overlapCount` `number`	How many indices appear in both train and test. count (integer)	Required / declared member No @default declared; consult the signature and description.
`sample` `number[]`	Up to 10 of the overlapping indices, as a sample. unitless by name	Required / declared member No @default declared; consult the signature and description.
`split` `number`	Index of the leaking split. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

LeakageReport

{@link checkLeakage}'s report: the leak findings plus the Law 2 report grammar.

/** {@link checkLeakage}'s report: the leak findings plus the Law 2 report grammar. */
export interface LeakageReport {
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        [k: string]: unknown;
    };
    /** The leakage warnings themselves (one `research.train_test_leakage` per leaking split). */
    diagnostics: {
        warnings: QuantWarning[];
    };
    /** `true` when no split leaks. */
    clean: boolean;
    /** Per-split leak details, aligned with `diagnostics.warnings`. */
    leaks: LeakageIssue[];
}

Fields, parameters & returned members (6)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`clean` `boolean`	`true` when no split leaks. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `{ warnings: QuantWarning[]; }`	The leakage warnings themselves (one `research.train_test_leakage` per leaking split). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`leaks` `LeakageIssue[]`	Per-split leak details, aligned with `diagnostics.warnings`. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

MultipleTestMethod

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

// ───────────────────────── multiple-testing correction ─────────────────────────
export type MultipleTestMethod = 'bonferroni' | 'sidak' | 'holm' | 'benjaminiHochberg';

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

MultipleTestOptions

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface MultipleTestOptions {
    /** Correction method (default `'holm'`). */
    method?: MultipleTestMethod;
    /** Significance level (default 0.05). */
    alpha?: number;
}

Fields, parameters & returned members (2)

Name / type	Meaning & unit	Optional / default
`alpha` `number`	Significance level (default 0.05). unitless by name	Optional No @default declared; consult the signature and description.
`method` `MultipleTestMethod`	Correction method (default `'holm'`). unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

MultipleTestResult

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface MultipleTestResult {
    method: MultipleTestMethod;
    alpha: number;
    /** Adjusted p-values aligned with the input order. */
    adjusted: number[];
    /** Whether each hypothesis is rejected at `alpha` (`adjusted ≤ alpha`). */
    rejected: boolean[];
}

Fields, parameters & returned members (4)

Name / type	Meaning & unit	Optional / default
`adjusted` `number[]`	Adjusted p-values aligned with the input order. unitless by name	Required / declared member No @default declared; consult the signature and description.
`alpha` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`method` `MultipleTestMethod`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`rejected` `boolean[]`	Whether each hypothesis is rejected at `alpha` (`adjusted ≤ alpha`). unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

ParameterSweepResult

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

// ───────────────────────── parameter-sweep diagnostics ─────────────────────────
export interface ParameterSweepResult {
    trialCount: number;
    bestSharpe: number;
    meanSharpe: number;
    varianceSharpe: number;
    /** Expected maximum Sharpe under the null (the deflation benchmark `SR₀`). */
    expectedMaxSharpe: number;
    /** Deflated Sharpe of the selected (best) configuration. */
    /** `null` when the selected statistics carry no Sharpe (a zero-variance series). */
    deflatedSharpe: number | null;
    /** Un-deflated PSR of the selected configuration; `null` with `deflatedSharpe`. */
    probabilisticSharpe: number | null;
}

Fields, parameters & returned members (7)

Name / type	Meaning & unit	Optional / default
`bestSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`deflatedSharpe` `number \| null`	`null` when the selected statistics carry no Sharpe (a zero-variance series). unitless by name	Required / declared member No @default declared; consult the signature and description.
`expectedMaxSharpe` `number`	Expected maximum Sharpe under the null (the deflation benchmark `SR₀`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`meanSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`probabilisticSharpe` `number \| null`	Un-deflated PSR of the selected configuration; `null` with `deflatedSharpe`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`varianceSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

ProbabilisticSharpeResult

{@link probabilisticSharpeRatio}'s envelope: the probability plus the applied benchmark.

/** {@link probabilisticSharpeRatio}'s envelope: the probability plus the applied benchmark. */
export type ProbabilisticSharpeResult = Computed<number | null, {
    benchmarkSharpe: number;
    observations: number;
}>;

Fields, parameters & returned members (49)

Name / type	Meaning & unit	Optional / default
`assumptions` `import('@insiderfinance/totalfinance/core').Assumptions<{ benchmarkSharpe: number; observations: number; }>`	Every applied convention, echoed back. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.asOf` `number`	an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)	Optional No @default declared; consult the signature and description.
`assumptions.benchmarkSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.calendar` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.calendarVersion` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.compounding` `import('@insiderfinance/totalfinance/core').InterestCompounding`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.compounding.periodsPerYear` `number`	per year (count)	Required / declared member No @default declared; consult the signature and description.
`assumptions.compounding.type` `'periodic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.dayCount` `import('@insiderfinance/totalfinance/core').DayCount`	count (integer)	Optional No @default declared; consult the signature and description.
`assumptions.dividendModel` `import('@insiderfinance/totalfinance/core').DividendModel`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.engine` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.expiryConvention` `'us-equity-close' \| 'explicit-instant'`	How the contract's expiry label was resolved to an instant: `'us-equity-close'` when a date-only `YYYY-MM-DD` expiry resolved to the US equity/options close — 16:00 America/New_York, or 13:00 on an early-close day; `'explicit-instant'` when the caller supplied a zoned datetime. Named so the convention is never silent (alignment spec P1.6); instrument builders own the full story in Phase 3. unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.model` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.observations` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.seed` `number`	The randomness seed this result was computed under — REQUIRED echo for a `randomness: 'seeded'` Pricer (Gate C, 2026-08-23): a stochastic result that does not name its seed cannot be replayed from the result alone. Deterministic paths never set it. unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.timeToExpiryConvention` `never`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.timeToExpiryYears` `number`	years (decimal)	Optional No @default declared; consult the signature and description.
`assumptions.units` `import('@insiderfinance/totalfinance/core').GreekUnits`	unitless by name	Optional No @default declared; consult the signature and description.
`assumptions.units.rho` `import('@insiderfinance/totalfinance/core').RhoUnit`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.units.theta` `import('@insiderfinance/totalfinance/core').ThetaUnit`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.units.vega` `import('@insiderfinance/totalfinance/core').VegaUnit`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `import('@insiderfinance/totalfinance/core').Diagnostics`	How the value was computed, plus any warnings. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`provenance` `import('@insiderfinance/totalfinance/core').Provenance`	Optional data lineage when the inputs came from a provider. unitless by name	Optional No @default declared; consult the signature and description.
`provenance.asOf` `number`	an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)	Optional No @default declared; consult the signature and description.
`provenance.dataset` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`provenance.provider` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`provenance.receivedAt` `number`	unitless by name	Optional No @default declared; consult the signature and description.
`provenance.requestId` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`provenance.sourceVersion` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`provenance.warnings` `QuantWarning[]`	unitless by name	Optional No @default declared; consult the signature and description.
`value` `number \| null`	The computed value. Never `NaN` or `±Infinity`: a value the model cannot produce is `null` beside a diagnostic that says why (Law 7 — a warning never licenses a non-finite number). unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

PurgedKFoldOptions

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface PurgedKFoldOptions {
    /** Number of folds (≥ 2). */
    folds: number;
    /** Fraction of `n` to embargo after each test fold (default 0). */
    embargo?: number;
    /** Observations to purge on each side of a test fold (label-overlap buffer; default 0). */
    purgeGap?: number;
}

Fields, parameters & returned members (3)

Name / type	Meaning & unit	Optional / default
`embargo` `number`	Fraction of `n` to embargo after each test fold (default 0). unitless by name	Optional No @default declared; consult the signature and description.
`folds` `number`	Number of folds (≥ 2). unitless by name	Required / declared member No @default declared; consult the signature and description.
`purgeGap` `number`	Observations to purge on each side of a test fold (label-overlap buffer; default 0). unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

SharpeStatistics

Sample statistics of a return series needed for Sharpe inference. All in per-observation units.

// ───────────────────────── Sharpe inference ─────────────────────────
/** Sample statistics of a return series needed for Sharpe inference. All in per-observation units. */
export interface SharpeStatistics {
    /**
     * Per-observation Sharpe ratio `mean(excess)/std` (NOT annualized). `null` (C hygiene) when the
     * returns have zero variance: there is no dispersion to scale by, and the report says so.
     */
    sharpe: number | null;
    /** Number of observations. */
    observations: number;
    /** Skewness `γ₃` of the returns. */
    skewness: number;
    /** Non-excess kurtosis `γ₄` of the returns (3 for a normal distribution). */
    kurtosis: number;
}

Fields, parameters & returned members (4)

Name / type	Meaning & unit	Optional / default
`kurtosis` `number`	Non-excess kurtosis `γ₄` of the returns (3 for a normal distribution). unitless by name	Required / declared member No @default declared; consult the signature and description.
`observations` `number`	Number of observations. unitless by name	Required / declared member No @default declared; consult the signature and description.
`sharpe` `number \| null`	Per-observation Sharpe ratio `mean(excess)/std` (NOT annualized). `null` (C hygiene) when the returns have zero variance: there is no dispersion to scale by, and the report says so. unitless by name	Required / declared member No @default declared; consult the signature and description.
`skewness` `number`	Skewness `γ₃` of the returns. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

SharpeStatisticsReport

{@link sharpeStatistics}'s report: the stats plus the applied conventions (Law 2 report grammar).

/** {@link sharpeStatistics}'s report: the stats plus the applied conventions (Law 2 report grammar). */
export interface SharpeStatisticsReport extends SharpeStatistics {
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        [k: string]: unknown;
    };
    /** Structured warnings; always present (possibly empty). */
    diagnostics: {
        warnings: QuantWarning[];
    };
}

Fields, parameters & returned members (8)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`kurtosis` `number`	Non-excess kurtosis `γ₄` of the returns (3 for a normal distribution). unitless by name	Required / declared member No @default declared; consult the signature and description.
`observations` `number`	Number of observations. unitless by name	Required / declared member No @default declared; consult the signature and description.
`sharpe` `number \| null`	Per-observation Sharpe ratio `mean(excess)/std` (NOT annualized). `null` (C hygiene) when the returns have zero variance: there is no dispersion to scale by, and the report says so. unitless by name	Required / declared member No @default declared; consult the signature and description.
`skewness` `number`	Skewness `γ₃` of the returns. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

Split

A train/test split as sorted index arrays into a length-`n` sample.

// ───────────────────────── cross-validation splitters ─────────────────────────
/** A train/test split as sorted index arrays into a length-`n` sample. */
export interface Split {
    train: number[];
    test: number[];
}

Fields, parameters & returned members (2)

Name / type	Meaning & unit	Optional / default
`test` `number[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`train` `number[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

SurvivorshipContext

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface SurvivorshipContext {
    /** Whether delisted / inactive instruments are included in the backtest universe. */
    includesDelisted?: boolean;
    /** Whether the universe is point-in-time (members as they were on each date). */
    pointInTimeUniverse?: boolean;
}

Fields, parameters & returned members (2)

Name / type	Meaning & unit	Optional / default
`includesDelisted` `boolean`	Whether delisted / inactive instruments are included in the backtest universe. unitless by name	Optional No @default declared; consult the signature and description.
`pointInTimeUniverse` `boolean`	Whether the universe is point-in-time (members as they were on each date). unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

WalkForwardOptions

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface WalkForwardOptions {
    /** Training window length (in observations). */
    trainSize: number;
    /** Test window length. */
    testSize: number;
    /** Step between successive folds (default `testSize`). */
    step?: number;
    /** `rolling` (sliding train window) or `anchored` (train always starts at 0). Default `rolling`. */
    mode?: 'rolling' | 'anchored';
}

Fields, parameters & returned members (4)

Name / type	Meaning & unit	Optional / default
`mode` `'rolling' \| 'anchored'`	`rolling` (sliding train window) or `anchored` (train always starts at 0). Default `rolling`. unitless by name	Optional No @default declared; consult the signature and description.
`step` `number`	Step between successive folds (default `testSize`). unitless by name	Optional No @default declared; consult the signature and description.
`testSize` `number`	Test window length. count (integer)	Required / declared member No @default declared; consult the signature and description.
`trainSize` `number`	Training window length (in observations). count (integer)	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

adjustPValues

Adjust a set of p-values for multiple testing. Bonferroni/Šidák/Holm control the family-wise error rate; Benjamini–Hochberg controls the false-discovery rate. Returns adjusted p-values (input order) and the rejection decisions at `alpha`.

export declare function adjustPValues(pValues: ArrayLike<number>, options?: MultipleTestOptions): MultipleTestResult;

Fields, parameters & returned members (8)

Name / type	Meaning & unit	Optional / default
`(options)` `MultipleTestOptions`	unitless by name	Optional No @default declared; consult the signature and description.
`(options).alpha` `number`	Significance level (default 0.05). unitless by name	Optional No @default declared; consult the signature and description.
`(options).method` `MultipleTestMethod`	Correction method (default `'holm'`). unitless by name	Optional No @default declared; consult the signature and description.
`(pValues)` `ArrayLike<number>`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.adjusted` `number[]`	Adjusted p-values aligned with the input order. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.alpha` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.method` `MultipleTestMethod`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.rejected` `boolean[]`	Whether each hypothesis is rejected at `alpha` (`adjusted ≤ alpha`). unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

checkLeakage

Flag any split whose train and test index sets overlap (look-ahead leakage). The findings are `research.train_test_leakage` warnings on `diagnostics.warnings` (one per leaking split), with the structured per-split detail mirrored on `leaks` and a `clean` verdict.

export declare function checkLeakage(splits: Split[]): LeakageReport;

Fields, parameters & returned members (7)

Name / type	Meaning & unit	Optional / default
`(splits)` `Split[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.clean` `boolean`	`true` when no split leaks. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics` `{ warnings: QuantWarning[]; }`	The leakage warnings themselves (one `research.train_test_leakage` per leaking split). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.leaks` `LeakageIssue[]`	Per-split leak details, aligned with `diagnostics.warnings`. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

deflatedSharpeRatio

Deflated Sharpe Ratio (Bailey & López de Prado 2014): the PSR evaluated against the *expected maximum* Sharpe that `N` independent trials would produce by chance, so selecting the best of a parameter sweep is penalised. Pass the trial Sharpes (variance computed for you) or `trialCount` plus their variance directly.

export declare function deflatedSharpeRatio(statistics: SharpeStatistics, trials: { trialSharpes: ArrayLike<number>; } | { trialCount: number; varianceSharpe: number; }): DeflatedSharpeResult;

Fields, parameters & returned members (17)

Name / type	Meaning & unit	Optional / default
`(statistics)` `SharpeStatistics`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(statistics).kurtosis` `number`	Non-excess kurtosis `γ₄` of the returns (3 for a normal distribution). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(statistics).observations` `number`	Number of observations. unitless by name	Required / declared member No @default declared; consult the signature and description.
`(statistics).sharpe` `number \| null`	Per-observation Sharpe ratio `mean(excess)/std` (NOT annualized). `null` (C hygiene) when the returns have zero variance: there is no dispersion to scale by, and the report says so. unitless by name	Required / declared member No @default declared; consult the signature and description.
`(statistics).skewness` `number`	Skewness `γ₃` of the returns. unitless by name	Required / declared member No @default declared; consult the signature and description.
`(trials)` `{ trialSharpes: ArrayLike<number>; } \| { trialCount: number; varianceSharpe: number; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(trials).trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`(trials).trialSharpes` `ArrayLike<number>`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(trials).varianceSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.deflatedSharpe` `number \| null`	`null` when the statistics carry no Sharpe (a zero-variance series). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.expectedMaxSharpe` `number`	Expected maximum Sharpe across `trialCount` under the null — the deflation benchmark `SR₀`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.probabilisticSharpe` `number \| null`	The un-deflated PSR (benchmark 0), for comparison. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

parameterSweepDiagnostics

Summarize a parameter sweep: given the per-trial Sharpes and the sample statistics of the *selected* (best) configuration's return series, report the dispersion of the trials and the deflated Sharpe — the honest probability the winner is real rather than the luckiest of many.

export declare function parameterSweepDiagnostics(trialSharpes: ArrayLike<number>, selected: SharpeStatistics): ParameterSweepResult;

Fields, parameters & returned members (13)

Name / type	Meaning & unit	Optional / default
`(selected)` `SharpeStatistics`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(selected).kurtosis` `number`	Non-excess kurtosis `γ₄` of the returns (3 for a normal distribution). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(selected).observations` `number`	Number of observations. unitless by name	Required / declared member No @default declared; consult the signature and description.
`(selected).sharpe` `number \| null`	Per-observation Sharpe ratio `mean(excess)/std` (NOT annualized). `null` (C hygiene) when the returns have zero variance: there is no dispersion to scale by, and the report says so. unitless by name	Required / declared member No @default declared; consult the signature and description.
`(selected).skewness` `number`	Skewness `γ₃` of the returns. unitless by name	Required / declared member No @default declared; consult the signature and description.
`(trialSharpes)` `ArrayLike<number>`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.bestSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.deflatedSharpe` `number \| null`	`null` when the selected statistics carry no Sharpe (a zero-variance series). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.expectedMaxSharpe` `number`	Expected maximum Sharpe under the null (the deflation benchmark `SR₀`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.meanSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.probabilisticSharpe` `number \| null`	Un-deflated PSR of the selected configuration; `null` with `deflatedSharpe`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.trialCount` `number`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`return.varianceSharpe` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

probabilisticSharpeRatio

Plain probability; use `.explain()` for the benchmark and observation count.

export declare const probabilisticSharpeRatio: import('@insiderfinance/totalfinance/core').SeriesFacade<[stats: SharpeStatistics, benchmarkSharpe?: number | undefined], number | null, { benchmarkSharpe: number; observations: number; }>;

Fields, parameters & returned members (7)

Name / type	Meaning & unit	Optional / default
`(callArguments)` `[stats: SharpeStatistics, benchmarkSharpe?: number \| undefined]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain` `(stats: SharpeStatistics, benchmarkSharpe?: number \| undefined) => Computed<number \| null, { benchmarkSharpe: number; observations: number; }>`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain().return.assumptions` `import('@insiderfinance/totalfinance/core').Assumptions<{ benchmarkSharpe: number; observations: number; }>`	Every applied convention, echoed back. unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain().return.diagnostics` `import('@insiderfinance/totalfinance/core').Diagnostics`	How the value was computed, plus any warnings. unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain().return.provenance` `import('@insiderfinance/totalfinance/core').Provenance`	Optional data lineage when the inputs came from a provider. unitless by name	Optional No @default declared; consult the signature and description.
`explain().return.value` `number \| null`	The computed value. Never `NaN` or `±Infinity`: a value the model cannot produce is `null` beside a diagnostic that says why (Law 7 — a warning never licenses a non-finite number). unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain(callArguments)` `[stats: SharpeStatistics, benchmarkSharpe?: number \| undefined]`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

probabilityOfBacktestOverfitting

**Probability of backtest overfitting** (Bailey & López de Prado's CSCV). Given a `T × N` matrix of per-period returns — `T` time observations (rows) × `N` strategy configurations you selected among (columns) — split the rows into `S` blocks, and over **every** `C(S, S/2)` symmetric partition into an in-sample and an out-of-sample half: pick the IS-best configuration, then measure its OOS rank. PBO is the fraction of splits where the IS winner lands **below the OOS median** — the probability that picking the best backtest buys you a below-average live result. `≈ 0.5` means the selection is worthless out of sample; `≈ 0` means a genuinely persistent edge. Depends only on `@insiderfinance/totalfinance/core`/`math`.

export declare function probabilityOfBacktestOverfitting(returns: number[][], options?: BacktestOverfittingProbabilityOptions): BacktestOverfittingProbabilityResult;

Fields, parameters & returned members (13)

Name / type	Meaning & unit	Optional / default
`(options)` `BacktestOverfittingProbabilityOptions`	unitless by name	Optional No @default declared; consult the signature and description.
`(options).splits` `number`	Number of disjoint contiguous row-blocks `S` (even, `4 ≤ S ≤ 16`). Default `16` (Bailey & López de Prado). The `C(S, S/2)` train/test splits grow fast in `S`; the observation count is trimmed to a multiple of `S` (the oldest rows dropped). unitless by name	Optional No @default declared; consult the signature and description.
`(returns)` `number[][]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.backtestOverfittingProbability` `number`	Probability of backtest overfitting: the fraction of the `C(S, S/2)` symmetric train/test splits on which the in-sample-best configuration ranks below the out-of-sample median (logit `λ < 0`). Near `0.5` for noise (selection is worthless out of sample), near `0` for a genuinely persistent edge. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.combinations` `number`	Number of symmetric train/test splits evaluated: `C(S, S/2)`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.medianLogit` `number`	Median logit `λ = ln(r̄/(1−r̄))` across the splits (`r̄` = OOS relative rank of the IS-best); `< 0` ⇒ overfit-leaning. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.observations` `number`	Observations (rows) used after trimming to a multiple of `S`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.splits` `number`	Blocks `S` actually used. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.trials` `number`	Number of strategy configurations (columns) `N`. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

purgedKFold

Purged & embargoed K-fold cross-validation (López de Prado, *Advances in Financial ML* ch. 7). Each fold's test set is a contiguous block; training drops any observation within `purgeGap` of the test block (label-overlap purge) and within the trailing `embargo·n` window after it. Throws a typed `input.out_of_range` naming the largest viable `purgeGap` when the requested purge (with the embargo) would leave a fold with an empty training set — an unusable split is an error, not an empty array to be discovered downstream.

export declare function purgedKFold(observationCount: number, options: PurgedKFoldOptions): Split[];

Fields, parameters & returned members (5)

Name / type	Meaning & unit	Optional / default
`(observationCount)` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options)` `PurgedKFoldOptions`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).embargo` `number`	Fraction of `n` to embargo after each test fold (default 0). unitless by name	Optional No @default declared; consult the signature and description.
`(options).folds` `number`	Number of folds (≥ 2). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).purgeGap` `number`	Observations to purge on each side of a test fold (label-overlap buffer; default 0). unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

sharpeStatistics

Sample Sharpe statistics of a return series: the per-observation (non-annualized) Sharpe plus the skewness and (non-excess) kurtosis that the probabilistic-Sharpe adjustment needs.

export declare function sharpeStatistics(returns: ArrayLike<number>, options?: { riskFreeRate?: number; }): SharpeStatisticsReport;

Fields, parameters & returned members (11)

Name / type	Meaning & unit	Optional / default
`(options)` `{ riskFreeRate?: number; }`	unitless by name	Optional No @default declared; consult the signature and description.
`(options).riskFreeRate` `number`	decimal rate (0.05 = 5%)	Optional No @default declared; consult the signature and description.
`(returns)` `ArrayLike<number>`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions` `{ [k: string]: unknown; conventionsVersion: string; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics` `{ warnings: QuantWarning[]; }`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics.warnings` `QuantWarning[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.kurtosis` `number`	Non-excess kurtosis `γ₄` of the returns (3 for a normal distribution). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.observations` `number`	Number of observations. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.sharpe` `number \| null`	Per-observation Sharpe ratio `mean(excess)/std` (NOT annualized). `null` (C hygiene) when the returns have zero variance: there is no dispersion to scale by, and the report says so. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.skewness` `number`	Skewness `γ₃` of the returns. unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

survivorshipWarning

Return a survivorship-bias warning when the backtest universe excludes delisted names or is not point-in-time — both bias results upward — or `null` when neither concern applies.

export declare function survivorshipWarning(context: SurvivorshipContext): QuantWarning | null;

Fields, parameters & returned members (7)

Name / type	Meaning & unit	Optional / default
`(context)` `SurvivorshipContext`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(context).includesDelisted` `boolean`	Whether delisted / inactive instruments are included in the backtest universe. unitless by name	Optional No @default declared; consult the signature and description.
`(context).pointInTimeUniverse` `boolean`	Whether the universe is point-in-time (members as they were on each date). unitless by name	Optional No @default declared; consult the signature and description.
`return.code` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.context` `Record<string, unknown>`	unitless by name	Optional No @default declared; consult the signature and description.
`return.message` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.severity` `import('@insiderfinance/totalfinance/core').WarningSeverity`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)