milia.plot.mpl.draw#

Matplotlib primitives behind every figure (same signatures as milia.plot.lets.draw).

Figures follow the house style of milia.plot.style; call milia.plot.style.configure() once beforehand.

Functions

band(frame, x, y, group, low, high[, ...])

Per-entity traces over a shaded band, entities leaving it highlighted.

bars(frame, x, y[, fill, facet, flip, ...])

Bar chart, dodged by fill, optionally horizontal and faceted.

dumbbell(frame, y, start, end[, title, ...])

Dumbbell chart: a start and end value per row, joined by a segment.

finish(fig, axes, keys, title, xlabel, ylabel)

Reference lines, panel titles, axis labels, house spines and a legend below the first axes.

grid(frame, facet[, fraction, aspect, minimum])

A figure with one axes per facet value, or a single axes.

groups(frame, x, y, group[, highlight, ...])

Points of many groups, each outlined, numbered and given its own marker.

heat(frame, x, y, value[, text, title, ...])

Heatmap of a value over two categorical axes, optionally annotated.

hist(frame, x[, fill, vlines, bins, title, ...])

Histogram, optionally split by a column.

lines(frame, x, y[, color, facet, points, ...])

Line chart: one line per series, optionally one panel per facet.

ranges(frame, y, x, low, high[, title, ...])

Points with horizontal ranges, one row per item (e.g. ranks with intervals).

scatter(frame, x, y[, color, label, hlines, ...])

Scatter plot, optionally coloured and labelled.

series(frame, color[, palette])

Split rows into series with their colours.

strip(frame, x, y[, color, hlines, title, ...])

Jittered strip of values per category.

milia.plot.mpl.draw.grid(frame, facet, fraction=0.48, aspect=0.618, minimum=0.0)#

A figure with one axes per facet value, or a single axes.

Parameters:
  • frame (DataFrame) – Data.

  • facet (str | None) – Column whose values become panels, sorted; None for one axes.

  • fraction (float) – Share of the text width a single panel occupies.

  • aspect (float) – Height-to-width ratio of a panel.

  • minimum (float) – Smallest height of a row of panels, in inches.

Return type:

tuple[Figure, list[Axes], list]

Returns:

(figure, axes, keys) – the figure, one axes per panel and each panel’s facet value.

Examples

>>> import pandas as pd
>>> figure, axes, keys = grid(pd.DataFrame({"f": ["b", "a"]}), "f")
>>> keys
['a', 'b']
milia.plot.mpl.draw.finish(fig, axes, keys, title, xlabel, ylabel, hlines=(), vlines=())#

Reference lines, panel titles, axis labels, house spines and a legend below the first axes.

Parameters:
  • fig (Figure) – The figure.

  • axes (list[Axes]) – Its axes.

  • keys (list) – Facet value of each axes (None for no title).

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label of the first axes.

  • hlines (Sequence[float]) – y values of dotted reference lines.

  • vlines (Sequence[float]) – x values of dotted reference lines.

Return type:

Figure

Returns:

The figure.

Examples

>>> import pandas as pd
>>> figure, axes, keys = grid(pd.DataFrame({"x": [1]}), None)
>>> finish(figure, axes, keys, "t", "x", "y", hlines=(0.5,)).axes[0].get_ylabel()
'y'
milia.plot.mpl.draw.series(frame, color, palette=None)#

Split rows into series with their colours.

Parameters:
  • frame (DataFrame) – Data.

  • color (str | None) – Column splitting series; one series when None.

  • palette (dict | None) – Fixed colour per series value; the palette in order by default.

Return type:

list[tuple[object, DataFrame, str]]

Returns:

(name, rows, colour) per series.

Examples

>>> import pandas as pd
>>> [name for name, _, _ in series(pd.DataFrame({"c": ["a", "b", "a"]}), "c")]
['a', 'b']
milia.plot.mpl.draw.lines(frame, x, y, color=None, facet=None, points=False, group=None, hlines=(), vlines=(), title=None, xlabel=None, ylabel=None, palette=None, widths=None)#

Line chart: one line per series, optionally one panel per facet.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Long-form data.

  • x (str) – x column.

  • y (str) – y column.

  • color (str | None) – Column splitting series.

  • facet (str | None) – Column splitting panels.

  • points (bool) – Also mark the points.

  • group (str | None) – Column grouping rows into separate lines within a series.

  • hlines (Sequence[float]) – y values of dotted reference lines.

  • vlines (Sequence[float]) – x values of dotted reference lines.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

  • palette (dict | None) – Fixed colour per series value.

  • widths (dict | None) – Line width per series value.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = lines(pd.DataFrame({"x": [0, 1], "y": [1.0, 2.0]}), "x", "y")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.bars(frame, x, y, fill=None, facet=None, flip=False, hlines=(), title=None, xlabel=None, ylabel=None)#

Bar chart, dodged by fill, optionally horizontal and faceted.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Long-form data.

  • x (str) – Category column.

  • y (str) – Value column.

  • fill (str | None) – Column splitting bars.

  • facet (str | None) – Column splitting panels.

  • flip (bool) – Draw horizontal bars.

  • hlines (Sequence[float]) – Values of reference lines.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = bars(pd.DataFrame({"x": ["a", "b"], "y": [1.0, 2.0]}), "x", "y")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.heat(frame, x, y, value, text=True, title=None, xlabel=None, ylabel=None)#

