API Reference

Plot creation

ggplot

Create a new ggplot object

qplot

Quick plot

watermark

Add watermark to plot

layer

Layer

PlotnineAnimation

Animation using ggplot objects

save_as_pdf_pages

Save multiple ggplot objects to a PDF file, one per page.

Mapping Aesthetics

Aesthetics are the visual properties of a plot. The following functions control how the data (and calculations based on the data) is mapped to the aesthetics.

aes

Create aesthetic mappings

after_stat

Evaluate mapping after statistic has been calculated

after_scale

Evaluate mapping after variable has been mapped to the scale

stage

Stage allows you evaluating mapping at more than one stage

geoms

Geometric objects (geoms) are responsible for the visual representation of data points. geom_* classes determine the kind of geometric objects and every plot must have at least one geom added to it. The distinct visual aspects of the representation are controlled by the aes mapping.

geom

Base class of all Geoms

geom_abline

Lines specified by slope and intercept

geom_area

Area plot

geom_bar

Bar plot

geom_blank

An empty plot

geom_boxplot

Box and whiskers plot

geom_col

Bar plot with base on the x-axis

geom_count

Plot overlapping points

geom_crossbar

Vertical interval represented by a crossbar

geom_density

Smooth density estimate

geom_density_2d

2D density estimate

geom_dotplot

Dot plot

geom_errorbar

Vertical interval represented as an errorbar

geom_errorbarh

Horizontal interval represented as an errorbar

geom_freqpoly

Frequency polygon

geom_bin2d

Heatmap of 2d bin counts

geom_histogram

Histogram

geom_hline

Horizontal line

geom_jitter

Scatter plot with points jittered to reduce overplotting

geom_label

Textual annotations with a background

geom_line

Connected points

geom_linerange

Vertical interval represented by lines

geom_map

Draw map feature

geom_path

Connected points

geom_point

Plot points (Scatter plot)

geom_pointrange

Vertical interval represented by a line with a point

geom_polygon

Polygon, a filled path

geom_quantile

Quantile lines from a quantile regression

geom_qq

Quantile-Quantile plot

geom_qq_line

Quantile-Quantile Line plot

geom_rect

Rectangles

geom_ribbon

Ribbon plot

geom_rug

Marginal rug plot

geom_segment

Line segments

geom_sina

Draw a sina plot

geom_smooth

A smoothed conditional mean

geom_spoke

Line segment parameterised by location, direction and distance

geom_step

Stepped connected points

geom_text

Textual annotations

geom_tile

Rectangles specified using a center points

geom_violin

Violin Plot

geom_vline

Vertical line

Labels

labs(*args, **kwargs)

Add labels for aesthetics and/or title

xlab(xlab)

Create x-axis label

ylab(ylab)

Create y-axis label

ggtitle(title)

Create plot title

stats

Statistical transformations (stats) do aggregations and other computations on data before it is drawn out. stat_* determine the type of computation done on the data. Different types of computations yield varied results, so a stat must be paired with a geom that can represent all or some of the computations.

stat

Base class of all stats

stat_bin

Count cases in each interval

stat_bin_2d

2 Dimensional bin counts

stat_bindot

Binning for a dot plot

stat_boxplot

Compute boxplot statistics

stat_count

Counts the number of cases at each x position

stat_density

Compute density estimate

stat_density_2d

Compute 2D kernel density estimation

stat_ecdf

Emperical Cumulative Density Function

stat_ellipse

Calculate normal confidence interval ellipse

stat_function

Superimpose a function onto a plot

stat_hull

2 Dimensional Convex Hull

stat_identity

Identity (do nothing) statistic

stat_qq

Calculation for quantile-quantile plot

stat_qq_line

Calculate line through quantile-quantile plot

stat_quantile

Compute quantile regression lines

stat_sina

Compute Sina plot values

stat_smooth

Calculate a smoothed conditional mean

stat_sum

Sum unique values

stat_summary

Calculate summary statistics depending on x

stat_summary_bin

Summarise y values at x intervals

stat_unique

Remove duplicates

stat_ydensity

Density estimate

facets

Faceting is a way to subset data and plot it on different panels.

facet

Base class for all facets

facet_grid(facets[, margins, scales, space, ...])

Wrap 1D Panels onto 2D surface

facet_null([shrink, figure])

A single Panel

facet_wrap([facets, nrow, ncol, scales, ...])

Wrap 1D Panels onto 2D surface

labeller([rows, cols, multi_line, default])

Return a labeller function

as_labeller(x[, default, multi_line])

Coerse to labeller function

label_value(label_info[, multi_line])

Convert series values to str and maybe concatenate them

label_both(label_info[, multi_line, sep])

