scirpy.tl.alpha_diversity

scirpy.tl.alpha_diversity(adata, groupby, *, target_col='clone_id', metric='normalized_shannon_entropy', inplace=True, key_added=None, airr_mod='airr', **kwargs)

Computes the alpha diversity of clonotypes within a group.

Use a metric out of normalized_shannon_entropy, D50, DXX, and scikit-bio’s alpha diversity metrics. Alternatively, provide a custom function to calculate the diversity based on count vectors as explained here http://scikit-bio.org/docs/latest/diversity.html

Normalized shannon entropy:

Uses the Shannon Entropy as diversity measure. The Entrotpy gets normalized to group size.

D50:

The diversity index (D50) is a measure of the diversity of an immune repertoire of J individual cells (the total number of CDR3s) composed of S distinct CDR3s in a ranked dominance configuration where ri is the abundance of the ith most abundant CDR3, r1 is the abundance of the most abundant CDR3, r2 is the abundance of the second most abundant CDR3, and so on. C is the minimum number of distinct CDR3s, amounting to >50% of the total sequencing reads. D50 therefore is given by C/S x 100. https://patents.google.com/patent/WO2012097374A1/en.

DXX:

Similar to D50 where XX indicates the percent of J (the total number of CDR3s). Requires to pass the percentage keyword argument which can be within 0 and 100.

Ignores NaN values.

Parameters

adata : AnnData | MuData | DataHandlerUnion[AnnData, MuData, DataHandler]

AnnData or MuData object that contains AIRR information.

groupby : str

Column of obs by which the grouping will be performed.

target_col : str (default: 'clone_id')

Column on which to compute the alpha diversity

metric : str | (ndarray) → int | floatUnion[str, Callable[[ndarray], Union[int, float]]] (default: 'normalized_shannon_entropy')

A metric used for diversity estimation out of normalized_shannon_entropy, D50, DXX, any of scikit-bio’s alpha diversity metrics, or a custom function.

inplace : bool (default: True)

If True, a column with the result will be stored in obs. Otherwise the result will be returned.

key_added : str | NoneOptional[str] (default: None)

Key under which the result will be stored in obs, if inplace is True. When the function is running on MuData, the result will be written to both mdata.obs["{airr_mod}:{key_added}"] and mdata.mod[airr_mod].obs[key_added].

Defaults to alpha_diversity_{target_col}.

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.

**kwargs

Additional arguments passed to the metric function.

Return type

DataFrame | NoneOptional[DataFrame]

Returns

Depending on the value of inplace returns a DataFrame with the alpha diversity for each group or adds a column to adata.obs.