tessl/pypi-plotnine

A Grammar of Graphics for Python providing a declarative approach to data visualization similar to R's ggplot2

—

Pending

Overview

Eval results

Files

Geometric Objects

Name: tessl/pypi-plotnine
Author: tessl

Geometric objects (geoms) are the visual representations that render your data as points, lines, bars, areas, and other shapes. Plotnine provides over 50 geometric objects covering all common visualization types, from basic scatter plots to complex statistical graphics. Each geom has specific aesthetic requirements and optional parameters for customization.

Capabilities

Point and Scatter Geoms

Visualize individual observations as points, with options for jittering, counting overlaps, and density-based coloring.

def geom_point(mapping=None, data=None, stat='identity', position='identity', 
               na_rm=False, inherit_aes=True, show_legend=None, **kwargs):
    """
    Scatter plot points.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill, shape, size, stroke
    
    Parameters:
    - stat: str, statistical transformation ('identity', 'count', etc.)
    - position: str or position object, position adjustment
    - na_rm: bool, whether to remove missing values
    - **kwargs: additional parameters (alpha, color, size, etc.)
    """

def geom_jitter(mapping=None, data=None, width=None, height=None, **kwargs):
    """
    Jittered points to reduce overplotting.
    
    Parameters:
    - width, height: float, amount of jittering in each direction
    """

def geom_count(mapping=None, data=None, **kwargs):
    """
    Count overlapping points and map count to size.
    
    Computed aesthetics: n (count)
    """

def geom_pointdensity(mapping=None, data=None, **kwargs):
    """
    Points colored by local density.
    
    Computed aesthetics: density
    """

Line and Path Geoms

Connect observations with lines, paths, and steps, supporting grouping and various line styles.

def geom_line(mapping=None, data=None, stat='identity', position='identity',
              na_rm=False, **kwargs):
    """
    Connect observations with lines, ordered by x values.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, linetype, size, group
    """

def geom_path(mapping=None, data=None, **kwargs):
    """
    Connect observations with lines in data order.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, linetype, size, group
    """

def geom_step(mapping=None, data=None, direction='hv', **kwargs):
    """
    Connect observations with step function.
    
    Parameters:
    - direction: str, step direction ('hv', 'vh', 'mid')
    """

def geom_segment(mapping=None, data=None, **kwargs):
    """
    Line segments between points.
    
    Required aesthetics: x, y, xend, yend
    Optional aesthetics: alpha, color, linetype, size
    """

def geom_spoke(mapping=None, data=None, **kwargs):
    """
    Line segments from center point with angle and radius.
    
    Required aesthetics: x, y, angle, radius
    Optional aesthetics: alpha, color, linetype, size
    """

Area and Shape Geoms

Create filled areas, ribbons, polygons, and rectangles for area-based visualizations.

def geom_area(mapping=None, data=None, stat='identity', position='stack',
              **kwargs):
    """
    Filled areas under curves.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill, linetype, size
    """

def geom_ribbon(mapping=None, data=None, **kwargs):
    """
    Ribbons between y limits.
    
    Required aesthetics: x, ymin, ymax
    Optional aesthetics: alpha, color, fill, linetype, size
    """

def geom_polygon(mapping=None, data=None, **kwargs):
    """
    Filled polygons.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill, linetype, size, group
    """

def geom_rect(mapping=None, data=None, **kwargs):
    """
    Rectangles.
    
    Required aesthetics: xmin, xmax, ymin, ymax
    Optional aesthetics: alpha, color, fill, linetype, size
    """

def geom_tile(mapping=None, data=None, **kwargs):
    """
    Tiles for heatmaps and grid visualizations.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill, linetype, size, width, height
    """

def geom_raster(mapping=None, data=None, **kwargs):
    """
    High-performance tiles for large datasets.
    
    Required aesthetics: x, y, fill
    """

Bar and Column Geoms

Create bar charts, histograms, and frequency visualizations with various positioning options.

def geom_bar(mapping=None, data=None, stat='count', position='stack',
             width=None, **kwargs):
    """
    Bar charts with automatic counting.
    
    Required aesthetics: x
    Optional aesthetics: alpha, color, fill, linetype, size, weight
    
    Computed aesthetics: count, prop
    """

def geom_col(mapping=None, data=None, position='stack', width=None, **kwargs):
    """
    Column charts using data values as heights.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill, linetype, size
    """

def geom_histogram(mapping=None, data=None, bins=30, binwidth=None, **kwargs):
    """
    Histograms.
    
    Required aesthetics: x
    Optional aesthetics: alpha, color, fill, linetype, size, weight
    
    Parameters:
    - bins: int, number of bins
    - binwidth: float, width of bins
    """

def geom_freqpoly(mapping=None, data=None, **kwargs):
    """
    Frequency polygons.
    
    Required aesthetics: x
    Optional aesthetics: alpha, color, linetype, size, weight
    """