Concatenate the index and the value of the series.

label_context(label_info[, multi_line, sep])

Create an unabiguous label string

scales

Scales control the mapping from data to aesthetics. They take data and adjust it to fit the different aspects of the visual sense i.e. length, colour, size and shape.

Base scales

scale(**kwargs)

Base class for all scales

scale_discrete(**kwargs)

Base class for all discrete scales

scale_continuous(**kwargs)

Base class for all continuous scales

scale_datetime(**kwargs)

Base class for all date/datetime scales

Alpha scales

scale_alpha([range])

Continuous Alpha Scale

scale_alpha_discrete(**kwargs)

Discrete Alpha Scale

scale_alpha_continuous

alias of plotnine.scales.scale_alpha.scale_alpha

scale_alpha_datetime([range])

Datetime Alpha Scale

Identity Scales

scale_alpha_identity(**kwargs)

No alpha scaling

scale_color_identity(**kwargs)

No color scaling

scale_colour_identity

alias of plotnine.scales.scale_identity.scale_color_identity

scale_fill_identity(**kwargs)

No color scaling

scale_linetype_identity(**kwargs)

No linetype scaling

scale_shape_identity(**kwargs)

No shape scaling

scale_size_identity(**kwargs)

No size scaling

Color and fill scales

scale_color_brewer([type, palette, direction])

Sequential, diverging and qualitative discrete color scales

scale_color_cmap([cmap_name, lut])

Create color scales using Matplotlib colormaps

scale_color_continuous

alias of plotnine.scales.scale_color.scale_color_cmap

scale_color_desaturate([color, prop, reverse])

Create a desaturated color gradient

scale_color_datetime(**kwargs)

Datetime color scale

scale_color_discrete

alias of plotnine.scales.scale_color.scale_color_hue

scale_color_distiller([type, palette, ...])

Sequential and diverging continuous color scales

scale_color_gradient([low, high])

Create a 2 point color gradient

scale_color_gradient2([low, mid, high, midpoint])

Create a 3 point diverging color gradient

scale_color_gradientn(colors[, values])

Create a n color gradient

scale_color_gray

alias of plotnine.scales.scale_color.scale_color_grey

scale_color_grey([start, end])

Sequential grey color scale.

scale_color_hue([h, l, s, color_space])

Qualitative color scale with evenly spaced hues

scale_fill_brewer([type, palette, direction])

Sequential, diverging and qualitative color scales

scale_fill_cmap([cmap_name, lut])

Create color scales using Matplotlib colormaps

scale_fill_continuous

alias of plotnine.scales.scale_color.scale_fill_cmap

scale_fill_datetime(**kwargs)

Datetime fill scale

scale_fill_desaturate([color, prop, reverse])

Create a desaturated color gradient

scale_fill_discrete

alias of plotnine.scales.scale_color.scale_fill_hue

scale_fill_distiller([type, palette, ...])

Sequential, diverging continuous color scales

scale_fill_gradient([low, high])

Create a 2 point color gradient

scale_fill_gradient2([low, mid, high, midpoint])

Create a 3 point diverging color gradient

scale_fill_gradientn(colors[, values])

Create a n color gradient

scale_fill_gray

alias of plotnine.scales.scale_color.scale_fill_grey

scale_fill_grey([start, end])

Sequential grey color scale.

scale_fill_hue([h, l, s, color_space])

Qualitative color scale with evenly spaced hues

Manual scales

scale_alpha_manual(values, **kwargs)

Custom discrete alpha scale

scale_color_manual(values, **kwargs)

Custom discrete color scale

scale_colour_manual

alias of plotnine.scales.scale_manual.scale_color_manual

scale_fill_manual(values, **kwargs)

Custom discrete fill scale

scale_linetype_manual(values, **kwargs)

Custom discrete linetype scale

scale_shape_manual(values, **kwargs)

Custom discrete shape scale

scale_size_manual(values, **kwargs)

Custom discrete size scale

Linetype scales

scale_linetype(**kwargs)

Scale for line patterns

scale_linetype_discrete

alias of plotnine.scales.scale_linetype.scale_linetype

Shape scales

scale_shape([unfilled])

Scale for shapes

scale_shape_discrete

alias of plotnine.scales.scale_shape.scale_shape

Size scales

scale_size

alias of plotnine.scales.scale_size.scale_size_continuous

scale_size_area([max_size])

Continuous area size scale

scale_size_continuous([range])

Continuous area size scale

scale_size_discrete(**kwargs)

Discrete area size scale

scale_size_radius([range])

Continuous radius size scale

scale_size_datetime([range])

Datetime area-size scale

Position scales

scale_x_continuous(**kwargs)

Continuous x position

scale_x_date

