@spec alpha_beta_apply_measurement(
  Sidereon.Estimation.AlphaBetaState.t() | map(),
  number(),
  number(),
  Sidereon.Estimation.AlphaBetaGains.t() | map()
) ::
  {:ok, Sidereon.Estimation.AlphaBetaState.t()}
  | {:error, primitive_error() | :invalid_state | :invalid_gains}

Apply one scalar measurement to a predicted alpha-beta state.

@spec alpha_beta_filter_step(
  Sidereon.Estimation.AlphaBetaState.t() | map(),
  number(),
  number(),
  Sidereon.Estimation.AlphaBetaGains.t() | map()
) ::
  {:ok, Sidereon.Estimation.AlphaBetaStep.t()}
  | {:error, primitive_error() | :invalid_state | :invalid_gains}

Run one alpha-beta predict and measurement update step.

@spec alpha_beta_predict(Sidereon.Estimation.AlphaBetaState.t() | map(), number()) ::
  {:ok, Sidereon.Estimation.AlphaBetaState.t()}
  | {:error, primitive_error() | :invalid_state}

Project an alpha-beta state by dt without applying a measurement.

@spec alpha_beta_steady_state_gains(number()) ::
  {:ok, Sidereon.Estimation.AlphaBetaGains.t()} | {:error, primitive_error()}

Compute steady-state alpha-beta gains from a positive tracking index.

@spec cfar_ca_false_alarm_probability(pos_integer(), number(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

CA-CFAR false-alarm probability from absolute threshold and noise level.

@spec cfar_ca_multiplier_from_pfa(pos_integer(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

CA-CFAR threshold multiplier from searched-cell count and target false-alarm probability.

@spec cfar_ca_pfa_from_multiplier(pos_integer(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

CA-CFAR false-alarm probability from searched-cell count and multiplier.

@spec cfar_ca_threshold(pos_integer(), number(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

CA-CFAR absolute threshold from searched cells, target false-alarm probability, and noise level.

@spec ewma(number(), number(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

Exponentially weighted moving average update.

alpha must be in [0, 1].

@spec ewma_power_of_two(number(), number(), non_neg_integer()) ::
  {:ok, float()} | {:error, primitive_error()}

EWMA update with alpha = 1 / 2^shift.

@spec kalman_cv_steady_state_gains(number(), number(), number()) ::
  {:ok, Sidereon.Estimation.ScalarKalmanGains.t()} | {:error, primitive_error()}

Compute steady-state gains for the scalar constant-velocity Kalman model.

dt is the sample interval in seconds and measurement_variance is in squared measurement units.

@spec mad([number()], number()) :: {:ok, float()} | {:error, primitive_error()}

Median absolute deviation spread estimate with Gaussian consistency scaling.

scale_floor is a non-negative lower bound on the returned spread.

@spec mad_gaussian_consistency() :: float()

MAD Gaussian consistency factor 1 / Phi^-1(3/4).

@spec nis(number(), number()) :: {:ok, float()} | {:error, primitive_error()}

Normalized innovation squared statistic.

@spec nis_expected_value(pos_integer()) ::
  {:ok, float()} | {:error, primitive_error()}

Expected NIS value for a positive number of degrees of freedom.

@spec nis_gate(number(), number(), pos_integer(), number()) ::
  {:ok, Sidereon.Estimation.NisGate.t()} | {:error, primitive_error()}

Test a scalar innovation against a chi-square NIS gate.

@spec nis_gate_threshold(pos_integer(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

Chi-square gate threshold for dof and confidence in (0, 1).

@spec normalized_innovation(number(), number()) ::
  {:ok, float()} | {:error, primitive_error()}

Scalar normalized innovation innovation / sqrt(innovation_variance).