plotnine

https://plotnine.org/reference
Admin
plotnine is a Grammar of Graphics implementation for Python, allowing users to create declarative...
Tokens:271,353
Snippets:2,268
Trust Score:7.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### guide.setup() method

Source: https://plotnine.org/reference/guide.html

Sets up guide for drawing process. Takes a guides parameter.

```python
setup(guides)
```

--------------------------------

### Setup: Import libraries and plotnine components

Source: https://plotnine.org/reference/examples/stage-preview.html

Loads the autoreload extension and imports the necessary libraries and plotnine components used throughout the examples.

```python
%load_ext autoreload
%autoreload 2
%aimport plotnine

import pandas as pd
import numpy as np

from plotnine import (
    ggplot,
    aes,
    after_stat,
    stage,
    geom_bar,
    geom_text,
    geom_bin_2d,
    stat_bin_2d,
)
```

--------------------------------

### guide.train() method

Source: https://plotnine.org/reference/guide.html

Creates the key for the guide. Takes a scale and optional aesthetic parameter. Returns guide if training is successful.

```python
train(scale, aesthetic=None)
```

--------------------------------

### guide() constructor signature

Source: https://plotnine.org/reference/guide.html

Defines the base guide class constructor with parameters for title, theme, position, direction, reverse, and order.

```python
guide(
    title=None,
    theme=Theme(),
    position=None,
    direction=None,
    reverse=False,
    order=0
)
```

--------------------------------

### setup

Source: https://plotnine.org/reference/layer.html

Method to set up the layer.

```APIDOC
## setup

### Description
Prepare layer for the plot building. Give the layer access to the data, mapping and environment.

### Parameters
- **plot** - Required - The plot object.
```

--------------------------------

### guides()

Source: https://plotnine.org/reference/guides.html

The guides function assigns or removes guides for scale aesthetics. It accepts keyword arguments for each aesthetic scale, allowing specification of the guide type or removal via NoGuide.

```APIDOC
## guides()

### Description
Guides for each scale. Used to assign or remove a particular guide to the scale of an aesthetic.

### Method
Function call

### Endpoint
`guides(alpha=None, color=None, fill=None, linetype=None, shape=None, size=None, stroke=None, colour=None)`

### Parameters
#### Keyword Arguments
- **alpha** (Optional[LegendOrColorbar | NoGuide]) - Optional - Guide for alpha scale.
- **color** (Optional[LegendOrColorbar | NoGuide]) - Optional - Guide for color scale.
- **fill** (Optional[LegendOrColorbar | NoGuide]) - Optional - Guide for fill scale.
- **linetype** (Optional[LegendOnly | NoGuide]) - Optional - Guide for linetype scale.
- **shape** (Optional[LegendOnly | NoGuide]) - Optional - Guide for shape scale.
- **size** (Optional[LegendOnly | NoGuide]) - Optional - Guide for size scale.
- **stroke** (Optional[LegendOnly | NoGuide]) - Optional - Guide for stroke scale.
- **colour** (Optional[LegendOnly | NoGuide]) - Optional - Guide for colour scale.

### Request Example
```python
guides(color='legend', size=None)
```

### Response
#### Success Response
No explicit return value documented.

```

--------------------------------

### expand parameter examples

Source: https://plotnine.org/reference/scale.html

Examples of valid values for the expand parameter to control axis limit expansion.

```python
* `(0, 0)` - Do not expand.
  * `(0, 1)` - Expand lower and upper limits by 1 unit.
  * `(1, 0)` - Expand lower and upper limits by 100%.
  * `(0, 0, 0, 0)` - Do not expand, as `(0, 0)`.
  * `(0, 0, 0, 1)` - Expand upper limit by 1 unit.
  * `(0, 1, 0.1, 0)` - Expand lower limit by 1 unit and upper limit by 10%.
  * `(0, 0, 0.1, 2)` - Expand upper limit by 10% plus 2 units.
```

--------------------------------

### expand parameter examples

Source: https://plotnine.org/reference/scale_fill_hue.html

Examples of the expand parameter configurations, which determine how the scale is expanded using multiplicative and additive constants.

```python
(mul, add)
(mul_low, add_low, mul_high, add_high)
```

