### Install oxipng for Image Optimization

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs the oxipng tool, used as a test image optimizer. Alternatively, it can be installed using cargo.

```console
brew install oxipng   # Test image optimiser (OR `cargo install oxipng`)
```

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

### Install Plotnine with pip (Documentation Generation)

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs plotnine with packages needed for generating documentation.

```console
pip install 'plotnine[doc]'
```

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

### guide_colorbar

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Initializes a colorbar guide for continuous color/fill aesthetics. This guide can be customized for title, labels, dimensions, and direction.

```APIDOC
## guide_colorbar

### Description
Initializes a colorbar guide for continuous color/fill aesthetics. This guide can be customized for title, labels, dimensions, and direction.

### Parameters
#### Parameters
- **title** (str) - Optional - None - Colorbar title
- **title_position** (str) - Optional - None - Title position ("top", "bottom", "left", "right")
- **title_theme** (element) - Optional - None - Title appearance
- **label** (bool) - Optional - True - Show colorbar labels
- **label_position** (str) - Optional - None - Label position
- **label_theme** (element_text) - Optional - None - Label appearance
- **barwidth** (float) - Optional - None - Width of colorbar in cm
- **barheight** (float) - Optional - None - Height of colorbar in cm
- **nbin** (int) - Optional - 20 - Number of color bins
- **raster** (bool) - Optional - True - Use raster for colorbar
- **ticks** (bool) - Optional - True - Show tick marks
- **draw_ulim** (bool) - Optional - True - Draw upper limit line
- **draw_llim** (bool) - Optional - True - Draw lower limit line
- **direction** (str) - Optional - "vertical" - Colorbar direction ("horizontal" or "vertical")
- **default_unit** (str) - Optional - "line" - Unit for dimensions
- **reverse** (bool) - Optional - False - Reverse color direction
- **order** (int) - Optional - 0 - Display order

### Returns
`guide_colorbar` object

### Examples
```python
from plotnine import (
    ggplot,
    aes,
    geom_point,
    scale_color_continuous,
    guide_colorbar,
    guides
)

# Colorbar for continuous color scale
(ggplot(mtcars, aes(x='wt', y='mpg', color='hp'))
+ geom_point(size=3)
+ scale_color_continuous()
+ guides(
    color=guide_colorbar(
        title='Horsepower',
        barwidth=1,
        barheight=8,
        direction='vertical'
    )
)
)

# Horizontal colorbar
(ggplot(mtcars, aes(x='wt', y='mpg', color='hp'))
+ geom_point(size=3)
+ scale_color_continuous()
+ guides(
    color=guide_colorbar(
        title='HP',
        direction='horizontal',
        barwidth=8,
        barheight=1
    )
)
)
```
```

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

### Install Plotnine with pip (Basic)

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs the core plotnine package. This is sufficient for most users.

```console
pip install plotnine
```

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

### Install Plotnine with pip (All Packages)

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs plotnine with all available extra and optional packages.

```console
pip install 'plotnine[all]'
```

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

### Install Plotnine Development Version from GitHub

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs the latest development version of plotnine directly from its GitHub repository.

```console
pip install git+https://github.com/has2k1/plotnine.git
```

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

### Install Plotnine with pip (Testing)

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs plotnine with packages required for running tests.

```console
pip install 'plotnine[test]'
```

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

### guides Function

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Configure all guides (legends, colorbars) in a plot. This function allows for the removal or specification of guide types for different aesthetics.

```APIDOC
## guides

### Description
Configure all guides (legends, colorbars) in a plot.

### Signature
```python
class guides:
    def __init__(self, **kwargs: str | guide | Literal["none", False] | None)
```

### Parameters
Guide parameters take aesthetic names as keys with values:
- `str` - Guide type name ("legend", "colorbar", etc.)
- `guide` object - Specific guide configuration
- `"none"` or `False` - Remove guide for aesthetic

| Aesthetic | Default Guide | Alternative |
|-----------|----------------|-------------|
| color/colour | guide_legend | guide_colorbar |
| fill | guide_legend | guide_colorbar |
| size | guide_legend | — |
| shape | guide_legend | — |
| linetype | guide_legend | — |
| alpha | guide_legend | — |
| stroke | guide_legend | — |

### Returns
`guides` object to add to a ggplot

### Examples
```python
from plotnine import ggplot, aes, geom_point, guides

# Remove all guides
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)')) + geom_point() + guides(color='none'))

# Use colorbar for color aesthetic
(ggplot(mtcars, aes(x='wt', y='mpg', color='hp')) + geom_point() + guides(color=guide_colorbar()))

# Remove size legend, keep color
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)', size='hp')) + geom_point() + guides(size='none'))
```
```

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

### Install Plotnine with pip (Development)

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs plotnine with packages required for development, including making releases.

```console
pip install 'plotnine[dev]'
```

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

### Controlling Guide Positioning

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Illustrates how to control the position and direction of guides (legends) using the `theme` settings. Common positions include 'bottom', 'top', 'left', 'right', and 'inside'.

