API Reference

Basic Classes

FeatureSpec(kind, name, **kwargs)

A base class of the plot objects.

PlotSpec(data, mapping, scales, layers[, ...])

A class of the initial plot object.

LayerSpec(**kwargs)

A class of the plot layer object.

LetsPlot()

Initialize the library and its options.

Plotting

ggplot([data, mapping])

Create a new ggplot plot.

GGBunch()

Collection of plots created by ggplot function.

gggrid(plots[, ncol, widths, heights, ...])

Combine several plots on one figure, organized in a regular grid.

ggmarginal(sides, *[, size])

Convert a given geometry layer to a marginal layer.

aes([x, y])

Define aesthetic mappings.

layer([geom, stat, data, mapping, position])

Create a new layer.

ggsave(plot, filename, *[, path, iframe, scale])

Export plot or bunch to a file.

Geometries

Standard Geometries

geom_point([mapping, data, stat, position, ...])

Draw points defined by an x and y coordinate, as for a scatter plot.

geom_path([mapping, data, stat, position, ...])

Connect observations in the order, how they appear in the data.

geom_line([mapping, data, stat, position, ...])

Connect points in the order of the variable on the x axis.

geom_smooth([mapping, data, stat, position, ...])

Add a smoothed conditional mean.

geom_bar([mapping, data, stat, position, ...])

Display a bar chart which makes the height of the bar proportional to the number of observed variable values, mapped to x axis.

geom_pie([mapping, data, stat, position, ...])

Draw pie chart.

geom_lollipop([mapping, data, stat, ...])

Draw lollipop chart.

geom_histogram([mapping, data, stat, ...])

Display a 1d distribution by dividing variable mapped to x axis into bins and counting the number of observations in each bin.

geom_dotplot([mapping, data, show_legend, ...])

Dotplot represents individual observations in a batch of data with circular dots.

geom_bin2d([mapping, data, stat, position, ...])

Display a 1d distribution by dividing variable mapped to x axis into bins and counting the number of observations in each bin.

geom_tile([mapping, data, stat, position, ...])

Display rectangles with x, y values mapped to the center of the tile.

geom_raster([mapping, data, stat, position, ...])

Display rectangles with x, y values mapped to the center of the tile.

geom_errorbar([mapping, data, stat, ...])

Display error bars defined by the upper and lower values.

geom_crossbar([mapping, data, stat, ...])

Display bars with horizontal median line.

geom_linerange([mapping, data, stat, ...])

Display a line range defined by an upper and lower value.

geom_pointrange([mapping, data, stat, ...])

Add a vertical line defined by upper and lower value with midpoint at y location.

geom_contour([mapping, data, stat, ...])

Display contours of a 3d surface in 2d.

geom_contourf([mapping, data, stat, ...])

Fill contours of a 3d surface in 2d.

geom_polygon([mapping, data, stat, ...])

Display a filled closed path defined by the vertex coordinates of individual polygons.

geom_map([mapping, data, stat, position, ...])

Display polygons from a reference map.

geom_abline([mapping, data, stat, position, ...])

Add a straight line with specified slope and intercept to the plot.

geom_hline([mapping, data, stat, position, ...])

Add a straight horizontal line to the plot.

geom_vline([mapping, data, stat, position, ...])

Add a straight vertical line to the plot.

geom_boxplot([mapping, data, stat, ...])

Display the distribution of data based on a five number summary ("minimum", first quartile (Q1), median, third quartile (Q3), and "maximum"), and "outlying" points individually.

geom_violin([mapping, data, stat, position, ...])

A violin plot is a mirrored density plot with an additional grouping as for a boxplot.

geom_area_ridges([mapping, data, stat, ...])

Plot the sum of the y and height aesthetics versus x.

geom_ydotplot([mapping, data, show_legend, ...])

Dotplot represents individual observations in a batch of data with circular dots.

geom_ribbon([mapping, data, stat, position, ...])

Display a y interval defined by ymin and ymax.

geom_area([mapping, data, stat, position, ...])

Display the development of quantitative values over an interval.

geom_density([mapping, data, stat, ...])

Display kernel density estimate, which is a smoothed version of the histogram.

geom_density2d([mapping, data, stat, ...])

Display density function contour.

