Declare how observations were collected — declarations • studyframe

Declarations use stable variable identifiers, initially equal to column names. Unknown components remain unknown; constructors do not infer a design from data. Sources describe the evidence for a declaration, not proof of its truth.

Usage

variable_spec(
  id,
  column = id,
  label = "",
  units = NULL,
  categories = list(),
  missing = list(),
  wave = NULL,
  source = "",
  status = "unknown",
  evidence = character(),
  instrument = NULL
)

sampling_stage(
  unit,
  strata = NULL,
  replacement = "unknown",
  method = "unknown",
  probability = NULL,
  fpc = NULL,
  fpc_kind = "population_size"
)

sampling_spec(
  id,
  population = "",
  stages = list(),
  state = "known",
  source = "",
  status = "documented",
  evidence = character(),
  phase = "realized"
)

variance_spec(
  method = "taylor",
  replicates = character(),
  combined = TRUE,
  scale = NULL,
  rscales = numeric(),
  mse = TRUE,
  rho = NULL,
  lonely_psu = "fail"
)

weight_spec(
  id,
  variable,
  sampling = NULL,
  role = "base",
  waves = character(),
  applies = list(),
  adjustments = character(),
  variance = variance_spec(),
  source = "",
  status = "documented",
  evidence = character(),
  phase = "realized"
)

assignment_spec(
  id,
  treatment,
  unit,
  blocks = NULL,
  mechanism = "unknown",
  prob = NULL,
  conditions = c(0, 1),
  state = "known",
  source = "",
  status = "documented",
  evidence = character(),
  phase = "realized"
)

Arguments

id: Stable identifier for a variable or declaration.
column: Column containing a variable (defaults to its identifier).
label: Human-readable definition.
units: Measurement units, or NULL when not documented.
categories: List of lists with value and label fields.
missing: List of lists with value and reason fields. Codes are retained in storage; adapters convert declared codes to NA before analysis.
wave: Measurement occasion, or NULL when not documented.
source: Source or explanation for the declaration.
status: One of documented, assumed, or unknown.
evidence: Character vector of source-artifact IDs.
instrument: An instrument_ref or NULL.
unit: Variable identifying sampling or assignment units.
strata: Variable identifying sampling strata, or NULL.
replacement: With, without, or unknown replacement.
method: Sampling method (srs, pps, unknown) or variance method.
probability: Variable containing stage inclusion probabilities, or NULL.
fpc: Variable containing finite-population information, or NULL.
fpc_kind: Interpretation of fpc: population_size or sampling_fraction.
population: Description of the population or frame.
stages: Ordered list of sampling_stage declarations.
state: known, unknown, or not_applicable.
phase: planned or realized; only realized declarations support inference.
replicates: Stable identifiers of replicate-weight columns.
combined: Whether replicate columns already include full-sample weights.
scale: Overall replicate variance scaling constant, or NULL.
rscales: Per-replicate scaling constants.
mse: Center replicate deviations at the full-sample estimate.
rho: Fay's parameter, or NULL.
lonely_psu: Explicit single-PSU handling policy (default fail).
variable: Variable containing a weight.
sampling: Identifier of the associated sampling declaration, or NULL.
role: Weight role: base, final, or analysis.
waves: Measurement occasions supported by the weight. Empty means applicability is undocumented, not that every occasion is supported.
applies: List of rules, each with a variable and a list of values. Rules are conjoined and define the weight's reference sample.
adjustments: Documented weight adjustments, as character strings.
variance: A variance_spec declaration.
treatment: Variable containing realized assignment.
blocks: Variable identifying assignment blocks, or NULL.
mechanism: complete, bernoulli, or unknown assignment.
prob: Probability of the second condition, constant across units.
conditions: Two ordered assignment codes: control, treatment.

Value

A plain list conforming to a component of the studyframe schema.

Examples

stage <- sampling_stage("school", method = "srs", strata = "district", replacement = "with")
design <- sampling_spec("sample", "District pupils", list(stage), source = "Protocol")
weight <- weight_spec("main", "weight", sampling = "sample", source = "Release guide")