dandelion.polars.tools.fetch_db

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

Download and prepare the reference database once and return it as a DataFrame that can be reused across many get_epitope() calls.

Calling this before a for-loop over samples avoids repeated HTTP downloads (the underlying bytes are also cached by _fetch_bytes(), but fetch_db additionally avoids repeating the parsing/filtering work on every iteration).

Parameters:

  • database (Literal[“vdjdb”, “iedb”, “both”], optional) – Database to query. - “vdjdb” : VDJdb (recommended for TCR). - “iedb” : IEDB (recommended for BCR / antibody data). - “both” : concatenate both databases into a single reference. Default is “vdjdb”.

  • receptor_type (Literal[“BCR”, “TCR”], optional) – Restrict to B- or T-cell receptors. Default is “TCR”.

  • chain (str | list[str] | None, optional) – Restrict to specific IMGT locus/loci, e.g. "TRA" or ["TRA", "TRB"]. Valid values: IGH, IGK, IGL, TRA, TRB, TRG, TRD.

  • 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, optional) – Filter VDJdb by antigen species, e.g. “EBV”, “CMV”, “SARS-CoV-2”. Only used when database is “vdjdb” or “both”.

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

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

Returns:

AIRR-compatible reference dataframe, ready to pass as the reference argument to get_epitope().

Return type:

DataFrame

Examples

>>> db = fetch_db(database="vdjdb", receptor_type="TCR", antigen_species="EBV")
>>> for sample_vdj, sample_adata in samples:
...     get_epitope(sample_vdj, sample_adata, reference=db)