Construct a validated analysis specification — analysis

One specification carries the same complete target declaration through a draft, ranked proposal, and analyst-confirmed component decision. Target direction is explicit: binary targets use neutral reference/comparison levels, ordered targets use ordered_levels, and continuous targets use an increasing/decreasing direction.

Usage

analysis_specification(
  id,
  target_field,
  target_type,
  reference_level = NULL,
  comparison_level = NULL,
  ordered_levels = character(0L),
  continuous_direction = NULL,
  lifecycle = "draft",
  selected_component = NULL,
  proposal_digest = NULL,
  proposal_decision = NULL,
  analyst_rationale = NULL,
  nuisance_fields = character(0L),
  orientation_anchor = NULL,
  claim_intent = c("exploratory", "primary_confirmatory")
)

Arguments

id: non-empty run identity
target_field: one colData target field
target_type: "binary", "ordered", or "continuous"
reference_level, comparison_level: binary target direction
ordered_levels: ordered target levels in predeclared direction
continuous_direction: "increasing" or "decreasing"
lifecycle: "draft", "proposal", or "confirmed"
selected_component: positive component index in the frozen reference basis; confirmed lifecycle only
proposal_digest: SHA-256 digest of the ranked proposal; proposal and confirmed lifecycles only
proposal_decision: "accepted" or "overridden"; confirmed lifecycle only
analyst_rationale: non-empty analyst rationale; confirmed lifecycle only
nuisance_fields: unique colData fields declared as confounders
orientation_anchor: optional numeric non-degenerate colData field distinct from target and nuisance roles
claim_intent: "exploratory" (default) or "primary_confirmatory"; intent does not establish eligibility

Value

a validated AnalysisSpecification v2 object

Details

A draft has no proposal or confirmation fields. A proposal adds only proposal_digest. A confirmed specification requires selected_component, the proposal digest, an accepted/overridden decision, and non-empty analyst rationale. Real-data confirmation remains a analyst action; this constructor validates the record but does not recommend a component.

Examples

draft <- analysis_specification(
    id = "aml-time",
    target_field = "weeks",
    target_type = "continuous",
    continuous_direction = "increasing"
)

confirmed <- analysis_specification(
    id = "aml-time",
    target_field = "weeks",
    target_type = "continuous",
    continuous_direction = "increasing",
    lifecycle = "confirmed",
    selected_component = 2L,
    proposal_digest = strrep("a", 64L),
    proposal_decision = "accepted",
    analyst_rationale = "Accepted the predeclared top-ranked component."
)