scirpy.tl.clonotype_imbalance

scirpy.tl.clonotype_imbalance#

scirpy.tl.clonotype_imbalance(adata, replicate_col, groupby, case_label, *, control_label=None, target_col='clone_id', additional_hue=None, fraction=None, inplace=True, overlap_key=None, key_added='clonotype_imbalance', airr_mod='airr')#

Aims to find clonotypes that are the most enriched or depleted in a category.

Uses Fischer’s exact test to rank clonotypes. Depends on execution of scirpy.tl.repertoire_overlap(). Adds two dataframes (abundance of clonotypes per sample; pval and logFC for clonotypes) to uns

Warning

This is an experimental function and will likely change in the future.

Parameters:
  • adata (Union[AnnData, MuData, DataHandler]) – AnnData or MuData object that contains AIRR information.

  • replicate_col (str) – Column with batch or sample labels.

  • groupby (str) – The column containing categories that we want to compare and find imbalance between

  • case_label (str) – The label in groupby column that we want to compare.

  • control_label (Optional[str] (default: None)) – The label in groupby column that we use as a baseline for comparison. If not set (None by default), all labels that are not equal to case_label make up the baseline.

  • target_col (str (default: 'clone_id')) – The clusters (clonotypes by default) that are imbalanced.

  • additional_hue (Union[str, bool, None] (default: None)) – An additional grouping factor. If the case_label was tumor for example, this could help make a distinction between imbalance in lung and colorectal tumors.

  • fraction (Union[str, bool, None] (default: None)) – If True, compute fractions of abundances relative to the groupby column rather than reporting abosolute numbers. Alternatively, a column name can be provided according to that the values will be normalized or an iterable providing cell weights directly. Setting it to False or None assigns equal weight to all cells.

  • inplace (bool (default: True)) – Whether results should be added to uns or returned directly.

  • overlap_key (Optional[str] (default: None)) – Under what key should the repertoire overlap results be looked up in uns. By default it is None to ensure that the overlap tool is executed with the right parameters.

  • key_added (str (default: 'clonotype_imbalance')) – Results will be added to uns under this key.

  • airr_mod (str (default: 'airr')) – Name of the modality with AIRR information is stored in the MuData object. if an AnnData object is passed to the function, this parameter is ignored.

Return type:

Optional[tuple[DataFrame, DataFrame]]

Returns:

Two dataframes: abundance of clonotypes per sample; pval and logFC for clonotypes.