Quantile of Marginal K Distribution

Computes the \(p\)-th quantile of the marginal distribution of \(K_J\).

Usage

quantile_K_marginal(
  p,
  J,
  a,
  b,
  logS,
  M = .QUAD_NODES_DEFAULT,
  M_verify = NULL,
  abs_tol = 1e-10,
  rel_tol = 1e-08,
  strict = FALSE
)

Arguments

p

Numeric; probability level(s) in \([0, 1]\). Can be scalar or vector.

J

Integer; sample size.

a

Numeric; shape parameter of Gamma prior (> 0).

b

Numeric; rate parameter of Gamma prior (> 0).

logS

Matrix; pre-computed log-Stirling matrix.

M

Integer; number of quadrature nodes (default: 80).

M_verify

Optional independent order satisfying the package verification rule (at least max(2*M, M+40)).

abs_tol, rel_tol

Non-negative selected-versus-verification tolerances.

strict

Logical; require successful higher-order verification.

Value

Integer vector of quantiles (same length as p). Each element is the smallest \(k\) such that \(P(K_J \leq k) \geq p\). The vector carries the CDF's "marginal_metadata" attribute so an approximate, unverified, or discrepant quadrature result is not silent.

Details

This is the standard quantile definition for discrete distributions: \(Q(p) = \min\{k : F(k) \geq p\}\). The lower endpoint follows the mathematical support: \(Q(0)=1\), while \(Q(1)=J\). The structural \(k=0\) vector entry is never returned.

The function is vectorized over p, allowing efficient computation of multiple quantiles in a single call. When M_verify is supplied, the selected- and verification-order integer quantiles are also compared exactly. A changed quantile downgrades metadata to "approximate"; strict = TRUE raises a typed convergence error. The selected-order quantile is always retained.

See also

cdf_K_marginal, pmf_K_marginal

Other marginal_K: K_moments(), cdf_K_marginal(), exact_K_moments(), mode_K_marginal(), pmf_K_marginal(), summary_K_marginal()

Examples

logS <- compute_log_stirling(50)

