, groupby, *, target_col='clone_id', metric='normalized_shannon_entropy', inplace=True, key_added=None, **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

Normalized shannon entropy:

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


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.


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.

adata : AnnData

Annotated data matrix

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, add a column to obs. Otherwise return a DataFrame with the alpha diversities.

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

Key under which the alpha diversity will be stored if inplace is True. Defaults to alpha_diversity_{target_col}.


Additional arguments passed to the metric function.

Return type

DataFrame | NoneOptional[DataFrame]


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