```python
* (0, 0) - Do not expand.
  * (0, 1) - Expand lower and upper limits by 1 unit.
  * (1, 0) - Expand lower and upper limits by 100%.
  * (0, 0, 0, 0) - Do not expand, as (0, 0).
  * (0, 0, 0, 1) - Expand upper limit by 1 unit.
  * (0, 1, 0.1, 0) - Expand lower limit by 1 unit and upper limit by 10%.
  * (0, 0, 0.1, 2) - Expand upper limit by 10% plus 2 units.
```

--------------------------------

### Imports and theme setup for geom_area examples

Source: https://plotnine.org/reference/geom_area.html

Imports and default theme setup for the geom_area examples. Sets the default theme to theme_linedraw() before plotting.

```python
from plotnine import (
    ggplot,
    aes,
    geom_area,
    geom_line,
    scale_x_date,
    scale_y_continuous,
    theme_linedraw,
    theme_set,
)
from plotnine.data import economics

# Set default theme
theme_set(theme_linedraw())
```

--------------------------------

### Import libraries for after_stat examples

Source: https://plotnine.org/reference/after_stat.html

Imports pandas, numpy, and plotnine components needed for the examples.

```python
import pandas as pd
import numpy as np

from plotnine import ggplot, aes, after_stat, geom_bar, labs
```

--------------------------------

### Import plotnine and set theme

Source: https://plotnine.org/reference/examples/geom_smooth-preview.html

Imports plotnine and the mpg dataset, and sets the matplotlib theme. This is the setup for all subsequent examples on this page.

```python
from plotnine import ggplot, aes, geom_point, geom_smooth, labs, theme_matplotlib, theme_set
from plotnine.data import mpg

theme_set(theme_matplotlib())
```

--------------------------------

### guide.draw() method

Source: https://plotnine.org/reference/guide.html

Draws the guide.

```python
draw()
```

--------------------------------

### Import libraries for histogram examples

Source: https://plotnine.org/reference/examples/geom_histogram-preview.html

Imports plotnine, diamonds dataset, and percent_format from mizani.formatters. Required for all subsequent examples.

```python
from plotnine import (
    ggplot,
    aes,
    after_stat,
    geom_histogram,
    facet_wrap,
    facet_grid,
    coord_flip,
    scale_y_continuous,
    scale_y_sqrt,
    scale_y_log10,
    scale_fill_manual,
    theme_bw,
    theme_xkcd,
)
from plotnine.data import diamonds
from mizani.formatters import percent_format
```

--------------------------------

### Complete after_scale example with theme_classic

Source: https://plotnine.org/reference/after_scale.html

Final example combining after_scale with an alpha channel and the theme_classic theme for a complete plot.

```python
(
    ggplot(df, aes("var1", color="factor(var1)"))
    + geom_bar(aes(fill=after_scale('color + "66"')), size=1)
    + theme_classic()
)
```

--------------------------------

### setup method signature

Source: https://plotnine.org/reference/layer.html

Signature for the setup method. It prepares the layer for plot building, giving access to data, mapping, and environment.

```python
setup(plot)
```

--------------------------------

### Imports for aes examples

Source: https://plotnine.org/reference/aes.html

Imports needed for the examples: pandas, numpy, and plotnine's ggplot, aes, and geom_point.

```python
import pandas as pd
import numpy as np

from plotnine import ggplot, aes, geom_point
```

--------------------------------

### Import plotnine for facet wrap example

Source: https://plotnine.org/reference/examples/facet_wrap-preview.html

Imports the necessary plotnine functions and the `mpg` dataset for the examples that follow.

```python
from plotnine import ggplot, aes, geom_point, labs, facet_wrap, theme
from plotnine.data import mpg
```

--------------------------------

### Imports for Stack examples

Source: https://plotnine.org/reference/Stack.html

Imports needed for the Stack examples. Includes plotnine, the Stack class, and the huron dataset.

```python
from plotnine import *
from plotnine.composition import Stack
from plotnine.data import huron
```

--------------------------------

### expand parameter example values

Source: https://plotnine.org/reference/scale_x_date.html

Examples of expand parameter values. Use these to control how the scale expands beyond the data limits. For instance, (0, timedelta(0)) disables expansion, while (0, timedelta(days=1)) expands both limits by one day.

