cellink.tl.external.munge_sumstats#
- cellink.tl.external.munge_sumstats(sumstats_file, out_prefix='GWAS_summary_statistics_munged', n_samples=None, merge_alleles=None, snplist=None, info_min=0.9, maf_min=0.01, a1_inc=False, signed_sumstats=None, p_col=None, a1_col=None, a2_col=None, snp_col=None, n_col=None, info_col=None, run=True, runner=None, **kwargs)#
Munge (clean and standardize) GWAS summary statistics for LDSC analysis
This function processes raw GWAS summary statistics files to prepare them for LD Score regression analysis. It performs quality control, standardizes column names, filters SNPs, and aligns alleles to a reference panel.
- Parameters:
sumstats_file (str) – Path to input GWAS summary statistics file. Can be plain text or gzipped. Should contain columns for SNP ID, effect allele, other allele, and p-value.
out_prefix (str, default "GWAS_summary_statistics_munged") – Prefix for output files. Will create {out_prefix}.sumstats.gz
n_samples (int, optional) – Total sample size. If the summary statistics file has a sample size column, this will be used to verify it. If there’s no sample size column, this will be added to all SNPs.
merge_alleles (str, optional) – Path to reference allele file (e.g., w_hm3.snplist) for aligning alleles and removing strand-ambiguous SNPs. Recommended for downstream analysis.
snplist (str, optional) – Path to file with SNP IDs to keep. Only SNPs in this list will be retained.
info_min (float, default 0.9) – Minimum INFO score for SNP inclusion. SNPs with INFO < info_min are removed.
maf_min (float, default 0.01) – Minimum minor allele frequency for SNP inclusion. SNPs with MAF < maf_min are removed.
a1_inc (bool, default False) – If True, A1 is the effect allele (increasing allele). If False, A1 is the other allele and the sign of the effect will be flipped.
signed_sumstats (tuple[str, float], optional) – Tuple of (column_name, sign) for identifying the direction of effect. Example: (“OR”, 1) means odds ratios where values >1 indicate positive effect. Example: (“BETA”, 0) means betas where values >0 indicate positive effect.
p_col (str, optional) – Name of the p-value column if non-standard (default: “P”)
a1_col (str, optional) – Name of the effect allele column if non-standard (default: “A1”)
a2_col (str, optional) – Name of the other allele column if non-standard (default: “A2”)
snp_col (str, optional) – Name of the SNP ID column if non-standard (default: “SNP”)
n_col (str, optional) – Name of the sample size column if non-standard (default: “N”)
info_col (str, optional) – Name of the INFO score column if non-standard (default: “INFO”)
run (bool, default True) – Whether to execute the command or just return it
runner (LDSCRunner, optional) – Runner instance to use. If None, uses the global runner.
**kwargs – Additional command line arguments to pass to munge_sumstats.py Common options include: - ignore: List of columns to ignore - daner: Set if input is in daner format (PGC) - no-alleles: Don’t require allele information - merge-alleles: Alternative way to specify reference alleles
- Return type:
- Returns:
dict Results dictionary containing: - ‘sumstats_file’: Path to the munged summary statistics file (if run=True) - ‘files_created’: List of created files (if run=True) - ‘command’: Command string (if run=False)
- Raises:
subprocess.CalledProcessError – If the munging process fails (e.g., due to malformed input file)
Examples
Basic usage with standard column names: >>> result = munge_sumstats( … sumstats_file=”height_gwas.txt.gz”, … out_prefix=”height_munged”, … n_samples=253288, … merge_alleles=”w_hm3.snplist”, … )
With custom column names: >>> result = munge_sumstats( … sumstats_file=”custom_gwas.txt”, … out_prefix=”custom_munged”, … n_samples=50000, … snp_col=”RSID”, … a1_col=”EFFECT_ALLELE”, … a2_col=”OTHER_ALLELE”, … p_col=”PVAL”, … signed_sumstats=(“BETA”, 0), … )
Case-control study with odds ratios: >>> result = munge_sumstats( … sumstats_file=”case_control_gwas.txt.gz”, … out_prefix=”case_control_munged”, … n_samples=10000, … merge_alleles=”w_hm3.snplist”, … signed_sumstats=(“OR”, 1), … a1_inc=True, … )
Just generate the command without running: >>> result = munge_sumstats( … sumstats_file=”height_gwas.txt.gz”, out_prefix=”height_munged”, n_samples=253288, run=False … ) >>> print(result[“command”])
Notes
The function expects summary statistics files to follow standard GWAS format
Strand-ambiguous SNPs (A/T or G/C) are removed when merge_alleles is used
The output file will be gzipped and named {out_prefix}.sumstats.gz
It’s highly recommended to use merge_alleles with a reference panel (e.g., HapMap3) to ensure proper allele alignment
For binary traits, signed_sumstats should typically be (“OR”, 1) or (“BETA”, 0)
For quantitative traits, signed_sumstats is typically (“BETA”, 0) or (“Z”, 0)