Facets and Strips

Extended Facets

The extended facets add selected ggh4x-style behaviours on top of plotnine’s facet system. Exact layout parity is limited by the extension points available in plotnine.

facet_grid2

class plotnine_extra.facet_grid2(rows=None, cols=None, *, margins=False, scales='fixed', space='fixed', shrink=True, labeller='label_value', as_table=True, drop=True, independent='none', axes='margins', remove_labels='none')

Bases: plotnine.facet_grid

Extended grid facets with independent scales.

Extends plotnine.facet_grid with support for truly independent position scales, configurable inner axes, and selective label removal.

Parameters:

• rows (str or list of str, optional) – Variables to facet by in rows.

• cols (str or list of str, optional) – Variables to facet by in columns.

• margins (bool or list of str) – Whether to display marginal facets.

• scales (str) – Whether scales are fixed (“fixed”), free (“free”, “free_x”, “free_y”).

• space (str or dict) – Panel spacing: “fixed”, “free”, “free_x”, “free_y” or a dict of ratios.

• shrink (bool) – Whether to shrink scales to fit output of statistics.

• labeller (str) – Labelling function for strip text.

• as_table (bool) – If True, facets are laid out like a table with the highest values at the bottom-right.

• drop (bool) – Whether to drop unused factor levels.

• independent (str) – Which axes have truly independent scales per panel. One of “none”, “x”, “y”, or “all”.

• axes (str) – Which inner axes to draw. One of “all”, “x”, “y”, or “margins”.

• remove_labels (str) – Which inner axis labels to remove. One of “none”, “x”, “y”, or “all”.

compute_layout(data)

Compute layout

Parameters:

data (list[pd.DataFrame]) – Dataframe for a each layer

Return type:

pd.DataFrame

init_scales(layout, x_scale=None, y_scale=None)

Initialise scales, applying any facetted_pos_scales.

Parameters:

• layout (pd.DataFrame)

• x_scale (Optional[scale])

• y_scale (Optional[scale])

Return type:

object

set_limits_breaks_and_labels(panel_params, ax)

Add limits, breaks and labels to the axes

Parameters:

• panel_params – range information for the axes

• ax – Axes

facet_wrap2

class plotnine_extra.facet_wrap2(facets=None, *, nrow=None, ncol=None, scales='fixed', shrink=True, labeller='label_value', as_table=True, drop=True, dir='h', axes='margins', remove_labels='none', trim_blank=True)

Bases: plotnine.facet_wrap

Extended wrapped facets.

Extends plotnine.facet_wrap with configurable inner axes, selective label removal, and blank-panel trimming.

Parameters:

• facets (str or list of str, optional) – Variables to facet by.

• nrow (int, optional) – Number of rows.

• ncol (int, optional) – Number of columns.

• scales (str) – Whether scales are fixed (“fixed”), free (“free”, “free_x”, “free_y”).

• shrink (bool) – Whether to shrink scales to fit output of statistics.

• labeller (str) – Labelling function for strip text.

• as_table (bool) – If True, facets are laid out like a table.

• drop (bool) – Whether to drop unused factor levels.

• dir (str) – Direction: “h” for horizontal, “v” for vertical.

• axes (str) – Which inner axes to draw. One of “all”, “x”, “y”, or “margins”.

• remove_labels (str) – Which inner axis labels to remove. One of “none”, “x”, “y”, or “all”.

• trim_blank (bool) – If True, trim blank panels from the layout.

compute_layout(data)

Compute layout

Parameters:

data (list[pd.DataFrame]) – Dataframe for a each layer

Return type:

pd.DataFrame

init_scales(layout, x_scale=None, y_scale=None)

Initialise scales, applying any facetted_pos_scales.

Parameters:

• layout (pd.DataFrame)

• x_scale (Optional[object])

• y_scale (Optional[object])

Return type:

object

set_limits_breaks_and_labels(panel_params, ax)

Add limits, breaks and labels to the axes

Parameters:

• panel_params – range information for the axes

• ax – Axes

facet_nested

class plotnine_extra.facet_nested(rows=None, cols=None, *, margins=False, scales='fixed', space='fixed', shrink=True, labeller='label_value', as_table=True, drop=True, nest_line=False, solo_line=False, resect=0, bleed=False)

Bases: plotnine.facet_grid

Grid facets with nested strips.

Extends plotnine.facet_grid so that hierarchical strip labels are merged when adjacent panels share the same parent category.

Parameters:

• rows (str or list of str, optional) – Variables to facet by in rows.

• cols (str or list of str, optional) – Variables to facet by in columns.

• margins (bool or list of str) – Whether to display marginal facets.

• scales (str) – Whether scales are fixed or free.

• space (str or dict) – Panel spacing mode.

• shrink (bool) – Whether to shrink scales to fit output of statistics.

• labeller (str) – Labelling function for strip text.

• as_table (bool) – If True, facets are laid out like a table.

• drop (bool) – Whether to drop unused factor levels.

