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

Related to geoms

annotate(geom[, x, y, xmin, xmax, xend, ...])	Create an annotation layer
annotation_logticks([sides, alpha, color, ...])	Marginal log ticks.
annotation_stripes([fill, fill_range, ...])	Alternating stripes, centered around each label.
arrow([angle, length, ends, type])	Define arrow (actually an arrowhead)

Labels

labs(**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])	A single Panel
facet_wrap(facets, *[, nrow, ncol, scales, ...])	Wrap 1D Panels onto 2D surface
labeller([rows, cols, multi_line, default])	Facet Strip Labelling
as_labeller([x, default, multi_line])	Coerse to labeller
label_value(label_info[, multi_line])	Keep value as the label
label_both(label_info[, multi_line, sep])	Concatenate the facet variable with the value
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 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 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 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 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 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 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 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 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 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 scale_linetype

Shape scales

scale_shape([unfilled])	Scale for shapes
scale_shape_discrete	alias of scale_shape

Size scales

scale_size	alias of 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 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 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 aesthetic 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, ...])	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
theme_gray([base_size, base_family])	A gray background with white gridlines.
theme_grey	alias of theme_gray
theme_light([base_size, base_family])	A theme similar to theme_linedraw
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_tufte([base_size, base_family, ticks])	Tufte Maximal Data, Minimal Ink Theme
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 the legend and the plotting area
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 and 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 between 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_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_text	Facet labels along both axes
strip_text_x	Facet labels along the horizontal axis
strip_text_y	Facet labels along the vertical axis
text	All text elements in the plot
title	All titles on the plot
themeable	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 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.
base_margin	A size that is proportional of the figure width and is used by some themes to determine other margins
close_all_figures	Development flag, e.g. set to True to prevent the queuing up of figures when errors happen.
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.