API Reference

Plot creation

ggplot Create a new ggplot object
qplot Quick plot
aes Create aesthetic mappings
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.


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_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


labs(*args, **kwargs) General class for all label adding classes
xlab(xlab) Create x-axis label
ylab(ylab) Create y-axis label
ggtitle(title) Create plot title


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_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


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 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([range]) 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]) Sequential, diverging and qualitative discrete color scales
scale_color_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, values]) 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]) Sequential, diverging and qualitative color scales
scale_fill_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, values]) 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([range]) 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


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_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 control the visual appearance of the non-data elements the plot.

theme([complete]) 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


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


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]) Transformed cartesian coordinate system


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
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


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.
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
presidential Terms of 11 presidents from Eisenhower to Obama.
seals Vector field of seal movements.
txhousing Housing sales in TX.