```text
(0, timedelta(0))
```

```text
(0, timedelta(days=1))
```

```text
(1, 0)
```

```text
(0, 0, 0, timedelta(hours=6))
```

```text
(0, timedelta(minutes=5), 0.1, timdelta(0))
```

```text
(0, 0, 0.1, timedelta(weeks=2))
```

--------------------------------

### Equivalent Beside constructor call

Source: https://plotnine.org/reference/Beside.html

Shows the equivalent Beside constructor call for the previous | operator example.

```python
Beside([p1, p2, p3])
```

--------------------------------

### guide.create_geoms() method

Source: https://plotnine.org/reference/guide.html

Creates layers of geoms for the guide. Returns self if geom layers were created, or None if no geom layers were created.

```python
create_geoms()
```

--------------------------------

### Preview mtcars data with head()

Source: https://plotnine.org/reference/examples/theme-preview.html

Displays the first five rows of the mtcars DataFrame to preview the data used in the examples.

```python
mtcars.head()
```

--------------------------------

### setup_data(data, params)

Source: https://plotnine.org/reference/position.html

Verify and return data.

```APIDOC
## setup_data(data, params)

### Description
Verify & return data.

### Method
setup_data

### Endpoint
setup_data(data, params)

### Parameters
- **data** - Required - Data to verify.
- **params** - Required - Parameters for the position.

### Request Example
```python
position.setup_data(data, params)
```

### Response
#### Success Response
Returns verified data.

#### Response Example
```python
<verified data>
```
```

--------------------------------

### Import plotnine and mpg data for geom_abline

Source: https://plotnine.org/reference/examples/geom_abline-preview.html

Imports ggplot, aes, geom_point, labs, geom_abline, and facet_grid from plotnine and the mpg dataset. This is the setup required before any geom_abline example.

```python
from plotnine import ggplot, aes, geom_point, labs, geom_abline, facet_grid
from plotnine.data import mpg
```

--------------------------------

### setup_params

Source: https://plotnine.org/reference/facet.html

Creates facet parameters.

```APIDOC
## setup_params

### Description
Create facet parameters.

### Method
`setup_params(data)`

### Parameters
- **data** (list[pd.DataFrame]) - Required - Plot data and data for the layers.
```

--------------------------------

### Printed data from setup_data

Source: https://plotnine.org/reference/examples/geom_density-preview.html

Output of the setup_data print in the previous example. Shows the computed density data with columns PANEL, count, density, group, n, scaled, x, y, ymin, and ymax for 1024 rows.

```text
      PANEL     count   density  group    n    scaled           x         y  \
0         1  0.519038  0.005139     -1  101  0.519039    0.000000  0.005139   
1         1  0.522757  0.005176     -1  101  0.522758    0.097752  0.005176   
2         1  0.526473  0.005213     -1  101  0.526474    0.195503  0.005213   
3         1  0.530187  0.005249     -1  101  0.530188    0.293255  0.005249   
4         1  0.533899  0.005286     -1  101  0.533900    0.391007  0.005286   
...     ...       ...       ...    ...  ...       ...         ...       ...   
1019      1  0.533899  0.005286     -1  101  0.533900   99.608993  0.005286   
1020      1  0.530187  0.005249     -1  101  0.530188   99.706745  0.005249   
1021      1  0.526473  0.005213     -1  101  0.526474   99.804497  0.005213   
1022      1  0.522757  0.005176     -1  101  0.522758   99.902248  0.005176   
1023      1  0.519038  0.005139     -1  101  0.519039  100.000000  0.005139   

      ymin      ymax  
0        0  0.005139  
1        0  0.005176  
2        0  0.005213  
3        0  0.005249  
4        0  0.005286  
...    ...       ...  
1019     0  0.005286  
1020     0  0.005249  
1021     0  0.005213  
1022     0  0.005176  
1023     0  0.005139  

[1024 rows x 10 columns]
```

--------------------------------

### setup_params(data)

Source: https://plotnine.org/reference/position.html

Verify, modify, and return a copy of the params.

```APIDOC
## setup_params(data)

### Description
Verify, modify & return a copy of the params.

### Method
setup_params

### Endpoint
setup_params(data)

### Parameters
- **data** - Required - Data to verify params against.

### Request Example
```python
position.setup_params(data)
```

### Response
#### Success Response
Returns a copy of the params.

#### Response Example
```python
<params>
```
```