```python
from plotnine import ggplot, aes, geom_point, theme

(    ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)'))
    + geom_point()
    + theme(
        legend_position='bottom',   # bottom, top, left, right, inside
        legend_direction='horizontal'
    )
)
```

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

### Simple facet_grid Example

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Demonstrates creating a basic grid of plot panels using facet_grid with explicit row and column facets.

```python
from plotnine import ggplot, aes, geom_point, facet_grid
from plotnine.data import mtcars

# Simple grid
(    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_grid('gear~cyl')
)
```

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

### Install Plotnine with pip (Extra Packages)

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs plotnine along with extra, optional packages for extended functionality.

```console
pip install 'plotnine[extra]'
```

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

### Using guide_colourbar

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Demonstrates how to use the `guide_colourbar` to specify a color bar guide for a plot. This is useful when you want to explicitly control the appearance of the color scale legend.

```python
from plotnine import ggplot, aes, geom_point, guide_colourbar, guides

(    ggplot(mtcars, aes(x='wt', y='mpg', colour='hp'))
    + geom_point(size=3)
    + guides(colour=guide_colourbar())
)
```

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

### Example: Using expand_limits to Add Padding

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Illustrates how to use `expand_limits` to add padding to the x and y axes, ensuring data points have some space from the plot boundaries.

```python
(ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + expand_limits(x=[0, 6], y=[5, 40])
)
```

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

### Plotnine position_fill Example

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/positions.md

Demonstrates how to use position_fill to stack bars and standardize their heights to 100%.

```python
from plotnine import ggplot, aes, geom_bar, position_fill

(ggplot(mtcars, aes(x='factor(cyl)', fill='factor(gear)'))
 + geom_bar(position=position_fill()))
```

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

### Custom Legend Configuration with guide_legend

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Customize the appearance and behavior of a legend using `guide_legend`. This example shows how to set the title, title position, number of columns, and reverse the order of legend items.

```python
from plotnine import (
    ggplot, aes, geom_point,
    guide_legend, guides,
    element_text
)

# Custom legend configuration
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)'))
 + geom_point()
 + guides(
    color=guide_legend(
        title='Cylinders',
        title_position='top',
        ncol=1,
        reverse=True
    )
))
```

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

### Remove All Guides for an Aesthetic

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Use `guides(aesthetic='none')` to remove a specific guide, such as the color legend, from the plot. This is useful when an aesthetic is mapped but you do not want a corresponding legend to be displayed.

```python
from plotnine import ggplot, aes, geom_point, guides

# Remove all guides
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)'))
 + geom_point()
 + guides(color='none'))
```

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

### Use Colorbar for Color Aesthetic

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Configure a colorbar for the color aesthetic by passing `guide_colorbar()` to the `guides` function. This is typically used for continuous color scales.

```python
from plotnine import ggplot, aes, geom_point, guides

# Use colorbar for color aesthetic
(ggplot(mtcars, aes(x='wt', y='mpg', color='hp'))
 + geom_point()
 + guides(color=guide_colorbar()))
```

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

### Define Guide Kind Type

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/types.md

Defines a type alias for the kind of guide to use, specifying 'legend', 'colorbar', or 'colourbar'.

```python
GuideKind: TypeAlias = Literal["legend", "colorbar", "colourbar"]
```

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

### Install Plotnine with Conda

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Installs plotnine using the conda package manager from the conda-forge channel.

```console
conda install -c conda-forge plotnine
```

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

### guide_legend Class

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Legend guide for categorical and discrete aesthetics. This class allows for detailed customization of the appearance and layout of legends.

```APIDOC
## guide_legend

### Description
Legend guide for categorical and discrete aesthetics.

### Signature
```python
class guide_legend:
    def __init__(
        self,
        title: Optional[str] = None,
        title_position: Optional[str] = None,
        title_theme: Optional[element] = None,
        label: bool = True,
        label_position: Optional[str] = None,
        label_theme: Optional[element_text] = None,
        keywidth: Optional[float] = None,
        keyheight: Optional[float] = None,
        reverse: bool = False,
        byrow: bool = False,
        ncol: Optional[int] = None,
        nrow: Optional[int] = None,
        order: int = 0,
    )
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| title | str | No | None | Legend title |
| title_position | str | No | None | Title position ("top", "bottom", "left", "right") |
| title_theme | element | No | None | Title appearance (element_text, element_line, etc.) |
| label | bool | No | True | Show legend labels |
| label_position | str | No | None | Label position relative to key |
| label_theme | element_text | No | None | Label appearance |
| keywidth | float | No | None | Width of legend keys in cm |
| keyheight | float | No | None | Height of legend keys in cm |
| reverse | bool | No | False | Reverse legend order |
| byrow | bool | No | False | Arrange legend items by row |
| ncol | int | No | None | Number of columns in legend |
| nrow | int | No | None | Number of rows in legend |
| order | int | No | 0 | Display order (lower values displayed first) |

