tessl/pypi-plotnine
A Grammar of Graphics for Python providing a declarative approach to data visualization similar to R's ggplot2
—
Pending
scales-and-axes.mddocs/
Scales and Axes
Scales control how data values map to visual properties, including axis transformations, color palettes, size ranges, and aesthetic mappings. Plotnine provides comprehensive scale functions for all aesthetic types, supporting continuous and discrete data, custom color palettes, axis transformations, and fine-grained control over legends and guides.
Capabilities
Position Scales (X and Y Axes)
Control the mapping of data to x and y positions, including transformations, limits, and formatting.
def scale_x_continuous(name=None, breaks=None, labels=None, limits=None,
expand=None, trans=None, **kwargs):
"""
Continuous x-axis scale.
Parameters:
- name: str, axis label
- breaks: list or function, axis tick positions
- labels: list or function, axis tick labels
- limits: tuple, axis limits (min, max)
- expand: tuple, expansion around data range
- trans: str or transformer, axis transformation
- **kwargs: additional scale parameters
"""
def scale_y_continuous(name=None, breaks=None, labels=None, limits=None,
expand=None, trans=None, **kwargs):
"""
Continuous y-axis scale.
Parameters: Same as scale_x_continuous
"""
def scale_x_discrete(name=None, breaks=None, labels=None, limits=None,
expand=None, **kwargs):
"""
Discrete x-axis scale.
Parameters:
- name: str, axis label
- breaks: list, which levels to display
- labels: list or dict, custom labels for levels
- limits: list, order and subset of levels to display
- expand: tuple, expansion around discrete values
"""
def scale_y_discrete(name=None, breaks=None, labels=None, limits=None,
expand=None, **kwargs):
"""
Discrete y-axis scale.
Parameters: Same as scale_x_discrete
"""Transformed Position Scales
Apply mathematical transformations to axes including logarithmic, square root, and reverse scaling.
def scale_x_log10(name=None, **kwargs):
"""
Log10 transformed x-axis.
Applies log10 transformation with appropriate breaks and labels.
"""
def scale_y_log10(name=None, **kwargs):
"""
Log10 transformed y-axis.
"""
def scale_x_sqrt(name=None, **kwargs):
"""
Square root transformed x-axis.
"""
def scale_y_sqrt(name=None, **kwargs):
"""
Square root transformed y-axis.
"""
def scale_x_reverse(name=None, **kwargs):
"""
Reversed x-axis (high to low).
"""
def scale_y_reverse(name=None, **kwargs):
"""
Reversed y-axis (high to low).
"""
def scale_x_symlog(name=None, **kwargs):
"""
Symmetric log transformed x-axis.
Combines linear and logarithmic scaling.
"""
def scale_y_symlog(name=None, **kwargs):
"""
Symmetric log transformed y-axis.
"""Date and Time Scales
Handle temporal data with appropriate formatting and breaks.
def scale_x_date(name=None, breaks=None, labels=None, limits=None, **kwargs):
"""
Date x-axis scale.
Parameters:
- breaks: str, date_breaks format ('1 day', '2 weeks', '1 month', etc.)
- labels: str or function, date label format
"""
def scale_y_date(name=None, breaks=None, labels=None, limits=None, **kwargs):
"""
Date y-axis scale.
"""
def scale_x_datetime(name=None, breaks=None, labels=None, limits=None, **kwargs):
"""
Datetime x-axis scale.
"""
def scale_y_datetime(name=None, breaks=None, labels=None, limits=None, **kwargs):
"""
Datetime y-axis scale.
"""
def scale_x_timedelta(name=None, **kwargs):
"""
Timedelta x-axis scale.
"""
def scale_y_timedelta(name=None, **kwargs):
"""
Timedelta y-axis scale.
"""Color Scales
Control color mappings for both continuous and discrete data with various palette options.
def scale_color_continuous(name=None, low=None, high=None, **kwargs):
"""
Default continuous color scale.
Parameters:
- name: str, legend title
- low, high: str, colors for low and high values
"""
def scale_color_discrete(name=None, **kwargs):
"""
Default discrete color scale.
"""
def scale_color_manual(name=None, values=None, breaks=None, **kwargs):
"""
Manual color scale with specified colors.
Parameters:
- values: dict or list, color mappings
- breaks: list, order of legend items
"""
def scale_color_gradient(name=None, low='#132B43', high='#56B1F7', **kwargs):
"""
Two-color gradient scale.
Parameters:
- low, high: str, endpoint colors
"""
def scale_color_gradient2(name=None, low='#832424', mid='white', high='#3A3A98',
midpoint=0, **kwargs):
"""
Three-color gradient scale.
Parameters:
- low, mid, high: str, gradient colors
- midpoint: float, data value for middle color
"""
def scale_color_gradientn(name=None, colors=None, values=None, **kwargs):
"""
Multi-color gradient scale.
Parameters:
- colors: list, gradient colors
- values: list, data values corresponding to colors (0-1 scale)
"""Color Palette Scales
Use predefined color palettes including ColorBrewer, matplotlib colormaps, and custom palettes.
def scale_color_brewer(name=None, type='seq', palette=1, direction=1, **kwargs):
"""
ColorBrewer color scales.
Parameters:
- type: str, palette type ('seq', 'div', 'qual')
- palette: str or int, palette name or number
- direction: int, 1 for normal, -1 for reversed
"""
def scale_color_hue(name=None, h=None, c=80, l=65, h_start=0, direction=1,
**kwargs):
"""
Evenly spaced hues around color wheel.
Parameters:
- h: tuple, hue range in degrees
- c: float, chroma (colorfulness)
- l: float, luminance (lightness)
- h_start: float, starting hue
- direction: int, direction around color wheel
"""
def scale_color_grey(name=None, start=0.2, end=0.8, **kwargs):
"""
Grayscale color palette.
Parameters:
- start, end: float, gray levels (0=black, 1=white)
"""
def scale_color_cmap(name=None, cmap=None, **kwargs):
"""
Matplotlib colormap scale.
Parameters:
- cmap: str, matplotlib colormap name
"""
def scale_color_distiller(name=None, type='seq', palette=1, direction=1,
**kwargs):
"""
ColorBrewer palettes for continuous data.
"""
def scale_color_desaturate(name=None, prop=0, **kwargs):
"""
Desaturated color scale.
Parameters:
- prop: float, proportion of desaturation (0-1)
"""Fill Scales
All color scales have corresponding fill versions for area-based geoms.
def scale_fill_continuous(name=None, **kwargs):
"""Default continuous fill scale."""
def scale_fill_discrete(name=None, **kwargs):
"""Default discrete fill scale."""
def scale_fill_manual(name=None, values=None, **kwargs):
"""Manual fill scale."""
def scale_fill_gradient(name=None, low='#132B43', high='#56B1F7', **kwargs):
"""Two-color fill gradient."""
def scale_fill_gradient2(name=None, low='#832424', mid='white', high='#3A3A98',
midpoint=0, **kwargs):
"""Three-color fill gradient."""
def scale_fill_gradientn(name=None, colors=None, values=None, **kwargs):
"""Multi-color fill gradient."""
def scale_fill_brewer(name=None, type='seq', palette=1, direction=1, **kwargs):
"""ColorBrewer fill scales."""
def scale_fill_hue(name=None, **kwargs):
"""Hue-based fill scale."""
def scale_fill_grey(name=None, start=0.2, end=0.8, **kwargs):
"""Grayscale fill scale."""
def scale_fill_cmap(name=None, cmap=None, **kwargs):
"""Matplotlib colormap fill scale."""
def scale_fill_distiller(name=None, type='seq', palette=1, direction=1, **kwargs):
"""ColorBrewer continuous fill scale."""Size Scales
Control the mapping of data to size aesthetics for points and lines.
def scale_size(name=None, range=None, **kwargs):
"""
Size scale for points and lines.
Parameters:
- range: tuple, size range (min_size, max_size)
"""
def scale_size_continuous(name=None, range=None, **kwargs):
"""Continuous size scale."""
def scale_size_discrete(name=None, range=None, **kwargs):
"""Discrete size scale."""
def scale_size_manual(name=None, values=None, **kwargs):
"""Manual size scale."""
def scale_size_identity(name=None, **kwargs):
"""Identity size scale (use data values directly)."""
def scale_size_area(name=None, max_size=6, **kwargs):
"""
Area-based size scale.
Maps data to point area rather than radius.
"""
def scale_size_radius(name=None, range=None, **kwargs):
"""
Radius-based size scale.
Maps data to point radius (default behavior).
"""Shape and Line Type Scales
Control point shapes and line types.
def scale_shape(name=None, **kwargs):
"""
Shape scale for points.
Maps discrete data to different point shapes.
"""
def scale_shape_discrete(name=None, **kwargs):
"""Discrete shape scale."""
def scale_shape_manual(name=None, values=None, **kwargs):
"""
Manual shape scale.
Parameters:
- values: dict or list, shape mappings (use matplotlib marker codes)
"""
def scale_shape_identity(name=None, **kwargs):
"""Identity shape scale."""
def scale_linetype(name=None, **kwargs):
"""
Line type scale.
Maps discrete data to different line styles.
"""
def scale_linetype_discrete(name=None, **kwargs):
"""Discrete line type scale."""
def scale_linetype_manual(name=None, values=None, **kwargs):
"""
Manual line type scale.
Parameters:
- values: dict or list, line type mappings
"""
def scale_linetype_identity(name=None, **kwargs):
"""Identity line type scale."""Alpha (Transparency) Scales
Control transparency mappings.
def scale_alpha(name=None, range=None, **kwargs):
"""
Alpha (transparency) scale.
Parameters:
- range: tuple, alpha range (min_alpha, max_alpha) from 0-1
"""
def scale_alpha_continuous(name=None, range=None, **kwargs):
"""Continuous alpha scale."""
def scale_alpha_discrete(name=None, range=None, **kwargs):
"""Discrete alpha scale."""
def scale_alpha_manual(name=None, values=None, **kwargs):
"""Manual alpha scale."""
def scale_alpha_identity(name=None, **kwargs):
"""Identity alpha scale."""Limit and Expansion Functions
Convenient functions for setting axis limits and controlling plot expansion.
def xlim(*args):
"""
Set x-axis limits.
Parameters:
- *args: min, max values or single tuple/list
Usage: xlim(0, 10) or xlim([0, 10])
"""
def ylim(*args):
"""
Set y-axis limits.
Usage: ylim(0, 10) or ylim([0, 10])
"""
def lims(**kwargs):
"""
Set limits for any aesthetic.
Parameters:
- **kwargs: aesthetic limits (x=(0, 10), y=(0, 5), color=['A', 'B'])
"""
def expand_limits(**kwargs):
"""
Expand plot limits to include specific values.
Parameters:
- **kwargs: values to include (x=0, y=[0, 10])
"""Identity Scales
Use data values directly without transformation.
def scale_color_identity(name=None, **kwargs):
"""Use data values as colors directly."""
def scale_fill_identity(name=None, **kwargs):
"""Use data values as fill colors directly."""
def scale_size_identity(name=None, **kwargs):
"""Use data values as sizes directly."""
def scale_alpha_identity(name=None, **kwargs):
"""Use data values as alpha values directly."""
def scale_shape_identity(name=None, **kwargs):
"""Use data values as shapes directly."""
def scale_linetype_identity(name=None, **kwargs):
"""Use data values as line types directly."""Usage Patterns
Customizing Axis Appearance
# Custom axis labels and limits
ggplot(data, aes(x='x', y='y')) + \
geom_point() + \
scale_x_continuous(name='Custom X Label', limits=(0, 10),
breaks=[0, 2.5, 5, 7.5, 10]) + \
scale_y_continuous(name='Custom Y Label', trans='log10')Color Customization
# Manual color specification
ggplot(data, aes(x='x', y='y', color='group')) + \
geom_point() + \
scale_color_manual(values={'A': 'red', 'B': 'blue', 'C': 'green'})
# ColorBrewer palette
ggplot(data, aes(x='x', y='y', fill='category')) + \
geom_point(shape='o') + \
scale_fill_brewer(type='qual', palette='Set1')Gradient Scales
# Two-color gradient
ggplot(data, aes(x='x', y='y', color='value')) + \
geom_point() + \
scale_color_gradient(low='blue', high='red')
# Three-color diverging gradient
ggplot(data, aes(x='x', y='y', fill='zscore')) + \
geom_point(shape='s') + \
scale_fill_gradient2(low='blue', mid='white', high='red', midpoint=0)Date and Time Axes
# Date axis with custom breaks
ggplot(data, aes(x='date', y='value')) + \
geom_line() + \
scale_x_date(breaks='1 month', labels='%b %Y')Install with Tessl CLI
npx tessl i tessl/pypi-plotnine