Statistical Geoms

Visualize statistical summaries including box plots, violin plots, density curves, and smoothed trends.

def geom_boxplot(mapping=None, data=None, outlier_colour=None, 
                 outlier_shape=None, outlier_size=None, **kwargs):
    """
    Box and whisker plots.
    
    Required aesthetics: x or y (one must be discrete)
    Optional aesthetics: alpha, color, fill, linetype, size, weight
    
    Computed aesthetics: lower, upper, middle, ymin, ymax
    """

def geom_violin(mapping=None, data=None, scale='area', **kwargs):
    """
    Violin plots.
    
    Required aesthetics: x or y (one must be discrete)
    Optional aesthetics: alpha, color, fill, linetype, size, weight
    
    Parameters:
    - scale: str, scaling method ('area', 'count', 'width')
    """

def geom_density(mapping=None, data=None, **kwargs):
    """
    Smooth density estimates.
    
    Required aesthetics: x
    Optional aesthetics: alpha, color, fill, linetype, size, weight
    
    Computed aesthetics: density, count, scaled
    """

def geom_density_2d(mapping=None, data=None, **kwargs):
    """
    2D density contours.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, linetype, size
    
    Computed aesthetics: level, piece
    """

def geom_smooth(mapping=None, data=None, method='auto', se=True, **kwargs):
    """
    Smoothed conditional means.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill, linetype, size, weight
    
    Parameters:
    - method: str, smoothing method ('auto', 'lm', 'loess', 'gam')
    - se: bool, whether to display confidence interval
    """

Reference Line Geoms

Add reference lines including horizontal, vertical, and diagonal lines for plot annotation.

def geom_hline(mapping=None, data=None, yintercept=None, **kwargs):
    """
    Horizontal reference lines.
    
    Parameters:
    - yintercept: float or list, y-intercept value(s)
    Optional aesthetics: alpha, color, linetype, size
    """

def geom_vline(mapping=None, data=None, xintercept=None, **kwargs):
    """
    Vertical reference lines.
    
    Parameters:
    - xintercept: float or list, x-intercept value(s)
    Optional aesthetics: alpha, color, linetype, size
    """

def geom_abline(mapping=None, data=None, slope=None, intercept=None, **kwargs):
    """
    Diagonal reference lines.
    
    Parameters:
    - slope, intercept: float, line parameters
    Optional aesthetics: alpha, color, linetype, size
    """

Error Bar and Range Geoms

Display uncertainty and ranges with error bars, confidence intervals, and range indicators.

def geom_errorbar(mapping=None, data=None, width=None, **kwargs):
    """
    Vertical error bars.
    
    Required aesthetics: x, ymin, ymax
    Optional aesthetics: alpha, color, linetype, size
    
    Parameters:
    - width: float, width of error bar caps
    """

def geom_errorbarh(mapping=None, data=None, height=None, **kwargs):
    """
    Horizontal error bars.
    
    Required aesthetics: y, xmin, xmax
    Optional aesthetics: alpha, color, linetype, size
    """

def geom_linerange(mapping=None, data=None, **kwargs):
    """
    Vertical line ranges.
    
    Required aesthetics: x, ymin, ymax
    Optional aesthetics: alpha, color, linetype, size
    """

def geom_pointrange(mapping=None, data=None, **kwargs):
    """
    Points with line ranges.
    
    Required aesthetics: x, y, ymin, ymax
    Optional aesthetics: alpha, color, fill, linetype, shape, size
    """

def geom_crossbar(mapping=None, data=None, **kwargs):
    """
    Hollow bars with middle line.
    
    Required aesthetics: x, y, ymin, ymax
    Optional aesthetics: alpha, color, fill, linetype, size
    """

Text and Label Geoms

Add text annotations and labels to plots with positioning and formatting options.

def geom_text(mapping=None, data=None, parse=False, nudge_x=0, nudge_y=0,
              check_overlap=False, **kwargs):
    """
    Text annotations.
    
    Required aesthetics: x, y, label
    Optional aesthetics: alpha, angle, color, family, fontface, hjust, 
                        lineheight, size, vjust
    
    Parameters:
    - parse: bool, whether to parse text as expressions
    - nudge_x, nudge_y: float, position adjustments
    - check_overlap: bool, whether to avoid overlapping text
    """

def geom_label(mapping=None, data=None, **kwargs):
    """
    Text labels with background boxes.
    
    Required aesthetics: x, y, label
    Optional aesthetics: alpha, angle, color, family, fontface, hjust,
                        lineheight, size, vjust, fill
    """

Specialized Geoms

Additional geoms for specific visualization needs including quantile plots, maps, and dot plots.

def geom_qq(mapping=None, data=None, distribution='norm', **kwargs):
    """
    Quantile-quantile plots.
    
    Required aesthetics: sample
    Optional aesthetics: alpha, color, fill, linetype, shape, size
    
    Parameters:
    - distribution: str or scipy distribution, theoretical distribution
    """

