Specifies source conditioning in a selection model

selection_model() declares which sources a selection model conditions on or integrates out, and how estimate-level publication weights combine within a selection group. These are fixed model choices, not parameters with prior distributions.

selection_model(
  estimate_random_effects = "integrate",
  other_random_effects = "condition",
  known_sampling_variance = "integrate",
  weight_rule = "product",
  group = NULL
)

selection_model_spec(prior)

check_selection_model(model, name = "model")

# S3 method for class 'selection_model'
print(x, ...)

Arguments

estimate_random_effects

either "integrate" (the default) or "condition" for the estimate-level random-effect term. In a random formula, this is the sole declared term whose grouping map has one distinct level per retained estimate. No such term is required; multiple qualifying terms are an error when the model binds its data.

other_random_effects

either "condition" (the default) or "integrate" for all remaining declared random-effect terms.

known_sampling_variance

either "integrate" (the default) or "condition" for the complete sampling-error vector with known covariance. This choice also applies to univariate models and independent sampling errors. Conditioning retains the full unknown realized error; integration averages its full distribution before selection normalization.

weight_rule

either "product" (the default), the product of estimate weights, or "best", the weight of the bin containing the smallest p-value within each publication group. The best-p-value rule does not select the largest publication weight.

group

publication-group column for weight_rule = "best", specified as a bare or backticked column name or a single character string. The default NULL requests automatic resolution by the consuming model; a best-rule branch requires resolved publication groups when its data are bound. Product selection is invariant to publication partitions, so under weight_rule = "product" no publication-group column is required or resolved and print() reports the group as unused. Supplying a group alongside the product rule is inert rather than an error, so that a caller can parameterize weight_rule and forward one group for both rules. References are captured without evaluating the column. Derived groups must first be stored as data columns.

prior

a single prior object or NULL. Mixtures must be examined one branch at a time.

model

a selection-model specification to validate.

name

argument name used in validation messages.

x

a selection-model specification.

...

additional arguments, currently unused.

Value

selection_model() returns an object of class selection_model containing only the four choices and a character column reference or NULL. selection_model_spec() returns the validated specification from a weightfunction prior or the selection child of a composed prior_bias(); it returns NULL for a prior without a selection component. check_selection_model() and print() invisibly return their validated input.

Details

The three source choices are independent. Conditioning retains unknown latent effects during selection normalization; it does not make them observed or fixed. Integration averages the source before normalization. Sampling versus marginalizing a JAGS node is a separate computational choice. The consuming model binds source roles and, for the best-p-value rule, publication groups to its data, so a prior can be constructed before data exist. An ensemble needs publication groups only for its best-rule branches.

Publication groups describe how the best-p-value selection rule combines outcomes. They do not create random effects or define sampling covariance. Under the product rule, multiplying all estimate weights gives the same selection weight for every partition into groups. Its joint normalization therefore does not depend on group, including with correlated outcomes. Integration blocks instead follow dependencies from sampling covariance and random effects marked "integrate"; assigning singleton publication groups does not make correlated outcomes independent. A consuming model may impose additional covariance-support restrictions on best-rule publication groups.

Known sampling covariance \(V\) describes the complete error vector \(e \sim N(0,V)\). With positive sampling standard deviations it can be written as \(V = S R S\) and \(e = S z\), where \(S\) contains the standard deviations and \(z \sim N(0,R)\). Conditioning retains all of \(e\); there is no automatically integrated residual sampling component. Covariance factorizations are computational representations and do not define additional selection sources. P-values retain the original marginal sampling standard deviations under either choice.

If every nonzero source is conditioned on, the candidate result is deterministic. Positive selection weights then cancel in normalization, leaving the unselected distribution and no likelihood information about those weights. A retained context with zero acceptance probability has no normalized selected distribution and must not be silently discarded.

Estimate-level identification follows the declared grouping map, not numerical independence, coefficient supports, or posterior variances. A one-to-one term with correlated known group covariance remains estimate-level and retains that full covariance. Other terms are not split into coefficient families. See random_effects_level_roles() for the shared formula resolver.

Ordinary forwarding through wrapper arguments preserves the original column reference. Wrappers can also explicitly forward with group = {{group}}. To pass a column name stored in a variable, use do.call(selection_model, list(group = column_name)). A bare symbol always denotes a column, even if a vector with that name exists elsewhere.

Examples

model <- selection_model(
  estimate_random_effects = "integrate",
  other_random_effects = "condition",
  known_sampling_variance = "integrate",
  weight_rule = "best",
  group = paper_id
)
p <- prior_weightfunction(steps = .05, model = model)
selection_model_spec(p)
#> Selection model:
#>   Estimate random effects: integrate (average effects before normalization).
#>   Other random effects: condition (retain unknown effects during normalization).
#>   Known sampling error: integrate (average full error vector before normalization).
#>   Weight rule: best (Weight of the best p-value).
#>   Group: 'paper_id' (unresolved data column).
#>   Sources are resolved when model data are bound.