geom_density2df([mapping, data, stat, ...])

Fill density function contour.

geom_jitter([mapping, data, stat, position, ...])

Display jittered points, especially for discrete plots or dense plots.

geom_freqpoly([mapping, data, stat, ...])

Display a line chart which makes the y value proportional to the number of observed variable values, mapped to x axis.

geom_step([mapping, data, stat, position, ...])

Connect observations in the order in which they appear in the data by stairs.

geom_rect([mapping, data, stat, position, ...])

Display an axis-aligned rectangle defined by two corners.

geom_segment([mapping, data, stat, ...])

Draw a straight line segment between two points.

geom_text([mapping, data, stat, position, ...])

Add a text directly to the plot.

geom_label([mapping, data, stat, position, ...])

Add a text directly to the plot with a rectangle behind the text.

geom_qq([mapping, data, stat, position, ...])

Display quantile-quantile plot.

geom_qq2([mapping, data, stat, position, ...])

Display quantile-quantile plot.

geom_qq_line([mapping, data, stat, ...])

Display quantile-quantile fitting line.

geom_qq2_line([mapping, data, stat, ...])

Display quantile-quantile fitting line.

Additional Geometries

geom_imshow(image_data[, cmap, norm, alpha, ...])

Display image specified by ndarray with shape.

geom_image(image_data[, cmap, norm, vmin, ...])

Function geom_image() is deprecated.

geom_livemap(*[, location, zoom, ...])

Display an interactive map.

Extras

arrow([angle, length, ends, type])

Describe arrows to add to a line.

as_discrete(variable[, label, order_by, order])

The function is used to annotate a numeric data series as categorical data with the possibility of its ordering for the purposes of given visualization.

layer_labels([variables])

Configure annotations (for pie chart).

Facets

facet_grid([x, y, scales, x_order, y_order, ...])

Split data by one or two faceting variables.

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

Split data by one or more faceting variables.

Scales

Position Scales

scale_x_discrete([name, breaks, labels, ...])

Discrete position scale x.

scale_y_discrete([name, breaks, labels, ...])

Discrete position scale y.

scale_x_discrete_reversed([name, breaks, ...])

Reversed discrete position scale x.

scale_y_discrete_reversed([name, breaks, ...])

Reversed discrete position scale y.

scale_x_continuous([name, breaks, labels, ...])

Continuous position scale x.

scale_y_continuous([name, breaks, labels, ...])

Continuous position scale y.

scale_x_log10([name, breaks, labels, ...])

Continuous position scale x where trans='log10'.

scale_y_log10([name, breaks, labels, ...])

Continuous position scales y where trans='log10'.

scale_x_reverse([name, breaks, labels, ...])

Continuous position scale x where trans='reverse'.

scale_y_reverse([name, breaks, labels, ...])

Continuous position scale y where trans='reverse'.

Color Scales

scale_color_manual(values[, name, breaks, ...])

Create your own discrete scale for color aesthetic.

scale_color_gradient([low, high, name, ...])

Define smooth color gradient between two colors for color aesthetic.

scale_color_continuous([low, high, name, ...])

Define smooth color gradient between two colors for color aesthetic.

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

Define diverging color gradient for color aesthetic.

scale_color_gradientn([colors, name, ...])

Define smooth color gradient between multiple colors for color aesthetic.

scale_color_hue([h, c, l, h_start, ...])

Qualitative color scale with evenly spaced hues for color aesthetic.

scale_color_discrete([direction, name, ...])

Qualitative colors.

scale_color_grey([start, end, name, breaks, ...])

Sequential grey color scale for color aesthetic.

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

Sequential, diverging and qualitative color scales from colorbrewer2.org for color aesthetic.

scale_color_viridis([alpha, begin, end, ...])

The viridis color maps are designed to be perceptually-uniform, both in regular form and also when converted to black-and-white.

Fill Scales

scale_fill_manual(values[, name, breaks, ...])

Create your own discrete scale for fill aesthetic.

scale_fill_gradient([low, high, name, ...])

Define smooth color gradient between two colors for fill aesthetic.

scale_fill_continuous([low, high, name, ...])

Define smooth color gradient between two colors for fill aesthetic.

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

Define diverging color gradient for fill aesthetic.

scale_fill_gradientn([colors, name, breaks, ...])

