@insiderfinance/totalfinance/performance/analyze

type

AnalyzeInput

Input for {@link analyze}: an explicit `equity` curve (growth of capital) **or** a per-period `returns` series — a tagged union so the caller can never silently confuse the two (WS3.3b).

/**
 * Input for {@link analyze}: an explicit `equity` curve (growth of capital) **or** a per-period
 * `returns` series — a tagged union so the caller can never silently confuse the two (WS3.3b).
 */
export type AnalyzeInput = {
    equity: ArrayLike<number>;
} | {
    returns: ArrayLike<number>;
};

Fields, parameters & returned members (2)

Name / type	Meaning & unit	Optional / default
`equity` `ArrayLike<number>`	unitless by name	Required / declared member 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.

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

AnalyzeOptions

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

export interface AnalyzeOptions {
    /** Annualization factor. Defaults to 252 (daily); echoed in the summary's `assumptions`. */
    periodsPerYear?: number;
    riskFreeRate?: number;
    /**
     * Per-period benchmark **return** series aligned to the equity curve's returns (length =
     * `equity.length − 1`). When supplied, the summary adds beta, alpha, tracking error, information
     * ratio, and the Treynor ratio.
     */
    benchmark?: ArrayLike<number>;
}

Fields, parameters & returned members (3)

Name / type	Meaning & unit	Optional / default
`benchmark` `ArrayLike<number>`	Per-period benchmark return series aligned to the equity curve's returns (length = `equity.length − 1`). When supplied, the summary adds beta, alpha, tracking error, information ratio, and the Treynor ratio. unitless by name	Optional No @default declared; consult the signature and description.
`periodsPerYear` `number`	Annualization factor. Defaults to 252 (daily); echoed in the summary's `assumptions`. per year (count)	Optional No @default declared; consult the signature and description.
`riskFreeRate` `number`	decimal rate (0.05 = 5%)	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

PerformanceSummary

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

export interface PerformanceSummary {
    periods: number;
    /** `null` when compounding overflowed (disclosed via `performance.non_finite_metric`). */
    totalReturn: number | null;
    /** `null` when compounding overflowed (disclosed via `performance.non_finite_metric`). */
    annualizedReturn: number | null;
    annualizedVolatility: number | null;
    /** `null` when the metric is undefined for this input (disclosed via warnings). */
    sharpe: number | null;
    /** `null` when the metric is undefined for this input (disclosed via warnings). */
    sortino: number | null;
    /** `null` when the metric is undefined for this input (disclosed via warnings). */
    calmar: number | null;
    maxDrawdown: number;
    drawdown: DrawdownResult;
    /** Omega ratio at a 0 per-period threshold. */
    /** `null` when the metric is undefined for this input (disclosed via warnings). */
    omega: number | null;
    /** Fraction of non-zero return periods that were positive. */
    /** `null` when the metric is undefined for this input (disclosed via warnings). */
    hitRate: number | null;
    /** Gross gains ÷ gross losses across the return series. */
    /** `null` when the metric is undefined for this input (disclosed via warnings). */
    profitFactor: number | null;
    /** Mean per-period return (expectancy); `null` on an empty series or overflow (disclosed). */
    expectancy: number | null;
    /** Diagnostics — e.g. `performance.suspicious_equity_input` when an equity curve looks like returns. */
    warnings: QuantWarning[];
    /** Beta to the benchmark (only when `options.benchmark` is supplied). */
    beta?: number | null;
    /** Annualized Jensen's alpha (only when `options.benchmark` is supplied). */
    alpha?: number | null;
    /** Annualized tracking error (only when `options.benchmark` is supplied). */
    trackingError?: number | null;
    /** Information ratio (only when `options.benchmark` is supplied). */
    informationRatio?: number | null;
    /** Treynor ratio (only when `options.benchmark` is supplied). */
    treynor?: number | null;
    /** The conventions actually applied — a serialized summary is self-interpreting (spec §7.4). */
    assumptions: {
        /** Annualization factor used for all annualized metrics. */
        periodsPerYear: number;
        /** Per-period risk-free rate used for Sharpe/Sortino/alpha/Treynor (0 when unspecified). */
        riskFreeRate: number;
        /** Length of the benchmark return series, present only when a benchmark was supplied. */
        benchmarkLength?: number;
    };
}

Fields, parameters & returned members (28)