--------------------------------

### Customize legend names via guides

Source: https://plotnine.org/reference/examples/scale_color_discrete-preview.html

Use guide_legend within the guides function to rename the legend titles.

```python
(
    ggplot(df)
    + geom_col(aes("x", "y", fill="cat"))
    + geom_point(aes("x", y="yfit", color="cat"))
    + geom_path(aes("x", y="yfit", color="cat"))
    + scale_color_discrete(l=0.4)
    + guides( # new
        fill=guide_legend(title="Data"), color=guide_legend(title="Model")
    )
)
```

--------------------------------

### setup_data

Source: https://plotnine.org/reference/layer.html

Method to set up data.

```APIDOC
## setup_data

### Description
Prepare/modify data for plotting.
```

--------------------------------

### setup_params method

Source: https://plotnine.org/reference/facet.html

Create facet parameters. Takes plot data and data for the layers.

```python
setup_params(data)
```

--------------------------------

### Import statements for Beside example

Source: https://plotnine.org/reference/Beside.html

Imports required for the Beside examples, including plotnine components and the Beside class.

```python
from plotnine import (
    ggplot,
    aes,
    geom_boxplot,
    geom_violin,
    geom_sina,
    labs,
    element_blank,
    theme,
    theme_xkcd,
    theme_538,
)
from plotnine.composition import Beside
from plotnine.data import mpg
```

--------------------------------

### setup_data

Source: https://plotnine.org/reference/facet.html

Allows the facet to manipulate the data.

```APIDOC
## setup_data

### Description
Allow the facet to manipulate the data.

### Method
`setup_data(data)`

### Parameters
- **data** (list[pd.DataFrame]) - Required - Data for each of the layers.

### Returns
- **list[pd.DataFrame]** - Data for each of the layers.

### Notes
This method will be called after `setup_params`, therefore the `params` property will be set.
```

--------------------------------

### setup_data method

Source: https://plotnine.org/reference/facet.html

Allow the facet to manipulate the data. Called after setup_params, so the params property will be set. Returns a list of DataFrames for each layer.

```python
setup_data(data)
```

--------------------------------

### setup_data(data)

Source: https://plotnine.org/reference/coord.html

Allow the coordinate system to manipulate the layer data.

```APIDOC
## setup_data(data)

### Description
Allow the coordinate system to manipulate the layer data.

### Method
setup_data

### Endpoint
setup_data(data)

### Parameters
#### Path Parameters
- **data** (list[pd.DataFrame]) - Required - Data for all Layer.

### Request Example
```python
coord.setup_data(data)
```

### Response
#### Success Response
Returns modified layer data.

#### Response Example
```python
list[pd.DataFrame]
```
```

--------------------------------

### where aesthetic examples

Source: https://plotnine.org/reference/geom_ribbon.html

Examples of aes() calls showing good and bad usage of the 'where' parameter for excluding horizontal regions.

```python
aes(ymin=0, ymax="col1", where="col1 > 0")  # good
 aes(ymin=0, ymax="col1", where="col1 > 10")  # bad

 aes(ymin=col2, ymax="col1", where="col1 > col2")  # good
 aes(ymin=col2, ymax="col1", where="col1 > col3")  # bad
```

--------------------------------

### setup_params(data)

Source: https://plotnine.org/reference/geom.html

Override this method to verify and/or adjust parameters.

```APIDOC
## setup_params(data)

### Description
Override this method to verify and/or adjust parameters.

### Method
setup_params

### Parameters
- **data** (pd.DataFrame) - Required - Data

### Returns
- (not specified in source)
```

--------------------------------

### setup_aes_params(data)

Source: https://plotnine.org/reference/geom.html

Override this method to verify and/or adjust aesthetic parameters.

```APIDOC
## setup_aes_params(data)

### Description
Override this method to verify and/or adjust aesthetic parameters.

### Method
setup_aes_params

### Parameters
- **data** (pd.DataFrame) - Required - Data

### Returns
- (not specified in source)
```

--------------------------------

### Example: range_x = scales.x.dimension()

Source: https://plotnine.org/reference/stat.html