Define smooth color gradient between multiple colors for fill aesthetic.

scale_fill_hue([h, c, l, h_start, ...])

Qualitative color scale with evenly spaced hues for fill aesthetic.

scale_fill_discrete([direction, name, ...])

Qualitative colors.

scale_fill_grey([start, end, name, breaks, ...])

Sequential grey color scale for fill aesthetic.

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

Sequential, diverging and qualitative color scales from colorbrewer2.org for fill aesthetic.

scale_fill_viridis([alpha, begin, end, ...])

The viridis color maps are designed to be perceptually-uniform, both in regular form and also when converted to black-and-white.

Flexible Color Scales

scale_manual(aesthetic, values, *[, name, ...])

Create your own discrete scale for the specified aesthetics.

scale_gradient(aesthetic, *[, low, high, ...])

Define smooth color gradient between two colors for the specified aesthetics.

scale_continuous(aesthetic, *[, low, high, ...])

Define smooth color gradient between two colors for the specified aesthetics.

scale_gradient2(aesthetic, *[, low, mid, ...])

Define diverging color gradient for the specified aesthetics.

scale_gradientn(aesthetic, *[, colors, ...])

Define smooth color gradient between multiple colors for the specified aesthetics.

scale_hue(aesthetic, *[, h, c, l, h_start, ...])

Qualitative color scale with evenly spaced hues for the specified aesthetics.

scale_discrete(aesthetic, *[, direction, ...])

Qualitative colors.

scale_grey(aesthetic, *[, start, end, name, ...])

Sequential grey color scale for the specified aesthetics.

scale_brewer(aesthetic, *[, type, palette, ...])

Sequential, diverging and qualitative color scales from colorbrewer2.org for the specified aesthetics.

scale_viridis(aesthetic, *[, alpha, begin, ...])

The viridis color maps are designed to be perceptually-uniform, both in regular form and also when converted to black-and-white.

Shape Scales

scale_shape([solid, name, breaks, labels, ...])

Scale for shapes.

scale_shape_manual(values[, name, breaks, ...])

Create your own discrete scale for shape aesthetic.

Size Scales

scale_size_manual(values[, name, breaks, ...])

Create your own discrete scale for size aesthetic.

scale_size([range, name, breaks, labels, ...])

Scale for size.

scale_size_area([max_size, name, breaks, ...])

Continuous scale for size that maps 0 to 0.

scale_linewidth([range, name, breaks, ...])

Scale for linewidth.

scale_stroke([range, name, breaks, labels, ...])

Scale for stroke.

Alpha Scales

scale_alpha_manual(values[, name, breaks, ...])

Create your own discrete scale for alpha (transparency) aesthetic.

scale_alpha([range, name, breaks, labels, ...])

Scale for alpha.

Linetype Scales

scale_linetype_manual(values[, name, ...])

Create your own discrete scale for line type aesthetic.

Datetime Scales

scale_x_datetime([name, breaks, labels, ...])

Position scale x for date/time data.

scale_y_datetime([name, breaks, labels, ...])

Position scale y for date/time data.

scale_x_time([name, breaks, labels, limits, ...])

Position scale x for data representing "time delta" values expressed in milliseconds.

scale_y_time([name, breaks, labels, limits, ...])

Position scale y for data representing "time delta" values expressed in milliseconds.

Identity Scales

scale_identity(aesthetic, *[, name, breaks, ...])

Use this scale when your data has already been scaled.

scale_color_identity([name, breaks, labels, ...])

Use this scale when your data has already been scaled.

scale_fill_identity([name, breaks, labels, ...])

Use this scale when your data has already been scaled.

scale_shape_identity([name, breaks, labels, ...])

Use this scale when your data has already been scaled.

scale_linetype_identity([name, breaks, ...])

Use this scale when your data has already been scaled.

scale_alpha_identity([name, breaks, labels, ...])

Use this scale when your data has already been scaled.

scale_size_identity([name, breaks, labels, ...])

Use this scale when your data has already been scaled.

scale_linewidth_identity([name, breaks, ...])

Use this scale when your data has already been scaled.

scale_stroke_identity([name, breaks, ...])

Use this scale when your data has already been scaled.

Scale Limits

lims(x, y)

