dandelion.polars.tools.get_epitope

dandelion.polars.tools.get_epitope(vdj, adata, database='vdjdb', receptor_type='TCR', chain=None, min_vdjdb_score=1, antigen_species=None, organism_filter=None, timeout=120, reference=None)[source]

Query immune receptor databases for epitope information and write results into adata.obs, vdj._metadata, and vdj._data.

Parameters:

  • vdj (DandelionPolars) – Dandelion object after check_contigs / find_clones / transfer processing.

  • adata (AnnData) – Gene expression AnnData object after transfer(adata, vdj).

  • database (Literal[“vdjdb”, “iedb”, “both”], optional) – Database to query. - “vdjdb” : VDJdb (recommended for TCR). - “iedb” : IEDB (recommended for BCR / antibody data). - “both” : query both databases separately and annotate with distinct columns. Default is “vdjdb”.

  • receptor_type (Literal[“BCR”, “TCR”] | None, optional) – Receptor type filter. Default is “TCR”.

  • chain (str | list[str] | None, optional) – Restrict matching to specific IMGT locus/loci, e.g. "TRA" or ["TRA", "TRB"]. Valid values: IGH, IGK, IGL, TRA, TRB, TRG, TRD. When set, only contigs of that chain (in vdj.data) are matched against reference entries of that same chain — so annotations on vdj._data never bleed across chains, and per-cell aggregates in adata.obs / vdj._metadata only reflect the requested chain(s).

  • min_vdjdb_score (int, optional) – Minimum VDJdb confidence score (0–3). Only used when database is “vdjdb” or “both”. Default is 1.

  • antigen_species (str | None, optional) – Filter VDJdb by antigen species, e.g. “EBV”, “CMV”, “SARS-CoV-2”. Only used when database is “vdjdb” or “both”.

  • organism_filter (str | None, optional) – Filter IEDB by antigen organism substring, e.g. “Epstein-Barr”, “influenza”. Only used when database is “iedb” or “both”.

  • timeout (int, optional) – HTTP request timeout in seconds. Default is 120.

  • reference (pd.DataFrame | None, optional) – Pre-fetched reference database DataFrame returned by fetch_db(). When supplied, all download and filter parameters (database, receptor_type, antigen_species, organism_filter, min_vdjdb_score, timeout) are ignored and no HTTP request is made. chain still applies — it’s used at annotation time regardless of how reference was produced. Use this to avoid redundant downloads when calling get_epitope inside a loop:

    db = fetch_db(database="vdjdb", receptor_type="TCR")
for vdj, adata in samples:
    get_epitope(vdj, adata, reference=db)
Returns:

Results are written to three places: - vdj._data : per-contig (chain-specific) match columns —

epitope_{db}, organism_{db}, mhc_class_{db}, mhc_allele_{db}, epitope_{db}_primary, organism_{db}_primary.

  • vdj._metadata : per-cell convenience columns — just epitope and organism (mhc_class/mhc_allele stay contig-only). Two calls to Dandelion’s own vdj.update_metadata(retrieve=..., split=...) produce a flat merged form (epitope_{db}) and a VDJ/VJ chain-split form (epitope_{db}_VDJ / epitope_{db}_VJ); epitope_{db}_primary is then derived explicitly (the first "|"-token of the flat merged column — a cell’s chains merged together for this one field, deliberately) rather than via Dandelion’s own first=True. 4 columns per concept, 8 total per db (epitope + organism).

  • adata.obs : mirrors whichever of those expected columns were actually produced.

where {db} is “vdjdb” and/or “iedb” depending on database.

Return type:

None

Examples

>>> get_epitope(vdj, adata)
>>> get_epitope(vdj, adata, antigen_species="EBV")
>>> get_epitope(vdj, adata, database="iedb", receptor_type="BCR")
>>> get_epitope(vdj, adata, database="both", receptor_type="TCR")
>>> get_epitope(vdj, adata, chain="TRB")            # beta chain only
>>> get_epitope(vdj, adata, chain=["TRA", "TRB"])   # alpha + beta

# Efficient multi-sample loop — download only once: >>> db = fetch_db(database=”vdjdb”, receptor_type=”TCR”, antigen_species=”EBV”) >>> for vdj_s, adata_s in sample_pairs: … get_epitope(vdj_s, adata_s, reference=db)