Geoms¶

Point and Distribution Geoms¶

geom_pointdensity¶

class plotnine_extra.geom_pointdensity(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_point

Scatterplot with density estimation at each point

Usage

geom_pointdensity(
mapping=None, data=None, *, stat=”pointdensity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y alpha `1`{.py} color `’black’`{.py} fill `None`{.py} group shape `’o’`{.py} size `1.5`{.py} stroke `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="pointdensity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_PARAMS = {'na_rm': False, 'position': 'identity', 'stat': 'pointdensity'}¶: Required parameters for the geom

geom_beeswarm¶

class plotnine_extra.geom_beeswarm(mapping=None, data=None, **kwargs)[source]¶

Bases: _PositionGeomMixin, plotnine.geom_point

Points jittered to avoid overplotting using the beeswarm algorithm

Points are arranged so that they do not overlap, producing a layout that resembles a beeswarm. The shape gives a good indication of the data distribution while showing every individual observation.

Usage

geom_beeswarm(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y alpha `1`{.py} color `’black’`{.py} fill `None`{.py} group shape `’o’`{.py} size `1.5`{.py} stroke `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
method (str) – Algorithm for arranging points: "swarm" (default), "compactswarm", "center" / "centre", "hex", or "square".
cex (float) – Scaling factor for point spacing (1-3 recommended).
side (int) – 0 both sides (default), 1 right/up only, -1 left/down only.
priority (str) – Placement order: "ascending" (default), "descending", "density", "random", "none".
dodge_width (float | None) – Amount by which to dodge overlapping groups.
corral (str) – Handle runaway points: "none" (default), "gutter", "wrap", "random", "omit".
corral_width (float) – Width of the corral region.
**kwargs (Any) – Aesthetics or parameters used by the stat.

See also

plotnine_extra.positions.position_beeswarm, plotnine_extra.geoms.geom_quasirandom.geom_quasirandom

DEFAULT_PARAMS = {'na_rm': False, 'position': 'identity', 'stat': 'identity'}¶: Required parameters for the geom

geom_quasirandom¶

class plotnine_extra.geom_quasirandom(mapping=None, data=None, **kwargs)[source]¶

Bases: _PositionGeomMixin, plotnine.geom_point

Points jittered to reduce overplotting using quasi-random noise

The jitter is density-aware so the point cloud reflects the underlying data distribution, similar to a violin plot with individual points.

Usage

geom_quasirandom(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y alpha `1`{.py} color `’black’`{.py} fill `None`{.py} group shape `’o’`{.py} size `1.5`{.py} stroke `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
method (str) – "quasirandom" (default) for a van der Corput low-discrepancy sequence, or "pseudorandom" for uniform random jitter.
width (float | None) – Maximum jitter width. None auto-calculates from the data resolution.
varwidth (bool) – Scale width proportionally to group size.
bandwidth (float) – Bandwidth adjustment for the density estimate.
nbins (int | None) – Number of bins for density estimation.
dodge_width (float | None) – Amount by which to dodge overlapping groups.
**kwargs (Any) – Aesthetics or parameters used by the stat.

See also

plotnine_extra.positions.position_quasirandom, plotnine_extra.geoms.geom_beeswarm.geom_beeswarm

DEFAULT_PARAMS = {'na_rm': False, 'position': 'identity', 'stat': 'identity'}¶: Required parameters for the geom

geom_spoke¶

class plotnine_extra.geom_spoke(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_segment

Line segment parameterised by location, direction and distance

Usage

geom_spoke(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, lineend=”butt”, arrow=None, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— angle radius x y alpha `1`{.py} color `’black’`{.py} group linetype `’solid’`{.py} size `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
**kwargs (Any) – Aesthetics or parameters used by the stat.

See also

plotnine.geom_segment: For documentation of extra parameters.

REQUIRED_AES = {'angle', 'radius', 'x', 'y'}¶: Required aesthetics for the geom

setup_data(data)[source]¶

Modify the data before drawing takes place

This function is called before position adjustments are done. It is used by geoms to create the final aesthetics used for drawing. The base class method does nothing, geoms can override this method for two reasons:

The stat does not create all the aesthetics (usually position aesthetics) required for drawing the geom, but those aesthetics can be computed from the available data. For example [](~plotnine.geoms.geom_boxplot) and [](~plotnine.geoms.geom_violin).
The geom inherits from another geom (superclass) which does the drawing and the superclass requires certain aesthetics to be present in the data. For example [](~plotnine.geoms.geom_tile) and [](~plotnine.geoms.geom_area).

Parameters:: data (pd.DataFrame) – Data used for drawing the geom.
Returns:: Data used for drawing the geom.
Return type:: pd.DataFrame

geom_pointpath¶

class plotnine_extra.geom_pointpath(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_point

Draw points connected by a path.

Usage

geom_pointpath(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, linesize=0.5, linecolor=None, linetype=”solid”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y alpha `1`{.py} color `’black’`{.py} fill `None`{.py} group shape `’o’`{.py} size `1.5`{.py} stroke `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
linesize (float, default 0.5) – Width of the connecting line.
linecolor (str, optional) – Override the line colour. Defaults to the point colour.
linetype (str, default "solid") – Line dash pattern.
**kwargs (Any) – Aesthetics or parameters used by the stat.

Notes

Internally a geom_path layer is added alongside the point geom so a single + geom_pointpath() produces both artists. The path uses the same colour mapping as the points unless linecolor overrides it.

DEFAULT_PARAMS = {'linecolor': None, 'linesize': 0.5, 'linetype': 'solid', 'na_rm': False, 'position': 'identity', 'stat': 'identity'}¶: Required parameters for the geom

geom_outline_point¶

class plotnine_extra.geom_outline_point(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_point

Draw points with an outline halo.

Usage

geom_outline_point(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, outline_colour=”black”, outline_size=1.0, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y alpha `1`{.py} color `’black’`{.py} fill `None`{.py} group shape `’o’`{.py} size `1.5`{.py} stroke `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
outline_colour (str, default "black") – Colour of the halo.
outline_size (float, default 1.0) – Halo size, added to the regular point size.
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_PARAMS = {'na_rm': False, 'outline_colour': 'black', 'outline_size': 1.0, 'position': 'identity', 'stat': 'identity'}¶: Required parameters for the geom

Statistical Annotation Geoms¶

geom_bracket¶

class plotnine_extra.geom_bracket(mapping=None, data=None, **kwargs)[source]¶

Bases: geom

Draw significance brackets with labels

Draws a U-shaped bracket (two vertical tips connected by a horizontal bar) with a centered text label, typically used for significance annotations.

Usage

geom_bracket(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, tip_length=0.02, bracket_nudge_y=0, label_size=8, vjust=0, bracket=True, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label xmax xmin y alpha `1`{.py} color `’black’`{.py} group

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
tip_length (float, default=0.02) – Length of the bracket tips as a fraction of the y data range.
bracket_nudge_y (float, default=0) – Vertical offset for the bracket.
label_size (float, default=8) – Font size for the label text.
vjust (float, default=0) – Vertical justification of the label relative to the bracket.
bracket (bool, default=True) – If False, suppress the bracket line and draw only the label. Mirrors the bracket parameter of ggcompare::geom_bracket.
**kwargs (Any) – Aesthetics or parameters used by the stat.

REQUIRED_AES = {'label', 'xmax', 'xmin', 'y'}¶: Required aesthetics for the geom

DEFAULT_AES = {'alpha': 1, 'color': 'black'}¶: Default aesthetics for the geom

DEFAULT_PARAMS = {'bracket': True, 'bracket_nudge_y': 0, 'label_size': 8, 'na_rm': False, 'position': 'identity', 'stat': 'identity', 'tip_length': 0.02, 'vjust': 0}¶: Required parameters for the geom

static draw_legend(data, da, lyr)¶

Brackets carry no useful legend, return an empty area.

Parameters:

data (pd.Series)
da (DrawingArea)

Return type:

DrawingArea

static draw_group(data, panel_params, coord, ax, params)[source]¶

Plot data belonging to a group.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Keys of interest to the geom are:

`python "x_range" # tuple "y_range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (axes) – Axes on which to plot.
params (dict) – Combined parameters for the geom and stat. Also includes the zorder.

geom_pwc¶

class plotnine_extra.geom_pwc(mapping=None, data=None, **kwargs)[source]¶

Bases: geom_bracket

Pairwise comparison brackets (geom form of stat_pwc).

Usage

geom_pwc(
mapping=None, data=None, *, stat=”pwc”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, tip_length=0.02, bracket_nudge_y=0, label_size=8, vjust=0, bracket=True, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label xmax xmin y alpha `1`{.py} color `’black’`{.py} group

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="pwc") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
**kwargs (Any) – Aesthetics or parameters used by the stat.

Notes

All statistical-test parameters live on plotnine_extra.stats.stat_pwc. This class simply sets the default stat so that calling geom_pwc(...) is equivalent to writing stat_pwc(geom='bracket', ...). Rendering is inherited from geom_bracket.

DEFAULT_PARAMS = {'bracket': True, 'bracket_nudge_y': 0, 'label_size': 8, 'na_rm': False, 'position': 'identity', 'stat': 'pwc', 'tip_length': 0.02, 'vjust': 0}¶: Required parameters for the geom

geom_signif¶

class plotnine_extra.geom_signif(mapping=None, data=None, *, y_position=None, annotations=None, **kwargs)[source]¶

Bases: geom_bracket

Significance brackets with labels (ggsignif-style alias).

Matches geom_bracket in behaviour but lets ggsignif users keep their familiar parameter names:

y_position → bracket y position (top edge)
annotations → label aesthetic
xmin / xmax → passed straight through
tip_length / vjust → forwarded as-is

:param Same as geom_bracket. y_position and: :param annotations are accepted as aliases for y and: :param label to ease migration from ggsignif.:

Parameters:

y_position (Any)
annotations (Any)
kwargs (Any)

Box, Violin, and Margin Geoms¶

geom_box¶

class plotnine_extra.geom_box(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_rect

Draw a rectangular highlight box.

Usage

geom_box(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– —————- xmax xmin ymax ymin alpha `1`{.py} color `None`{.py} fill `’#595959’`{.py} group linetype `’solid’`{.py} size `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
**kwargs (Any) – Aesthetics or parameters used by the stat.

Notes

This is not a box-and-whisker plot. For that, see plotnine.geom_boxplot(). The class is provided to match the ggh4x naming.

DEFAULT_PARAMS = {'na_rm': False, 'position': 'identity', 'stat': 'identity'}¶: Required parameters for the geom

geom_half_boxplot¶

class plotnine_extra.geom_half_boxplot(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_boxplot

Half-width boxplot shifted to one side

Draws a narrower boxplot offset to the left or right, designed for combining with half-violins and jittered points in raincloud plots.

Usage

geom_half_boxplot(
mapping=None, data=None, *, stat=”boxplot”, position=”dodge2”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, width=None, outlier_alpha=1, outlier_color=None, outlier_shape=”o”, outlier_size=1.5, outlier_stroke=0.5, notch=False, varwidth=False, notchwidth=0.5, fatten=2, side=”r”, nudge=0, half_width=0.5, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– —————- lower middle upper x ymax ymin alpha `1`{.py} color `’#333333’`{.py} fill `’white’`{.py} group linetype `’solid’`{.py} shape `’o’`{.py} size `0.5`{.py} weight `1`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="boxplot") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="dodge2") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
side (str) – Which side to shift to: "r" (right) or "l" (left). Default "r".
nudge (float) – Additional horizontal offset in data units. Default 0.
half_width (float) – Width of the half-boxplot as a fraction of the full boxplot width. Default 0.5.
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_PARAMS = {'fatten': 2, 'half_width': 0.5, 'na_rm': False, 'notch': False, 'notchwidth': 0.5, 'nudge': 0, 'outlier_alpha': 1, 'outlier_color': None, 'outlier_shape': 'o', 'outlier_size': 1.5, 'outlier_stroke': 0.5, 'position': 'dodge2', 'side': 'r', 'stat': 'boxplot', 'varwidth': False, 'width': None}¶: Required parameters for the geom

static draw_group(data, panel_params, coord, ax, params)[source]¶

Plot data belonging to a group.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Keys of interest to the geom are:

`python "x_range" # tuple "y_range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (axes) – Axes on which to plot.
params (dict) – Combined parameters for the geom and stat. Also includes the zorder.

geom_half_violin¶

class plotnine_extra.geom_half_violin(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_violin

Half-violin plot showing one side of the density

Draws only the left or right half of a violin, enabling raincloud plots when combined with geom_boxplot and jittered points.

Usage

geom_half_violin(
mapping=None, data=None, *, stat=”ydensity”, position=”dodge”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, draw_quantiles=None, style=”full”, scale=”area”, trim=True, width=None, side=”r”, nudge=0, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– —————- x y alpha `1`{.py} color `’#333333’`{.py} fill `’white’`{.py} group linetype `’solid’`{.py} size `0.5`{.py} weight `1`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="ydensity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="dodge") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
side (str) – Which side to draw: "r" (right/top) or "l" (left/bottom). Default "r".
nudge (float) – Amount to shift the half-violin away from center in data units. Default 0.
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_PARAMS = {'draw_quantiles': None, 'na_rm': False, 'nudge': 0, 'position': 'dodge', 'scale': 'area', 'side': 'r', 'stat': 'ydensity', 'style': 'full', 'trim': True, 'width': None}¶: Required parameters for the geom

static draw_group(data, panel_params, coord, ax, params)[source]¶

Plot data belonging to a group.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Keys of interest to the geom are:

`python "x_range" # tuple "y_range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (axes) – Axes on which to plot.
params (dict) – Combined parameters for the geom and stat. Also includes the zorder.

geom_rectmargin¶

class plotnine_extra.geom_rectmargin(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_rect

Draw rectangles in the panel margin(s).

Usage

geom_rectmargin(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, sides=”b”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– —————- xmax xmin ymax ymin alpha `1`{.py} color `None`{.py} fill `’#595959’`{.py} group linetype `’solid’`{.py} size `0.5`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
sides (str, default "b") – Which margin to draw on. Concatenation of "t", "b", "l", "r".
**kwargs (Any) – Aesthetics or parameters used by the stat.

Notes

Marginal positioning is achieved by mapping ymin / ymax to -Inf / Inf (or xmin / xmax) so the rectangles span the panel edge. sides controls which axis is collapsed.

DEFAULT_PARAMS = {'na_rm': False, 'position': 'identity', 'sides': 'b', 'stat': 'identity'}¶: Required parameters for the geom

setup_data(data)[source]¶

Modify the data before drawing takes place

The stat does not create all the aesthetics (usually position aesthetics) required for drawing the geom, but those aesthetics can be computed from the available data. For example [](~plotnine.geoms.geom_boxplot) and [](~plotnine.geoms.geom_violin).
The geom inherits from another geom (superclass) which does the drawing and the superclass requires certain aesthetics to be present in the data. For example [](~plotnine.geoms.geom_tile) and [](~plotnine.geoms.geom_area).

Parameters:: data – Data used for drawing the geom.
Returns:: Data used for drawing the geom.

geom_tilemargin¶

class plotnine_extra.geom_tilemargin(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_tile

Draw tiles in the panel margin(s).

Usage

geom_tilemargin(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, sides=”b”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– —————- x y alpha `1`{.py} color `None`{.py} fill `’#333333’`{.py} group height `None`{.py} linetype `’solid’`{.py} size `0.1`{.py} width `None`{.py}

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
sides (str, default "b") – Which margin to draw on. Concatenation of "t", "b", "l", "r".
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_PARAMS = {'na_rm': False, 'position': 'identity', 'sides': 'b', 'stat': 'identity'}¶: Required parameters for the geom

setup_data(data)[source]¶

Modify the data before drawing takes place

The stat does not create all the aesthetics (usually position aesthetics) required for drawing the geom, but those aesthetics can be computed from the available data. For example [](~plotnine.geoms.geom_boxplot) and [](~plotnine.geoms.geom_violin).
The geom inherits from another geom (superclass) which does the drawing and the superclass requires certain aesthetics to be present in the data. For example [](~plotnine.geoms.geom_tile) and [](~plotnine.geoms.geom_area).

Parameters:: data – Data used for drawing the geom.
Returns:: Data used for drawing the geom.

Text Geoms¶

geom_richtext¶

class plotnine_extra.geom_richtext(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_text

Text labels with a background box and basic rich-text formatting

An enhanced version of geom_label that supports a subset of markdown and HTML formatting in label text:

**bold** → bold text
*italic* → italic text
  → line break
x → superscript
x → subscript

Usage

geom_richtext(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, parse=False, nudge_x=0, nudge_y=0, adjust_text=None, format_string=None, path_effects=None, boxstyle=”round”, boxcolor=None, label_padding=0.25, label_r=0.15, label_size=0.7, tooth_size=None, text_color=None, fill_alpha=None, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label x y alpha `1`{.py} angle `0`{.py} color `’black’`{.py} family `None`{.py} fill `’white’`{.py} fontstyle `’normal’`{.py} fontvariant `None`{.py} fontweight `’normal’`{.py} group ha `’center’`{.py} lineheight `1.2`{.py} size `11`{.py} va `’center’`{.py}

The bold aesthetics are required.

Aesthetics Descriptions

size

: Float or one of:

```python {

”xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”

ha

: Horizontal alignment. One of `{“left”, “center”, “right”}`{.py}.

va

: Vertical alignment. One of
`{“top”, “center”, “bottom”, “baseline”, “center_baseline”}`{.py}.

family

: Font family. Can be a font name
e.g. “Arial”, “Helvetica”, “Times”, … or a family that is one of `{“serif”, “sans-serif”, “cursive”, “fantasy”, “monospace”}}`{.py}

fontweight

: Font weight. A numeric value in range 0-1000 or a string that is
one of:

```python {

”ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”

fontstyle

: Font style. One of `{“normal”, “italic”, “oblique”}`{.py}.

fontvariant

: Font variant. One of `{“normal”, “small-caps”}`{.py}.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
boxstyle (str) – Matplotlib box style ("round", "square", etc.).
boxcolor (str | None) – Border colour of the label box. None uses the text colour.
label_padding (float) – Padding inside the box.
label_r (float) – Corner-rounding radius (for round box styles).
label_size (float) – Border line width of the box.
text_color (str | None) – Override text colour independently of the box colour.
fill_alpha (float | None) – Alpha for the fill colour (separate from text alpha).
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_AES = {'alpha': 1, 'angle': 0, 'color': 'black', 'family': None, 'fill': 'white', 'fontstyle': 'normal', 'fontvariant': None, 'fontweight': 'normal', 'ha': 'center', 'lineheight': 1.2, 'size': 11, 'va': 'center'}¶: Default aesthetics for the geom

DEFAULT_PARAMS = {'adjust_text': None, 'boxcolor': None, 'boxstyle': 'round', 'fill_alpha': None, 'format_string': None, 'label_padding': 0.25, 'label_r': 0.15, 'label_size': 0.7, 'na_rm': False, 'nudge_x': 0, 'nudge_y': 0, 'parse': False, 'path_effects': None, 'position': 'identity', 'stat': 'identity', 'text_color': None, 'tooth_size': None}¶: Required parameters for the geom

static draw_group(data, panel_params, coord, ax, params)[source]¶

Plot data belonging to a group.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Keys of interest to the geom are:

`python "x_range" # tuple "y_range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (axes) – Axes on which to plot.
params (dict) – Combined parameters for the geom and stat. Also includes the zorder.

static draw_legend(data, da, lyr)[source]¶

Draw letter ‘a’ in the box

Parameters:

data (Series) – Data Row
da (DrawingArea) – Canvas
lyr (layer) – Layer

Returns:

out

Return type:

DrawingArea

geom_textbox¶

class plotnine_extra.geom_textbox(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_text

Text box with word wrapping

Draws a box of defined size containing text that is automatically wrapped at word boundaries. Supports the same basic markdown formatting as geom_richtext.

Usage

geom_textbox(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, parse=False, nudge_x=0, nudge_y=0, adjust_text=None, format_string=None, path_effects=None, boxstyle=”round”, boxcolor=None, label_padding=0.4, label_r=0.15, label_size=0.5, tooth_size=None, text_width=30, halign=”left”, valign=”top”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label x y alpha `1`{.py} angle `0`{.py} color `’black’`{.py} family `None`{.py} fill `’white’`{.py} fontstyle `’normal’`{.py} fontvariant `None`{.py} fontweight `’normal’`{.py} group ha `’center’`{.py} lineheight `1.2`{.py} size `11`{.py} va `’center’`{.py}

The bold aesthetics are required.

Aesthetics Descriptions

size

: Float or one of:

```python {

”xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”

ha

: Horizontal alignment. One of `{“left”, “center”, “right”}`{.py}.

va

: Vertical alignment. One of
`{“top”, “center”, “bottom”, “baseline”, “center_baseline”}`{.py}.

family

: Font family. Can be a font name
e.g. “Arial”, “Helvetica”, “Times”, … or a family that is one of `{“serif”, “sans-serif”, “cursive”, “fantasy”, “monospace”}}`{.py}

fontweight

: Font weight. A numeric value in range 0-1000 or a string that is
one of:

```python {

”ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”

fontstyle

: Font style. One of `{“normal”, “italic”, “oblique”}`{.py}.

fontvariant

: Font variant. One of `{“normal”, “small-caps”}`{.py}.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
boxstyle (str) – Matplotlib box style ("round", "square", etc.).
boxcolor (str | None) – Border colour of the text box.
label_padding (float) – Inner padding around the text.
label_r (float) – Corner-rounding radius.
label_size (float) – Border line width.
text_width (int) – Maximum number of characters per line for word wrapping.
halign (str) – Horizontal text alignment inside the box: "left" (default), "center", or "right".
valign (str) – Vertical text alignment inside the box: "top" (default), "center", or "bottom".
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_AES = {'alpha': 1, 'angle': 0, 'color': 'black', 'family': None, 'fill': 'white', 'fontstyle': 'normal', 'fontvariant': None, 'fontweight': 'normal', 'ha': 'center', 'lineheight': 1.2, 'size': 11, 'va': 'center'}¶: Default aesthetics for the geom

DEFAULT_PARAMS = {'adjust_text': None, 'boxcolor': None, 'boxstyle': 'round', 'format_string': None, 'halign': 'left', 'label_padding': 0.4, 'label_r': 0.15, 'label_size': 0.5, 'na_rm': False, 'nudge_x': 0, 'nudge_y': 0, 'parse': False, 'path_effects': None, 'position': 'identity', 'stat': 'identity', 'text_width': 30, 'tooth_size': None, 'valign': 'top'}¶: Required parameters for the geom

static draw_group(data, panel_params, coord, ax, params)[source]¶

Plot data belonging to a group.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Keys of interest to the geom are:

`python "x_range" # tuple "y_range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (axes) – Axes on which to plot.
params (dict) – Combined parameters for the geom and stat. Also includes the zorder.

static draw_legend(data, da, lyr)[source]¶

Draw letter ‘a’ in the box

Parameters:

data (Series) – Data Row
da (DrawingArea) – Canvas
lyr (layer) – Layer

Returns:

out

Return type:

DrawingArea

geom_text_repel¶

class plotnine_extra.geom_text_repel(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_text

Repulsive text labels that avoid overlapping

Labels are repositioned using a force-directed algorithm to avoid overlapping each other and data points. Connector segments are drawn from the original data point to the repositioned label.

Usage

geom_text_repel(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, parse=False, nudge_x=0, nudge_y=0, adjust_text=None, format_string=None, path_effects=None, box_padding=0.01, point_padding=0.01, force=1.0, max_iter=500, seed=42, min_segment_length=0.01, segment_color=”grey”, segment_alpha=0.6, segment_size=0.5, direction=”both”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label x y alpha `1`{.py} angle `0`{.py} color `’black’`{.py} family `None`{.py} fontstyle `’normal’`{.py} fontvariant `None`{.py} fontweight `’normal’`{.py} group ha `’center’`{.py} lineheight `1.2`{.py} size `8`{.py} va `’center’`{.py}

The bold aesthetics are required.

Aesthetics Descriptions

size

: Float or one of:

```python {

”xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”

ha

: Horizontal alignment. One of `{“left”, “center”, “right”}`{.py}.

va

: Vertical alignment. One of
`{“top”, “center”, “bottom”, “baseline”, “center_baseline”}`{.py}.

family

: Font family. Can be a font name
e.g. “Arial”, “Helvetica”, “Times”, … or a family that is one of `{“serif”, “sans-serif”, “cursive”, “fantasy”, “monospace”}}`{.py}

fontweight

: Font weight. A numeric value in range 0-1000 or a string that is
one of:

```python {

”ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”

fontstyle

: Font style. One of `{“normal”, “italic”, “oblique”}`{.py}.

fontvariant

: Font variant. One of `{“normal”, “small-caps”}`{.py}.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
box_padding (float) – Padding around text boxes (fraction of axis range).
point_padding (float) – Padding around data points (fraction of axis range).
force (float) – Repulsion force multiplier.
max_iter (int) – Maximum repulsion iterations.
seed (int) – Random seed for reproducibility.
min_segment_length (float) – Minimum segment length (fraction of x-range) below which no connector line is drawn.
segment_color (str) – Colour of connector segments.
segment_alpha (float) – Alpha of connector segments.
segment_size (float) – Line width of connector segments.
direction (str) – "both", "x", or "y": restricts which axes are affected by repulsion.
**kwargs (Any) – Aesthetics or parameters used by the stat.

REQUIRED_AES = {'label', 'x', 'y'}¶: Required aesthetics for the geom

DEFAULT_AES = {'alpha': 1, 'angle': 0, 'color': 'black', 'family': None, 'fontstyle': 'normal', 'fontvariant': None, 'fontweight': 'normal', 'ha': 'center', 'lineheight': 1.2, 'size': 8, 'va': 'center'}¶: Default aesthetics for the geom

DEFAULT_PARAMS = {'adjust_text': None, 'box_padding': 0.01, 'direction': 'both', 'force': 1.0, 'format_string': None, 'max_iter': 500, 'min_segment_length': 0.01, 'na_rm': False, 'nudge_x': 0, 'nudge_y': 0, 'parse': False, 'path_effects': None, 'point_padding': 0.01, 'position': 'identity', 'seed': 42, 'segment_alpha': 0.6, 'segment_color': 'grey', 'segment_size': 0.5, 'stat': 'identity'}¶: Required parameters for the geom

draw_panel(data, panel_params, coord, ax)[source]¶

Plot all groups

For efficiency, geoms that do not need to partition different groups before plotting should override this method and avoid the groupby.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Attributes are of interest to the geom are:

`python "panel_params.x.range" # tuple "panel_params.y.range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (Axes) – Axes on which to plot.
params – Combined parameters for the geom and stat. Also includes the zorder.

geom_label_repel¶

class plotnine_extra.geom_label_repel(mapping=None, data=None, **kwargs)[source]¶

Bases: geom_text_repel

Repulsive text labels with a background box

Like geom_text_repel but draws a filled rectangle behind each label for improved readability.

Usage

geom_label_repel(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, parse=False, nudge_x=0, nudge_y=0, adjust_text=None, format_string=None, path_effects=None, box_padding=0.01, point_padding=0.01, force=1.0, max_iter=500, seed=42, min_segment_length=0.01, segment_color=”grey”, segment_alpha=0.6, segment_size=0.5, direction=”both”, label_padding=0.25, fill_alpha=0.8, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label x y alpha `1`{.py} angle `0`{.py} color `’black’`{.py} family `None`{.py} fill `’white’`{.py} fontstyle `’normal’`{.py} fontvariant `None`{.py} fontweight `’normal’`{.py} group ha `’center’`{.py} lineheight `1.2`{.py} size `8`{.py} va `’center’`{.py}

The bold aesthetics are required.

Aesthetics Descriptions

size

: Float or one of:

```python {

”xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”

ha

: Horizontal alignment. One of `{“left”, “center”, “right”}`{.py}.

va

: Vertical alignment. One of
`{“top”, “center”, “bottom”, “baseline”, “center_baseline”}`{.py}.

family

: Font family. Can be a font name
e.g. “Arial”, “Helvetica”, “Times”, … or a family that is one of `{“serif”, “sans-serif”, “cursive”, “fantasy”, “monospace”}}`{.py}

fontweight

: Font weight. A numeric value in range 0-1000 or a string that is
one of:

```python {

”ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”

fontstyle

: Font style. One of `{“normal”, “italic”, “oblique”}`{.py}.

fontvariant

: Font variant. One of `{“normal”, “small-caps”}`{.py}.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
box_padding (float) – Padding around text boxes (fraction of axis range).
point_padding (float) – Padding around data points (fraction of axis range).
force (float) – Repulsion force multiplier.
max_iter (int) – Maximum repulsion iterations.
seed (int) – Random seed for reproducibility.
min_segment_length (float) – Minimum connector length (fraction of x-range).
segment_color (str) – Connector segment colour.
segment_alpha (float) – Connector segment alpha.
segment_size (float) – Connector line width.
direction (str) – "both", "x", or "y".
label_padding (float) – Padding inside the label box.
fill_alpha (float) – Alpha for the background fill.
**kwargs (Any) – Aesthetics or parameters used by the stat.

DEFAULT_AES = {'alpha': 1, 'angle': 0, 'color': 'black', 'family': None, 'fill': 'white', 'fontstyle': 'normal', 'fontvariant': None, 'fontweight': 'normal', 'ha': 'center', 'lineheight': 1.2, 'size': 8, 'va': 'center'}¶: Default aesthetics for the geom

DEFAULT_PARAMS = {'adjust_text': None, 'box_padding': 0.01, 'direction': 'both', 'fill_alpha': 0.8, 'force': 1.0, 'format_string': None, 'label_padding': 0.25, 'max_iter': 500, 'min_segment_length': 0.01, 'na_rm': False, 'nudge_x': 0, 'nudge_y': 0, 'parse': False, 'path_effects': None, 'point_padding': 0.01, 'position': 'identity', 'seed': 42, 'segment_alpha': 0.6, 'segment_color': 'grey', 'segment_size': 0.5, 'stat': 'identity'}¶: Required parameters for the geom

draw_panel(data, panel_params, coord, ax)[source]¶

Plot all groups

For efficiency, geoms that do not need to partition different groups before plotting should override this method and avoid the groupby.

Parameters:

data (pd.DataFrame) – Data to be plotted by this geom. This is the dataframe created in the plot_build pipeline.
panel_params (panel_view) –
The scale information as may be required by the axes. At this point, that information is about ranges, ticks and labels. Attributes are of interest to the geom are:

`python "panel_params.x.range" # tuple "panel_params.y.range" # tuple `
coord (coord) – Coordinate (e.g. coord_cartesian) system of the geom.
ax (Axes) – Axes on which to plot.
params – Combined parameters for the geom and stat. Also includes the zorder.

geom_text_aimed¶

class plotnine_extra.geom_text_aimed(mapping=None, data=None, **kwargs)[source]¶

Bases: plotnine.geom_text

Draw text rotated to align with a target direction.

Usage

geom_text_aimed(
mapping=None, data=None, *, stat=”identity”, position=”identity”, na_rm=False, inherit_aes=True, show_legend=None, raster=False, parse=False, nudge_x=0, nudge_y=0, adjust_text=None, format_string=None, path_effects=None, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label x y alpha `1`{.py} angle `0`{.py} color `’black’`{.py} family `None`{.py} fontstyle `’normal’`{.py} fontvariant `None`{.py} fontweight `’normal’`{.py} group ha `’center’`{.py} lineheight `1.2`{.py} size `11`{.py} va `’center’`{.py}

The bold aesthetics are required.

Aesthetics Descriptions

size

: Float or one of:

```python {

”xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”

ha

: Horizontal alignment. One of `{“left”, “center”, “right”}`{.py}.

va

: Vertical alignment. One of
`{“top”, “center”, “bottom”, “baseline”, “center_baseline”}`{.py}.

family

: Font family. Can be a font name
e.g. “Arial”, “Helvetica”, “Times”, … or a family that is one of `{“serif”, “sans-serif”, “cursive”, “fantasy”, “monospace”}}`{.py}

fontweight

: Font weight. A numeric value in range 0-1000 or a string that is
one of:

```python {

”ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”

fontstyle

: Font style. One of `{“normal”, “italic”, “oblique”}`{.py}.

fontvariant

: Font variant. One of `{“normal”, “small-caps”}`{.py}.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
stat (str | stat, default="identity") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
inherit_aes (bool, default=True) – If `False`{.py}, overrides the default aesthetics.
show_legend (bool | dict, default=None) – Whether this layer should be included in the legends. None`{.py} the default, includes any aesthetics that are mapped. If a [](:class:`bool), False`{.py} never includes and `True`{.py} always includes. A [](:class:`dict) can be used to exclude specific aesthetis of the layer from showing in the legend. e.g `show_legend={‘color’: False}`{.py}, any other aesthetic are included by default.
raster (bool, default=False) – If True, draw onto this layer a raster (bitmap) object even ifthe final image is in vector format.
**kwargs (Any) – Aesthetics or parameters used by the stat.

Notes

If the data contains both xend and yend columns, they are interpreted as the direction the text should point. Otherwise the regular angle aesthetic is used.

DEFAULT_PARAMS = {'adjust_text': None, 'format_string': None, 'na_rm': False, 'nudge_x': 0, 'nudge_y': 0, 'parse': False, 'path_effects': None, 'position': 'identity', 'stat': 'identity'}¶: Required parameters for the geom

setup_data(data)[source]¶

Modify the data before drawing takes place

The stat does not create all the aesthetics (usually position aesthetics) required for drawing the geom, but those aesthetics can be computed from the available data. For example [](~plotnine.geoms.geom_boxplot) and [](~plotnine.geoms.geom_violin).
The geom inherits from another geom (superclass) which does the drawing and the superclass requires certain aesthetics to be present in the data. For example [](~plotnine.geoms.geom_tile) and [](~plotnine.geoms.geom_area).

Parameters:: data (pd.DataFrame) – Data used for drawing the geom.
Returns:: Data used for drawing the geom.
Return type:: pd.DataFrame

Background Annotations¶

annotation_stripes¶

class plotnine_extra.annotation_stripes(fill=('#AAAAAA', '#CCCCCC'), fill_range='auto', direction='vertical', extend=(0, 1), **kwargs)[source]¶

Bases: plotnine.annotate

Alternating stripes, centered around each label.

Useful as a background for geom_jitter.

Parameters:

fill (Sequence[str]) – List of colors for the strips.
fill_range (Literal['auto', 'cycle', 'no', 'nocycle']) –
How to fill stripes beyond the range of scale:

```python “cycle” # keep cycling the colors of the

# stripes after the range ends

”nocycle” # stop cycling the colors of the
# stripes after the range ends

”auto” # “cycle” for continuous scales and
# “nocycle” for discrete scales.

”no” # Do not add stripes passed the range
# passed the range of the scales

```
direction (Literal['horizontal', 'vertical']) – Orientation of the stripes
extend (tuple[float, float]) – Range of the stripes. The default is (0, 1), top to bottom. The values should be in the range [0, 1].
**kwargs (Any) – Other aesthetic parameters for the rectangular stripes. They include; alpha, color, linetype, and size.