dlm-js
    Preparing search index...

    Function dlmMLE

    • Estimate DLM parameters (s, w, and optionally arphi) by maximum likelihood via autodiff.

      The entire optimization step — valueAndGrad(loss) (Kalman filter forward pass + AD backward pass) and optax Adam moment/parameter updates — is wrapped in a single jit() call, so every iteration runs from compiled code.

      The parameterization maps unconstrained reals → positive values: s = exp(θ_s), w[i] = exp(θ_{w,i}) AR coefficients (when options.fitar = true) are optimized directly (unconstrained — not log-transformed, matching MATLAB DLM behavior).

      When sFixed is supplied (a per-timestep σ array, e.g. known measurement uncertainties), the observation noise is not estimated — it is treated as a known constant. Only W (and optionally arphi) are optimized. The returned s field will be NaN in this case.

      Parameters

      • y: ArrayLike<number>

        Observations (n×1)

      • options: DlmOptions = {}

        Model specification (order, trig, ns, arphi, fitar, etc.)

      • Optionalinit: { arphi?: number[]; s?: number; w?: number[] }

        Initial guess for parameters (optional; arphi defaults to options.arphi)

      • maxIter: number = 200

        Maximum optimizer iterations (default: 200)

      • lr: number = 0.05

        Learning rate for Adam (default: 0.05)

      • tol: number = 1e-6

        Convergence tolerance on relative lik change (default: 1e-6). Requires 5 consecutive steps below this threshold before stopping, to guard against transient near-zero steps during oscillation (e.g. assocScan path).

      • dtype: DType = DType.Float64

        Computation precision (default: Float64)

      • Optionalcallbacks: {
            onInit?: (
                theta: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>,
            ) => void;
            onIteration?: (
                iter: number,
                theta: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>,
                lik: number,
            ) => void;
        }
        • OptionalonInit?: (theta: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>) => void

          Called before iteration 0 with the initial theta.

        • OptionalonIteration?: (
              iter: number,
              theta: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike>,
              lik: number,
          ) => void

          Called after each iteration with the updated theta and lik.

      • OptionalX: ArrayLike<number>[]

        Optional covariate matrix (n rows × q cols), passed through to dlmFit

      • OptionalsFixed: ArrayLike<number>

        Optional per-timestep σ array (length n). When provided, s is fixed and not estimated; only W is optimized.

      • OptionaladamOpts: any

        Optional Adam hyperparameters (b1, b2, eps). Default: b1=0.9, b2=0.9, eps=1e-8. The b2=0.9 default is much faster to adapt than the canonical 0.999 on DLM likelihoods (measured: reaches same loss in ~3× fewer iterations on Nile and ozone benchmarks).

      • OptionalforceAssocScan: boolean

        Force use of makeKalmanLossAssoc (associativeScan-based loss) regardless of device/dtype. Useful for benchmarking the parallel loss path on CPU/WASM backends where it would not normally be selected.

      Returns Promise<DlmMleResult>

      MLE result with estimated parameters and full DLM fit