cellink.tl.external.run_magma_gpa#

cellink.tl.external.run_magma_gpa(gene_results, gene_covar, out_prefix, magma_bin='magma', univariate=False, run=True, **kwargs)#

Run MAGMA Step III — gene property analysis (GPA).

Tests the linear association between continuous per-gene scores and GWAS gene-level z-scores. Unlike GSA (which uses a top-N threshold), GPA uses all genes with scores as quantitative covariates.

When univariate=False (default), all cell types are tested jointly in a single MAGMA call (--gene-covar). This is efficient but MAGMA may drop highly collinear covariates. Set univariate=True to test each cell type independently — this is slower but always produces a result for every cell type (matches run_magma_gpa_univariate.py in the pipeline).

LDSC → MAGMA GPA workflow

>>> covar = scores_to_covar(specificity_df, "brainscope_seismic.covar")
>>> run_magma_gpa(gene_results="scz.genes.raw", gene_covar=str(covar), out_prefix="results/scz_gpa_seismic")

Parameters:

gene_results (str) – Path to .genes.raw from run_magma_gene_analysis().
gene_covar (str) – Path to .covar file from scores_to_covar().
out_prefix (str) – Prefix for output files. Creates {out_prefix}.gsa.out.
magma_bin (str (default: 'magma')) – Path to the MAGMA binary.
univariate (bool (default: False)) – If True, run each cell type (covariate column) as a separate MAGMA call and combine results. Recommended when covariates are highly correlated (e.g. residual CV or negated scores), which causes MAGMA’s collinearity filter to silently drop columns in joint mode.
run (bool (default: True)) – If False, return the command without executing (only valid when univariate=False).
**kwargs – Additional flags forwarded to MAGMA in joint mode.

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, joint mode only).

Examples

Joint analysis (default):

>>> run_magma_gpa(
...     gene_results="results/scz.genes.raw",
...     gene_covar="covars/brainscope_seismic.covar",
...     out_prefix="results/scz_gpa_seismic",
... )

Univariate analysis (safe for correlated scores):

>>> run_magma_gpa(
...     gene_results="results/scz.genes.raw",
...     gene_covar="covars/brainscope_residual_cv.covar",
...     out_prefix="results/scz_gpa_residual_cv",
...     univariate=True,
... )

cellink.tl.external.run_magma_gpa

Contents

cellink.tl.external.run_magma_gpa#