This is a shortcut for supplying the limits parameter to the x and y axes.

xlim(*limits)

This is a shortcut for supplying the limits parameter to the x axis.

ylim(*limits)

This is a shortcut for supplying the limits parameter to the y axis.

Scale Guides

guide_legend([nrow, ncol, byrow])

Legend guide.

guide_colorbar([barwidth, barheight, nbin])

Continuous color bar guide.

guides(**kwargs)

Set guides for each scale.

Positions

position_dodge([width])

Adjust position by dodging overlaps to the side.

position_dodgev([height])

Adjust position by dodging overlaps to the side.

position_jitter([width, height])

Adjust position by assigning random noise to points.

position_nudge([x, y])

Adjust position by nudging a given offset.

position_jitterdodge([dodge_width, ...])

This is primarily used for aligning points generated through geom_point() with dodged boxplots (e.g., a geom_boxplot() with a fill aesthetic supplied).

position_fill([vjust, mode])

Adjust position by stacking overlapping objects on top of each other and standardise each stack to have constant height.

position_stack([vjust, mode])

Adjust position by stacking overlapping objects on top of each other.

Coordinate Systems

coord_cartesian([xlim, ylim, flip])

The Cartesian coordinate system is the most familiar and common type of coordinate system.

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

A fixed scale coordinate system forces a specified ratio between the physical representations of data units on the axes.

coord_map([xlim, ylim, flip])

Project a portion of the earth, which is approximately spherical, onto a flat 2D plane.

coord_flip([xlim, ylim])

Flip axis of default coordinate system so that horizontal axis becomes vertical and vice versa.

Theme

Base

theme(*[, line, rect, text, title, axis, ...])

Use theme() to modify individual components of a theme, allowing you to control all non-data components of the plot.

element_blank()

Specify how non-data components of the plot are drawn.

element_rect([fill, color, size, blank])

Specify how non-data components of the plot are drawn.

element_line([color, size, blank])

Specify how non-data components of the plot are drawn.

element_text([color, family, face, size, ...])

Specify how non-data components of the plot are drawn.

margin([t, r, b, l])

Dimensions of each margin.

ggsize(width, height)

Specify overall size of plot.

Predefined Themes

theme_none()

A completely empty theme.

theme_bw()

Grey lines on white backgrounds with black plot border.

theme_classic()

Black axes and no gridlines.

theme_grey()

Grey background and white gridlines.

theme_light()

Light grey lines of various widths on white backgrounds.

theme_minimal()

A minimalistic theme without axes lines.

theme_minimal2()

Default theme similar to theme_minimal() but with x axis line and only major grid lines.

Flavors

flavor_darcula()

Darcula color scheme.

flavor_high_contrast_dark()

High contrast dark color scheme.

flavor_high_contrast_light()

High contrast light color scheme.

flavor_solarized_dark()

Solarized dark color scheme.

flavor_solarized_light()

Solarized light color scheme.

Labels

ggtitle(label[, subtitle])

Add title to the plot.

labs([title, subtitle, caption])

Change plot title and axis label.

xlab(label)

Add label to the x axis.

ylab(label)

Add label to the y axis.

Tooltips

layer_tooltips([variables])

Configure tooltips.

Font Features

font_metrics_adjustment(width_correction)

Adjust estimated width of text labels on plot.

font_family_info(family[, width_correction, ...])

Specify properties of a particular font-family to adjust estimated width of text labels on plot.

Sampling

sampling_random(n[, seed])

Return a subset of randomly selected items.

sampling_random_stratified(n[, seed, ...])

Randomly sample from each stratum (subgroup).

sampling_pick(n)

'Pick' sampling.

sampling_systematic(n)

Return a subset where items are selected at a regular interval.

sampling_group_random(n[, seed])

Return a subset of randomly selected groups.

sampling_group_systematic(n)

Return a subset where groups are selected at a regular interval.

sampling_vertex_vw(n)

Simplify a polyline using the Visvalingam-Whyatt algorithm.

sampling_vertex_dp(n)

Simplify a polyline using the Douglas-Peucker algorithm.

Bistro Module

image_matrix(image_data_array[, cmap, norm, ...])

Display a set of images in a grid.

corr_plot(data[, show_legend, flip, threshold])

This class is intended to build correlation matrix plot.