Example of using scale information to find out the physical size of a scale. This is used in the compute_group and compute_panel methods.

```python
range_x = scales.x.dimension()
```

--------------------------------

### setup_panel_params(scale_x, scale_y)

Source: https://plotnine.org/reference/coord.html

Compute the range and break information for the panel.

```APIDOC
## setup_panel_params(scale_x, scale_y)

### Description
Compute the range and break information for the panel.

### Method
setup_panel_params

### Endpoint
setup_panel_params(scale_x, scale_y)

### Parameters
#### Path Parameters
- **scale_x** - Required - X scale.
- **scale_y** - Required - Y scale.

### Request Example
```python
coord.setup_panel_params(scale_x, scale_y)
```

### Response
#### Success Response
Returns panel parameters.

#### Response Example
```python
# Example not provided in source
```
```

--------------------------------

### Create DataFrame for after_stat examples

Source: https://plotnine.org/reference/after_stat.html

Creates a pandas DataFrame with a single column 'var1' containing repeated values, used in the subsequent plotting examples.

```python
df = pd.DataFrame({
    "var1": [1, 2, 2, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 5]
})
```

--------------------------------

### Imports and notebook setup for PlotnineAnimation

Source: https://plotnine.org/reference/PlotnineAnimation.html

Imports and setup for using PlotnineAnimation in a Jupyter notebook. The rc setting enables HTML5 video display for animations.

```python
import pandas as pd
import numpy as np
from plotnine import ggplot, aes, geom_path, theme, theme_void, lims
from plotnine.animation import PlotnineAnimation

# for animation in the notebook
from matplotlib import rc

rc("animation", html="html5")

```

--------------------------------

### setup_layout(layout)

Source: https://plotnine.org/reference/coord.html

Allow the coordinate system alter the layout dataframe.

```APIDOC
## setup_layout(layout)

### Description
Allow the coordinate system alter the layout dataframe.

### Method
setup_layout

### Endpoint
setup_layout(layout)

### Parameters
#### Path Parameters
- **layout** (pd.DataFrame) - Required - Dataframe in which data is assigned to panels and scales.

### Request Example
```python
coord.setup_layout(layout)
```

### Response
#### Success Response
Returns layout dataframe altered according to the requirements of the coordinate system.

#### Response Example
```python
pd.DataFrame
```

### Notes
The input dataframe may be changed.
```

--------------------------------

### Imports for after_scale examples

Source: https://plotnine.org/reference/after_scale.html

Imports required for the after_scale examples: pandas for data handling and plotnine components including ggplot, aes, after_scale, geom_bar, and theme_classic.

```python
import pandas as pd

from plotnine import ggplot, aes, after_scale, geom_bar, theme_classic
```

--------------------------------

### setup_params(data)

Source: https://plotnine.org/reference/coord.html

Create additional parameters. A coordinate system may need to create parameters depending on the original data that the layers get.

```APIDOC
## setup_params(data)

### Description
Create additional parameters. A coordinate system may need to create parameters depending on the _original_ data that the layers get.

### Method
setup_params

### Endpoint
setup_params(data)

### Parameters
#### Path Parameters
- **data** (list[pd.DataFrame]) - Required - Data for each layer before it is manipulated in any way.

### Request Example
```python
coord.setup_params(data)
```

### Response
#### Success Response
Returns additional parameters.

#### Response Example
```python
# Example not provided in source
```
```

--------------------------------

### format_string example

Source: https://plotnine.org/reference/geom_text.html

Example of using the format_string parameter to format text labels with str.format. The comment shows the expected transformation: 2.348 becomes "2.35%".

```python
# 2.348 -> "2.35%"
geom_text(format_string="{:.2f}%")
```

--------------------------------

### Preview meat data with head()

Source: https://plotnine.org/reference/examples/geom_line-preview.html

Displays the first five rows of the meat dataset to inspect its structure before reshaping.

```python
meat.head()
```

--------------------------------

### Generate sample data for before/after measurements

Source: https://plotnine.org/reference/examples/geom_violin-preview.html

Generates a sample dataset with 'before' and 'after' measurements, each with 20 points, and creates a DataFrame with columns 'value', 'when', and 'id'. The 'when' column is converted to a categorical type with the order 'before', 'after'.

