dandelion.polars.preprocessing.check_contigs

dandelion.polars.preprocessing.check_contigs(vdj, adata=None, productive_only=True, library_type=None, umi_foldchange_cutoff=2.0, consensus_foldchange_cutoff=5.0, ntop_vdj=1, ntop_vj=2, filter_missing=True, filter_extra=True, filter_ambiguous=False, filter_pseudo=None, save=None, verbose=True, **kwargs)[source]

Check contigs for whether they can be considered as ambiguous or not.

This function identifies and marks contigs as ambiguous, extra, or chimeric based on UMI/consensus dominance tests and gene call consistency. Uses vectorized polars operations for high performance.

Parameters:

vdj (DandelionPolars | pl.DataFrame | str) – V(D)J AIRR data to check. Can be DandelionPolars object, polars DataFrame, or file path to AIRR .tsv file.
adata (AnnData | None, optional) – AnnData object to filter. If provided, will track which cells have contigs. If None, assumes all cells in AIRR table should be kept.
productive_only (bool, default=True) – Whether to retain only productive contigs.
library_type (Literal[“ig”, “tr-ab”, “tr-gd”] | None, optional) –
If specified, filter based on expected contig types:
- ig: IGH, IGK, IGL
- tr-ab: TRA, TRB
- tr-gd: TRG, TRD
umi_foldchange_cutoff (float, default=2.0) – Minimum UMI fold-change threshold for dominance test.
consensus_foldchange_cutoff (float, default=5.0) – Minimum consensus count fold-change threshold for dominance test.
ntop_vdj (int, default=1) – Number of top VDJ contigs to keep (IGH, TRB, TRD).
ntop_vj (int, default=2) – Number of top VJ contigs to keep (IGK, IGL, TRA, TRG).
filter_missing (bool, default=True) – If True and adata provided, remove cells not found in AnnData object.
filter_extra (bool, default=True) – Whether to remove contigs marked as extra.
filter_ambiguous (bool, default=False) – Whether to remove contigs marked as ambiguous.
filter_pseudo (dict[str, list[str]] | None, optional) – Dictionary specifying how rows/contigs would be filtered based on gene functionality. Keys are “v”, “d”, “j” and values are lists of functionality strings to filter out. For instance, to only keep functional genes, you would set filter_pseudo={“v”: [“P”, “ORF”], “d”: [“P”, “ORF”], “j”: [“P”, “ORF”]}. None defaults to no filtering based on gene functionality. Requires that functionality columns (v_call_functionality, d_call_functionality, j_call_functionality) are present in the AIRR table, populated by ddl.pp.annotate_functionality.
save (str | None, optional) – If provided, save filtered table with _checked.tsv suffix.
verbose (bool, default=True) – Whether to print progress messages.
**kwargs – Additional kwargs passed to DandelionPolars constructor.

Returns:

If adata provided: (DandelionPolars object, updated AnnData) If adata is None: DandelionPolars object only

Return type:

tuple[DandelionPolars, AnnData] | DandelionPolars

Raises:

IndexError – If no contigs pass filtering.
ValueError – If save filename doesn’t end with .tsv.

Notes

This function: 1. Filters by productive status and library type (if specified) 2. Marks ambiguous/extra contigs using vectorized dominance tests 3. Marks chimeric contigs (mismatched BCR/TCR genes) 4. Optionally filters contigs based on flags 5. Creates DandelionPolars object with metadata

The vectorized implementation uses mark_ambiguous_contigs_vec for 10-100x performance improvement over the original pandas-based version.

Examples

>>> # Basic usage with DandelionPolars object
>>> ddl_polars = check_contigs(ddl_polars)

>>> # With AnnData filtering
>>> ddl_polars, adata = check_contigs(ddl_polars, adata=adata)

>>> # Custom thresholds
>>> ddl_polars = check_contigs(
...     ddl_polars,
...     umi_foldchange_cutoff=3.0,
...     consensus_foldchange_cutoff=10.0,
...     ntop_vdj=2,
...     ntop_vj=3
... )

>>> # From file path
>>> ddl_polars = check_contigs("filtered_contig_annotations.tsv")