alias of plotnine.scales.scale_xy.scale_x_datetime

scale_x_datetime(**kwargs)

Continuous x position for datetime data points

scale_x_discrete(*args, **kwargs)

Discrete x position

scale_x_log10(**kwargs)

Continuous x position log10 transformed scale

scale_x_reverse(**kwargs)

Continuous x position reverse transformed scale

scale_x_sqrt(**kwargs)

Continuous x position sqrt transformed scale

scale_x_timedelta(**kwargs)

Continuous x position for timedelta data points

scale_y_continuous(**kwargs)

Continuous y position

scale_y_date

alias of plotnine.scales.scale_xy.scale_y_datetime

scale_y_datetime(**kwargs)

Continuous y position for datetime data points

scale_y_discrete(*args, **kwargs)

Discrete y position

scale_y_log10(**kwargs)

Continuous y position log10 transformed scale

scale_y_reverse(**kwargs)

Continuous y position reverse transformed scale

scale_y_sqrt(**kwargs)

Continuous y position sqrt transformed scale

scale_y_timedelta(**kwargs)

Continuous y position for timedelta data points

Scale limits

lims(**kwargs)

Set aesthtic limits

xlim(*limits)

Set x-axis limits

ylim(*limits)

Set y-axis limits

expand_limits(**kwargs)

Expand the limits any aesthetic using data

Scale guides

Guides allow you to interpret data represented on a scales. Guides include the x and y axes, legends and colorbars.

guides(**kwargs)

Guides for each scale

guide(**kwargs)

Base class for all guides

guide_legend(**kwargs)

Legend guide

guide_colorbar(**kwargs)

Guide colorbar

positions

Overlapping objects can be visualized better if their positions are adjusted. That is what the position_* class do. Each geom is associated with one position adjustment class.

position_dodge([width, preserve])

Dodge overlaps and place objects side-by-side

position_dodge2([width, preserve, padding])

Dodge overlaps and place objects side-by-side

position_fill([vjust, reverse])

Normalise stacked objects to unit height

position_identity()

Do not adjust the position

position_jitter([width, height, random_state])

Jitter points to avoid overplotting

position_jitterdodge([jitter_width, ...])

Dodge and jitter to minimise overlap

position_nudge([x, y])

Nudge points

position_stack([vjust, reverse])

Stack plotted objects on top of each other

themes

Themes control the visual appearance of the non-data elements the plot.

theme([complete, axis_title_x, ...])

This is a base class for themes.

theme_538([base_size, base_family])

Theme in the likeness of fivethirtyeight.com plots

theme_bw([base_size, base_family])

White background with black gridlines

theme_classic([base_size, base_family])

A classic-looking theme, with x & y axis lines and no gridlines.

theme_dark([base_size, base_family])

The dark cousin of theme_light, with similar line sizes but a dark background.

theme_gray([base_size, base_family])

A gray background with white gridlines.

theme_grey

alias of plotnine.themes.theme_gray.theme_gray

theme_light([base_size, base_family])

A theme similar to theme_linedraw but with light grey lines and axes to direct more attention towards the data.

theme_linedraw([base_size, base_family])

A theme with only black lines of various widths on white backgrounds

theme_matplotlib([rc, fname, use_defaults])

The default matplotlib look and feel.

theme_minimal([base_size, base_family])

A minimalistic theme with no background annotations

theme_seaborn([style, context, font, font_scale])

Theme for seaborn.

theme_void([base_size, base_family])

A classic-looking theme, with x & y axis lines and no gridlines.

theme_xkcd([base_size, scale, length, ...])

xkcd theme

Themeables

These define aspects of a plot that can be themed. They can be used to create a new theme or modify an existing theme. They define the keyword arguments to theme. Users should never create instances of themeable.

aspect_ratio

Aspect ratio of the panel(s)

axis_line

x & y axis lines

axis_line_x

x-axis line

axis_line_y

y-axis line

axis_text

Axis tick labels

axis_text_x

x-axis tick labels

axis_text_y

y-axis tick labels

axis_ticks

x & y major and minor axis tick lines

axis_ticks_direction

axis tick direction

axis_ticks_direction_x

x-axis tick direction

axis_ticks_direction_y

y-axis tick direction

axis_ticks_length

Axis tick length

axis_ticks_length_major

Axis major-tick length

axis_ticks_length_minor

Axis minor-tick length

axis_ticks_major

x & y axis major tick lines

axis_ticks_major_x

x-axis major tick lines

axis_ticks_major_y

y-axis major tick lines

axis_ticks_minor

x & y axis minor tick lines

axis_ticks_minor_x

x-axis tick lines

axis_ticks_minor_y

y-axis minor tick lines