### Returns
`guide_legend` object

### Examples
```python
from plotnine import (
    ggplot, aes, geom_point,
    guide_legend, guides,
    element_text
)

# Custom legend configuration
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)')) + geom_point() + guides(color=guide_legend(title='Cylinders', title_position='top', ncol=1, reverse=True)))

# Multiple column legend
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)')) + geom_point() + guides(color=guide_legend(title='Cylinders', ncol=2, byrow=True)))
```
```

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

### Removing Guides by Aesthetic

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Shows how to remove a guide (legend) for a specific aesthetic by setting its value to `False` or `'none'`. This is useful for decluttering plots when a legend is not needed for certain aesthetics.

```python
from plotnine import ggplot, aes, geom_point, guides

# Use False or 'none' to remove guide
(    ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)', size='hp'))
    + geom_point()
    + guides(
        color=False,      # No legend for color
        size='none'        # No legend for size
    )
)
```

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

### Example: Using lims to Set Axis Limits

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Demonstrates how to use the `lims` function to set specific limits for the x and y axes in a ggplot object.

```python
(ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + lims(x=(1, 6), y=(10, 35))
)
```

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

### Apply Custom Facet Labels with labeller

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Shows how to use `labeller` with custom functions to format facet strip labels for multiple variables. This example customizes labels for 'gear' and 'cyl' variables.

```python
from plotnine import ggplot, aes, geom_point, facet_wrap, labeller

def gear_labels(x):
    return f"Gears: {x}"

def cyl_labels(x):
    return f"Cylinders: {x}"

(    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_wrap(
        'gear~cyl',
        labeller=labeller(gear=gear_labels, cyl=cyl_labels)
    )
)
```

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

### Define NoGuide Type

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/types.md

Defines a type alias for values that disable guide display, accepting 'none' or False.

```python
NoGuide: TypeAlias = Literal["none", False]
```

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

### Get current default theme

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Use theme_get() to retrieve the current default theme object.

```python
def theme_get() -> theme
```

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

### Add Color Mapping and Multiple Layers

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/ggplot.md

This example shows how to add a color mapping to an aesthetic and include multiple layers, such as points and a smoothed conditional mean line, to a ggplot.

```python
from plotnine import ggplot, aes, geom_point, stat_smooth

(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(gear)'))
    + geom_point()
    + stat_smooth(method='lm')
)
```

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

### Get Current DPI and Figure Size

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/configuration.md

Retrieves the current values for the 'dpi' and 'figure_size' global options.

```python
from plotnine import get_option

current_dpi = get_option('dpi')
print(f"Current DPI: {current_dpi}")

current_size = get_option('figure_size')
print(f"Current figure size: {current_size}")
```

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

### API Reference Files

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/COMPLETION_SUMMARY.txt

The plotnine library provides 11 API reference markdown files, each detailing specific components. These files contain function signatures, parameter tables, return types, error conditions, and usage examples.

```APIDOC
## API Reference Files

### Description
The plotnine library includes 11 dedicated markdown files for its API reference. These files are organized to provide comprehensive documentation for all exported functions, classes, and components.

### Usage
Navigate to the `api-reference/*.md` files to find detailed documentation for specific components. Each file contains:

- Function signatures with parameter types.
- Parameter tables with defaults and descriptions.
- Return types.
- Error conditions and custom exceptions.
- Usage examples for major functions.
- Cross-references to related components.

### Content
- 200+ functions and classes documented.
- 30+ type definitions.
- Comprehensive parameter documentation.
- Error handling details.
- Practical usage examples.
```

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

### scale_x_continuous

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Configures a continuous x-axis scale, allowing control over its name, breaks, labels, limits, expansion, transformation, and guide.

```APIDOC
## scale_x_continuous

### Description
Continuous x-axis scale.

### Method Signature
```python
def scale_x_continuous(
    name: Optional[str] = None,
    breaks: Optional[Sequence[float]] = None,
    labels: Optional[Sequence[str]] = None,
    limits: Optional[tuple[float, float]] = None,
    expand: Optional[tuple[float, float]] = None,
    trans: Optional[str | Transformer] = None,
    guide: Optional[str | guide] = None,
    **kwargs: Any,
) -> scale
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **name** (str) - Optional - Scale name (for axis label)
- **breaks** (Sequence[float]) - Optional - Positions of axis breaks/ticks
- **labels** (Sequence[str]) - Optional - Labels for breaks
- **limits** (tuple[float, float]) - Optional - Data range to display
- **expand** (tuple[float, float]) - Optional - Expansion factors (for padding)
- **trans** (str | Transformer) - Optional - Transformation ("identity", "log10", "sqrt", "reverse")
- **guide** (str | guide) - Optional - Guide type ("axis")

### Request Example
```python
from plotnine import ggplot, aes, geom_point, scale_x_continuous

(ggplot(mtcars, aes(x='wt', y='mpg'))
 + geom_point()
 + scale_x_continuous(
    name='Weight (1000 lbs)',
    breaks=[2, 3, 4, 5],
    limits=(1.5, 5.5)
))
```

### Response
#### Success Response (200)
Returns a continuous x-axis scale object.

#### Response Example
None provided.
```

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