# Single quantile (median)
quantile_K_marginal(0.5, 50, 1.5, 0.5, logS)
#> [1] 8
#> attr(,"marginal_metadata")
#> attr(,"marginal_metadata")$schema_version
#> [1] 1
#> 
#> attr(,"marginal_metadata")$engine
#> [1] "gauss-laguerre-log-mixture"
#> 
#> attr(,"marginal_metadata")$status
#> [1] "approximate"
#> 
#> attr(,"marginal_metadata")$reason
#> [1] "fixed_order_unverified"
#> 
#> attr(,"marginal_metadata")$support
#> lower upper 
#>     1    50 
#> 
#> attr(,"marginal_metadata")$returned_support
#> lower upper 
#>     0    50 
#> 
#> attr(,"marginal_metadata")$normalization
#> attr(,"marginal_metadata")$normalization$log_constant
#> [1] 0
#> 
#> attr(,"marginal_metadata")$normalization$probability_sum
#> [1] 1
#> 
#> attr(,"marginal_metadata")$normalization$underflow_zero_count
#> [1] 0
#> 
#> attr(,"marginal_metadata")$normalization$pre_rescale_probability_sum
#> [1] 1
#> 
#> attr(,"marginal_metadata")$normalization$linear_rescale
#> [1] 0
#> 
#> 
#> attr(,"marginal_metadata")$truncation
#> attr(,"marginal_metadata")$truncation$truncated
#> [1] FALSE
#> 
#> attr(,"marginal_metadata")$truncation$requested_mass
#> [1] 1
#> 
#> attr(,"marginal_metadata")$truncation$achieved_mass
#> [1] 1
#> 
#> attr(,"marginal_metadata")$truncation$omitted_mass
#> [1] 0
#> 
#> 
#> attr(,"marginal_metadata")$verification
#> attr(,"marginal_metadata")$verification$performed
#> [1] FALSE
#> 
#> attr(,"marginal_metadata")$verification$passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$M_selected
#> [1] 80
#> 
#> attr(,"marginal_metadata")$verification$M_verification_required
#> [1] 160
#> 
#> attr(,"marginal_metadata")$verification$verification_available
#> [1] TRUE
#> 
#> attr(,"marginal_metadata")$verification$M_verification
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$l1_difference
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$max_difference
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$tolerance
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$l1_passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$moment_consistency
#> attr(,"marginal_metadata")$verification$moment_consistency$passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$moment_consistency$selected
#> NULL
#> 
#> attr(,"marginal_metadata")$verification$moment_consistency$verification
#> NULL
#> 
#> 
#> attr(,"marginal_metadata")$verification$absolute_tolerance
#> [1] 1e-10
#> 
#> attr(,"marginal_metadata")$verification$relative_tolerance
#> [1] 1e-08
#> 
#> 
#> attr(,"marginal_metadata")$selected
#> attr(,"marginal_metadata")$selected$schema_version
#> [1] 1
#> 
#> attr(,"marginal_metadata")$selected$distribution
#> [1] "Gamma(shape, rate)"
#> 
#> attr(,"marginal_metadata")$selected$shape
#> [1] 1.5
#> 
#> attr(,"marginal_metadata")$selected$rate
#> [1] 0.5
#> 
#> attr(,"marginal_metadata")$selected$M_selected
#> [1] 80
#> 
#> attr(,"marginal_metadata")$selected$M_verification
#> [1] NA
#> 
#> attr(,"marginal_metadata")$selected$normalization
#> [1] "log-sum-exp"
#> 
#> attr(,"marginal_metadata")$selected$normalized_weight_sum
#> [1] 1
#> 
#> attr(,"marginal_metadata")$selected$node_rule
#> attr(,"marginal_metadata")$selected$node_rule$schema_version
#> [1] 1
#> 
#> attr(,"marginal_metadata")$selected$node_rule$engine
#> [1] "golub-welsch-dense-eigen"
#> 
#> attr(,"marginal_metadata")$selected$node_rule$M_selected
#> [1] 80
#> 
#> attr(,"marginal_metadata")$selected$node_rule$alpha_param
#> [1] 0.5
#> 
#> attr(,"marginal_metadata")$selected$node_rule$cache_key
#> [1] "M=80|alpha=0.5"
#> 
#> attr(,"marginal_metadata")$selected$node_rule$cache_hit
#> [1] TRUE
#> 
#> attr(,"marginal_metadata")$selected$node_rule$zero_normalized_weights
#> [1] 29
#> 
#> attr(,"marginal_metadata")$selected$node_rule$normalized_weight_sum
#> [1] 1
#> 
#> 
#> 
#> attr(,"marginal_metadata")$verification_rule
#> NULL
#> 
#> attr(,"marginal_metadata")$discrete_verification
#> attr(,"marginal_metadata")$discrete_verification$quantile
#> attr(,"marginal_metadata")$discrete_verification$quantile$performed
#> [1] FALSE
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$probabilities
#> [1] 0.5
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$selected
#> [1] 8
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$verification
#> NULL
#> 
#> 
#> 

