A1 Closed-Form Prior Elicitation

Maps target beliefs about the number of clusters $(\mu_K, \sigma^2_K)$ to Gamma hyperprior parameters $(a, b)$ using the A1 closed-form approximation based on Negative Binomial moment matching.

Usage

DPprior_a1(
  J,
  mu_K,
  var_K,
  scaling = c("log", "harmonic", "digamma"),
  epsilon = .TOL_PROJECTION_BUFFER,
  projection = c("error", "nearest")
)

Arguments

J: Integer; number of items/sites (must be >= 2).
mu_K: Numeric; target prior mean of $K_J$ (must satisfy $1 < \mu_K < J$).
var_K: Numeric; target prior variance of $K_J$ (must be > 0).
scaling: Character; scaling constant method: "log" (default), "harmonic", or "digamma".
epsilon: Numeric; preferred numerical-interior buffer and near-boundary tolerance. The buffer is adaptively capped in narrow feasible domains and floored at local floating-point spacing. A target is changed only when an explicit projection is requested. Default is .TOL_PROJECTION_BUFFER (1e-6).
projection: Character; A1 target-projection policy. The default "error" never changes the requested target. Set "nearest" to explicitly opt into projection of an A1-infeasible variance to the nearest numerically interior A1 target. The original and projected targets, distance, and policy are retained in the result.

Value

A canonical dpprior.result/1 DPprior_fit object. Gamma shape and rate are in parameters; the immutable canonical target is in target$K; proxy achievements and residuals are in achieved and residuals. The proxy, computation, verification, and provenance records retain the closed-form formula, scaling, projection, and algebraic round-trip evidence. A1 is always labelled status = "approximate", usable = TRUE, and verified = FALSE: its proxy identity is not finite-design verification. Registered flat aliases are migration views and are not authoritative scientific fields.

Details

Theory (TSMM Stage 1)

The A1 method uses a shifted Negative Binomial approximation: $$K_J - 1 \mid \alpha \approx \text{Poisson}(\alpha \cdot c_J)$$

With $\alpha \sim \text{Gamma}(a, b)$, the marginal becomes: $$K_J - 1 \approx \text{NegBin}(a, b/(b + c_J))$$

Inverse Formulas (Theorem 1)

Let $m = \mu_K - 1$ (shifted mean) and $D = \sigma^2_K - m$. If $D > 0$ (overdispersion): $$a = m^2 / D, \quad b = m \cdot c_J / D$$

If $D \leq 0$, the target is infeasible for A1. The default is a typed error. Projection occurs only with projection = "nearest" and emits exactly one typed projection warning.

Feasibility

The NegBin model requires overdispersion: $\sigma^2_K > \mu_K - 1$. High-confidence specifications (low variance) may violate this constraint under the A1 proxy, even though they may be feasible under the exact DP.

References

Lee, J. (2026). Design-Conditional Prior Elicitation for Dirichlet Process Mixtures. arXiv preprint arXiv:2602.06301.

Examples

# Basic usage with moment targets
fit <- DPprior_a1(J = 50, mu_K = 5, var_K = 8)
print(fit)
#> DPprior Prior Elicitation Result
#> ============================================= 
#> 
#> Schema: dpprior.result/1
#> Method: A1 (mode: a1_proxy)
#> Status: approximate; usable: yes; verified: no
#> 
#> Target (J = 50):
#>   E[K_J]   = 5.0000
#>   Var(K_J) = 8.0000
#> 
#> Canonical candidate:
#>   alpha ~ Gamma(a = 4.0000, b = 3.9120)
#>   Achieved E[K_J] = 5.000000; Var(K_J) = 8.000000
#>   Maximum absolute moment residual = 0.00e+00
#> 
#> Canonical guidance: A1 proxy mapping was verified; the finite-J target was not independently verified. This canonical candidate is not decision-ready; inspect status and verification evidence before use.

# Using VIF specification
fit <- DPprior_a1(J = 50, mu_K = 5, var_K = vif_to_variance(5, 2))

# Using confidence-based specification
vif <- confidence_to_vif("medium")
fit <- DPprior_a1(J = 50, mu_K = 5, var_K = vif_to_variance(5, vif))

# Explicit projection of an A1-infeasible variance
fit <- DPprior_a1(J = 50, mu_K = 5, var_K = 3,
                  projection = "nearest")
#> Warning: A1 target projection explicitly requested: var_K 3 -> 4.000017 (distance 1.000017; fixed-support upper bound 180).

# Compare scaling methods
fit_log <- DPprior_a1(50, 5, 8, scaling = "log")
fit_harm <- DPprior_a1(50, 5, 8, scaling = "harmonic")