• nest_line (bool) – If True, draw a nesting indicator line between parent and child strip levels.

• solo_line (bool) – If True, draw a line even when a parent category has only one child.

• resect (float) – Amount (in [0, 1]) to shorten the nesting line at each end.

• bleed (bool) – If True, allow nesting indicators to extend into neighbouring strips.

make_strips(layout_info, ax)

Create strips with merged parent labels.

When adjacent panels share the same value for a parent (outer) faceting variable, the duplicate label is blanked out so that the parent strip appears to span multiple panels.

Parameters:

• layout_info (layout_details)

• ax (Axes)

Return type:

Strips

set_limits_breaks_and_labels(panel_params, ax)

Add limits, breaks and labels to the axes

Parameters:

• panel_params – range information for the axes

• ax – Axes

facet_nested_wrap

class plotnine_extra.facet_nested_wrap(facets=None, *, nrow=None, ncol=None, scales='fixed', shrink=True, labeller='label_value', as_table=True, drop=True, dir='h', nest_line=False, solo_line=False, resect=0, bleed=False)

Bases: plotnine.facet_wrap

Wrapped facets with nested strips.

Extends plotnine.facet_wrap so that hierarchical strip labels are merged when adjacent panels share the same parent category.

Parameters:

• facets (str or list of str, optional) – Variables to facet by.

• nrow (int, optional) – Number of rows.

• ncol (int, optional) – Number of columns.

• scales (str) – Whether scales are fixed or free.

• shrink (bool) – Whether to shrink scales to fit output of statistics.

• labeller (str) – Labelling function for strip text.

• as_table (bool) – If True, facets are laid out like a table.

• drop (bool) – Whether to drop unused factor levels.

• dir (str) – Direction: “h” for horizontal, “v” for vertical.

• nest_line (bool) – If True, draw a nesting indicator line between parent and child strip levels.

• solo_line (bool) – If True, draw a line even when a parent category has only one child.

• resect (float) – Amount (in [0, 1]) to shorten the nesting line at each end.

• bleed (bool) – If True, allow nesting indicators to extend into neighbouring strips.

make_strips(layout_info, ax)

Create strips with merged parent labels.

When adjacent panels (in the same row) share the same value for a parent faceting variable, the duplicate label is blanked out so the parent strip visually spans those panels.

Parameters:

• layout_info (layout_details)

• ax (Axes)

Return type:

Strips

set_limits_breaks_and_labels(panel_params, ax)

Add limits, breaks and labels to the axes

Parameters:

• panel_params – range information for the axes

• ax – Axes

facet_manual

class plotnine_extra.facet_manual(facets=None, *, design=None, scales='fixed', shrink=True, labeller='label_value', as_table=True, drop=True, respect=False, widths=None, heights=None, axes='margins', remove_labels='none', trim_blank=False)

Bases: facet

Manually specify panel layout via a design matrix.

Allows arbitrary placement of facet panels using a text design string or a 2-D array. Use # to denote empty cells in the layout.

Parameters:

• facets (str or list of str, optional) – Variables to facet by. Each unique combination is assigned a panel label from the design.

• design (str or array-like, optional) – Layout specification. A multi-line string like "AB\n#C" or a 2-D list / numpy array.

• scales (str) – Whether scales are fixed (“fixed”), free (“free”, “free_x”, “free_y”).

• shrink (bool) – Whether to shrink scales to fit output of statistics.

• labeller (str) – Labelling function for strip text.

• as_table (bool) – If True, facets are laid out like a table.

• drop (bool) – Whether to drop unused factor levels.

• respect (bool) – If True, panel sizes respect the aspect ratio.

• widths (Optional[Sequence[float]])

• heights (Optional[Sequence[float]])

• axes (Literal['all', 'x', 'y', 'margins'])

• remove_labels (Literal['none', 'x', 'y', 'all'])

• trim_blank (bool)

compute_layout(data)

Compute layout

Parameters:

data (list[DataFrame]) – Dataframe for a each layer

Return type:

DataFrame

map(data, layout)

Assign a data points to panels

Parameters:

• data (DataFrame) – Data for a layer

• layout (DataFrame) – As returned by self.compute_layout

Returns:

Data with all points mapped to the panels on which they will be plotted.

Return type:

DataFrame

make_strips(layout_info, ax)

Create strips for the facet

Parameters:

• layout_info (layout_details) – Layout information. Row from the layout table

• ax (Axes) – Axes to label

Return type:

Strips

init_scales(layout, x_scale=None, y_scale=None)

Parameters:

• layout (pd.DataFrame)

• x_scale (Optional[scale])

• y_scale (Optional[scale])

Return type:

object

set_limits_breaks_and_labels(panel_params, ax)

Add limits, breaks and labels to the axes

Parameters:

• panel_params – range information for the axes

• ax – Axes

Per-panel Scales

Per-panel position scales are attached with + facetted_pos_scales(...) or through scale_x_facet and scale_y_facet. Use free or independent facet scales so plotnine can apply the per-panel replacements.

