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 |
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 |
Annotations
| annotate | Create an annotation layer |
| annotation_logticks | Marginal log ticks. |
| annotation_stripes | Alternating stripes, centered around each label. |
| arrow | Define arrow (actually an arrowhead) |
Labels
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 | Empirical 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 | 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
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 |
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 | 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
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 |
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.
| 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_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 |
| subplots_adjust | |
| 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 |
Coordinates
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 |
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 |
| 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 in inches |
| figure_format | The format for the inline figures outputted by the jupyter kernel. |
| get_option | Get package option |
| set_option | 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 | 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 |
| pageviews | |
| presidential | Terms of 11 presidents from Eisenhower to Obama. |
| seals | Vector field of seal movements. |
| txhousing | Housing sales in TX. |