Composition¶

Compose¶

class plotnine_extra.Compose(items)[source]¶

Bases: object

Base class for those that create plot compositions

As a user, you will never directly work with this class, except through the operators that it makes possible. The operators are of two kinds:

### 1. Composing Operators

The combine plots or compositions into a single composition. Both operands are either a plot or a composition.

: Arrange operands vertically.: Powered by the subclass [](~plotnine_extra.composition.Stack).

: Arrange operands side by side.: Powered by the subclass [](~plotnine_extra.composition.Beside).

: Arrange operands side by side _and_ at the same nesting: level. Also powered by the subclass [](~plotnine_extra.composition.Beside).

: Arrange operands in a 2D grid.: Powered by the subclass [](~plotnine_extra.composition.Wrap).

### 2. Plot Modifying Operators

The modify all or some of the plots in a composition. The left operand is a composition and the right operand is a _plotaddable_; any object that can be added to a ggplot object e.g. _geoms_, _stats_, _themes_, _facets_, … .

: Add right hand side to all plots in the composition.

: Add right hand side to all plots in the top-most nesting: level of the composition.

: Add right hand side to the last plot in the composition.

Parameters:: items (list[ggplot | Compose]) – The objects to be arranged (composed)

See also

plotnine_extra.composition.Beside, plotnine_extra.composition.Stack, plotnine_extra.composition.Wrap, plotnine_extra.composition.plot_spacer

figure: Figure¶

property layout: plot_layout¶: The plot_layout of this composition

property annotation: plot_annotation¶: The plot_annotation of this composition

property nrow: int¶

property ncol: int¶

property theme: plotnine.theme¶

Theme for this composition

This is the default theme plus combined with theme from the annotation.

iter_sub_compositions()[source]¶

iter_plots()[source]¶

iter_plots_all()[source]¶: Recursively generate all plots under this composition

property last_plot: ggplot¶: Last plot added to the composition

show()[source]¶

Display plot in the cells output

This function is called for its side-effects.

draw(*, show=False)[source]¶

Render the arranged plots

Parameters:: show (bool) – Whether to show the plot.
Returns:: Matplotlib figure
Return type:: Figure

save(filename, format=None, dpi=None, **kwargs)[source]¶

Save a composition as an image file

Parameters:

filename (str | Path | BytesIO) – File name to write the plot to.
format (str | None) – Image format to use, automatically extracted from file name extension.
dpi (int | None) – DPI to use for raster graphics. If None, defaults to using the dpi of theme to the first plot.
**kwargs – These are ignored. Here to “softly” match the API of ggplot.save().

Beside¶

class plotnine_extra.Beside(items)[source]¶

Bases: Compose

Place plots or compositions side by side

Usage

plot | plot plot | composition composition | plot composition | composition

Typically, you will use this class through the | operator.

See also

plotnine_extra.composition.Stack, plotnine_extra.composition.Wrap, plotnine_extra.composition.plot_spacer, plotnine_extra.composition.Compose

Parameters:: items (list[ggplot | Compose])

Stack¶

class plotnine_extra.Stack(items)[source]¶

Bases: Compose

Place plots or compositions on top of each other

Usage

plot / plot plot / composition composition / plot composition / composition

Typically, you will use this class through the / operator.

See also

plotnine_extra.composition.Beside, plotnine_extra.composition.Wrap, plotnine_extra.composition.plot_spacer, plotnine_extra.composition.Compose

Parameters:: items (list[ggplot | Compose])

Wrap¶

class plotnine_extra.Wrap(items)[source]¶

Bases: Compose

Wrap plots or compositions into a grid

Usage

plot + plot plot + composition composition + plot composition + composition

Typically, you will use this class through the + operator.

Parameters:

items (list[ggplot | Compose]) – The objects to be arranged (composed)
nrow – Number of rows in the composition
ncol – Number of cols in the composition

See also

plotnine_extra.composition.Beside, plotnine_extra.composition.Stack, plotnine_extra.composition.plot_spacer, plotnine_extra.composition.Compose

plot_layout¶

plotnine_extra.plot_layout(*, nrow=None, ncol=None, byrow=None, widths=None, heights=None)[source]¶

Customise the layout of plots in a composition

Parameters:

nrow (int | None)
ncol (int | None)
byrow (bool | None)
widths (Sequence[float] | None)
heights (Sequence[float] | None)

Return type:

None

plot_annotation¶

plotnine_extra.plot_annotation(*, title=None, subtitle=None, caption=None, footer=None, theme=<factory>)[source]¶

Annotate a composition

This applies to only the top-level composition. When a composition with an annotation is added to larger composition, the annotation of the sub-composition becomes irrelevant.

Parameters:

title (str | None)
subtitle (str | None)
caption (str | None)
footer (str | None)
theme (plotnine.theme)

Return type:

None

plot_spacer¶

plotnine_extra.plot_spacer(fill=None)[source]¶

Blank area as wide or as tall as a plot

Parameters:

fill (str | tuple[float, float, float] | tuple[float, float, float, float] | None) –

Background color. The default is a transparent area, but it can be changed through this parameter.

The color can also be modified by adding a [](~plotnine.theme) and setting the [](~plotnine.themes.themeable.plot_background).

See also

plotnine_extra.composition.Beside, plotnine_extra.composition.Stack, plotnine_extra.composition.Compose