mantispy.tl.composition_shift#

mantispy.tl.composition_shift(adata, key, groupby='Metadata_Perturbation', reference='negcon', block=('Metadata_Plate', 'Metadata_Well'), replicate='Metadata_sgRNA', n_permutations=999, seed=0, key_added='composition_shift', copy=False)[source]#

Change in each group’s share of cells per category against the reference, compared within blocks.

The category is a label per cell, such as a cell-cycle state or a cluster. Within each block (a well on a plate), the group’s share of cells in every category is compared with the reference’s, and the differences are averaged over blocks. The distance is the total variation distance of that average, half the sum of its absolute values: 0 when the group’s composition matches the reference, 1 when they share no category.

The p-value comes from relabelling replicate (the guide) as group or reference, one relabelling per permutation applied in every block, so the guide is the replicate even though every well of a pooled screen holds every guide. For one row per guide, pass the guide column as both groupby and replicate: each guide is then compared with the reference guides.

Parameters:
adata AnnData

Object-resolution object carrying the category in obs[key].

key str

obs column holding a label per cell. A cell without a value is left out.

groupby str (default: 'Metadata_Perturbation')

obs column naming the groups to score, one row of the result each.

reference str (default: 'negcon')

The rows to compare against: "negcon" for the negative controls, or the name of a boolean obs column. The reference has no row of its own.

block Sequence[str] | str | None (default: ('Metadata_Plate', 'Metadata_Well'))

obs column or columns the comparison is paired within, normally the plate and well, so the same well position on two plates stays two blocks; None pools all rows. The default uses whichever of the two columns the object has.

replicate str | None (default: 'Metadata_sgRNA')

obs column naming the independent replicate the permutation relabels, normally the guide. None relabels single cells, which treats every cell as independent and warns. Each replicate must belong to one group.

n_permutations int (default: 999)

Permutations for the null.

seed int (default: 0)

Seed for the permutations.

key_added str (default: 'composition_shift')

Key the table is written under in uns["mantispy"].

copy bool (default: False)

Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes uns["mantispy"][key_added] with one row per group: group, the distance, n_blocks that held both the group and the reference, pvalue, the Benjamini-Hochberg qvalue over the groups, min_pvalue, the smallest p-value the design could reach, and one column per category with the group’s share minus the reference’s.

Raises:

  • KeyError – obs lacks a block column.

  • ValueError – n_permutations is not positive, reference selects no cells, a block column holds missing values, or a replicate spans more than one group.