cellink.tl.external.make_annot_from_bimfile

cellink.tl.external.make_annot_from_bimfile(bimfile, annot_file, gene_set_file=None, bed_file=None, nomerge=False, run=True, runner=None, scores=None, score_agg='max', gene_coord_file=None, windowsize=100000, **kwargs)

Create a binary or continuous S-LDSC annotation file from a PLINK bimfile.

Pass scores for a continuous annotation (each SNP gets the aggregated per-gene score of overlapping gene windows). Omit scores and supply gene_set_file or bed_file for a binary (0/1) annotation via LDSC’s make_annot.py.

Both modes write the same five-column format (CHR, BP, SNP, CM, ANNOT), so downstream calls are identical regardless of mode.

Parameters:

• bimfile (str) – Path to PLINK .bim file.

• annot_file (str) – Output annotation file. Should end in .annot.gz.

• gene_set_file (str, optional) – Binary mode. File of gene names (one per line).

• bed_file (str, optional) – Binary mode. UCSC BED file defining annotation regions.

• nomerge (bool, default False) – Binary mode. Count overlapping BED intervals instead of merging.

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

• runner (LDSCRunner, optional) – Binary mode. LDSC runner (Docker/Singularity/local).

• scores (pd.Series, optional) – Continuous mode. Per-gene scores indexed by gene IDs matching gene_coord_file. Requires gene_coord_file.

• score_agg ({"max", "sum", "mean"}, default "max") – Continuous mode. Aggregation when multiple gene windows overlap a SNP.

• gene_coord_file (str, optional) – Gene coordinate file. Required in continuous mode; optional in binary mode. Accepts headed (GENE/CHR/START/END) or headless 4-column format.

• windowsize (int, default 100_000) – Flanking window in bp around each gene body.

• **kwargs – Binary mode. Extra flags forwarded to make_annot.py.

Return type:

dict[str, Any]

Returns:

dict Always contains annot_file and files_created. Continuous mode additionally returns n_nonzero_snps and n_genes_matched.

Examples

Binary annotation:

>>> make_annot_from_bimfile(
...     bimfile="1000G.EUR.QC.22.bim",
...     annot_file="CD8_Naive.22.annot.gz",
...     gene_set_file="CD8_Naive.GeneSet",
...     gene_coord_file="gene_coords.txt",
...     windowsize=100_000,
... )

Continuous annotation (same downstream call):

>>> make_annot_from_bimfile(
...     bimfile="1000G.EUR.QC.22.bim",
...     annot_file="CD8_Naive.22.annot.gz",
...     scores=specificity_df["CD8 Naive"],
...     gene_coord_file="gene_coords.txt",
...     windowsize=100_000,
... )