axis_ticks_pad

Axis tick padding

axis_ticks_pad_major

Axis major-tick padding

axis_ticks_pad_minor

Axis minor-tick padding

axis_title

Axis labels

axis_title_x

x axis label

axis_title_y

y axis label

dpi

DPI with which to draw/save the figure

figure_size

Figure size in inches

legend_background

Legend background

legend_box

How to box up multiple legends

legend_box_background

Legend box background

legend_box_just

Justification of legend boxes

legend_box_margin

Padding between the legends and the box

legend_box_spacing

Spacing between legend and the anchor point

legend_direction

Layout items in the legend

legend_entry_spacing

Spacing between two entries in a legend

legend_entry_spacing_x

Horizontal spacing between two entries in a legend

legend_entry_spacing_y

Vertical spacing between two entries in a legend

legend_key

Legend key background

legend_key_height

Legend key background height

legend_key_size

Legend key background width and height

legend_key_width

Legend key background width

legend_margin

Padding between the legend the inner box

legend_position

Location of legend

legend_spacing

Spacing between two adjacent legends

legend_text

Legend text

legend_text_colorbar

Colorbar text

legend_text_legend

Legend text for the common legend

legend_title

Legend title

legend_title_align

Alignment of legend title

line

All line elements

panel_background

Panel background

panel_border

Panel border

panel_grid

Grid lines

panel_grid_major

Major grid lines

panel_grid_major_x

Vertical major grid lines

panel_grid_major_y

Horizontal major grid lines

panel_grid_minor

Minor grid lines

panel_grid_minor_x

Vertical minor grid lines

panel_grid_minor_y

Horizontal minor grid lines

panel_ontop

Place panel background & gridlines over/under the data layers

panel_spacing

Spacing between the facet panels

panel_spacing_x

Horizontal spacing betweend the facet panels

panel_spacing_y

Vertical spacing between the facet panels

plot_background

Plot background

plot_margin

Plot Margin

plot_title

Plot title

rect

All rectangle elements

strip_background

Facet label background

strip_background_x

Horizontal facet label background

strip_background_y

Vertical facet label background

strip_margin

Margin between the strip background and the panel border

strip_margin_x

Vertical margin between the strip background and the panel border

strip_margin_y

Horizontal margin between the strip background and the panel border

strip_text

Facet labels along both axes

strip_text_x

Facet labels along the horizontal axis

strip_text_y

Facet labels along the vertical axis

subplots_adjust

Adjust position of subplots on in the figure

text

All text elements in the plot

title

All titles on the plot

themeable

themeable is an abstract class of things that can be themed.

Theme helper functions and classes

theme_set(new)

Change the current(default) theme

theme_get()

Return the default theme

theme_update(**kwargs)

Modify elements of the current theme

element_line([color, size, linetype, ...])

Theme element: Line

element_rect([fill, color, size, linetype, ...])

Theme element: Rectangle

element_text([family, style, weight, color, ...])

Theme element: Text

coordinates

Coordinate systems put together the two position scales to produce a 2d location.

coord_cartesian([xlim, ylim, expand])

Cartesian coordinate system

coord_equal

alias of plotnine.coords.coord_fixed.coord_fixed

coord_fixed([ratio, xlim, ylim, expand])

Cartesian coordinates with fixed relationship between x and y scales

coord_flip([xlim, ylim, expand])

Flipped cartesian coordinates

coord_trans([x, y, xlim, ylim, expand])

Transformed cartesian coordinate system

options

When working interactively, some of the options make it convenient to create plots that have a common look and feel. Another way to do it, to set a default theme using theme_set().

aspect_ratio

Default aspect ratio used by the themes

base_family

The base font family for all text that is part of the theme

close_all_figures

Development flag, e.g.

current_theme

Theme used when none is added to the ggplot object

dpi

Default DPI used by the themes

figure_size

Default figure size inches

get_option(name)

Get package option

set_option(name, value)

Set package option

datasets

These datasets ship with the plotnine and you can import them with from the plotnine.data sub-package.

diamonds

Prices of 50,000 round cut diamonds

economics

US economic time series.

economics_long

US economic time series.

faithful

Old Faithful Geyser Data

faithfuld

Old Faithful Geyser Data

huron

Level of Lake Huron 1875–1972

luv_colours

colors in Luv space.

meat

midwest

Midwest demographics.

mpg

Fuel economy data from 1999 and 2008 for 38 popular models of car

msleep

An updated and expanded version of the mammals sleep dataset.

mtcars

Motor Trend Car Road Tests

pageviews

presidential

Terms of 11 presidents from Eisenhower to Obama.

seals

Vector field of seal movements.

txhousing

Housing sales in TX.