# Changelog¶

## v0.10.2¶

(Not yet released)

### Enhancements¶

`ggplot`

object gained a new method`save_helper()`

. It gives you access to the matplotlib figure that will be saved to file.

### API Changes¶

`__add__()`

and`__iadd__()`

now accept the same types of objects. In this change`__iadd__()`

has gained the ability to accept a list of objects.`draw()`

no longer accepts the argument`return_ggplot`

and the return value is always a matplolib figure.

### Bug Fixes¶

Fixed bug where a discrete position scale failed when mapping an empty variable. (#647)

Fixed bug where

`facet_grid`

with a datetime column run into an exception. (#629)Fixed bug where

`geom_violin`

with facetting and "scales = free" did not work. (#655)Fixed bug in

`position_dodge2`

to work with preserve="single" for`geom_rect`

and any other geoms that accept a min-max range along the x-axis.

## v0.10.1¶

(2022-09-10)

*This is a re-release of v0.10.0*.

In the previous release the project description fileformat changed and not all references to it were corrected. PYPI read file that did not exist, got no description. This release is fixes error.

## v0.10.0¶

(2022-09-10)

### Bug Fixes¶

Fixed bug in

`stat_bin_2d`

where bins whose edges are zero or negative would yield the wrong plot. (#604)Fixed bug

`stat_density_2d`

which had been broken by Matplotlib 1.6.0 (#619)Fixed

`geom_text`

when using`adjust_text`

for the arrows to have the same color as the text.

### New Features¶

`geom_ribbon`

acquired new parameter`where`

which can be used shade withing given limits .Added support for objects with a

`to_pandas`

method to convert them to a pandas dataframe. You can now pass in polars dataframes.`geom_ribbon`

acquired new parameter`outline_type`

which controls how to stroke the boundaries of the shaded area. This parameter is also available to`geom_area`

and`geom_density`

. #605

### API Changes¶

The automatic groups generated by the system and depending on the aesthetic mappings now only depend those aesthetics that have scales. This is more strict than has been, should affect very few cases of code that has been written and it should be less suprising to the users.

`geom_area`

and`geom_density`

now default to showing only the upper outline/boundary of the area. Use`outline_type="full"`

for the old behaviour.

## v0.9.0¶

(2022-07-01)

### API Changes¶

For the calls to

`ggplot`

, the order of the positional arguments is`(data, mapping)`

and for calls`geoms`

and`stats`

the order is`(mapping, data)`

. In practice, you can still provide one/two positional arguments in any order. However, the are a few cases where old code will breaks due to duplicate parameters.

### New Features¶

Added

`geom_pointdensity`

, a 2D density plot that does not hide the distribution of the individual data points.`position_dodge2`

gained the ability to reverse the order of the plotted groups. (#515)Added

`theme_tufte`

, a theme that reduces the distractions around plot data.`labs`

can now be used to create a`caption`

. This caption can be styled using the`plot_caption`

parameter to`theme`

.theme(plot_caption=element_text(size=13))

You can now align the

`plot_title`

horizontally to the left or right.theme(plot_title=element_text(ha='left'))

Before, the title was always centered.

### Bug Fixes¶

Fixed bug in

`facet_grid`

and`facet_wrap`

where the`drop`

parameter was ignored. (#510)Fixed issue with

`annotation_logticks`

where the wrong range was used for the x|y axis. (#525)Fixed bug in

`geom_smooth`

where using a coordinate transformation without computing the standard error led to a crash. (#526)Fixed bug where you could not specific the cap/end of a dashed line when styling a plot with

`element_line`

.Fixed legend for

`geom_map`

so that the entries have the same stroke and points on the map. (#534)Fixed

`geom_history`

for some cases when it fails to automatically determine the number of bins. (#543)Fixed

`facet_grid`

and`facet_wrap`

when mapping to lists/arrays/series so that the rows mapped this way are not mixed up. (#548)Fixed

`stat_bin_2d`

not to error for matplotlib >= 3.5.0 so that it does not throw a Numpy error. (#567)Fixed

`geom_map`

to be able to draw Polygons with holes in them.Fixed

`geom_map`

to be able to draw MultiPolygons.Fixed

`scale_x_discrete`

and`scale_x_discrete`

to work properly with`None`

values. (#523)Fixed

`geom_point`

to respect not to use the`fill`

mapping on unfilled shapes. (#100)Fixed

`position_stack`

to work with scales that have non-linear transformations. e.g.`scale_y_log10`

. (#580)Fixed scales to work with limits passed as a function.

Fixed

`axis_ticks`

so you can change the colour of the axis ticks. This was probably a regression due to changes in Matplotlib.Fixed

`panel_ontop`

so that if is set to`False`

, then the data visualised below the grid-lines. (#585)Fixed

`geom_ribbon`

,`geom_area`

and`geom_density`

to work with`coord_flip`

. (#596)

### Enhancements¶

`stat_summary`

now has a default summary function. (#528)`stat_density`

now uses a fast computation path for gaussian densities with no weights. This was probably a regression.`geom_map`

can now draw MultiPoints, MultiLineStrings and MultiPolgons.`geom_text`

with`adjust_text`

can now be used in more than one layer with good enough results.

## v0.8.0¶

(2021-03-24)

### API Changes¶

How you map to calculated aesthetics has changed. Use the

`after_stat()`

function. The old methods`'stat(name)'`

and`'..name..'`

have been deprecated.

### New Features¶

You can now map to aesthetics at three different stages. See

`aes`

,`after_stat()`

,`after_scale()`

and`stage`

.`geom_violin`

gained the a new parameter`style`

with which you can draw half violin (density curve on one side and flat on the other).Added

`geom_raster`

.`geoms`

gained new parameter`raster`

for the`Layer`

. You can use it to rasterize any layer when the resulting plot is of vector format e.g.`pdf`

.Using the

`space`

parameter,`facet_grid`

gained the ability to have rows and columns of panels of different sizes.

### Bug Fixes¶

Fixed issue where some plots with a colorbar would fail for specific themes. (#424)

Fixed

`geom_map`

to plot`MultiLineString`

geom types.Fixed

`geom_text`

to allow any order of`mapping`

and`data`

positional arguments.Fixed bug were the plotted image may have ignored theming that relied on some Matplotlib rcParams. (#451)

Fixed the

`weight`

aesthetic in`geom_boxplot`

, previously ignored it is now recognised. (#438)Fixed

`annotation_logticks`

and`annotation_stripes`

to work without global data and aesthetics. (#469)Fix

`scale_shape_discrete`

when print many unfilled shapes not to assign the same shapes to more than one group. (#473)Fixed bug in

`stat_ellipse`

where the center of the ellipse assuming a multivariate t-distribution was incorrectly calculated. (#493)

### Enhancements¶

Manual scales now match the values of the breaks if the breaks are given. (#445)

Using

`print`

to show a ggplot object will not show the hash (`<ggplot: ...>`

) anymore. There is now a difference between`repr(p)`

and`str(p)`

. (#453)Added option to for the

`base_family`

of a theme, now you can set it once with and have it be applied to all themes. (#436)from plotnine.options import set_option set_option('base_family', 'Comic Sans MS')

You can now add

`None`

to a ggplot, doing so returns a copy of the the ggplot object. (#474)Better handling of multiline facet labels. (#484)

## v0.7.1¶

(2020-08-05)

### Bug Fixes¶

Fixed issue where a plot has no data and the geoms have no data, but the mappings are valid. (#404)

Fixed

`preserve='single'`

in`plotnine.positions.position_dodge`

and`plotnine.positions.position_dodge2`

to work for geoms that only have`x`

aesthetic and not`xmin`

and`xmax`

e.g`plotnine.geoms.geom_text`

.Fix regression in

`v0.7.0`

where plots with a colorbar would fail if using`theme_matplotlib`

.

## v0.7.0¶

(2020-06-05)

### API Changes¶

Changed the default method of caculating bandwidth for all stats that use kernel density estimation. The affected stats are

`stat_density`

,`stat_ydensity`

, and`stat_sina`

. These stats can now work with groups that have a single unique value.Changed

`plotnine.scale.scale_colour_continuous`

to refer to the same scale as`plotnine.scale.scale_color_continuous`

.Changed

`plotnine.scale.scale_color_cmap`

so the parameter cmap_name refers to the name of the color palette and name refers to the name of the scale. (#371)

### New Features¶

`aes`

got an internal function`reorder`

which makes it easy to change the ordering of a discrete variable according to some other variable/column.`stat_smooth`

can now use formulae for linear models.

### Bug Fixes¶

Fixed issue where a wrong warning could be issued about changing the transform of a specialised scale. It mostly affected the

*timedelta*scale.Fixed

`plotnine.geoms.geom_violin`

and other geoms when used with`position='dodge'`

not to crash when if a layer has an empty group of data.Fixed bug in

`plotnine.geoms.geom_path`

for some cases when groups had less than 2 points. (#319)Fixed all stats that compute kernel density estimates to work when all the data points are the same. (#317)

Fixed issue where setting the group to a string value i.e.

`group='string'`

outside`aes()`

failed due to an error.Fixed issue where discrete position scales could not deal with fewer limits than those present in the data. (#342)

Fixed issue with using custom tuple linetypes~ with

`plotnine.scales.scale_linetype_manual`

. (#352)Fixed

`plotnine.geoms.geom_map`

to work with facets. (#359)Fixed

`plotnine.position.jitter_dodge`

to work when`color`

is used as an aesthetic. (#372)Fixed

`plotnine.geoms.geom_qq`

to work with facets (#379)Fixed skewed head in

`plotnine.geoms.arrow`

when drawn on facetted plot (#388)Fixed issue with

`plotnine.stats.stat_density`

where weights could not be used with a gaussian model. (#392)Fixed bug where

`guide_colorbar`

width and height could not be controlled by`legend_key_width`

and`legend_key_height`

. (#360)

### Enhancements¶

You can now set the bandwidth parameter

`bw`

of`stat_ydensity`

.Parameters ha and va of

`geom_text`

have been converted to aesthetics. You can now map to them. (#325)All themes (except theme_matplotlib) now do not show minor ticks. (#348)

## v0.6.0¶

(2019-08-21)

### API Changes¶

The

`draw`

parameter of`plotnine.geoms.geom_map`

has been removed. Shapefiles should contain only one type of geometry and that is the geometry that is drawn.Ordinal (Ordered categorical) columns are now mapped to ordinal scales. This creates different plots.

The default mapping for the computed aesthetic

*size*of`stat_sum`

has changed to`'stat(n)'`

. This also changes the default plot for`geom_count`

.

### New Features¶

`geom_text`

gained the`adjust_text`

parameter, and can now repel text.Added

`annotation_logticks`

.Added

`geom_sina`

Added scales for ordinal (ordered categorical) columns.

`geom_step`

gained the option`mid`

for the direction parameter. The steps are taken mid-way between adjacent x values.Added

`annotation_stripes`

.

### Bug Fixes¶

Fixed bug where facetting would fail if done on a plot with annotation(s) and one of the facetting columns was also a variable in the environment.

Fixed bug where

`coord_flip`

would not flip geoms created by`geom_rug`

(#216).Fixed bug where plots with

`theme_xkcd`

cannot be saved twice (#199)Fixed bug that made it impossible to map to columns with the same name as a calculated columns of the stat. (#234)

Fixed bug in

`geom_smooth`

that made it difficult to use it with stats other than`stat_smooth`

. (#242)Fixed bug in

`position_dodge`

where by bar plot could get thinner when facetting and useing`preserve = 'single'`

. (#224)Fixed bug in

`coord_trans`

where if the transformation reversed the original limits, the order in which the data was laid out remained unchanged. (#253)Fixed bug in

`stat_count`

where`float`

weights were rounded and lead to a wrong plot. (#260)Fixed bug where one could not use the British spelling

`colour`

to rename a color scale. (#264)Fixed bug in

`lims`

,`xlim`

, and`ylim`

where`datetime`

and`timedelta`

limits resulted in an error.Fixed bug where

`geom_rect`

could not be used with`coord_trans`

. (#256)Fixed bug where using free scales with facetting and flipping the coordinate axes could give unexpected results. (#286)

Fixed unwanted tick along the axis for versions of Matplotlib >= 3.1.0.

Fixed

`geom_text`

not to error when using`hjust`

and`vjust`

. (#287)Fixed bug where

`geom_abline`

`geom_hline`

and`geom_vline`

could give wrong results when used with`coord_trans`

.Fixed bug where layers with only infinite values would lead to an exception if they were the first layer encountered when choosing a scale.

### Enhancements¶

Legends are now plotted in a predictable order which dedends on how the plot is constructed.

The spokes drawn by

`geom_spoke`

can now have a fixed angle.Aesthetics that share a scale (e.g. color and fill can have the same scale) get different guides if mapped to different columns.

When the transform of a specialised (one that is not and identity scale) continuous scale is altered, the user is warned about a possible error in what they expect. (#254, #255)

The

`method_args`

parameter in`stat_smooth`

can now differentiate between arguments for initialising and those for fitting the smoothing model.`position_nudge`

can now deal with more geoms e.g.`geom_boxplot`

.- The
`limits`

parameter of`scale_x_discrete`

and `scale_y_discrete`

can now be a function.

- The
The

`width`

of the boxplot can now be set irrespective of the stat.The mid-point color of

`scale_color_distiller`

now matches that of the trainned data.The way in which layers are created has been refactored to give packages that that extend plotnine more flexibility in manipulating the layers.

You can now specify one sided limits for coordinates. e.g. coord_cartesian(limits=(None, 10)).

All the themeables have been lifted into the definition of

`theme`

so they can be suggested autocomplete.

## v0.5.1¶

(2018-10-17)

### Bug Fixes¶

Changed the dependency for mizani to

`v0.5.2`

. This fixes an issue where facetting may create plots with missing items. (#210)

## v0.5.0¶

(2018-10-16)

### API Changes¶

### Bug Fixes¶

Fixed issue where with the subplots_adjust themeable could not be used to set the wspace and hspace Matplotlib subplot parameters. (#185)

Fixed in

`stat_bin`

where setting custom limits for the scale leads to an error. (#189)Fixed issue interactive plots where the x & y coordinates of the mouse do not show. (#187)

Fixed bug in

`geom_abline`

where passing the mapping as a keyword parameter lead to a wrong plot. (#196)Fixed issue where

`minor_breaks`

for tranformed scaled would have to be given in the transformed coordinates. Know they are given the data coordinates just like the major`breaks`

.

### Enhancements¶

For all geoms, with

`coord_cartesian`

`float('inf')`

or`np.inf`

are interpreted as the boundary of the plot panel.Discrete scales now show missing data (

`None`

and`nan`

). This behaviour is controlled by the new`na_translate`

option.The

`minor_breaks`

parameter for continuous scales can now be given as an integer. An integer is taken to controll the number of minor breaks between any set of major breaks.

## v0.4.0¶

*2018-01-08*

### API Changes¶

Calculated aesthetics are accessed using the

`stat()`

function. The old method (double dots`..name..`

) still works.`stat_qq`

calculates slightly different points for the theoretical quantiles.The

`scales`

(when set to*free*,*free_x*or*free_y*') parameter of`facet_grid`

and`facet_wrap`

assigns the same scale across the rows and columns.

### New Features¶

Added

`geom_qq_line`

and`stat_qq_line`

, for lines through Q-Q plots.Added

`geom_density_2d`

and`geom_stat_2d`

.Added

`stat_ellipse`

.Added

`geom_map`

.Plotnine learned to respect plydata groups.

Added

`stat_hull`

.Added

`save_as_pdf_pages()`

.

### Bug Fixes¶

Fixed issue where colorbars may chop off the colors at the limits of a scale.

Fixed issue with creating fixed mappings to datetime and timedelta type values.(#88)

Fixed

`scale_x_datetime`

and`scale_y_datetime`

to handle the intercepts along the axes (#97).Fixed

`stat_bin`

and`stat_bin_2d`

to properly handle the`breaks`

parameter when used with a transforming scale.Fixed issue with x and y scales where the

`name`

of the scale was ignored when determining the axis titles. Now, the`name`

parameter is specified, it is used as the title. (#105)Fixed bug in discrete scales where a column could not be mapped to integer values. (#108)

Make it possible to hide the legend with

`theme(legend_position='none')`

. (#119)Fixed issue in

`stat_summary_bin`

where some input values gave an error. (#123)Fixed

`geom_ribbon`

to sort data before plotting. (#127)Fixed

`IndexError`

in`facet_grid`

when row/column variable has 1 unique value. (#129)Fixed

`facet_grid`

when`scale='free'`

,`scale='free_x'`

or`scale='free_y'`

, the panels share axes along the row or column.Fixed

`geom_boxplot`

so that user can create a boxplot by specifying all required aesthetics. (#136)Fixed

`geom_violin`

to work when some groups are empty. (#131)Fixed continuous scales to accept

`minor=None`

(#120)Fixed bug for discrete position scales, where

`drop=False`

did not drop unused categories (#139)Fixed bug in

`stat_ydensity`

that caused an exception when a panel had no data. (#147)Fixed bug in

`coord_trans`

where coordinate transformation and facetting could fail with a`KeyError`

. (#151)Fixed bug that lead to a

`TypeError`

when aesthetic mappings to could be recognised as being groupable. It was easy to stumble on this bug when using`geom_density`

. (#165)Fixed bug in

`facet_wrap`

where some combination of parameters lead to unexpected panel arrangements. (#163)Fixed bug where the legend text of colorbars could not be themed. (#171)

## v0.3.0¶

*(2017-11-08)*

### API Changes¶

`geom_smooth`

gained an extra parameter`legend_fill_ratio`

that control the area of the legend that is filled to indicate confidence intervals. (#32)`plotnine.ggplot.save()`

gained an extra parameter`verbose`

. It no longer guesses when to print information and when not to.`plotnine.ggplot.draw()`

gained an extra parameter`return_ggplot`

.If the

`minor_breaks`

parameter of scales is a callable, it now expects one argument, the`limits`

. Previously it accepted`breaks`

and`limits`

.

### New Features¶

Added

`PlotnineAnimation`

for animations.Added

`watermark`

for watermarks.Added datetime scales for

`alpha`

,`colour`

,`fill`

and`size`

aesthetics

### Enhancements¶

Changed parameter settings for

`stat_smooth`

.Default

`span=0.75`

instead of`2/3`

When using loess smoothing, the control parameter

`surface`

is only set to the value`'direct'`

if predictions will be made outside the data range.

Better control of scale limits. You can now specify individual limits of a scale.

scale_y_continuous(limits=(0, None)) xlim(None, 100)

You can also use

`expand_limits()`

Low and high

`scale`

limits can now be expanded separately with different factors multiplicative and additive factors.The layer parameter show_legend can now accept a

`dict`

for finer grained control of which aesthetics to exclude in the legend.Infinite values are removed before statistical computations

`stats`

(#40).`stats`

also gained new parameter`na_rm`

, that controls whether missing values are removed before statistical computations.`qplot()`

can now use the name and a Pandas series to label the scales of the aesthetics.You can now put stuff to add to a ggplot object into a list and add that that instead. No need to wrap the list around the internal class Layers.

lst = [geom_point(), geom_line()] g = ggplot(df, aes('x', 'y')) print(g + lst)

Using a list allows you to bundle up objects. It can be convenient when creating some complicated plots. See the Periodic Table Example.

You can now use a

`dict`

(with manual scales) to map data values to aesthetics (#169).You can now specify infinite coordinates with

`plotnine.geoms.geom_rect`

(#166)

### Bug Fixes¶

Fixed bug where facetting led to a reordering of the data. This would manifest as a bug for

`geoms`

where order was important. (#26)Fix bug where facetting by a column whose name (eg.

`class`

) is a python keyword resulted in an exception. (#28)Fix bug where y-axis scaling was calculated from the

`xlim`

argument.Fix bug where initialising geoms from stats, and positions from geoms, when passed as classes (e.g.

`stat_smooth(geom=geom_point)`

, would fail.Fixed bug in

`plotnine.ggplot.save()`

where specifying the`width`

and`height`

would mess up the`strip_text`

and`spacing`

for the facetted plots. (#44).Fixed bug in

`geom_abline`

,`geom_hline`

and`geom_vline`

where facetting on a column that is not mapped to an aesthetic fails. (#48)Fixed bug in

`geom_text`

, the`fontstyle`

parameter was being ignored.Fixed bug where boolean data was mapped to the same value on the coordinate axis. (#57)

Fixed bug in

`facet_grid`

where the`scales`

sometimes has no effect. (#58)Fixed bug in

`stat_boxplot`

where setting the`width`

parameter caused an exception.

## v0.2.1¶

*(2017-06-22)*

Fixed bug where manually setting the aesthetic

`fill=None`

or`fill='None'`

could lead to a black fill instead of an empty fill.Fixed bug where computed aesthetics could not be used in larger statements. (#7)

Fixed bug in

`stat_summary`

where the you got an exception for some types of the x aesthetic values.Fixed bug where

`ggplot(data=df)`

resulted in an exception.Fixed missing axis ticks and labels for

`facet_wrap`

when the scales are allowed to vary (e.g scales='free') between the panels.Fixed bug in

`stat_density`

where changing the x limits lead to an exception (#22)

## v0.2.0¶

*(2017-05-18)*

Fixed bug in

`scale_x_discrete`

and`scale_y_discrete`

where if they were instantiated with parameter`limits`

that is either a numpy array or a pandas series, plotting would fail with a`ValueError`

.Fixed exceptions when using

`pandas.pivot_table()`

for Pandas v0.20.0. The API was fixed.Fixed issues where lines/paths with segments that all belonged in the same group had joins that in some cases were "butted".

### API Changes¶

`geom_text`

now uses`ha`

and`va`

as parameter names for the horizontal and vertical alignment. This is what matplotlib users expect. The previous names`hjust`

and`vjust`

are silently accepted.`Layers()`

can now be used to bundle up`geoms`

and`stats`

. This makes it easy to reuse`geoms`

and stats or organise them in sensible bundles when making complex plots.

## v0.1.0¶

*(2017-04-25)*

First public release