cellink.tl.external.run_magma_gsa

cellink.tl.external.run_magma_gsa(gene_results, set_annot, out_prefix, magma_bin='magma', run=True, **kwargs)

Run MAGMA Step III — gene-set analysis (GSA).

Tests whether genes in each set have higher GWAS association signals than background genes, using the gene-level results from run_magma_gene_analysis(). Input gene sets are supplied as a GMT file (see scores_to_gmt() or genesets_dir_to_entrez_gmt()).

LDSC → MAGMA GSA workflow

Two paths lead here from LDSC outputs:

1. From continuous per-gene scores (e.g. specificity, SEISMIC):

   >>> gmt = scores_to_gmt(specificity_df, "top10.gmt")
   >>> run_magma_gsa(gene_results="scz.genes.raw", set_annot=str(gmt), out_prefix="results/scz_gsa")
   

2. From LDSC binary .GeneSet files:

   >>> gmt = genesets_dir_to_entrez_gmt(geneset_dir="ldsc_genesets", out_gmt="magma_genesets/genesets.gmt")
   >>> run_magma_gsa(gene_results="scz.genes.raw", set_annot=str(gmt), out_prefix="results/scz_gsa")
   

Parameters:

• gene_results (str) – Path to .genes.raw from run_magma_gene_analysis().

• set_annot (str) – Path to GMT-format gene-set file. Gene identifiers must be ENSG or Entrez IDs consistent with those in gene_results.

• out_prefix (str) – Prefix for output files. Creates {out_prefix}.gsa.out.

• magma_bin (str (default: 'magma')) – Path to the MAGMA binary.

• run (bool (default: True)) – If False, return the command without executing.

• **kwargs – Additional flags passed verbatim to MAGMA (e.g. model="multi").

Return type:

dict[str, Any]

Returns:

dict results_file — path to .gsa.out. files_created — list (if run=True). command — command list (if run=False).

Examples

>>> run_magma_gsa(
...     gene_results="results/scz.genes.raw",
...     set_annot="genesets/top10_seismic.gmt",
...     out_prefix="results/scz_gsa_seismic",
... )

See also

scores_to_gmt

Build GMT from a scores DataFrame.

genesets_dir_to_entrez_gmt

Build GMT from LDSC .GeneSet files.

run_magma_gpa

Continuous gene property analysis (alternative to GSA).