dlm-js
    Preparing search index...

    Interface DlmMleOptions

    Options for dlmMLE.

    interface DlmMleOptions {
        adamOpts?: { b1?: number; b2?: number; eps?: number };
        algorithm?: DlmAlgorithm;
        arCoefficients?: number[];
        callbacks?: {
            onInit?: (theta: FloatArray) => void;
            onIteration?: (iter: number, theta: FloatArray, deviance: number) => void;
        };
        checkpoint?: number
        | boolean;
        dtype?: DlmDtype;
        fitAr?: boolean;
        fullSeasonal?: boolean;
        harmonics?: number;
        init?: {
            arCoefficients?: number[];
            obsStd?: number;
            processStd?: number[];
        };
        loss?: DlmLossFn
        | "ml";
        lr?: number;
        maxIter?: number;
        naturalOpts?: {
            fdStep?: number;
            hessian?: "fd" | "exact";
            lambdaGrow?: number;
            lambdaInit?: number;
            lambdaShrink?: number;
        };
        obsStdFixed?: ArrayLike<number>;
        optimizer?: "adam" | "natural";
        order?: number;
        seasonLength?: number;
        spline?: boolean;
        tol?: number;
        X?: ArrayLike<number>[];
    }

    Hierarchy (View Summary)

    Properties

    adamOpts?: { b1?: number; b2?: number; eps?: number }

    Adam hyperparameters. Default: b1=0.9, b2=0.9, eps=1e-8.

    algorithm?: DlmAlgorithm

    Algorithm selection. Default: auto-select from device/dtype.

    arCoefficients?: number[]

    AR coefficients (initial values). In MATLAB DLM, this is arphi.

    callbacks?: {
        onInit?: (theta: FloatArray) => void;
        onIteration?: (iter: number, theta: FloatArray, deviance: number) => void;
    }

    Callbacks for monitoring optimization progress.

    Type Declaration

    • OptionalonInit?: (theta: FloatArray) => void

      Called before iteration 0 with the initial theta.

    • OptionalonIteration?: (iter: number, theta: FloatArray, deviance: number) => void

      Called after each iteration with updated theta and deviance.

    checkpoint?: number | boolean

    Gradient checkpointing for lax.scan backward pass.

    • true: √N segment checkpointing (O(√N) memory, ~2× compute).
    • false (default): store all N carries (O(N) memory, fastest backward pass).
    • number: explicit segment size.

    Only affects the sequential scan loss path; ignored for assocScan.

    dtype?: DlmDtype

    Computation precision. Default: 'f64'.

    fitAr?: boolean

    Estimate AR coefficients via MLE. In MATLAB DLM, this is fitar.

    fullSeasonal?: boolean

    Full seasonal component (ns-1 dummy variables). In MATLAB DLM, this is fullseas.

    harmonics?: number

    Number of trigonometric harmonic pairs. In MATLAB DLM, this is trig.

    init?: { arCoefficients?: number[]; obsStd?: number; processStd?: number[] }

    Initial parameter guess.

    loss?: DlmLossFn | "ml"

    Custom loss function for MAP estimation or other regularised objectives. Default: 'ml' (standard Kalman prediction-error likelihood).

    When a function is provided it receives:

    1. deviance — Kalman −2·logL (scalar np.Array).
    2. params — natural-scale parameter vector (1-D np.Array).
    3. meta — DlmParamMeta describing the params layout.

    params layout: [s?, w₀, …, w_{m-1}, φ₁, …, φ_p]

    • s and wᵢ are positive std devs (not log-transformed).
    • AR coefficients (when fitAr) are unconstrained.
    • When obsStdFixed is set, the leading s slot is absent.

    The entire chain — Kalman scan + custom penalty + AD backward pass + optimizer update — is wrapped in a single jit() call.

    Tip: use dlmPrior to create a callback with MATLAB DLM-style Inverse-Gamma priors on variances — no manual coding needed.

    const result = await dlmMLE(y, {
      order: 1,
      loss: (deviance, params, meta) => {
        // Split params into [obsStd, processStd] using meta
        const parts = np.split(params, [meta.nObs], 0);
        const processStd = parts[meta.nObs > 0 ? 1 : 0];
        const prior = np.multiply(np.array(0.1), np.sum(np.square(processStd)));
        return np.add(deviance, prior);
      },
    });
    lr?: number

    Adam learning rate. Default: 0.05.

    maxIter?: number

    Maximum optimizer iterations. Default: 200.

    naturalOpts?: {
        fdStep?: number;
        hessian?: "fd" | "exact";
        lambdaGrow?: number;
        lambdaInit?: number;
        lambdaShrink?: number;
    }

    Options for the 'natural' optimizer. Ignored when optimizer is 'adam'.

    Type Declaration

    • OptionalfdStep?: number

      Finite-difference step size for hessian='fd'. Default: 1e-5.

    • Optionalhessian?: "fd" | "exact"

      How to compute the Hessian. Default: 'fd'.

      • 'fd': central finite differences of the JIT'd gradient (2·nParams extra gradient evaluations per step, no extra JIT trace).
      • 'exact': exact AD Hessian via jit(hessian(lossFn)) (jacfwd(grad)). More accurate and avoids FD step-size tuning, but the first call incurs a large JIT compilation overhead (~20 s for nParams=2 on WASM as of jax-js v0.7.8). May become competitive as jax-js JIT improves.
    • OptionallambdaGrow?: number

      λ grow factor on rejected step. Default: 2.

    • OptionallambdaInit?: number

      Initial λ scale: λ₀ = lambdaInit · max(diag(H)). Default: 0.1.

    • OptionallambdaShrink?: number

      λ shrink factor on accepted step. Default: 0.5.

    obsStdFixed?: ArrayLike<number>

    Per-observation σ array (length n). When provided, obsStd is fixed and not estimated. In MATLAB DLM, this is sFixed.

    optimizer?: "adam" | "natural"

    Optimizer selection. Default: 'natural' for f64, 'adam' for f32.

    • 'adam': optax Adam (first-order, diagonal curvature approximation).
    • 'natural': Newton / Fisher scoring (second-order, full Hessian). Solves (H + λI)⁻¹ g with adaptive Levenberg-Marquardt damping. Converges in far fewer iterations than Adam but each step costs more. Best for small parameter spaces (nParams ≤ ~10). Uses lr as step size (default 1.0 for Newton).
    order?: number

    Polynomial trend order: 0 (level), 1 (level + slope), 2 (level + slope + acceleration). Default: 1.

    seasonLength?: number

    Seasons per cycle (period length). In MATLAB DLM, this is ns. Default: 12.

    spline?: boolean

    Spline mode for order=1: modifies W for integrated random walk.

    tol?: number

    Convergence tolerance on relative deviance change. Default: 1e-6.

    X?: ArrayLike<number>[]

    Covariate matrix: n rows × q columns.

    Properties