Define a PheWAS analysis specification — phewas

A specification describes exactly one fixed anchor and one family of phenotype tests. Metadata may use native list-columns for levels and scores, or |-delimited strings when it comes from TSV/YAML files. The canonical metadata vocabulary is phenotype, description, group, groupnum, and color; phenotype names the analysis-data column. Legacy phenotype_id/phecode/phenotype_column/column, label, category, and category_order fields are accepted only when they agree with any canonical fields supplied in the same table, and are not retained in the validated specification.

Usage

phewas_spec(
  analysis_id,
  anchor,
  direction = c("phenotypes_as_outcomes", "phenotypes_as_predictors"),
  phenotypes,
  covariates = character(),
  outcome_type = NULL,
  anchor_type = NULL,
  anchor_transform = c("none", "zscore"),
  anchor_reference = NULL,
  anchor_levels = NULL,
  anchor_scores = NULL,
  offset = NULL,
  exclusion_column = NULL,
  exclusion_values = NULL,
  eligibility,
  fdr_threshold,
  version = "1.0"
)

Arguments

analysis_id: Stable, unique name for the analysis.
anchor: Name of the fixed predictor (phenotypes as outcomes) or fixed outcome (phenotypes as predictors).
direction: Either "phenotypes_as_outcomes" or "phenotypes_as_predictors".
phenotypes: Data frame with phenotype metadata. Required columns are phenotype, description, group, groupnum, and color. Missing or blank variable_type values default to "binary"; binary phenotypes with a missing or blank reference default to "0". Outcome scans additionally require outcome_type.
covariates: Character vector of adjustment-variable columns.
outcome_type: Fixed-anchor outcome type for phenotype-predictor scans.
anchor_type: Fixed-anchor type. Required for phenotype-outcome scans.
anchor_transform: Either "none" or "zscore".
anchor_reference: Explicit reference for a binary anchor.
anchor_levels: Explicit ordered levels for an ordinal anchor.
anchor_scores: Optional strictly increasing ordinal-trend scores.
offset: Optional log-offset column for a fixed count outcome.
exclusion_column: Optional cohort marker column. Matching rows are removed before base-cohort completeness and anchor transformation.
exclusion_values: Explicit marker values to remove. Missing marker values are retained.
eligibility: Explicit named list containing min_n, min_cases, min_controls, and min_outcome_levels. min_cases and min_controls set the minimum non-reference and reference counts for each scanned binary phenotype, whether it is modeled as an outcome or predictor. They also protect event and nonevent counts when the fixed outcome is binary.
fdr_threshold: Threshold used to flag BH-adjusted results.
version: Specification schema version.

Value

A validated object of class phewas_spec.