# Multiple quantiles at once
quantile_K_marginal(c(0.1, 0.25, 0.5, 0.75, 0.9), 50, 1.5, 0.5, logS)
#> [1]  3  5  8 11 15
#> attr(,"marginal_metadata")
#> attr(,"marginal_metadata")$schema_version
#> [1] 1
#> 
#> attr(,"marginal_metadata")$engine
#> [1] "gauss-laguerre-log-mixture"
#> 
#> attr(,"marginal_metadata")$status
#> [1] "approximate"
#> 
#> attr(,"marginal_metadata")$reason
#> [1] "fixed_order_unverified"
#> 
#> attr(,"marginal_metadata")$support
#> lower upper 
#>     1    50 
#> 
#> attr(,"marginal_metadata")$returned_support
#> lower upper 
#>     0    50 
#> 
#> attr(,"marginal_metadata")$normalization
#> attr(,"marginal_metadata")$normalization$log_constant
#> [1] 0
#> 
#> attr(,"marginal_metadata")$normalization$probability_sum
#> [1] 1
#> 
#> attr(,"marginal_metadata")$normalization$underflow_zero_count
#> [1] 0
#> 
#> attr(,"marginal_metadata")$normalization$pre_rescale_probability_sum
#> [1] 1
#> 
#> attr(,"marginal_metadata")$normalization$linear_rescale
#> [1] 0
#> 
#> 
#> attr(,"marginal_metadata")$truncation
#> attr(,"marginal_metadata")$truncation$truncated
#> [1] FALSE
#> 
#> attr(,"marginal_metadata")$truncation$requested_mass
#> [1] 1
#> 
#> attr(,"marginal_metadata")$truncation$achieved_mass
#> [1] 1
#> 
#> attr(,"marginal_metadata")$truncation$omitted_mass
#> [1] 0
#> 
#> 
#> attr(,"marginal_metadata")$verification
#> attr(,"marginal_metadata")$verification$performed
#> [1] FALSE
#> 
#> attr(,"marginal_metadata")$verification$passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$M_selected
#> [1] 80
#> 
#> attr(,"marginal_metadata")$verification$M_verification_required
#> [1] 160
#> 
#> attr(,"marginal_metadata")$verification$verification_available
#> [1] TRUE
#> 
#> attr(,"marginal_metadata")$verification$M_verification
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$l1_difference
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$max_difference
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$tolerance
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$l1_passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$moment_consistency
#> attr(,"marginal_metadata")$verification$moment_consistency$passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$verification$moment_consistency$selected
#> NULL
#> 
#> attr(,"marginal_metadata")$verification$moment_consistency$verification
#> NULL
#> 
#> 
#> attr(,"marginal_metadata")$verification$absolute_tolerance
#> [1] 1e-10
#> 
#> attr(,"marginal_metadata")$verification$relative_tolerance
#> [1] 1e-08
#> 
#> 
#> attr(,"marginal_metadata")$selected
#> attr(,"marginal_metadata")$selected$schema_version
#> [1] 1
#> 
#> attr(,"marginal_metadata")$selected$distribution
#> [1] "Gamma(shape, rate)"
#> 
#> attr(,"marginal_metadata")$selected$shape
#> [1] 1.5
#> 
#> attr(,"marginal_metadata")$selected$rate
#> [1] 0.5
#> 
#> attr(,"marginal_metadata")$selected$M_selected
#> [1] 80
#> 
#> attr(,"marginal_metadata")$selected$M_verification
#> [1] NA
#> 
#> attr(,"marginal_metadata")$selected$normalization
#> [1] "log-sum-exp"
#> 
#> attr(,"marginal_metadata")$selected$normalized_weight_sum
#> [1] 1
#> 
#> attr(,"marginal_metadata")$selected$node_rule
#> attr(,"marginal_metadata")$selected$node_rule$schema_version
#> [1] 1
#> 
#> attr(,"marginal_metadata")$selected$node_rule$engine
#> [1] "golub-welsch-dense-eigen"
#> 
#> attr(,"marginal_metadata")$selected$node_rule$M_selected
#> [1] 80
#> 
#> attr(,"marginal_metadata")$selected$node_rule$alpha_param
#> [1] 0.5
#> 
#> attr(,"marginal_metadata")$selected$node_rule$cache_key
#> [1] "M=80|alpha=0.5"
#> 
#> attr(,"marginal_metadata")$selected$node_rule$cache_hit
#> [1] TRUE
#> 
#> attr(,"marginal_metadata")$selected$node_rule$zero_normalized_weights
#> [1] 29
#> 
#> attr(,"marginal_metadata")$selected$node_rule$normalized_weight_sum
#> [1] 1
#> 
#> 
#> 
#> attr(,"marginal_metadata")$verification_rule
#> NULL
#> 
#> attr(,"marginal_metadata")$discrete_verification
#> attr(,"marginal_metadata")$discrete_verification$quantile
#> attr(,"marginal_metadata")$discrete_verification$quantile$performed
#> [1] FALSE
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$passed
#> [1] NA
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$probabilities
#> [1] 0.10 0.25 0.50 0.75 0.90
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$selected
#> [1]  3  5  8 11 15
#> 
#> attr(,"marginal_metadata")$discrete_verification$quantile$verification
#> NULL
#> 
#> 
#> 

# Interquartile range
qs <- quantile_K_marginal(c(0.25, 0.75), 50, 1.5, 0.5, logS)
diff(qs)
#> [1] 6