### Evaluate Aesthetic at Different Stages

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/mapping.md

Use `stage` to define an aesthetic's value based on raw data, after statistical transformation, or after scaling. This example shows evaluating color based on raw data and then conditionally changing it after scaling.

```python
from plotnine import ggplot, aes, geom_point, stage

(ggplot(mtcars, aes(x='wt', y='mpg'))
 + geom_point(
    aes(
        color=stage(
            start='cyl',
            after_scale='(color == "red")'
        )
    )
)
)
```

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

### Remove Size Legend and Keep Color Legend

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Demonstrates how to selectively remove a guide for one aesthetic (e.g., size) while keeping another (e.g., color). This allows for fine-grained control over which legends appear in the plot.

```python
from plotnine import ggplot, aes, geom_point, guides

# Remove size legend, keep color
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)', size='hp'))
 + geom_point()
 + guides(size='none'))
```

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

### Plotnine position_dodge Default Example

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/positions.md

Illustrates the default usage of position_dodge for horizontally dodging boxplots. No specific setup is required beyond importing the function.

```python
from plotnine import ggplot, aes, geom_boxplot, position_dodge

(ggplot(mtcars, aes(x='factor(cyl)', y='mpg', fill='factor(gear)'))
 + geom_boxplot(position=position_dodge()))
```

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

### Initialize Project and Add Plotnine with Pixi

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Initializes a new project with pixi and adds Python and plotnine as dependencies.

```console
pixi init name-of-my-project
cd name-of-my-project
pixi add python plotnine
```

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

### theme_void

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a completely blank theme.

```APIDOC
## theme_void

### Description
Applies a completely blank theme.
```

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

### Create a Horizontal Colorbar

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Configure guide_colorbar to generate a horizontal colorbar. Adjust title, bar dimensions, and direction for horizontal display.

```python
from plotnine import (
    ggplot, aes, geom_point,
    scale_color_continuous,
    guide_colorbar, guides
)

# Horizontal colorbar
(    ggplot(mtcars, aes(x='wt', y='mpg', color='hp'))
    + geom_point(size=3)
    + scale_color_continuous()
    + guides(
        color=guide_colorbar(
            title='HP',
            direction='horizontal',
            barwidth=8,
            barheight=1
        )
    )
)
```

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

### Run Local Tests and Coverage

Source: https://github.com/has2k1/plotnine/blob/main/tools/release-checklist-tpl.md

Commands to switch to the main branch, pull updates, and run type checking, tests, and coverage locally.

```sh
git switch main
git pull origin/main
make typecheck
make test
make coverage
```

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

### geom_segment

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/geoms-and-stats.md

Draws line segments between specified start (x, y) and end (xend, yend) points.

```APIDOC
## geom_segment

### Description
Draw line segments between points.

### Method
`geom_segment(
    mapping=None,
    data=None,
    stat='identity',
    position='identity',
    na.rm=False,
    show_legend=None,
    **kwargs
)`

### Aesthetics
x, xend, y, yend, alpha, color, linetype, size
```

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

### Create a Vertical Colorbar

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Use guide_colorbar to create a vertical colorbar for a continuous color scale. Customize title, bar dimensions, and direction.

```python
from plotnine import (
    ggplot, aes, geom_point,
    scale_color_continuous,
    guide_colorbar, guides
)

# Colorbar for continuous color scale
(    ggplot(mtcars, aes(x='wt', y='mpg', color='hp'))
    + geom_point(size=3)
    + scale_color_continuous()
    + guides(
        color=guide_colorbar(
            title='Horsepower',
            barwidth=1,
            barheight=8,
            direction='vertical'
        )
    )
)
```

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

### Basic Scatter Plot with qplot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/qplot.md

Use `qplot` to create a basic scatter plot by specifying x and y aesthetics and the data source. Additional mappings for color and size can be applied.

```python
from plotnine import qplot
from plotnine.data import mtcars

# Scatter plot
qplot(x='wt', y='mpg', data=mtcars)
```

```python
# With color mapping
qplot(x='wt', y='mpg', color='factor(cyl)', data=mtcars)
```

```python
# With size mapping
qplot(x='wt', y='mpg', size='hp', data=mtcars)
```

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

### Import plotnine and load data

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Import necessary plotnine components and the sample mtcars dataset for plotting.

```python
from plotnine import *
from plotnine.data import mtcars
```

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

### scale_x_discrete

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Configures a categorical x-axis scale, allowing control over its name, breaks, labels, limits, expansion, and guide.

