Run one PheWAS testing family — run

Fits every selected phenotype in deterministic metadata order. Parallel execution uses a cross-platform PSOCK cluster and yields rows in the same order as sequential execution.

Usage

run_phewas(
  data,
  spec,
  backend = c("sequential", "psock"),
  workers = 1L,
  phenotype_ids = NULL,
  adjust = TRUE
)

Arguments

data: Analysis-ready data containing every column declared in spec.
spec: A validated phewas_spec.
backend: Either "sequential" or "psock".
workers: Positive number of PSOCK workers.
phenotype_ids: Optional explicit subset of phenotype values. This argument name is retained for API compatibility; result and metadata columns use the canonical name phenotype.
adjust: Apply BH and Bonferroni correction across all successful rows.

Value

A data.table subclass phewas_result, with spec and run_metadata attributes and one row per requested phenotype. formula and covariates record the requested model. effective_formula, effective_covariates, and dropped_invariant_covariates record the outcome-specific model after omitting covariates that are constant on its complete cases.

Details

Results support normal data.table operations. Use data.table::copy() before modifying a result with :=, or as.data.frame() for base-data-frame subsetting semantics. log_p is the authoritative natural-log p-value; neg_log10_p, the printable p_value_text, and all multiple-testing fields are derived without first rounding through a numeric p-value. Thus p_value may underflow to zero while the log-scale and text fields remain valid.

Examples

example <- phewas_example_data(n = 200)
spec <- phewas_spec(
  analysis_id = "example",
  anchor = "pgs",
  direction = "phenotypes_as_outcomes",
  phenotypes = example$forward_metadata,
  covariates = "age",
  anchor_type = "numeric",
  anchor_transform = "zscore",
  eligibility = list(
    min_n = 100L, min_cases = 10L, min_controls = 10L,
    min_outcome_levels = 3L
  ),
  fdr_threshold = 0.05
)
result <- run_phewas(example$data, spec)
as.data.frame(result)[c("phenotype", "description", "engine", "estimate",
  "status")]
#>          phenotype          description  engine  estimate status
#> 1     pheno_binary     Binary phenotype logistf 0.5552552     ok
#> 2 pheno_continuous Continuous phenotype      lm 0.8218222     ok
#> 3      pheno_count      Count phenotype  glm.nb 0.3835541     ok
#> 4    pheno_ordinal    Ordinal phenotype     clm 0.8701061     ok