grassp.pp.add_external_validation_markers

grassp.pp.add_external_validation_markers#

add_external_validation_markers(data, species, columns=None, uniprot_id_column=None, ignore_isoform_extensions=False, use_gene_names=False, gene_names_column=None)[source]#

Annotate proteins with external validation markers (MitoCarta, MitoCop, topology, etc.).

Matches protein IDs in .obs against curated external marker datasets that include protein topology annotations, signal peptides, transmembrane domains, and mitochondrial annotations. These markers are useful for validating subcellular localization predictions.

Available columns include:

  • Topological domain: UniProt topology annotations

  • Transmembrane: Transmembrane domain annotations (e.g., “Helical”)

  • Intramembrane: Intramembrane domain annotations

  • has_signal: Boolean indicating presence of signal peptide

  • has_transmem: Boolean indicating presence of transmembrane domain

  • has_intramem: Boolean indicating presence of intramembrane domain

  • has_topo_dom: Boolean indicating presence of topological domain

  • mitocarta: MitoCarta annotation (human/mouse only)

  • mitocarta_evidence: MitoCarta evidence code (human/mouse only)

  • mitocarta_subloc: MitoCarta subcellular location (human/mouse only)

  • mitocop: MitoCop annotation (human only)

This function modifies the AnnData object in-place by adding annotation columns to .obs.

Parameters:
data AnnData

AnnData object.

species str

Species code to determine which marker file to read. Examples: ‘hsap’ (human), ‘mmus’ (mouse), ‘scer’ (yeast), ‘atha’ (Arabidopsis), ‘dmel’ (fly).

columns list[str] | str | None (default: None)

Specific column(s) to include from the marker file. If None, includes all available columns. Can be a single column name (string) or a list of column names.

uniprot_id_column str | None (default: None)

Column in .obs containing UniProt IDs. If None, uses .obs_names.

ignore_isoform_extensions bool (default: False)

If True, strip UniProt isoform extensions (e.g., -2 from Q53H12-2) before merging. The original column values are retained after the merge. Default: False.

use_gene_names bool (default: False)

If True, merge markers using gene names instead of UniProt IDs. When True, the marker DataFrame will be deduplicated by gene name before merging (keeping row with fewest NaN values). Default: False.

gene_names_column str | None (default: None)

Column in .obs containing gene names/symbols. Only used when use_gene_names=True. If None, uses .obs_names. Default: None.

Return type:

None

Returns:

None Modifies data.obs in-place by adding marker annotation columns (converted to categorical dtype for string columns).

Examples

>>> import grassp as gr
>>> import pandas as pd
>>> adata = gr.datasets.hein_2024(enrichment='raw')
>>> # Add all external validation markers
>>> gr.pp.add_external_validation_markers(adata, species='hsap')
Added Topological domain annotations for ...
>>> # Add specific columns only. Adding a column twice is an error, so start over.
>>> adata = gr.datasets.hein_2024(enrichment='raw')
>>> gr.pp.add_external_validation_markers(
...     adata, species='hsap',
...     columns=['mitocarta', 'has_transmem']
... )
Added mitocarta annotations for ...