Technical Documentation: has2k1/plotnine
ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference
Overview (`README.md`)
plotnine
plotnine is an implementation of a grammar of graphics in Python
based on ggplot2.
The grammar allows you to compose plots by explicitly mapping variables in a
dataframe to the visual characteristics (position, color, size etc.) of objects that make up the plot.
Plotting with a grammar of graphics is powerful. Custom (and otherwise
complex) plots are easy to think about and build incrementally, while the
simple plots remain simple to create.
To learn more about how to use plotnine, check out the
documentation. Since plotnine
has an API similar to ggplot2, where it lacks in coverage the
ggplot2 documentation
may be helpful.
Example
from plotnine import *
from plotnine.data import mtcarsBuilding a complex plot piece by piece.
Scatter plot
python( ggplot(mtcars, aes("wt", "mpg")) + geom_point() )Scatter plot colored according some variable
python( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() )Scatter plot colored according some variable and
smoothed with a linear model with confidence intervals.python( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") )Scatter plot colored according some variable,
smoothed with a linear model with confidence intervals and
plotted on separate panels.python( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") + facet_wrap("gear") )Adjust the themes
I) Make it playful
python( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") + facet_wrap("gear") + theme_xkcd() )II) Or professional
python( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") + facet_wrap("gear") + theme_tufte() )
Installation
Official release
# Using pip
$ pip install plotnine # 1. should be sufficient for most
$ pip install 'plotnine[extra]' # 2. includes extra/optional packages
$ pip install 'plotnine[test]' # 3. testing
$ pip install 'plotnine[doc]' # 4. generating docs
$ pip install 'plotnine[dev]' # 5. development (making releases)
$ pip install 'plotnine[all]' # 6. everything
# Or using conda
$ conda install -c conda-forge plotnine
# Or using pixi
$ pixi init name-of-my-project
$ cd name-of-my-project
$ pixi add python plotnineDevelopment version
$ pip install git+https://github.com/has2k1/plotnine.git
$ brew install oxipng # Test image optimiser (OR `cargo install oxipng`)Contributing
Our documentation could use some examples, but we are looking for something
a little bit special. We have two criteria:
- Simple looking plots that otherwise require a trick or two.
- Plots that are part of a data analytic narrative. That is, they provide
some form of clarity showing off thegeom,stat, ... at their
differential best.
If you come up with something that meets those criteria, we would love to
see it. See plotnine-examples.
If you discover a bug checkout the issues
if it has not been reported, yet please file an issue.
And if you can fix a bug, your contribution is welcome.
Testing
Plotnine has tests that generate images which are compared to baseline images known
to be correct. There may be small differences in the text rendering that throw off the
image comparisons, and the tests allow some very small differences.
Doc Quarto.Yml (`doc/_quarto.yml`)
project:
type: website
resources:
- objects.inv
render:
- "reference/**.qmd"
- "*.qmd"
website:
title: "plotnine {{< var version >}}"
favicon: "images/favicon.ico"
page-navigation: true
navbar:
left:
- file: reference/index.qmd
text: "Reference"
right:
- icon: github
href: https://github.com/has2k1/plotnine
format:
html:
toc: true
theme:
- lumen
- qrenderer.scss
- plotnine.scss
filters:
- interlinks
interlinks:
sources:
python:
url: https://docs.python.org/3/
matplotlib:
url: https://matplotlib.org/stable/
mizani:
url: https://mizani.readthedocs.io/en/stable/
numpy:
url: https://numpy.org/doc/stable/
scipy:
url: https://docs.scipy.org/doc/scipy/
statsmodels:
url: https://www.statsmodels.org/stable/
pandas:
url: https://pandas.pydata.org/pandas-docs/stable/
sklearn:
url: https://scikit-learn.org/stable/
skmisc:
url: https://has2k1.github.io/scikit-misc/stable/
adjustText:
url: https://adjusttext.readthedocs.io/en/latest/
patsy:
url: https://patsy.readthedocs.io/en/stable/
issuey:
issue-url: "https://github.com/has2k1/plotnine/issues/%id"
issue-text: "#%id"
issue-title: "Issue: #%id"
pull-request-url: "https://github.com/has2k1/plotnine/pulls/%id"
pull-request-text: "PR%id"
pull-request-title: "Pull Request: #%id"
Doc Quartodoc.Yml (`doc/_quartodoc.yml`)
interlinks:
fast: true
quartodoc:
dir: reference
title: API Reference
package: plotnine
dynamic: true
renderer:
style: _renderer.py
typing_module_paths:
- plotnine.typing
- plotnine.scales._runtime_typing
sections:
- title: Creating a Plot
desc: ""
contents:
- name: ggplot
members: [add, iadd, show, draw, build, save, save_helper]
- qplot
- watermark
- name: layer
package: plotnine.layer
- name: PlotnineAnimation
package: plotnine.animation
- save_as_pdf_pages
- title: Mapping Aesthetics
desc: |
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.
contents:
- name: aes
members: []
- after_stat
- after_scale
- stage
- I
- subtitle: Functions in the Aesthetic Evaluation Environment
desc: |
The expressions you write in the `aes()` call are evaluated inside an
environment with a few functions that you may need from time to time.
These functions are for your convenience, and you can expect them to
to always be there.
package: plotnine.mapping._eval_environment
contents:
- factor
- reorder
- title: Geoms
desc: |
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.
- package: plotnine.geoms.geom
contents:
- geom
- options: &no-members
members: []
contents:
- geom_abline
- geom_area
- geom_bar
- geom_beeswarm
- geom_bin_2d
- geom_blank
- geom_boxplot
- geom_col
- geom_contour
- geom_contour_filled
- geom_count
- geom_crossbar
- geom_density
- geom_density_2d
- geom_density_2d_filled
- geom_dotplot
- geom_errorbar
- geom_errorbarh
- geom_freqpoly
- geom_histogram
- geom_hline
- geom_jitter
- geom_label
- geom_line
- geom_linerange
- geom_map
- geom_path
- geom_point
- geom_pointdensity
- geom_pointrange
- geom_polygon
- geom_qq
- geom_qq_line
- geom_quantile
- geom_raster
- geom_rect
- geom_ribbon
- geom_rug
- geom_segment
- geom_sina
- geom_smooth
- geom_spoke
- geom_step
- geom_text
- geom_tile
- geom_violin
- geom_vline
- subtitle: Annotations
desc: ""
options: *no-members
contents:
- annotate
- annotation_logticks
- annotation_stripes
- arrow
- subtitle: Labels
desc: ""
contents:
- labs
- xlab
- ylab
- ggtitle
- title: Stats
desc: |
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.
- package: plotnine.stats.stat
contents:
- stat
- options: *no-members
contents:
- stat_beeswarm
- stat_bin
- stat_bin_2d
- stat_bindot
- stat_boxplot
- stat_contour
- stat_contour_filled
- stat_count
- stat_density
- stat_density_2d
- stat_density_2d_filled
- stat_ecdf
- stat_ellipse
- stat_function
- stat_hull
- stat_identity
- stat_qq
- stat_qq_line
- stat_quantile
- stat_sina
- stat_smooth
- stat_sum
- stat_summary
- stat_summary_bin
- stat_unique
- stat_ydensity
- title: Facets
desc: |
Faceting is a way to subset data and plot it on different panels.
- package: plotnine.facets.facet
contents:
- name: facet
include_attributes: false
- options: *no-members
contents:
- facet_grid
- facet_null
- facet_wrap
- labeller
- as_labeller
- label_value
- label_both
- label_context
- title: Scales
desc: |
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.
- subtitle: Base Scales
options: *no-members
contents:
- name: scale
package: plotnine.scales.scale
- name: scale_discrete
package: plotnine.scales.scale_discrete
- name: scale_continuous
package: plotnine.scales.scale_continuous
- name: scale_datetime
package: plotnine.scales.scale_datetime
- subtitle: Alpha Scales
options: *no-members
contents:
- scale_alpha
- scale_alpha_continuous
- scale_alpha_datetime
- scale_alpha_discrete
- scale_alpha_ordinal
- subtitle: Color and Fill Scales
options: *no-members
contents:
- scale_color_brewer
- scale_color_cmap
- scale_color_cmap_d
- scale_color_continuous
- scale_color_datetime
- scale_color_desaturate
- scale_color_discrete
- scale_color_distiller
- scale_color_gradient
- scale_color_gradient2
- scale_color_gradientn
- scale_color_gray
- scale_color_grey
- scale_color_hue
- scale_color_ordinal
- scale_fill_brewer
- scale_fill_cmap
- scale_fill_cmap_d
- scale_fill_continuous
- scale_fill_datetime
- scale_fill_desaturate
- scale_fill_discrete
- scale_fill_distiller
- scale_fill_gradient
- scale_fill_gradient2
- scale_fill_gradientn
- scale_fill_gray
- scale_fill_grey
- scale_fill_hue
- scale_fill_ordinal
- subtitle: Identity Scales
options: *no-members
contents:
- scale_alpha_identity
- scale_color_identity
- scale_colour_identity
- scale_fill_identity
- scale_linetype_identity
- scale_shape_identity
- scale_size_identity
- scale_stroke_identity
- subtitle: Linetype Scales
options: *no-members
contents:
- scale_linetype
- scale_linetype_discrete
- subtitle: Manual Scales
options: *no-members
contents:
- scale_alpha_manual
- scale_color_manual
- scale_colour_manual
- scale_fill_manual
- scale_linetype_manual
- scale_shape_manual
- scale_size_manual
- subtitle: Position Scales
contents:
- scale_x_continuous
- scale_x_date
- scale_x_datetime
- scale_x_discrete
- scale_x_log10
- scale_x_reverse
- scale_x_sqrt
- scale_x_symlog
- scale_x_timedelta
- scale_y_continuous
- scale_y_date
- scale_y_datetime
- scale_y_discrete
- scale_y_log10
- scale_y_reverse
- scale_y_sqrt
- scale_y_symlog
- scale_y_timedelta
- sec_axis
- dup_axis
- subtitle: Shape Scales
options: *no-members
contents:
- scale_shape
- scale_shape_discrete
- subtitle: Size Scales
options: *no-members
contents:
- scale_size
- scale_size_area
- scale_size_continuous
- scale_size_datetime
- scale_size_discrete
- scale_size_ordinal
- scale_size_radius
- subtitle: Stroke Scales
options: *no-members
contents:
- scale_stroke
- scale_stroke_continuous
- subtitle: Scale Limits
options: *no-members
contents:
- lims
- xlim
- ylim
- expand_limits
- title: Scale Guides
desc: |
Guides allow you to interpret data represented on a scales.
Guides include the `x` and `y` axes, legends and colorbars.
- package: plotnine.guides.guide
contents:
- name: guide
include_attributes: false
- options: *no-members
contents:
- guides
- guide_legend
- guide_colorbar
- title: Positions
desc: |
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.
- package: plotnine.positions.position
contents:
- name: position
include_attributes: false
- options: *no-members
contents:
- position_dodge
- position_dodge2
- position_fill
- position_identity
- position_jitter
- position_jitterdodge
- position_nudge
- position_stack
- title: Themes
desc: |
Themes control the visual appearance of the non-data elements the plot.
- contents:
- name: theme
include_attributes: false
- options: *no-members
contents:
- theme_538
- theme_bw
- theme_classic
- theme_dark
- theme_gray
- theme_grey
- theme_light
- theme_linedraw
- theme_matplotlib
- theme_minimal
- theme_seaborn
- theme_tufte
- theme_void
- theme_xkcd
- subtitle: Themeables
desc: |
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.
package: plotnine.themes.themeable
contents:
- themeable
- package: plotnine.themes.themeable
contents:
- aspect_ratio
- axis_line
- axis_line_r
- axis_line_r_end
- axis_line_r_start
- axis_line_theta
- axis_line_theta_inside
- axis_line_theta_outside
- axis_line_x
- axis_line_x_bottom
- axis_line_x_top
- axis_line_y
- axis_line_y_left
- axis_line_y_right
- axis_text
- axis_text_r
- axis_text_r_end
- axis_text_r_start
- axis_text_theta
- axis_text_theta_inside
- axis_text_theta_outside
- axis_text_x
- axis_text_x_bottom
- axis_text_x_top
- axis_text_y
- axis_text_y_left
- axis_text_y_right
- axis_ticks
- axis_ticks_length
- axis_ticks_length_major
- axis_ticks_length_major_r
- axis_ticks_length_major_theta
- axis_ticks_length_major_x
- axis_ticks_length_major_y
- axis_ticks_length_minor
- axis_ticks_length_minor_r
- axis_ticks_length_minor_theta
- axis_ticks_length_minor_x
- axis_ticks_length_minor_y
- axis_ticks_major
- axis_ticks_major_r
- axis_ticks_major_r_end
- axis_ticks_major_r_start
- axis_ticks_major_theta
- axis_ticks_major_theta_inside
- axis_ticks_major_theta_outside
- axis_ticks_major_x
- axis_ticks_major_x_bottom
- axis_ticks_major_x_top
- axis_ticks_major_y
- axis_ticks_major_y_left
- axis_ticks_major_y_right
- axis_ticks_minor
- axis_ticks_minor_r
- axis_ticks_minor_r_end
- axis_ticks_minor_r_start
- axis_ticks_minor_theta
- axis_ticks_minor_theta_inside
- axis_ticks_minor_theta_outside
- axis_ticks_minor_x
- axis_ticks_minor_x_bottom
- axis_ticks_minor_x_top
- axis_ticks_minor_y
- axis_ticks_minor_y_left
- axis_ticks_minor_y_right
- axis_ticks_x
- axis_ticks_y
- axis_title
- axis_title_x
- axis_title_x_bottom
- axis_title_x_top
- axis_title_y
- axis_title_y_left
- axis_title_y_right
- dpi
- figure_format
- figure_size
- legend_axis_line
- legend_background
- legend_box
- legend_box_background
- legend_box_just
- legend_box_margin
- legend_box_spacing
- legend_direction
- legend_frame
- legend_justification
- legend_justification_bottom
- legend_justification_inside
- legend_justification_left
- legend_justification_right
- legend_justification_top
- legend_key
- legend_key_height
- legend_key_size
- legend_key_spacing
- legend_key_spacing_x
- legend_key_spacing_y
- legend_key_width
- legend_margin
- legend_position
- legend_position_inside
- legend_spacing
- legend_text
- legend_text_colorbar
- legend_text_legend
- legend_text_position
- legend_ticks
- legend_ticks_length
- legend_title
- legend_title_position
- line
- panel_background
- panel_border
- panel_grid
- panel_grid_major
- panel_grid_major_x
- panel_grid_major_y
- panel_grid_minor
- panel_grid_minor_x
- panel_grid_minor_y
- panel_ontop
- panel_spacing
- panel_spacing_x
- panel_spacing_y
- plot_background
- plot_caption
- plot_caption_position
- plot_footer
- plot_footer_background
- plot_footer_line
- plot_footer_position
- plot_margin
- plot_margin_bottom
- plot_margin_left
- plot_margin_right
- plot_margin_top
- plot_subtitle
- plot_tag
- plot_tag_location
- plot_tag_position
- plot_title
- plot_title_position
- rect
- strip_align
- strip_align_x
- strip_align_y
- strip_background
- strip_background_x
- strip_background_y
- strip_placement
- strip_switch_pad
- strip_switch_pad_x
- strip_switch_pad_y
- strip_text
- strip_text_x
- strip_text_x_bottom
- strip_text_x_top
- strip_text_y
- strip_text_y_left
- strip_text_y_right
- svg_usefonts
- text
- title
- subtitle: Helpful Functions & Classes for Theming
options: *no-members
contents:
- theme_set
- theme_get
- theme_update
- options: *no-members
contents:
- element_line
- element_rect
- element_text
- element_blank
- title: Coordinates
desc: |
Coordinate systems put together the two position scales to produce
a 2d location.
- package: plotnine.coords.coord
contents:
- coord
- options: *no-members
contents:
- coord_cartesian
- coord_equal
- coord_fixed
- coord_flip
- coord_polar
- coord_radial
- coord_trans
- title: Composing Plots
package: plotnine.composition
contents:
- name: Compose
include_attributes: false
- Stack
- Beside
- Wrap
- plot_annotation
- plot_spacer
- plot_layout
- inset_element
- guide_area
- title: Options
desc: |
When working interactively, some of the options make it convenient to
create plots that have a common look and feel.
- subtitle: Accessing the Options
desc: |
These are the methods that access the options.
package: plotnine
options:
dynamic: false
contents:
- options.get_option
- options.set_option
- subtitle: The Available Options
desc: |
These are _all_ the options that you can set or get the values of.
package: plotnine
options:
dynamic: false
contents:
- options.aspect_ratio
- options.base_family
- options.base_margin
- options.current_theme
- options.dpi
- options.figure_size
- options.figure_format
- title: Tools
desc: |
Functions that you may occasioanally find helpful
package: plotnine.helpers
contents:
- get_aesthetic_limits
- package: plotnine.session
contents:
- last_plot
- title: Datasets
desc: |
These datasets ship with the plotnine and you can import them with
from the `plotnine.data` sub-package.
package: plotnine.data
contents:
- anscombe_quartet
- diamonds
- economics
- economics_long
- faithful
- faithfuld
- huron
- luv_colours
- meat
- midwest
- mpg
- msleep
- mtcars
- pageviews
- penguins
- presidential
- seals
- txhousing--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~6115 tokens
- Canonical Reference: https://codewiki.google/github.com/has2k1/plotnine