API Reference

Creating a Plot

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


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_bin_2d 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_pointdensity Scatterplot with density estimation at each point
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_raster Rasterized Rectangles specified using center points
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


annotate Create an annotation layer
annotation_logticks Marginal log ticks.
annotation_stripes Alternating stripes, centered around each label.
arrow Define arrow (actually an arrowhead)


labs Add labels for any aesthetics with a scale or title, subtitle & caption
xlab Label/name for the x aesthetic
ylab Label/name for the y aesthetic
ggtitle 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_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


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

facet Base class for all facets
facet_grid Wrap 1D Panels onto 2D surface
facet_null A single Panel
facet_wrap Wrap 1D Panels onto 2D surface
labeller Facet Strip Labelling
as_labeller Coerse to labeller
label_value Keep value as the label
label_both Concatenate the facet variable with the value
label_context 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 Base class for all scales
scale_discrete Base class for all discrete scales
scale_continuous Base class for all continuous scales
scale_datetime Base class for all date/datetime scales

Alpha Scales

scale_alpha Continuous Alpha Scale
scale_alpha_discrete Discrete Alpha Scale
scale_alpha_continuous alias of scale_alpha
scale_alpha_datetime Datetime Alpha Scale

Identity Scales

scale_alpha_identity No alpha scaling
scale_color_identity No color scaling
scale_colour_identity alias of scale_color_identity
scale_fill_identity No color scaling
scale_linetype_identity No linetype scaling
scale_shape_identity No shape scaling
scale_size_identity No size scaling

Color and Fill Scales

scale_color_brewer Sequential, diverging and qualitative discrete color scales
scale_color_continuous alias of scale_color_cmap
scale_color_cmap Create color scales using Matplotlib colormaps
scale_color_desaturate Create a desaturated color gradient
scale_color_datetime Datetime color scale
scale_color_discrete alias of scale_color_hue
scale_color_distiller Sequential and diverging continuous color scales
scale_color_gradient Create a 2 point color gradient
scale_color_gradient2 Create a 3 point diverging color gradient
scale_color_gradientn Create a n color gradient
scale_color_gray alias of scale_color_grey
scale_color_grey Sequential grey color scale.
scale_color_hue Qualitative color scale with evenly spaced hues
scale_fill_brewer Sequential, diverging and qualitative color scales
scale_fill_cmap Create color scales using Matplotlib colormaps
scale_fill_continuous alias of scale_fill_cmap
scale_fill_datetime Datetime fill scale
scale_fill_desaturate Create a desaturated color gradient
scale_fill_discrete alias of scale_fill_hue
scale_fill_distiller Sequential, diverging continuous color scales
scale_fill_gradient Create a 2 point color gradient
scale_fill_gradient2 Create a 3 point diverging color gradient
scale_fill_gradientn Create a n color gradient
scale_fill_gray alias of scale_fill_grey
scale_fill_grey Sequential grey color scale.
scale_fill_hue Qualitative color scale with evenly spaced hues

Manual Scales

scale_alpha_manual Custom discrete alpha scale
scale_color_manual Custom discrete color scale
scale_colour_manual alias of scale_color_manual
scale_fill_manual Custom discrete fill scale
scale_linetype_manual Custom discrete linetype scale
scale_shape_manual Custom discrete shape scale
scale_size_manual Custom discrete size scale

Linetype Scales

scale_linetype Scale for line patterns
scale_linetype_discrete alias of scale_linetype

Shape Scales

scale_shape Scale for shapes
scale_shape_discrete alias of scale_shape

Size Scales

scale_size alias of scale_size_continuous
scale_size_area Continuous area size scale
scale_size_continuous Continuous area size scale
scale_size_discrete Discrete area size scale
scale_size_radius Continuous radius size scale
scale_size_datetime Datetime area-size scale

Position Scales

scale_x_continuous Continuous x position
scale_x_date alias of scale_x_datetime
scale_x_datetime Continuous x position for datetime data points
scale_x_discrete Discrete x position
scale_x_log10 Continuous x position log10 transformed scale
scale_x_reverse Continuous x position reverse transformed scale
scale_x_sqrt Continuous x position sqrt transformed scale
scale_x_symlog Continuous x position symmetric logarithm transformed scale
scale_x_timedelta Continuous x position for timedelta data points
scale_y_continuous Continuous y position
scale_y_date alias of scale_y_datetime
scale_y_datetime Continuous y position for datetime data points
scale_y_discrete Discrete y position
scale_y_log10 Continuous y position log10 transformed scale
scale_y_reverse Continuous y position reverse transformed scale
scale_y_sqrt Continuous y position sqrt transformed scale
scale_y_symlog Continuous y position symmetric logarithm transformed scale
scale_y_timedelta Continuous y position for timedelta data points