facetted_pos_scales

plotnine_extra.facetted_pos_scales(x=None, y=None)

Set individual position scales for facet panels.

Returns an object that, when added to a ggplot, attaches per-panel position scales. Compatible facets (e.g. facet_grid2, facet_wrap2) will pick up these scales and apply them during plotting.

Parameters:

• x (list of scales, optional) – Position scales for the x-axis, one per panel column (or per unique SCALE_X group).

• y (list of scales, optional) – Position scales for the y-axis, one per panel row (or per unique SCALE_Y group).

Returns:

Object that can be added to a ggplot to apply per-panel position scales.

Return type:

FacettedPosScales

Examples

from plotnine import *
from plotnine_extra.facets import (
    facet_wrap2,
    facetted_pos_scales,
)

(
    ggplot(df, aes("x", "y"))
    + geom_point()
    + facet_wrap2("group", scales="free_x")
    + facetted_pos_scales(
        x=[
            scale_x_continuous(limits=(0, 10)),
            scale_x_continuous(limits=(0, 50)),
        ]
    )
)

scale_x_facet

plotnine_extra.scale_x_facet(expr, *args, type='continuous', **kwargs)

Apply x-axis scale to specific facet panels.

Parameters:

• expr (str or callable) – Expression identifying which panels to target.

• *args (Any) – Forwarded to the underlying scale constructor.

• **kwargs (Any) – Forwarded to the underlying scale constructor.

• type (Literal['continuous', 'discrete'])

• **kwargs

Returns:

Object that can be added to a ggplot.

Return type:

ScaleFacet

scale_y_facet

plotnine_extra.scale_y_facet(expr, *args, type='continuous', **kwargs)

Apply y-axis scale to specific facet panels.

Parameters:

• expr (str or callable) – Expression identifying which panels to target.

• *args (Any) – Forwarded to the underlying scale constructor.

• **kwargs (Any) – Forwarded to the underlying scale constructor.

• type (Literal['continuous', 'discrete'])

• **kwargs

Returns:

Object that can be added to a ggplot.

Return type:

ScaleFacet

Strips

Strip helpers are accepted by the extended facets where plotnine permits custom strip rendering. Unsupported strip and layout combinations raise explicit errors rather than being ignored.

strip_nested

class plotnine_extra.strip_nested(*, nest_line=False, solo_line=False, resect=0, bleed=False)

Bases: Strip

Nested strip labels.

Merges adjacent strip labels that share the same parent value, producing a hierarchical strip display.

Parameters:

• nest_line (bool) – If True, draw a line between parent and child strip levels.

• solo_line (bool) – If True, draw a line even when there is only one child category.

• resect (float) – Amount (in [0, 1]) to shorten the nesting line at each end.

• bleed (bool) – If True, nesting indicators may extend into neighbouring strips.

setup(layout)

Prepare nested strip data from the layout.

Parameters:

layout (Any)

Return type:

None

draw(label_info)

Draw merged strip labels with optional nest lines.

Parameters:

label_info (Any)

Return type:

Any

strip_themed

class plotnine_extra.strip_themed(*, background_x=None, background_y=None, text_x=None, text_y=None)

Bases: Strip

Individually themed strip labels.

Allows each strip level or individual strips to have distinct visual styling (background colour, text style, etc.) via per-strip theme elements.

Parameters:

• background_x (list of theme elements, optional) – Background themes for horizontal strip levels.

• background_y (list of theme elements, optional) – Background themes for vertical strip levels.

• text_x (list of theme elements, optional) – Text themes for horizontal strip levels.

• text_y (list of theme elements, optional) – Text themes for vertical strip levels.

draw(label_info)

Draw strips with individual theme overrides.

Parameters:

label_info (Any)

Return type:

Any

strip_split

class plotnine_extra.strip_split(position=('top', 'right'))

Bases: Strip

Split strip labels across panel sides.

Places different faceting variable levels on different sides of the panel (e.g. one variable on top, another on the right).

Parameters:

position (list of str) – Where to place each strip level. Values are “top”, “bottom”, “left”, or “right”.

draw(label_info)

Draw strips on their assigned sides.

Parameters:

label_info (Any)

Return type:

Any

strip_tag

class plotnine_extra.strip_tag(tag_pool=None, *, position='topleft', prefix='', suffix='')

Bases: Strip

Tag-style strip labels.

Instead of a strip bar above or beside the panel, labels are rendered as a small text tag within the panel area (e.g. “(a)”, “(b)”, …).

Parameters:

• tag_pool (list of str, optional) – Labels to use. Defaults to uppercase A-Z.

• position (str) – Where within the panel to place the tag. One of “topleft”, “top”, “topright”, “left”, “right”, “bottomleft”, “bottom”, “bottomright”.

• prefix (str) – Text prepended to each tag (e.g. “(“).

• suffix (str) – Text appended to each tag (e.g. “)”).

draw(label_info)

Draw tag text within the panel area.

Parameters:

label_info (Any)

Return type:

Any