Heatmap of a value over two categorical axes, optionally annotated.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Long-form data.

  • x (str) – Column of the x category.

  • y (str) – Column of the y category.

  • value (str) – Column of the value.

  • text (bool) – Write each value in its cell.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = heat(pd.DataFrame({"a": ["x", "y"], "b": ["u", "u"], "v": [0.1, 0.9]}), "a", "b", "v")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.scatter(frame, x, y, color=None, label=None, hlines=(), vlines=(), title=None, xlabel=None, ylabel=None)#

Scatter plot, optionally coloured and labelled.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Data.

  • x (str) – x column.

  • y (str) – y column.

  • color (str | None) – Column colouring points.

  • label (str | None) – Column labelling points.

  • hlines (Sequence[float]) – y values of reference lines.

  • vlines (Sequence[float]) – x values of reference lines.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = scatter(pd.DataFrame({"x": [0.0, 1.0], "y": [1.0, 0.0]}), "x", "y")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.groups(frame, x, y, group, highlight=None, markers=True, numbers=True, outline=True, title=None, xlabel=None, ylabel=None)#

Points of many groups, each outlined, numbered and given its own marker.

Colour alone cannot identify many groups, so each group has a marker shape, a pale outline (the convex hull of its points) and its name at its median. Neighbouring groups take the most different colours of the palette, and one group can be drawn in the highlight colour.

Matplotlib primitive behind milia.plot.figures.clusters.scatter().

Parameters:
  • frame (DataFrame) – Data.

  • x (str) – x column.

  • y (str) – y column.

  • group (str) – Column naming the group of each point.

  • highlight (str | None) – Name of the group drawn in the highlight colour.

  • markers (bool) – Give each group its own marker shape.

  • numbers (bool) – Write the name of each group at its median.

  • outline (bool) – Draw the convex hull of each group in a pale tint.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> data = pd.DataFrame({"x": [0, 1, 0, 5, 6, 5], "y": [0, 0, 1, 5, 5, 6], "g": ["1"] * 3 + ["2"] * 3})
>>> type(groups(data, "x", "y", "g")).__name__
'Figure'
milia.plot.mpl.draw.strip(frame, x, y, color=None, hlines=(), title=None, xlabel=None, ylabel=None)#

Jittered strip of values per category.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Data.

  • x (str) – Category column.

  • y (str) – Value column.

  • color (str | None) – Column colouring points.

  • hlines (Sequence[float]) – y values of reference lines.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = strip(pd.DataFrame({"x": ["a", "a", "b"], "y": [1.0, 2.0, 3.0]}), "x", "y")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.hist(frame, x, fill=None, vlines=(), bins=30, title=None, xlabel=None, ylabel=None)#

Histogram, optionally split by a column.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Data.

  • x (str) – Value column.

  • fill (str | None) – Column splitting the histogram.

  • vlines (Sequence[float]) – x values of reference lines.

  • bins (int) – Number of bins.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label; count by default.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = hist(pd.DataFrame({"x": [0.1, 0.4, 0.5]}), "x", bins=3)
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.ranges(frame, y, x, low, high, title=None, xlabel=None, ylabel=None)#

Points with horizontal ranges, one row per item (e.g. ranks with intervals).

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Data, in display order.

  • y (str) – Column naming each row.

  • x (str) – Column of the point.

  • low (str) – Column of the range start.

  • high (str) – Column of the range end.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = ranges(pd.DataFrame({"n": ["a"], "r": [1], "lo": [1], "hi": [2]}), "n", "r", "lo", "hi")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.dumbbell(frame, y, start, end, title=None, xlabel=None, ylabel=None)#

Dumbbell chart: a start and end value per row, joined by a segment.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Data.

  • y (str) – Column naming each row.

  • start (str) – Column of the start value.

  • end (str) – Column of the end value.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = dumbbell(pd.DataFrame({"n": ["a"], "s": [0.9], "e": [0.2]}), "n", "s", "e")
>>> type(figure).__name__
'Figure'
milia.plot.mpl.draw.band(frame, x, y, group, low, high, flagged=None, title=None, xlabel=None, ylabel=None)#

Per-entity traces over a shaded band, entities leaving it highlighted.

Matplotlib primitive behind the figures of milia.plot.figures.

Parameters:
  • frame (DataFrame) – Long-form traces.

  • x (str) – Step column.

  • y (str) – Value column.

  • group (str) – Entity column.

  • low (float) – Lower bound of the band.

  • high (float) – Upper bound of the band.

  • flagged (str | None) – Boolean column marking entities to highlight.

  • title (str | None) – Figure title.

  • xlabel (str | None) – x-axis label.

  • ylabel (str | None) – y-axis label.

Return type:

Figure

Returns:

A matplotlib Figure.

Examples

>>> import pandas as pd
>>> figure = band(pd.DataFrame({"s": [0, 1], "v": [1.0, 1.2], "g": ["a", "a"]}), "s", "v", "g", 0.9, 1.1)
>>> type(figure).__name__
'Figure'