Scale Limits

lims Set aesthetic limits
xlim Set x-axis limits
ylim Set y-axis limits
expand_limits 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.

guide Base class for all guides
guides Guides for each scale
guide_legend Legend guide
guide_colorbar 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 Base class for all positions
position_dodge Dodge overlaps and place objects side-by-side
position_dodge2 Dodge overlaps and place objects side-by-side
position_fill Normalise stacked objects to unit height
position_identity Do not adjust the position
position_jitter Jitter points to avoid overplotting
position_jitterdodge Dodge and jitter to minimise overlap
position_nudge Nudge points
position_stack Stack plotted objects on top of each other


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

theme Base class for themes
theme_538 Theme in the likeness of fivethirtyeight.com plots
theme_bw White background with black gridlines
theme_classic A classic-looking theme, with x & y axis lines and no gridlines
theme_dark The dark cousin of theme_light
theme_gray A gray background with white gridlines.
theme_grey alias of theme_gray
theme_light A theme similar to theme_linedraw
theme_linedraw A theme with only black lines of various widths on white backgrounds
theme_matplotlib The default matplotlib look and feel.
theme_minimal A minimalistic theme with no background annotations
theme_seaborn Theme for seaborn.
theme_tufte Tufte Maximal Data, Minimal Ink Theme
theme_void A classic-looking theme, with x & y axis lines and
theme_xkcd 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.

themeable Abstract class of things that can be themed.
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_major_x x-axis major-tick length
axis_ticks_length_major_y y-axis major-tick length
axis_ticks_length_minor Axis minor-tick length
axis_ticks_length_minor_x x-axis minor-tick length
axis_ticks_length_minor_y x-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_major_x x-axis major-tick padding
axis_ticks_pad_major_y y-axis major-tick padding
axis_ticks_pad_minor Axis minor-tick padding
axis_ticks_pad_minor_x x-axis minor-tick padding
axis_ticks_pad_minor_y y-axis minor-tick padding
axis_ticks_x x major and minor axis tick lines
axis_ticks_y y major and minor axis tick lines
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 guide boxes
legend_box_margin Padding between the legends and the box
legend_box_spacing Spacing between the legend and the plotting area
legend_direction Layout items in the legend
legend_key_spacing Spacing between two entries in a legend
legend_key_spacing_x Horizontal spacing between two entries in a legend
legend_key_spacing_y Vertical spacing between two entries in a legend
legend_frame Frame around colorbar
legend_justification Justification of any legend
legend_justification_bottom Justification of legends placed at the bottom
legend_justification_inside Justification of legends placed inside the axes
legend_justification_left Justification of legends placed on the left
legend_justification_right Justification of legends placed on the right
legend_justification_top Justification of legends placed at the top
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 and the inner box
legend_position Location of legend
legend_position_inside 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_text_position Position of the legend text
legend_ticks_length Length of ticks in the legend
legend_title Legend title
legend_title_position Position 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 between the facet panels
panel_spacing_y Vertical spacing between the facet panels
plot_background Plot background
plot_caption Plot caption
plot_margin Plot Margin
plot_margin_bottom Plot Margin at the bottom
plot_margin_left Plot Margin on the left
plot_margin_right Plot Margin on the right
plot_margin_top Plot Margin at the top
plot_subtitle Plot subtitle
plot_title Plot title
rect All rectangle elements
strip_align Alignment of the strip & its background w.r.t the panel border
strip_align_x Vertical alignment of the strip & its background w.r.t the panel border
strip_align_y Horizontal alignment of the strip & its background w.r.t the panel border
strip_background Facet label background
strip_background_x Horizontal facet label background
strip_background_y Vertical facet label background
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
svg_usefonts How to renderer fonts for svg images
text All text elements in the plot
title All titles on the plot

Helpful Functions & Classes for Theming

theme_set Change the current(default) theme
theme_get Return the default theme
theme_update Modify elements of the current theme
element_line theme element: line
element_rect Theme element: Rectangle
element_text Theme element: Text
element_blank Theme element: Blank


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

coord Base class for all coordinate systems
coord_cartesian Cartesian coordinate system
coord_equal Cartesian coordinates with fixed relationship between x and y scales
coord_fixed Cartesian coordinates with fixed relationship between x and y scales
coord_flip Flipped cartesian coordinates
coord_trans 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
base_family The base font family for all text that is part of the theme.
base_margin A size that is proportional of the figure width and
close_all_figures Development flag, e.g. set to True to prevent
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
figure_format The format for the inline figures outputed by the jupyter kernel.
get_option Get package option
set_option 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.
meat US Meat Production
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.