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

Initalize the library and its options.

Plotting

ggplot([data, mapping])

Create a new ggplot plot.

GGBunch()

Collection of plots created by ggplot function.

aes([x, y])

Define aesthetic mappings.

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

Create a new layer.

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

Exports 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, ...])

Connects 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_histogram([mapping, data, stat, ...])

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

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

Displays 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_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, ...])

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

Additional Geometries

geom_image(image_data[, norm, vmin, vmax])

Displays image specified by ndarray with shape (n, m) or (n, m, 3) or (n, m, 4).

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

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.

Facets

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

Splits data by one or two faceting variables.

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

Splits 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_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, direction, ...])

Sequential grey color scale for color aesthetic.

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

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

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_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, direction, ...])

Sequential grey color scale for fill aesthetic.

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

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

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.

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.

Identity Scales

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 Limits

lims(x, y)

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

xlim(*args)

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

ylim(*args)

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

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

Coordinates

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 representation of data units on the axes.

coord_map([xlim, ylim, flip])

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

theme_none()

A completely empty theme.

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.

element_blank()

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

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

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

element_line([color, size, blank])

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

element_text([color, blank])

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

ggsize(width, height)

Specify overall size of plot.

Labels

ggtitle(label)

Add title to the plot.

labs(**kwargs)

Change plot title, axis labels and legend titles.

xlab(label)

Add label to the x axis.

ylab(label)

Add label to the y axis.

Tooltips

layer_tooltips([variables])

Configure tooltips.

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, *[, norm, scale])

Display images in a grid.

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

This class is intended to build correlation matrix plot.

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, ...])

Makes raster tiles config.

maptiles_lets_plot([url, theme])

Makes vector tiles config.

maptiles_solid(color)

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