```python
np.random.seed(123)
n = 20
mu = (1, 2.3)
sigma = (1, 1.6)

before = np.random.normal(loc=mu[0], scale=sigma[0], size=n)
after = np.random.normal(loc=mu[1], scale=sigma[1], size=n)

df = pd.DataFrame(
    {
        "value": np.hstack([before, after]),
        "when": np.repeat(["before", "after"], n),
        "id": np.hstack([range(n), range(n)]),
    }
)

df["when"] = df["when"].astype(pdtypes.CategoricalDtype(categories=["before", "after"]))
df.head()
```

--------------------------------

### scale_fill_continuous

Source: https://plotnine.org/reference/scale_fill_continuous.html

Documentation for the scale_fill_continuous function, including its arguments and usage examples.

```APIDOC
## scale_fill_continuous

### Description
Creates a continuous fill scale for plot aesthetics, mapping data values to a color gradient.

### Usage
```r
scale_fill_continuous(
  cmap_name = "viridis",
  ...
)
```

### Arguments
- `cmap_name`: A string specifying the Matplotlib colormap name. Default is `"viridis"`.
- `name`: A string for the scale name, used as the label or title. Default is `NULL`.
- `breaks`: A vector of break points or a function. Default is `TRUE`.
- `limits`: A vector of limits or a function. Default is `NULL`.
- `labels`: A vector of labels or a function. Default is `TRUE`.
- `expand`: A numeric vector of length 2 or 4 for expansion. Default is `NULL`.
- `na_value`: A string specifying the color for missing values. Default is `"#7F7F7F"`.

### Details
This function creates a continuous color scale for fill aesthetics. It uses a Matplotlib colormap to map data values to colors. The scale can be customized with various parameters to control breaks, limits, labels, and expansion.

### Examples
```r
# Basic usage
library(ggplot2)
library(plotnine)

# Create a heatmap with default scale
ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
  geom_tile()

# Use a different colormap
ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
  geom_tile() +
  scale_fill_continuous(cmap_name = "plasma")
```
```

--------------------------------

### Linetype tuple format

Source: https://plotnine.org/reference/scale_linetype_manual.html

Tuples of the form (offset, (on, off, on, off, ...)) for linetypes, with examples.

```python
(0, (1, 1)), (1, (2, 2)), (2, (5, 3, 1, 3))
```

--------------------------------

### Save list of plots with save_as_pdf_pages

Source: https://plotnine.org/reference/save_as_pdf_pages.html

Example of passing a list of ggplot objects to save_as_pdf_pages.

```python
base_plot = ggplot(…)
plots = [base_plot + ggtitle('%d of 3' % i) for i in range(1, 3)]
save_as_pdf_pages(plots)
```

--------------------------------

### plotnine.composition.plot_spacer

Source: https://plotnine.org/reference/plot_spacer.html

Documentation for the plot_spacer function in plotnine.composition, including parameters, see also, and examples.

```APIDOC
## plot_spacer(fill=None)

### Description
Creates a blank area as wide or as tall as a plot, used for spacing in plot compositions.

### Parameters
- **fill** (str | tuple[float, float, float] | tuple[float, float, float, float] | None) - Optional - Background color. The default is a transparent area, but it can be changed through this parameter. The color can also be modified by adding a `theme` and setting the `plot_background`.

### See Also
- `Beside` - To arrange plots side by side
- `Stack` - To arrange plots vertically
- `Compose` - For more on composing plots

### Examples
```python
from plotnine import ggplot, aes, geom_point, geom_boxplot, theme, element_rect
from plotnine.composition import plot_spacer
from plotnine.data import mtcars

p1 = ggplot(mtcars, aes("wt", "mpg")) + geom_point()
p2 = ggplot(mtcars, aes("wt", "disp")) + geom_point()
p3 = ggplot(mtcars, aes("factor(cyl)", "wt")) + geom_boxplot()

p1 | plot_spacer() | p2
```

```python
p1 | (p2 / plot_spacer() / p3)
```

Change the color of the space.
```python
p1 | plot_spacer("#FF000022") | p2
```

Which is the same as
```python
p1 | (plot_spacer() + theme(plot_background=element_rect(fill="#FF000022"))) | p2
```
```
Tokens:
Raw