mantispy.tl.dose_trajectory

mantispy.tl.dose_trajectory#

mantispy.tl.dose_trajectory(adata, compound_key='Metadata_Compound', dose_key='Metadata_Concentration', reference='negcon', phase_key='dose_direction_phase', phases=('responding',), n_positions=3)#

Each compound’s whole path through its own responding window, on one comparable axis.

Comparing two compounds at the same concentration compares one that has engaged against one that has not. Comparing them at their own strongest concentration throws away everything on the way there, which for a compound whose phenotype turns along its window is most of what it did. This reads each compound’s window onto the same relative axis instead: position 0 is where it starts responding, position 1 is the top of its window, and the profile is interpolated in log concentration in between.

The result is one row per compound and one column per feature and position, so the usual tools apply to it: similarity() gives the compound-to-compound matrix, and a PCA or a clustering groups compounds by the shape of their response rather than by its size.

Parameters:

  • adata (AnnData) – Object carrying a compound, a dose and, normally, the phase column dose_direction() wrote.

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

  • dose_key (str (default: 'Metadata_Concentration')) – obs column holding the concentration.

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

  • phase_key (str | None (default: 'dose_direction_phase')) – obs column holding the phase, so the path is read over the window rather than the whole ladder. None, or a column that is absent, uses every concentration the compound was dosed at.

  • phases (Sequence[str] (default: ('responding',))) – Which phases count as the window.

  • n_positions (int (default: 3)) – Points the window is resampled to. Two is its ends; more describes the path between them, and cannot add detail a short window does not have.

Return type:

AnnData

Returns:

A new object of compounds by features-and-positions, at "perturbation" resolution. var carries feature and position; obs carries n_doses and the window’s ends. Compounds whose window holds fewer than two concentrations are left out, since a single point is not a path.

Raises:

  • KeyError – obs has no compound_key or no dose_key.

  • ValueError – n_positions is below two, or fewer than two reference rows.

Notes

The axis is relative, so position 0 means a different concentration for every compound. That is the point, and it is also the caveat: two compounds matched here are matched on what they do in their own effective range, which is a claim about mechanism rather than about potency. Read it beside the benchmark doses from dose_features(), which is where the potency lives.

How much this says over comparing the top of each window alone depends on how long the windows are. On the OASIS pilot, where most compounds respond over two or three of the ten concentrations, the two agree closely; the pairs they disagree on are the ones with long windows.