Name / type	Meaning & unit	Optional / default
`alpha` `number \| null`	Annualized Jensen's alpha (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`annualizedReturn` `number \| null`	`null` when compounding overflowed (disclosed via `performance.non_finite_metric`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`annualizedVolatility` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions` `{ benchmarkLength?: number; periodsPerYear: number; riskFreeRate: number; }`	The conventions actually applied — a serialized summary is self-interpreting (spec §7.4). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.benchmarkLength` `number`	Length of the benchmark return series, present only when a benchmark was supplied. count (integer)	Optional No @default declared; consult the signature and description.
`assumptions.periodsPerYear` `number`	Annualization factor used for all annualized metrics. per year (count)	Required / declared member No @default declared; consult the signature and description.
`assumptions.riskFreeRate` `number`	Per-period risk-free rate used for Sharpe/Sortino/alpha/Treynor (0 when unspecified). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`beta` `number \| null`	Beta to the benchmark (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`calmar` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`drawdown` `DrawdownResult`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`drawdown.longestDurationPeriods` `number`	Longest underwater stretch, in periods. periods	Required / declared member No @default declared; consult the signature and description.
`drawdown.maxDrawdown` `number`	Maximum drawdown as a positive fraction (0.2 = a 20% peak-to-trough decline). unitless by name	Required / declared member No @default declared; consult the signature and description.
`drawdown.peakIndex` `number`	Index of the peak preceding the worst drawdown. count (integer)	Required / declared member No @default declared; consult the signature and description.
`drawdown.recoveryIndex` `number`	Index at which equity first regained the pre-drawdown peak after the worst trough (WS3.3c). Absent when the curve never recovered by the end of the series (still underwater). count (integer)	Optional No @default declared; consult the signature and description.
`drawdown.troughIndex` `number`	Index of the trough of the worst drawdown. count (integer)	Required / declared member No @default declared; consult the signature and description.
`expectancy` `number \| null`	Mean per-period return (expectancy); `null` on an empty series or overflow (disclosed). unitless by name	Required / declared member No @default declared; consult the signature and description.
`hitRate` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`informationRatio` `number \| null`	Information ratio (only when `options.benchmark` is supplied). decimal fraction / multiple	Optional No @default declared; consult the signature and description.
`maxDrawdown` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`omega` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`periods` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`profitFactor` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`sharpe` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`sortino` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`totalReturn` `number \| null`	`null` when compounding overflowed (disclosed via `performance.non_finite_metric`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`trackingError` `number \| null`	Annualized tracking error (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`treynor` `number \| null`	Treynor ratio (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`warnings` `QuantWarning[]`	Diagnostics — e.g. `performance.suspicious_equity_input` when an equity curve looks like 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

analyze

The performance summary facade (dx §2.3): plain call → the summary; `.explain()` → the core Computed envelope around it (the summary's own warnings ride `diagnostics.warnings`, its echoed conventions ride `assumptions`).

export declare const analyze: import('@insiderfinance/totalfinance/core').SeriesFacade<[input: AnalyzeInput, options?: AnalyzeOptions | undefined], PerformanceSummary, { benchmarkLength?: number; periodsPerYear: number; riskFreeRate: number; }>;

Fields, parameters & returned members (30)

Name / type	Meaning & unit	Optional / default
`(callArguments)` `[input: AnalyzeInput, options?: AnalyzeOptions \| undefined]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain` `(input: AnalyzeInput, options?: AnalyzeOptions \| undefined) => Computed<PerformanceSummary, { benchmarkLength?: number; periodsPerYear: number; riskFreeRate: number; }>`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`explain().return.assumptions` `import('@insiderfinance/totalfinance/core').Assumptions<{ benchmarkLength?: number; periodsPerYear: number; riskFreeRate: 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` `PerformanceSummary`	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)` `[input: AnalyzeInput, options?: AnalyzeOptions \| undefined]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.alpha` `number \| null`	Annualized Jensen's alpha (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`return.annualizedReturn` `number \| null`	`null` when compounding overflowed (disclosed via `performance.non_finite_metric`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.annualizedVolatility` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions` `{ benchmarkLength?: number; periodsPerYear: number; riskFreeRate: number; }`	The conventions actually applied — a serialized summary is self-interpreting (spec §7.4). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.benchmarkLength` `number`	Length of the benchmark return series, present only when a benchmark was supplied. count (integer)	Optional No @default declared; consult the signature and description.
`return.assumptions.periodsPerYear` `number`	Annualization factor used for all annualized metrics. per year (count)	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.riskFreeRate` `number`	Per-period risk-free rate used for Sharpe/Sortino/alpha/Treynor (0 when unspecified). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`return.beta` `number \| null`	Beta to the benchmark (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`return.calmar` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.drawdown` `DrawdownResult`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.expectancy` `number \| null`	Mean per-period return (expectancy); `null` on an empty series or overflow (disclosed). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.hitRate` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`return.informationRatio` `number \| null`	Information ratio (only when `options.benchmark` is supplied). decimal fraction / multiple	Optional No @default declared; consult the signature and description.
`return.maxDrawdown` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.omega` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.periods` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.profitFactor` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). decimal fraction / multiple	Required / declared member No @default declared; consult the signature and description.
`return.sharpe` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.sortino` `number \| null`	`null` when the metric is undefined for this input (disclosed via warnings). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.totalReturn` `number \| null`	`null` when compounding overflowed (disclosed via `performance.non_finite_metric`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.trackingError` `number \| null`	Annualized tracking error (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`return.treynor` `number \| null`	Treynor ratio (only when `options.benchmark` is supplied). unitless by name	Optional No @default declared; consult the signature and description.
`return.warnings` `QuantWarning[]`	Diagnostics — e.g. `performance.suspicious_equity_input` when an equity curve looks like 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)