cellink.tl.external.preprocess_for_sldsc

cellink.tl.external.preprocess_for_sldsc(adata, *, celltype_col, log_transform=True, filter_protein_coding=True, filter_expressed=True, filter_mhc=True, mhc_chr=None, mhc_start=None, mhc_end=None, fetch_annotation=True, genome_build='GRCh37', gene_identifier_mode='name', remove_version_suffix=True, gene_col='gene', biotype_col=None, chr_col=None, start_col=None, end_col=None, inplace=True)

Preprocess single-cell data for S-LDSC cell-type-specific analysis.

This function performs comprehensive preprocessing including: - Optional log1p transformation - Gene annotation fetching from Ensembl BioMart (GRCh37 or GRCh38) - Gene filtering (protein-coding, expressed, unique names, MHC exclusion) - Computation of mean expression per cell type - Computation of specificity scores (Duncan et al. 2025; doi:10.1038/s41593-024-01834-w)

Parameters:

• adata (AnnData) – Annotated data matrix of shape n_obs x n_vars (cells x genes).

• celltype_col (str) – Column name in adata.obs containing cell type labels.

• log_transform (bool (default: True)) – Whether to apply log1p transformation. Set to False if already log-transformed.

• filter_protein_coding (bool (default: True)) – Whether to filter for protein-coding genes only.

• filter_expressed (bool (default: True)) – Whether to filter out genes with zero expression across all cells.

• filter_mhc (bool (default: True)) – Whether to exclude genes in the MHC region (chr6:25-34Mb by default).

• mhc_chr (str (default: None)) – Chromosome containing MHC region (default: “6”).

• mhc_start (int (default: None)) – Start position of MHC region in base pairs.

• mhc_end (int (default: None)) – End position of MHC region in base pairs.

• fetch_annotation (bool (default: True)) – Whether to fetch gene annotations from Ensembl BioMart. If False, expects existing annotation columns in adata.var.

• genome_build (Literal['GRCh37', 'GRCh38'] (default: 'GRCh37')) – Genome build version: “GRCh37” or “GRCh38”. Only used if fetch_annotation=True.

• gene_identifier_mode (str (default: 'name')) –

  Gene identifier: “name” or “ensembl”. Only used if fetch_annotation=True. remove_version_suffix

  Whether to remove version suffixes from gene names or gene IDs (e.g., ENSG00000123456.7 → ENSG00000123456).

• gene_col (str | None (default: 'gene')) – Column name for gene symbols or IDs. If None, uses var_names if fetch_annotation is True is auto-detected.

• biotype_col (str | None (default: None)) – Column name for gene biotype. Auto-detected if None.

• chr_col (str | None (default: None)) – Column name for chromosome. Auto-detected if None.

• start_col (str | None (default: None)) – Column name for gene start position. Auto-detected if None.

• end_col (str | None (default: None)) – Column name for gene end position. Auto-detected if None.

• inplace (bool (default: True)) – Whether to update adata in place or return a copy.

Return type:

tuple[AnnData, DataFrame, DataFrame] | None

Returns:

AnnData, pd.DataFrame, pd.DataFrame - Filtered AnnData object - Cluster-normalized-to-1000 matrix and specificity derived from that (genes x cell types) - Specificity scores per cell type (genes x cell types) Returns None if inplace=True.

Raises:

• AssertionError – If celltype_col is not present in adata.obs.

• ValueError – If required annotation columns are missing and fetch_annotation=False.

• ImportError – If pybiomart is not installed and fetch_annotation=True.

Examples

>>> # Using GRCh37 (default)
>>> adata_filtered, mean_expr, specificity = preprocess_for_sldsc(adata, celltype_col="cell_type", inplace=False)
>>> # Using GRCh38
>>> adata_filtered, mean_expr, specificity = preprocess_for_sldsc(
...     adata, celltype_col="cell_type", genome_build="GRCh38", inplace=False
... )