Choosing a readout

Several functions score how well a screen reproduces and how active its perturbations are. They answer different questions, so the one to report depends on what you want to claim.

Readout	Question it answers	Report it when
tl.map(mode="activity")	Is this perturbation distinguishable from the negative controls on its own plate?	You want to know which perturbations do anything. This is the default first readout for a screen with controls.
tl.map(mode="replicability")	Do a perturbation’s replicates retrieve each other against the other perturbations on a plate, controls left out?	You want replicate reproducibility within a plate.
tl.map(mode="cross_plate")	Do a perturbation’s replicates on other plates retrieve each other against all other profiles?	Replicates sit on different plates or batches, and you need reproducible biology rather than plate effects.
tl.map(mode="consistency")	Do perturbations that share an annotation, such as a mechanism or a target, look more alike than those that do not?	You have consensus profiles of active perturbations and a mechanism or gene-set annotation to test.
tl.percent_replicating	Is the median replicate correlation above a non-replicate null?	You must compare with published numbers. It thresholds rather than ranks and depends on the number of replicates, so prefer mAP otherwise.
tl.hit_calling	Is this perturbation’s profile far from the controls, with a calibrated call per perturbation?	You need a list of hits rather than a score for every perturbation.
tl.edistance	How far apart are two whole distributions of profiles?	You want a distance between groups, or between each group and the controls, that uses the full distribution and not only its centre.

Which to report

Start with activity to find the perturbations that differ from the controls. Report cross_plate next to it whenever replicates are spread over plates, because a signal that does not survive a plate change is not reproducible. Add consistency on the active perturbations to ask whether they group by mechanism or target. Use hit_calling when the deliverable is a hit list, and edistance when the deliverable is a distance. Report percent_replicating only for comparison with earlier work.

tl.map needs the optional copairs extra. See Is the screen any good? for the readouts applied to a screen, and the map() reference for the pair definitions behind each mode.