```APIDOC
## scale_x_discrete

### Description
Categorical x-axis scale.

### Method Signature
```python
def scale_x_discrete(
    name: Optional[str] = None,
    breaks: Optional[Sequence[str]] = None,
    labels: Optional[Sequence[str]] = None,
    limits: Optional[Sequence[str]] = None,
    expand: Optional[tuple[float, float]] = None,
    guide: Optional[str | guide] = None,
    **kwargs: Any,
) -> scale
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **name** (str) - Optional - Scale name (for axis label)
- **breaks** (Sequence[str]) - Optional - Positions of axis breaks/ticks
- **labels** (Sequence[str]) - Optional - Labels for breaks
- **limits** (Sequence[str]) - Optional - Data range to display
- **expand** (tuple[float, float]) - Optional - Expansion factors (for padding)
- **guide** (str | guide) - Optional - Guide type ("axis")

### Request Example
None provided.

### Response
#### Success Response (200)
Returns a categorical x-axis scale object.

#### Response Example
None provided.
```

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

### show() Method

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/ggplot.md

Displays the plot using the configured matplotlib backend. This is a convenient method for quickly viewing the generated visualization.

```APIDOC
## show()

Display the plot using the matplotlib backend.

### Signature

```python
def show(self) -> None
```
```

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

### Plotnine position_dodge with Width Example

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/positions.md

Shows how to customize the dodging width in position_dodge for boxplots. A width of 0.5 is applied.

```python
from plotnine import ggplot, aes, geom_boxplot, position_dodge

(ggplot(mtcars, aes(x='factor(cyl)', y='mpg', fill='factor(gear)'))
 + geom_boxplot(position=position_dodge(width=0.5)))
```

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

### facet_grid with Columns Only

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Shows how to create a facet grid with panels arranged only in columns, using '.' for the row specification.

```python
from plotnine import ggplot, aes, geom_point, facet_grid
from plotnine.data import mtcars

# Columns only
(
    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_grid('.~cyl')
)
```

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

### theme_void

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_void for a completely blank theme.

```python
class theme_void: ...
```

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

### theme_get

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Retrieves the current default theme settings.

```APIDOC
## theme_get

### Description
Get the current default theme.

### Returns
Current default theme
```

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

### Combine Multiple Plots Horizontally

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/ggplot.md

This example demonstrates how to combine two different ggplot objects horizontally using the '|' operator for a side-by-side layout.

```python
p1 = ggplot(mtcars, aes('wt', 'mpg')) + geom_point()
p2 = ggplot(mtcars, aes('cyl', 'mpg')) + geom_boxplot()

p1 | p2  # Horizontal layout
```

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

### theme_light

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_light for a light theme with a subtle gray panel background.

```python
class theme_light: ...
```

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

### theme_minimal

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a minimal theme with no background elements.

```APIDOC
## theme_minimal

### Description
Applies a minimal theme with no background elements.
```

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

### theme_bw

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a black and white theme with no background.

```APIDOC
## theme_bw

### Description
Applies a black and white theme with no background.
```

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

### Multiple Geoms with qplot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/qplot.md

Specify a list of geoms to `qplot` to overlay multiple plot types on the same axes. This is useful for combining, for example, points with a smoothed line.

```python
qplot(
    x='wt', y='mpg',
    data=mtcars,
    geom=['point', 'smooth']
)
```

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

### Scale X Discrete Function Signature

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Defines the function signature for a discrete (categorical) x-axis scale. It includes parameters for name, breaks, labels, limits, expansion, and guide.

```python
def scale_x_discrete(
    name: Optional[str] = None,
    breaks: Optional[Sequence[str]] = None,
    labels: Optional[Sequence[str]] = None,
    limits: Optional[Sequence[str]] = None,
    expand: Optional[tuple[float, float]] = None,
    guide: Optional[str | guide] = None,
    **kwargs: Any,
) -> scale:
```

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

### theme_light

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a light theme with a subtle gray panel background.

```APIDOC
## theme_light

### Description
Applies a light theme with a subtle gray panel background.
```

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

### Scale X Continuous Function Signature

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Defines the function signature for a continuous x-axis scale. It accepts parameters for name, breaks, labels, limits, expansion, transformation, and guide.

```python
def scale_x_continuous(
    name: Optional[str] = None,
    breaks: Optional[Sequence[float]] = None,
    labels: Optional[Sequence[str]] = None,
    limits: Optional[tuple[float, float]] = None,
    expand: Optional[tuple[float, float]] = None,
    trans: Optional[str | Transformer] = None,
    guide: Optional[str | guide] = None,
    **kwargs: Any,
) -> scale:
```

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

### theme_bw

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_bw for a black and white theme with no background.

```python
class theme_bw: ...
```

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

### Scale Color Brewer with Qualitative Palette

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Applies a qualitative color scale from the ColorBrewer palettes. Specify the palette name and direction.

```python
def scale_color_brewer(
    type: Literal["sequential", "diverging", "qualitative"] = "sequential",
    palette: Optional[str] = None,
    direction: int = 1,
    **kwargs: Any,
) -> scale:
```

```python
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)'))
    + geom_point()
    + scale_color_brewer(type='qualitative', palette='Set1')
)
```

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

### Plotnine ggplot with Continuous X-axis Scale

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Example demonstrating how to use scale_x_continuous to customize the x-axis of a ggplot. It sets a custom name, specific breaks, and data limits for the x-axis.

```python
from plotnine import ggplot, aes, geom_point, scale_x_continuous

