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, drop_allna_columns=True, _allna_chunksize=1000000, **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 a reference allele file with columns SNP A1 A2 (e.g. the classic w_hm3.snplist). This is a filter, not an alignment step: munge_sumstats.py drops any SNP whose (A1, A2) pair has no valid correspondence to the reference’s pair (including strand-ambiguous ones), but every SNP it keeps has its A1/A2/Z taken verbatim from sumstats_file. cellink never invokes ldsc’s own --merge-alleles flag. Passing merge_alleles here instead runs filter_sumstats_by_merge_alleles() first (a from-scratch reimplementation of the same filtering logic, keeping the identical final SNP set), then calls plain munge_sumstats.py without the flag on the result.

• snplist (str, optional) – Non-functional in the pinned ldsc version (1.0.1); passing it raises ValueError. Pass a 3-column file via merge_alleles instead.

• 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”)

• drop_allna_columns (bool, default True) – Set to False to pass the file through unmodified.

• 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:

str | None

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 always removed, with or without merge_alleles. merge_alleles adds an additional reference-correspondence filter on top of this; it is not what enables strand-ambiguous filtering in the first place

• The output file will be gzipped and named {out_prefix}.sumstats.gz

• merge_alleles only filters out SNPs with no valid allele correspondence to the reference; it does not rewrite/align the alleles or flip signs of the SNPs it keeps (see the merge_alleles parameter above). Using it reduces false strand-ambiguous hits but does not by itself guarantee two munged files are in consistent orientation

• merge_alleles never invokes ldsc’s own –merge-alleles flag; see the merge_alleles parameter above for what cellink does instead

• 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)