def geom_qq_line(mapping=None, data=None, distribution='norm', **kwargs):
    """
    Reference lines for Q-Q plots.
    
    Required aesthetics: sample
    Optional aesthetics: alpha, color, linetype, size
    """

def geom_quantile(mapping=None, data=None, quantiles=None, **kwargs):
    """
    Quantile regression lines.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, linetype, size, weight
    
    Parameters:
    - quantiles: list, quantiles to compute (default: [0.25, 0.5, 0.75])
    """

def geom_rug(mapping=None, data=None, sides='bl', **kwargs):
    """
    Marginal rug plots.
    
    Required aesthetics: x or y
    Optional aesthetics: alpha, color, linetype, size
    
    Parameters:
    - sides: str, which sides to draw ('t', 'r', 'b', 'l')
    """

def geom_dotplot(mapping=None, data=None, binaxis='x', method='dotdensity',
                 binwidth=None, **kwargs):
    """
    Dot plots.
    
    Required aesthetics: x
    Optional aesthetics: alpha, color, fill
    
    Parameters:
    - binaxis: str, axis to bin along
    - method: str, binning method
    - binwidth: float, width of bins
    """

def geom_sina(mapping=None, data=None, **kwargs):
    """
    Sina plots (jittered violin plots).
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, size
    """

def geom_bin2d(mapping=None, data=None, bins=30, **kwargs):
    """
    2D binning (heatmap).
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill
    
    Parameters:
    - bins: int or tuple, number of bins in each direction
    """

def geom_bin_2d(mapping=None, data=None, bins=30, **kwargs):
    """
    2D binning (heatmap) - alternative name for geom_bin2d.
    
    Required aesthetics: x, y
    Optional aesthetics: alpha, color, fill
    
    Parameters:
    - bins: int or tuple, number of bins in each direction
    """

def geom_blank(mapping=None, data=None, **kwargs):
    """
    Empty geom for setting plot limits.
    
    Required aesthetics: x, y (or other aesthetics to set limits)
    """

def geom_map(mapping=None, data=None, map=None, **kwargs):
    """
    Polygon maps.
    
    Required aesthetics: x, y, group
    Optional aesthetics: alpha, color, fill, linetype, size
    
    Parameters:
    - map: DataFrame, map data with polygon coordinates
    """

Annotation Functions

Add annotations and decorative elements to plots.

def annotate(geom, x=None, y=None, xmin=None, xmax=None, ymin=None, ymax=None,
             **kwargs):
    """
    Add annotations to plots.
    
    Parameters:
    - geom: str, type of annotation ('point', 'text', 'rect', etc.)
    - x, y: position coordinates
    - xmin, xmax, ymin, ymax: range coordinates for rect annotations
    - **kwargs: aesthetic parameters for the annotation
    """

def annotation_logticks(base=10, sides='bl', scaled=True, **kwargs):
    """
    Add logarithmic tick marks.
    
    Parameters:
    - base: float, logarithm base
    - sides: str, which sides to add ticks
    - scaled: bool, whether ticks should be scaled
    """

def annotation_stripes(direction='horizontal', **kwargs):
    """
    Add background stripes.
    
    Parameters:
    - direction: str, stripe direction ('horizontal', 'vertical')
    """

def arrow(angle=30, length=0.25, ends='last', type='open'):
    """
    Create arrow specification for geom_segment and geom_path.
    
    Parameters:
    - angle: float, angle of arrow head
    - length: float, length of arrow head
    - ends: str, which ends get arrows ('last', 'first', 'both')
    - type: str, arrow type ('open', 'closed')
    """

Usage Patterns

Layering Multiple Geoms

# Combine points and smoothed line
ggplot(data, aes(x='x', y='y')) + \
    geom_point(alpha=0.6) + \
    geom_smooth(method='lm', color='red')

# Bar chart with error bars
ggplot(summary_data, aes(x='category', y='mean')) + \
    geom_col(fill='lightblue') + \
    geom_errorbar(aes(ymin='mean - se', ymax='mean + se'), width=0.2)

Aesthetic Mapping vs Fixed Values

# Map aesthetics to data
ggplot(data, aes(x='x', y='y')) + geom_point(aes(color='group', size='value'))

# Set fixed aesthetic values
ggplot(data, aes(x='x', y='y')) + geom_point(color='blue', size=3, alpha=0.7)

# Mix mapped and fixed aesthetics  
ggplot(data, aes(x='x', y='y')) + geom_point(aes(color='group'), size=3)

Statistical Geoms with Computed Aesthetics

# Histogram with fill mapped to count
ggplot(data, aes(x='value')) + \
    geom_histogram(aes(fill=after_stat('count')), bins=20)

# Density plot with color mapped to density level
ggplot(data, aes(x='x', y='y')) + \
    geom_density_2d(aes(color=after_stat('level')))

Install with Tessl CLI