(ggplot(mtcars, aes(x='wt', y='mpg'))
+ geom_point()
+ scale_x_continuous(
    name='Weight (1000 lbs)',
    breaks=[2, 3, 4, 5],
    limits=(1.5, 5.5)
))
```

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

### theme_minimal

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_minimal for a minimal theme with no background elements.

```python
class theme_minimal: ...
```

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

### Configure Plot Legends

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/INDEX.md

Control the appearance and behavior of plot legends. Examples include hiding a legend, specifying the number of columns in a legend, or setting the direction for a color bar.

```python
guides(color='none')
guide_legend(ncol=2)
guide_colorbar(direction='horizontal')
```

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

### Basic Plot Construction with Plotnine

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/OVERVIEW.md

Demonstrates the fundamental structure of creating a plot in Plotnine by layering components like ggplot, geometries, statistics, scales, and themes.

```python
(ggplot(data, aes(x='col1', y='col2'))
    + geom_point()
    + stat_smooth()
    + scale_color_manual(...)
    + theme_minimal()
)
```

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

### theme_classic

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a classic theme resembling base R graphics.

```APIDOC
## theme_classic

### Description
Applies a classic theme resembling base R graphics.
```

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

### facet_grid with Free Scales and Space

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Illustrates using 'free' scales and 'free' space in facet_grid to allow individual panels to adjust their axis limits and sizes independently.

```python
from plotnine import ggplot, aes, geom_point, facet_grid
from plotnine.data import mtcars

# Free scales with variable panel sizes
(
    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_grid('gear~cyl', scales='free', space='free')
)
```

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

### Add Statistical Transformations to a Plot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/INDEX.md

Applies statistical transformations to the data before rendering. Examples include fitting a linear model ('lm') or summarizing data using a specified function (e.g., np.mean).

```python
stat_smooth(method='lm')
stat_summary(fun=np.mean)
```

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

### geom_segment: Draw Line Segments

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/geoms-and-stats.md

Use geom_segment to draw individual line segments between specified start and end points (x, y, xend, yend). Aesthetics include alpha, color, linetype, and size.

```python
geom_segment(
    mapping=None,
    data=None,
    stat='identity',
    position='identity',
    na.rm=False,
    show_legend=None,
    **kwargs
)
```

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

### Tag Pre-release Version

Source: https://github.com/has2k1/plotnine/blob/main/tools/release-checklist-tpl.md

Commands to tag a pre-release version (e.g., rc1) and push the release branch. These are deployed to TestPyPi.

```git
git tag -as v<VERSION>rc1 -m "Version <VERSION>rc1"  # e.g. <VERSION>a1, <VERSION>b1, <VERSION>rc1
git push -u origin release-v<VERSION>
```

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

### Add Geometric Elements to a Plot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/INDEX.md

Examples of adding various geometric shapes (geoms) to represent data points, lines, bars, histograms, and boxplots. Choose the geom that best suits your data visualization needs.

```python
geom_point()
geom_line()
geom_bar()
geom_histogram()
geom_boxplot()
```

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

### facet_grid with Rows Only

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Illustrates how to create a facet grid with panels arranged only in rows, using '.' for the column specification.

```python
from plotnine import ggplot, aes, geom_point, facet_grid
from plotnine.data import mtcars

# Rows only
(
    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_grid('gear~.')
)
```

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

### Set and Revert DPI

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/configuration.md

Demonstrates setting the 'dpi' option to 150 and then reverting it to its previous value.

```python
from plotnine import set_option, get_option

# Save old value
old_dpi = set_option('dpi', 150)
print(f"Changed DPI from {old_dpi} to 150")

# Change back
set_option('dpi', old_dpi)
```

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

### Scale Color Manual with Specific Mappings

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/scales.md

Applies a manual color mapping to a categorical variable, assigning specific colors to each category.

```python
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)'))
    + geom_point()
    + scale_color_manual(
        values={'4': 'red', '6': 'blue', '8': 'green'}
    )
)
```

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

### theme_classic

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_classic for a classic theme resembling base R graphics.

```python
class theme_classic: ...
```

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

### Create a Basic Scatter Plot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/README.md

This snippet demonstrates how to create a basic scatter plot using plotnine. It requires importing the necessary components and data.

```python
from plotnine import ggplot, aes, geom_point
from plotnine.data import mtcars

