utils

Utility functions for plotting.

class dmslogo.utils.AxLimSetter(*, datalim_pad=0.05, include_zero=True, max_from_quantile=None, min_from_quantile=None, all_equal_data=(-0.001, 0.001), min_upperlim=None, max_lowerlim=None)

Bases: object

Object to determine axis limits from data.

Args:

datalim_pad (float >= 0)

Padding of data limits.

include_zero (bool)

Extend upper and lower data limits to ensure they include zero?

max_from_quantile (None or 2-tuple (quantile, frac))

Used to set limits based on quantiles of data as described below.

min_from_quantile (None or 2-tuple (quantile, frac))

Used to set limits based on quantiles of data as described below.

all_equal_data (‘raise’ or 2-tuple (minus_min, plus_max))

If all the data are equal, it will not be possible to set limits using algorithm below. In this case, raise an error or add the indicated amounts to the data limits.

min_upperlim (None or float)

Ensure upper limit always at least this large.

max_lowerlim (None or float)

Ensure lower limit always at least this small.

The axis limits may just be simple padding of the data limits, but the max_from_quantile and min_from_quantile arguments allow the option to set limits in a meaningful way so data that are just “noise” of very similar values are plotted far inside the axis limits. Specifically, axis limits are determined by AxLimSetter.get_lims() as follows:

1. The user passes the data, and the upper and lower data limits are determined as the simple min and max of the data.

2. If include_zero, these data limits are adjusted to ensure the lower data limit is <= 0 and the upper data limit is >= 0.

3. If max_from_quantile is not None, the upper axis limit is set so that the indicated quantile of the data is frac of the way from the lower data limit to the upper axis limit. However, if the data max exceeds the upper axis limit this way, then the upper axis limit is set to the data max.

4. If min_from_quantile is not None, similar setting of the lower axis limit is done.

5. The limits from above are padded by datalim_pad to the total extent of the axis on both sides.

6. The limits are adjusted if needed to satisfy min_upperlim and max_lowerlim.

Example that just adds simple padding to data:

>>> data = [0.5, 0.6, 0.4, 0.4, 0.3, 0.5]
>>> setter_default = AxLimSetter()
>>> setter_default.get_lims(data)
(-0.03, 0.63)

Now use the max_from_quantile option to set an upper limit that substantially exceeds the “noise” of the all-similar values:

>>> setter_max_quantile = AxLimSetter(max_from_quantile=(0.5, 0.05))
>>> setter_max_quantile.get_lims(data)
(-0.45, 9.45)

Demonstrate min_upperlim:

>>> setter_min_upperlim = AxLimSetter(max_from_quantile=(0.5, 0.05),
...                                   min_upperlim=10)
>>> setter_min_upperlim.get_lims(data)
(-0.45, 10.0)

get_lims(data)

Get 2-tuple (ax_min, ax_max) given list or array of data.

dmslogo.utils.breaksAndLabels(xi, x, n)

Get breaks and labels for an axis.

Useful when you would like to re-label a numeric x-axis with string labels.

Uses matplotlib.ticker.MaxNLocator to choose pretty breaks.

Args:

xi (list or array)

Integer values actually assigned to axis points.

x (list)

Strings corresponding to each numeric value in xi.

n (int)

Approximate number of ticks to use.

Returns:

The tuple (breaks, labels) where breaks gives the locations of breaks taken from xi, and labels is the label for each break.

>>> xi = list(range(213))
>>> x = [str(i + 1) for i in xi]
>>> (breaks, labels) = breaksAndLabels(xi, x, 5)
>>> breaks
[0, 50, 100, 150, 200]
>>> labels
['1', '51', '101', '151', '201']

dmslogo.utils.despine(fig=None, ax=None, top=True, right=True, left=False, bottom=False, offset=None, trim=False)

Remove the top and right spines from plot(s).

Args:

fig (matplotlib figure)

Figure to despine all axes of, default uses current figure.

ax (matplotlib axes)

Specific axes object to despine.

top, right, left, bottom (bool)

If True, remove that spine.

offset (int or dict)

Absolute distance, in points, spines should be moved away from the axes (negative values move spines inward). A single value applies to all spines; a dict can be used to set offset values per side.

trim (bool)

If True, limit spines to the smallest and largest major tick on each non-despined axis.