volcano

volcano(
    points
    *
    significance
    effect=None
    significance_direction='above'
    labels=None
    groups=None
)

Declare a scatter a volcano plot. Experimental.

A volcano plot puts effect size (x, usually log2 fold change) against significance (y, usually -log10 p). Declared one, the chart opens with how many points clear the threshold and which, offers a rotor over just those points, and announces each point’s name – the gene a reader came for rather than two numbers the axes already describe.

Nothing in the drawing says where the threshold is, so it is never guessed: significance is required.

Parameters

Name	Type	Description	Default
points	Axes, PathCollection or sequence of PathCollection	What ax.scatter returned, several of them (one per color, say), or the axes they are drawn on – which is what sns.scatterplot returns – for every scatter on it. They become one layer, in the order given, or the order they were drawn for an Axes. Given one scatter of several on an axes, only that one is converted; the others stay plain scatter layers. Declaring points again replaces the layer an earlier call made of them.	required
significance	float	The cutoff on the y axis: 1.3 for p < 0.05 on a -log10(p) axis.	required
effect	float or None	The cutoff on the magnitude of x: 1 for a two-fold change on a log2 axis. None declares none.	None
significance_direction	('above', 'below')	Which side of significance the significant points are on. "below" is for a raw p-value axis.	"above"
labels	sequence or None	A name per point, in the order the points were given to the scatter calls – the gene names.	None
groups	sequence or None	A region per point, in the same order, announced beside it.	None

Returns

Name	Type	Description
	Maidr	The figure’s Maidr, now holding the volcano layer in place of the scatter layers of those points.

Raises

Name	Type	Description
	TypeError	If points is not a scatter or axes, or a cutoff is not a number.
	ValueError	If there is no scatter to declare, a cutoff is invalid, or labels or groups does not hold one entry per point.

Examples

>>> import matplotlib.pyplot as plt
>>> import maidr
>>> fig, ax = plt.subplots()
>>> points = ax.scatter([-2.5, 0.1, 3.2], [6.0, 0.4, 8.1])
>>> _ = maidr.volcano(
...     points, significance=1.3, effect=1.0, labels=["TP53", "GAPDH", "MYC"]
... )