Summarize QQ Plots and Per-Test Lambda Values

Source: R/summarize_qq_and_lambdas.R

Computes per-test \(\lambda_{\mathrm{GC}}\) values for a vector of test columns, writes a single-series QQ plot for the headline omnibus, optionally writes a multi-panel per-family QQ plot, and (optionally) saves the lambdas to an RDS for downstream consumption. All written artifacts are tagged with label so the caller can run the function twice (e.g. on the full set and on a subset) without filename collisions.

summarize_qq_and_lambdas(
  df,
  label,
  output_dir,
  test_columns = NULL,
  omni_test,
  families = NULL,
  subtitle = NULL,
  rds_basename = ".family_lambdas",
  pdf_basename_omni = "qq_omni",
  pdf_basename_family = "qq_by_family",
  family_palette = NULL,
  palette_pch = c(16, 17, 15, 18, 8, 4),
  family_title = NULL,
  write_rds = TRUE,
  verbose = TRUE
)

Arguments

df

data.frame of results, one row per analysis unit; must contain every column in test_columns and omni_test.

label

Short string used as the filename / title suffix.

output_dir

Directory to write the PDFs and RDS into (created if missing).

test_columns

Character vector of column names whose p-values get a lambda entry. May be NULL only if families is given (then derived as unlist(families)).

omni_test

Character. Name of the headline omnibus column; must be in test_columns.

families

Optional named list mapping family label -> character vector of test columns to draw on that panel. If NULL, the per-family PDF is skipped. If supplied alongside test_columns, the two sets must match.

subtitle

Optional string appended to the omni title and drawn as outer mtext on the family grid.

rds_basename

File-stem for the lambdas RDS (default ".family_lambdas"; final name "<basename>_<label>.rds").

pdf_basename_omni

File-stem for the qq_omni PDF. Default "qq_omni".

pdf_basename_family

File-stem for the qq_by_family PDF. Default "qq_by_family".

family_palette

Optional character vector of colors for the family-grid points; NULL uses hcl.colors(max_family_size, "Dark 3").

palette_pch

Optional integer vector of plotting symbols cycled by within-family position. Default c(16, 17, 15, 18, 8, 4).

family_title

Optional function(fam) -> character for the panel title; NULL (default) uses "<fam> family".

write_rds

Logical. If TRUE (default), save the per-test lambdas to "<rds_basename>_<label>.rds".

verbose

Logical. If TRUE (default), cats a timestamped line per written file.

Value

Invisibly, a list with lambda_omni, lambdas (named per test_columns), n (nrow(df)), and paths (qq_omni; qq_by_family, which is NA when no families are supplied; and family_lambdas_rds, which is NA when write_rds is FALSE).

Details

This helper does no row filtering; callers pass an already-filtered df. Per-test lambda is compute_lambda_gc of each column (NA flows through, e.g. for a column with fewer than 50 non-NA p-values). The omnibus QQ uses plot_qq.