qq_plot([data, sample, x, y, distribution, ...])

Produce a Q-Q plot (quantile-quantile plot).

joint_plot(data, x, y, *[, geom, bins, ...])

Produce a joint plot that contains bivariate and univariate graphs at the same time.

residual_plot([data, x, y, method, deg, ...])

Produce a residual plot that shows the difference between the observed response and the fitted response values.

Geospatial

NamesGeocoder([level, request])

Do not use this class explicitly.

geocode([level, names, countries, states, ...])

Create a NamesGeocoder.

geocode_cities([names])

Create a NamesGeocoder object for cities.

geocode_counties([names])

Create a NamesGeocoder object for counties.

geocode_states([names])

Create a NamesGeocoder object for states.

geocode_countries([names])

Create a NamesGeocoder object for countries.

distance(lon0, lat0, lon1, lat1[, units])

Calculate the distance between two points.

maptiles_zxy(url[, attribution, min_zoom, ...])

Make raster tiles config.

maptiles_lets_plot([url, theme])

Make vector tiles config.

maptiles_solid(color)

Make solid color tiles config.

LETS_PLOT_COLOR

Default vector tiles.

LETS_PLOT_LIGHT

Vector tiles, light theme.

LETS_PLOT_DARK

Vector tiles, dark theme.

SOLID

Blank tiles.

OSM

OpenStreetMap's standard tile layer.

OPEN_TOPO_MAP

OpenTopoMap's tile layer.

STAMEN_DESIGN_TONER

Stamen design, toner theme.

STAMEN_DESIGN_TONER_HIRES

Stamen design, toner theme.

STAMEN_DESIGN_TONER_LIGHT

Stamen design, toner lite theme.

STAMEN_DESIGN_TONER_LIGHT_HIRES

Stamen design, toner lite theme.

STAMEN_DESIGN_TONER_HYBRID

Stamen design, toner hybrid theme.

STAMEN_DESIGN_TONER_HYBRID_HIRES

Stamen design, toner hybrid theme.

STAMEN_DESIGN_TONER_LABELS

Stamen design, toner labels theme.

STAMEN_DESIGN_TONER_LABELS_HIRES

Stamen design, toner labels theme.

STAMEN_DESIGN_TERRAIN

Stamen design, terrain theme.

STAMEN_DESIGN_TERRAIN_HIRES

Stamen design, terrain theme.

STAMEN_DESIGN_WATERCOLOR

Stamen design, watercolor theme.

CARTO_POSITRON

CARTO tiles, positron theme.

CARTO_POSITRON_HIRES

CARTO tiles, positron theme.

CARTO_POSITRON_NO_LABELS

CARTO tiles, positron (no labels) theme.

CARTO_POSITRON_NO_LABELS_HIRES

CARTO tiles, positron (no labels) theme.

CARTO_DARK_MATTER_NO_LABELS

CARTO tiles, dark matter (no labels) theme.

CARTO_DARK_MATTER_NO_LABELS_HIRES

CARTO tiles, dark matter (no labels) theme.

CARTO_VOYAGER

CARTO tiles, voyager theme.

CARTO_VOYAGER_HIRES

CARTO tiles, voyager theme.

CARTO_MIDNIGHT_COMMANDER

CARTO tiles, midnight commander theme.

CARTO_MIDNIGHT_COMMANDER_HIRES

CARTO tiles, midnight commander theme.

CARTO_ANTIQUE

CARTO tiles, antique theme.

CARTO_ANTIQUE_HIRES

CARTO tiles, antique theme.

CARTO_FLAT_BLUE

CARTO tiles, flat blue theme.

CARTO_FLAT_BLUE_HIRES

CARTO tiles, flat blue theme.

NASA_CITYLIGHTS_2012

NASA tiles, CityLights 2012 theme.

NASA_BLUEMARBLE_NEXTGENERATION

NASA tiles, BlueMarble NextGeneration theme.

NASA_GREYSCALE_SHADED_RELIEF_30M

NASA tiles, greyscale shaded relief (30m) theme.

NASA_COLOR_SHADED_RELIEF_30M

NASA tiles, color shaded relief (30m) theme.

NASA_TERRA_TRUECOLOR

NASA tiles, Terra TrueColor theme.