(ggplot(mtcars, aes(x='wt', y='mpg'))
 + geom_point()
)
```

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

### Update Changelog and Commit

Source: https://github.com/has2k1/plotnine/blob/main/tools/release-checklist-tpl.md

Commands to edit the changelog file, commit the changes, and push them.

```git
nvim doc/changelog.qmd
git commit -am "Update changelog for release"
git push
```

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

### Update Code Quality Checkers

Source: https://github.com/has2k1/plotnine/blob/main/tools/release-checklist-tpl.md

Commands to update pre-commit, ruff, and pyright. Ensure pyright is updated in pyproject.toml.

```bash
pre-commit autoupdate
```

```bash
pip install --upgrade ruff
```

```sh
pip install --upgrade pyright
PYRIGHT_VERSION=$(pyright --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
python -c "
import pathlib, re
f = pathlib.Path('pyproject.toml')
f.write_text(re.sub(r'pyright==[0-9]+\.[0-9]+\.[0-9]+', 'pyright==$PYRIGHT_VERSION', f.read_text()))
"
```

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

### Create Release Branch

Source: https://github.com/has2k1/plotnine/blob/main/tools/release-checklist-tpl.md

Command to create a new Git branch for the release.

```git
git switch -c release-v<VERSION>
```

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

### Tag Final Version and Release

Source: https://github.com/has2k1/plotnine/blob/main/tools/release-checklist-tpl.md

Commands to tag the final release version and push the tag. This triggers the final release to PyPI.

```git
git tag -as v<VERSION> -m "Version <VERSION>"
git push
```

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

### Create a Basic Scatter Plot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/ggplot.md

This snippet demonstrates how to create a basic scatter plot using ggplot, specifying the data and aesthetic mappings for the x and y axes.

```python
from plotnine import ggplot, aes, geom_point
from plotnine.data import mtcars

(ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
)
```

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

### theme_seaborn

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a Seaborn-style theme.

```APIDOC
## theme_seaborn

### Description
Applies a Seaborn-style theme.
```

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

### Global Configuration

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/COMPLETION_SUMMARY.txt

Information on the global configuration options system for plotnine, allowing users to customize library behavior.

```APIDOC
## Global Configuration

### Description
This section details the options system used for global configuration within plotnine, enabling users to modify various aspects of the library's behavior.

### Location
Refer to `configuration.md` for documentation on configuration options.

### Content
- Documentation for the plotnine options system.
- Details on available configuration settings.
```

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

### theme_tufte

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies a Tufte-style minimalist theme.

```APIDOC
## theme_tufte

### Description
Applies a Tufte-style minimalist theme.
```

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

### Multiple Column Legend Layout

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/guides.md

Configure a legend to display items in multiple columns using `guide_legend` with `ncol` and `byrow` parameters. This is useful for managing legends with many discrete items.

```python
from plotnine import (
    ggplot, aes, geom_point,
    guide_legend, guides,
    element_text
)

# Multiple column legend
(ggplot(mtcars, aes(x='wt', y='mpg', color='factor(cyl)'))
 + geom_point()
 + guides(
    color=guide_legend(
        title='Cylinders',
        ncol=2,
        byrow=True
    )
))
```

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

### Set Default Theme

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/configuration.md

Establishes a default theme (e.g., `theme_minimal`) for all newly created plots.

```python
from plotnine import theme_set, theme_minimal

# Set minimal theme as default
theme_set(theme_minimal())

# All new plots use minimal theme
from plotnine import ggplot, aes, geom_point
from plotnine.data import mtcars

(ggplot(mtcars, aes(x='wt', y='mpg'))
 + geom_point())
```

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

### Convert Dictionary to Labeller

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Demonstrates using `as_labeller` to convert a dictionary into a labeller function for facet strips. This is useful for mapping specific values to custom labels.

```python
from plotnine import ggplot, aes, geom_point, facet_wrap, as_labeller

# From dict
my_labels = {
    '4': 'Four Cylinders',
    '6': 'Six Cylinders',
    '8': 'Eight Cylinders'
}

(    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_wrap('~cyl', labeller=as_labeller(my_labels))
)
```

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

### Configure Global Plotnine Options

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/INDEX.md

Set and retrieve global configuration options for plotnine, such as default figure size and DPI. This affects all subsequent plots unless overridden locally. Requires importing `set_option` and `get_option`.

```python
from plotnine import set_option, get_option

set_option('figure_size', (10, 6))
set_option('dpi', 150)
```

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

### Type Definitions

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/COMPLETION_SUMMARY.txt

Detailed documentation for over 30 type definitions used within the plotnine library, including type aliases.

```APIDOC
## Type Definitions

### Description
This section provides complete documentation for all type definitions and type aliases used within the plotnine library. Over 30 distinct type definitions are covered.

### Location
Refer to `types.md` for a comprehensive list and explanation of all type definitions.

### Content
- Documentation for 30+ type definitions.
- Explanation of type aliases.
```

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

### Convert Function to Labeller

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/facets.md

Illustrates using `as_labeller` to convert a Python function into a labeller for facet strips. This allows for programmatic generation of facet labels.

```python
from plotnine import ggplot, aes, geom_point, facet_wrap, as_labeller

# From function
def cyl_label(x):
    return f"{x} cyl"

(    ggplot(mtcars, aes(x='wt', y='mpg'))
    + geom_point()
    + facet_wrap('~cyl', labeller=as_labeller(cyl_label))
)
```

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

### theme

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

The `theme` class is used to configure the visual appearance of plots. It can be used to create a new theme or modify an existing one by specifying various themeable parameters.

```APIDOC
## theme

### Description

Base class for themes and partial theme modifications. Allows customization of various visual elements of a plot.

### Signature

```python
class theme(
    complete: bool = False,
    axis_title_x: Optional[element] = None,
    axis_title_y: Optional[element] = None,
    axis_text_x: Optional[element] = None,
    axis_text_y: Optional[element] = None,
    plot_title: Optional[element_text] = None,
    plot_subtitle: Optional[element_text] = None,
    plot_caption: Optional[element_text] = None,
    legend_title: Optional[element_text] = None,
    legend_text: Optional[element_text] = None,
    legend_position: Union[str, tuple[float, float]] = "right",
    panel_background: Optional[element_rect] = None,
    panel_grid_major: Optional[element_line] = None,
    panel_grid_minor: Optional[element_line] = None,
    **kwargs: Any,
)
```

### Parameters

Key themeable parameters:

- **axis_title_x** (element) - Optional - x-axis title appearance
- **axis_title_y** (element) - Optional - y-axis title appearance
- **axis_text_x** (element) - Optional - x-axis tick labels
- **axis_text_y** (element) - Optional - y-axis tick labels
- **plot_title** (element_text) - Optional - Main plot title
- **plot_subtitle** (element_text) - Optional - Plot subtitle
- **plot_caption** (element_text) - Optional - Plot caption
- **legend_title** (element_text) - Optional - Legend title
- **legend_text** (element_text) - Optional - Legend item text
- **legend_position** (str | tuple) - Optional - Legend position ("left", "right", "top", "bottom", "inside", or coordinates). Defaults to "right".
- **panel_background** (element_rect) - Optional - Panel background
- **panel_grid_major** (element_line) - Optional - Major grid lines
- **panel_grid_minor** (element_line) - Optional - Minor grid lines
- **complete** (bool) - Optional - If True, replaces entire theme. If False, modifies current theme. Defaults to False.

### Returns

`theme` object to add to a ggplot.

### Examples

```python
from plotnine import ggplot, aes, geom_point, theme, element_text, element_line, element_rect
from plotnine.data import mtcars

(ggplot(mtcars, aes(x='wt', y='mpg'))
 + geom_point()
 + theme(
    axis_title_x=element_text(size=12, face='bold'),
    axis_text_x=element_text(angle=45, hjust=1),
    plot_title=element_text(size=14, face='bold', hjust=0.5),
    panel_grid_major=element_line(color='lightgray'),
    panel_background=element_rect(fill='white', color='black'),
    legend_position='bottom'
))
```
```

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

### theme_dark

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_dark for a dark theme with a dark background.

```python
class theme_dark: ...
```

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

### theme_tufte

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_tufte for a Tufte-style minimalist theme.

```python
class theme_tufte: ...
```

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

### theme_xkcd

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Applies an XKCD-style theme. Requires matplotlib xkcd context.

```APIDOC
## theme_xkcd

### Description
Applies an XKCD-style theme (requires matplotlib xkcd context).
```

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

### ggplot Class Initialization

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/ggplot.md

Initializes a new ggplot object, which serves as the foundation for building plots. It accepts default data and aesthetic mappings that can be inherited by subsequent layers.

```APIDOC
## ggplot

**Module:** `plotnine.ggplot`

Create a new ggplot object - the main interface for building plots using the grammar of graphics.

### Signature

```python
class ggplot:
    def __init__(
        self,
        data: Optional[DataLike] = None,
        mapping: Optional[aes] = None,
    )
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| data | DataLike | No | None | Default data for plot. Every layer that does not have data of its own will use this one. Can be a pandas DataFrame, a callable that returns a DataFrame, or an object with `to_pandas()` method. |
| mapping | aes | No | None | Default aesthetics mapping for the plot. These will be used by all layers unless specifically overridden. |

### Returns

`ggplot` object representing a complete plot specification.
```

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

### Create a Basic Scatter Plot

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/INDEX.md

This snippet demonstrates how to create a basic scatter plot using ggplot, aes, and geom_point with the mtcars dataset. Ensure plotnine and its data module are imported.

```python
from plotnine import ggplot, aes, geom_point
from plotnine.data import mtcars

(ggplot(mtcars, aes(x='wt', y='mpg'))
+ geom_point()
)
```

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

### theme_seaborn

Source: https://github.com/has2k1/plotnine/blob/main/_autodocs/api-reference/themes.md

Apply the theme_seaborn for a Seaborn-style theme.

```python
class theme_seaborn: ...
```

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

### Create a basic scatter plot

Source: https://github.com/has2k1/plotnine/blob/main/README.md

Generates a simple scatter plot using 'wt' on the x-axis and 'mpg' on the y-axis from the mtcars dataset.

```python
(ggplot(mtcars, aes("wt", "mpg"))
    + geom_point()
)
```