mantispy.tl.dose_features

Contents

mantispy.tl.dose_features#

mantispy.tl.dose_features(adata, compound_key='Metadata_Compound', dose_key='Metadata_Concentration', reference='negcon', cutoff_mads=3.0, min_doses=4, key_added='dose_features', copy=False)#

Which features respond to a compound’s concentration, and at what concentration each one starts.

dose_response() grades one number per well against the dose. This grades every feature, which answers a different question: not whether the compound did something, but what it did and in what order.

Each feature gets a benchmark dose, the lowest concentration at which its median response reaches cutoff_mads times the spread the controls show on it. This is the ToxCast pipeline’s 3 * bmad read as a dose rather than as a yes or no, and it is defined for a feature that is still climbing at the top concentration, which an EC50 is not. Sorting the table by bmd gives the order the phenotype arrives in.

Parameters:

  • adata (AnnData) – Object carrying a compound and a dose per row, at well resolution.

  • compound_key (str (default: 'Metadata_Compound')) – obs column holding the compound identity.

  • dose_key (str (default: 'Metadata_Concentration')) – obs column holding the concentration. Rows with a zero or missing dose are left out, since the doses are read in log space.

  • reference (str | None (default: 'negcon')) – Rows that set each feature’s baseline and spread. "negcon" reads Metadata_Control.

  • cutoff_mads (float (default: 3.0)) – Multiples of the controls’ MAD a feature has to reach to get a benchmark dose. The ToxCast pipeline uses three.

  • min_doses (int (default: 4)) – Distinct doses below which a compound is left out of the table.

  • key_added (str (default: 'dose_features')) – Name for the output table.

  • 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], one row per compound and feature, with compound, feature, n_doses, bmd, max_z, direction, spearman, pvalue and qvalue. bmd is NaN for a feature that never reaches the cutoff, which is the table’s activity call. max_z is the largest response any concentration reached, in MADs of the controls, and direction is its sign. qvalue corrects the Spearman p-values within each compound, which is the experiment.

Raises:

  • KeyError – obs has no compound_key or no dose_key.

  • ValueError – Fewer than two reference rows, so there is no scale to read a response against.

Notes

A benchmark dose at the lowest concentration tested is a bound, not an estimate: the feature was already past the cutoff before the series began.

The Spearman correlation runs over the compound’s wells, not over the per-dose medians, so it uses the replicates. A feature with a missing value in any of those wells has no Spearman and no q-value; its benchmark dose is still read, because the medians skip missing wells.

Features whose controls show no spread are left out entirely. Run mantispy.pp.normalize() and drop var["degenerate_scale"] first and there will be none.

Contents