CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-proplot

A succinct matplotlib wrapper for making beautiful, publication-quality graphics.

—

Pending
Overview
Eval results
Files

figure-subplots.mddocs/

Figure and Subplot Creation

Core functionality for creating figures and subplot arrangements with proplot's enhanced grid layouts, automatic sizing, and publication-ready formatting options. Proplot provides significant enhancements over matplotlib's default figure creation with automatic layout management, physical unit support, and advanced subplot sharing capabilities.

Capabilities

Figure Creation

Create empty proplot figures with enhanced layout management and automatic sizing capabilities.

def figure(**kwargs):
    """
    Create an empty proplot figure with enhanced features.
    
    Parameters:
    - figwidth (unit-spec): Figure width in physical units
    - figheight (unit-spec): Figure height in physical units  
    - figsize (tuple): Figure size as (width, height) tuple
    - journal (str): Preset journal size ('aaas1', 'agu1', 'nat1', etc.)
    - tight (bool): Enable tight layout algorithm
    - **kwargs: Additional parameters passed to Figure constructor
    
    Returns:
    proplot.figure.Figure: Enhanced figure instance
    """

Subplot Grid Creation

Create figures with subplot grids using proplot's enhanced grid system with automatic spacing and alignment.

def subplots(*args, **kwargs):
    """
    Create figure with subplots using proplot's enhanced grid system.
    
    Parameters:
    - nrows (int): Number of subplot rows (default: 1)
    - ncols (int): Number of subplot columns (default: 1)  
    - array (array-like): 2D array specifying subplot arrangement
    - proj (str): Projection name for all subplots
    - sharex (int/bool/str): X-axis sharing level (0-4)
    - sharey (int/bool/str): Y-axis sharing level (0-4)
    - share (int/bool/str): Both axes sharing level
    - spanx (bool): Span x-axis labels across subplots
    - spany (bool): Span y-axis labels across subplots
    - refwidth (unit-spec): Reference subplot width
    - refheight (unit-spec): Reference subplot height
    - refaspect (float/tuple): Reference aspect ratio
    - wspace (unit-spec): Width spacing between subplots
    - hspace (unit-spec): Height spacing between subplots
    - **kwargs: Figure creation and formatting parameters
    
    Returns:
    tuple: (fig, axs) where fig is Figure and axs is SubplotGrid
    """

Enhanced Figure Class

Main proplot figure class with automatic layout management, panel integration, and advanced formatting capabilities.

class Figure:
    """
    Main proplot figure class with automatic layout management.
    
    Enhanced replacement for matplotlib.figure.Figure with:
    - Physical unit support for all dimensions
    - Automatic layout algorithm with tight spacing
    - Integrated panel (colorbar/legend) management  
    - Academic journal size presets
    - Advanced subplot sharing and spanning
    """
    
    def __init__(self, *,
                 # Figure sizing
                 figwidth=None, figheight=None, figsize=None,
                 width=None, height=None,
                 journal=None,
                 
                 # Reference subplot sizing  
                 refnum=None, ref=None,
                 refwidth=None, refheight=None, 
                 axwidth=None, axheight=None,
                 refaspect=None, aspect=None,
                 
                 # Axis sharing
                 sharex=None, sharey=None, share=None,
                 
                 # Label spanning and alignment
                 spanx=None, spany=None, span=None,
                 alignx=None, aligny=None, align=None,
                 
                 # Spacing and layout
                 left=None, right=None, top=None, bottom=None,
                 wspace=None, hspace=None, space=None,
                 
                 # Tight layout
                 tight=None,
                 outerpad=None, innerpad=None, panelpad=None,
                 wpad=None, hpad=None, pad=None,
                 
                 **kwargs):
        """
        Create enhanced figure with automatic layout management.
        
        Parameters:
        - figwidth/width (unit-spec): Figure width
        - figheight/height (unit-spec): Figure height  
        - figsize (tuple): Figure size (width, height)
        - journal (str): Academic journal preset size
        - refwidth/axwidth (unit-spec): Reference subplot width
        - refheight/axheight (unit-spec): Reference subplot height
        - refaspect/aspect (float/tuple): Reference aspect ratio
        - sharex/sharey/share (int/bool/str): Axis sharing levels
        - spanx/spany/span (bool): Label spanning flags
        - alignx/aligny/align (bool): Label alignment flags
        - left/right/top/bottom (unit-spec): Figure margins
        - wspace/hspace/space (unit-spec): Subplot spacing
        - tight (bool): Enable tight layout algorithm
        - outerpad/innerpad/panelpad (unit-spec): Layout padding
        - **kwargs: Additional matplotlib Figure parameters
        """
    
    def add_subplot(self, *args, number=None, **kwargs):
        """
        Add single subplot to figure.
        
        Parameters:
        - *args: Subplot specification (nrows, ncols, index) or GridSpec
        - number (int): Explicit subplot number
        - proj (str): Projection name for this subplot
        - **kwargs: Axes creation and formatting parameters
        
        Returns:
        proplot.axes.Axes: Created axes instance
        """
    
    def add_subplots(self, array=None, *, ncols=1, nrows=1, 
                     order='C', proj=None, projection=None,
                     proj_kw=None, projection_kw=None, 
                     basemap=None, **kwargs):
        """
        Add multiple subplots to figure.
        
        Parameters:
        - array (array-like): 2D array specifying subplot layout
        - ncols (int): Number of columns (if array not specified)
        - nrows (int): Number of rows (if array not specified)
        - order (str): Subplot numbering order ('C' or 'F')
        - proj/projection (str/sequence): Projection(s) for subplots
        - proj_kw/projection_kw (dict): Projection keyword arguments
        - basemap (bool): Use basemap projections
        - **kwargs: Gridspec and subplot parameters
        
        Returns:
        proplot.gridspec.SubplotGrid: Container of created axes
        """
    
    def colorbar(self, mappable, values=None, loc=None, location=None,
                 row=None, col=None, rows=None, cols=None, span=None,
                 space=None, pad=None, width=None, **kwargs):
        """
        Add colorbar panel to figure.
        
        Parameters:
        - mappable: Mappable object for colorbar (ScalarMappable, Axes, etc.)
        - values (array-like): Explicit colorbar tick values
        - loc/location (str): Panel location ('left', 'right', 'top', 'bottom')
        - row/col/rows/cols (int/sequence): Subplot selection for panel
        - span (bool/int/sequence): Span panel across multiple subplots
        - space (unit-spec): Space between panel and subplots
        - pad (unit-spec): Padding around panel content  
        - width (unit-spec): Panel width
        - **kwargs: Colorbar formatting parameters
        
        Returns:
        matplotlib.colorbar.Colorbar: Created colorbar instance
        """
    
    def legend(self, handles=None, labels=None, loc=None, location=None,
               row=None, col=None, rows=None, cols=None, span=None,
               space=None, pad=None, width=None, **kwargs):
        """
        Add legend panel to figure.
        
        Parameters:
        - handles (sequence): Legend handles (artists)
        - labels (sequence): Legend labels (strings)
        - loc/location (str): Panel location ('left', 'right', 'top', 'bottom')
        - row/col/rows/cols (int/sequence): Subplot selection for panel
        - span (bool/int/sequence): Span panel across multiple subplots
        - space (unit-spec): Space between panel and subplots
        - pad (unit-spec): Padding around panel content
        - width (unit-spec): Panel width
        - **kwargs: Legend formatting parameters
        
        Returns:
        matplotlib.legend.Legend: Created legend instance
        """
    
    def format(self, axs=None, *,
               figtitle=None, suptitle=None, suptitle_kw=None,
               llabels=None, leftlabels=None, leftlabels_kw=None,
               rlabels=None, rightlabels=None, rightlabels_kw=None,
               blabels=None, bottomlabels=None, bottomlabels_kw=None,
               tlabels=None, toplabels=None, toplabels_kw=None,
               rowlabels=None, collabels=None,
               includepanels=None, mathtext_fallback=None, **kwargs):
        """
        Format figure and subplot labels.
        
        Parameters:
        - axs (SubplotGrid): Specific axes to format (default: all)
        - figtitle/suptitle (str): Figure title
        - suptitle_kw (dict): Title formatting parameters
        - leftlabels/llabels/rowlabels (sequence): Left side labels
        - rightlabels/rlabels (sequence): Right side labels  
        - bottomlabels/blabels/collabels (sequence): Bottom labels
        - toplabels/tlabels (sequence): Top labels
        - *labels_kw (dict): Label-specific formatting parameters
        - includepanels (bool): Include panels in formatting
        - mathtext_fallback (bool): Enable mathtext fallback
        - **kwargs: Additional formatting parameters passed to axes
        """
    
    def save(self, filename, **kwargs):
        """
        Save figure with enhanced path handling.
        
        Parameters:
        - filename (str): Output filename with user path expansion
        - **kwargs: Additional parameters passed to matplotlib savefig
        """
    
    @property
    def gridspec(self):
        """proplot.gridspec.GridSpec: The figure's GridSpec instance."""
    
    @property  
    def subplotgrid(self):
        """proplot.gridspec.SubplotGrid: All numbered subplots."""

Grid Specification

Advanced grid specification class for precise subplot arrangement and spacing control.

class GridSpec:
    """
    Grid specification for advanced subplot arrangement.
    
    Enhanced replacement for matplotlib.gridspec.GridSpec with:
    - Physical unit support for all spacing parameters
    - Advanced panel integration
    - Automatic tight layout calculation
    - Flexible ratio-based sizing
    """
    
    def __init__(self, nrows=1, ncols=1, *,
                 # Margins
                 left=None, right=None, top=None, bottom=None,
                 
                 # Spacing  
                 wspace=None, hspace=None, space=None,
                 
                 # Ratios
                 wratios=None, hratios=None,
                 width_ratios=None, height_ratios=None,
                 
                 # Tight layout
                 wequal=None, hequal=None, equal=None,
                 outerpad=None, innerpad=None, panelpad=None,
                 wpad=None, hpad=None, pad=None,
                 
                 **kwargs):
        """
        Create grid specification for subplot layout.
        
        Parameters:
        - nrows (int): Number of grid rows
        - ncols (int): Number of grid columns
        - left/right/top/bottom (unit-spec): Fixed figure margins
        - wspace/hspace/space (unit-spec/sequence): Inter-subplot spacing
        - wratios/width_ratios (sequence): Relative subplot widths
        - hratios/height_ratios (sequence): Relative subplot heights  
        - wequal/hequal/equal (bool): Equal spacing flags
        - outerpad/innerpad/panelpad (unit-spec): Layout padding
        - wpad/hpad/pad (unit-spec/sequence): Tight layout padding
        - **kwargs: Additional matplotlib GridSpec parameters
        """
    
    def update(self, **kwargs):
        """
        Update grid parameters and reposition subplots.
        
        Parameters:
        - **kwargs: Any GridSpec constructor parameters
        """
    
    def get_geometry(self):
        """
        Get total grid geometry including panels.
        
        Returns:
        tuple: (total_rows, total_cols) including panel space
        """
    
    def get_subplot_geometry(self):
        """
        Get subplot-only grid geometry.
        
        Returns:
        tuple: (subplot_rows, subplot_cols) excluding panels
        """
    
    def get_panel_geometry(self):
        """
        Get panel-only grid geometry.
        
        Returns:  
        tuple: (panel_rows, panel_cols) for panel space only
        """
    
    @property
    def figure(self):
        """proplot.figure.Figure: Associated figure instance."""
    
    @property
    def nrows(self):
        """int: Number of subplot rows."""
    
    @property  
    def ncols(self):
        """int: Number of subplot columns."""
    
    @property
    def hratios(self):
        """list: Height ratios for rows."""
    
    @property
    def wratios(self):
        """list: Width ratios for columns."""

Subplot Container

List-like container for managing collections of subplots with both 1D and 2D indexing capabilities.

class SubplotGrid:
    """
    Container for subplot grids with enhanced indexing and formatting.
    
    List-like container that supports:
    - 1D indexing: axs[0], axs[1:3], axs[-1]
    - 2D indexing: axs[0,1], axs[:,0], axs[1,:]
    - Collective formatting: axs.format(xlim=(0,10))
    - Dynamic method generation for all axes operations
    """
    
    def __init__(self, sequence=None, **kwargs):
        """
        Create subplot grid container.
        
        Parameters:
        - sequence (iterable): Initial sequence of axes
        - **kwargs: Additional container parameters
        """
    
    def __getitem__(self, key):
        """
        Get subplot(s) using 1D or 2D indexing.
        
        Parameters:
        - key (int/slice/tuple): Index specification
        
        Returns:
        Axes or SubplotGrid: Single axes or subset of axes
        """
    
    def format(self, **kwargs):
        """
        Format all axes in the grid.
        
        Parameters:
        - **kwargs: Formatting parameters passed to each axes
        """
    
    def panel(self, *args, **kwargs):
        """
        Create panels for all axes in grid.
        
        Parameters:
        - *args, **kwargs: Panel creation parameters
        
        Returns:
        SubplotGrid: Container of created panel axes
        """
    
    @property
    def figure(self):
        """proplot.figure.Figure: Associated figure instance."""
    
    @property
    def gridspec(self):
        """proplot.gridspec.GridSpec: Associated GridSpec instance."""
    
    @property
    def shape(self):
        """tuple: Grid shape as (nrows, ncols)."""

Journal Size Presets

Predefined figure sizes for academic journals:

JOURNAL_SIZES = {
    # Science magazines
    'aaas1': '5.5cm',     # Single column Science
    'aaas2': '12cm',      # Double column Science
    
    # American Geophysical Union
    'agu1': ('95mm', '115mm'),    # Single column
    'agu2': ('190mm', '115mm'),   # Double column
    'agu3': ('95mm', '230mm'),    # Single column, full page
    'agu4': ('190mm', '230mm'),   # Double column, full page
    
    # American Meteorological Society
    'ams1': 3.2,          # Single column (inches)
    'ams2': 5.5,          # Small double column
    'ams3': 6.5,          # Large double column  
    'ams4': 7.48,         # Full page width
    
    # Nature Research
    'nat1': 89,           # Single column (mm)
    'nat2': 183,          # Double column (mm)
    
    # PNAS
    'pnas1': 8.7,         # Single column (cm)
    'pnas2': 11.4,        # 1.3 column
    'pnas3': 17.8,        # Double column (cm)
    
    # Additional formats available...
}

Axis Sharing Levels

Comprehensive sharing system for coordinating axes across subplots:

# Sharing level specifications:
SHARING_LEVELS = {
    0: "No sharing",
    False: "No sharing", 
    
    1: "Share labels only",
    'labels': "Share labels only",
    'labs': "Share labels only",
    
    2: "Share labels and limits", 
    'limits': "Share labels and limits",
    'lims': "Share labels and limits",
    
    3: "Share labels, limits, and tick labels",
    True: "Share labels, limits, and tick labels",
    
    4: "Complete sharing across all subplots",
    'all': "Complete sharing across all subplots"
}

Usage Examples

Basic Figure Creation

import proplot as pplt

# Simple figure
fig = pplt.figure(figwidth=8, figheight=6)

# Figure with subplots
fig, axs = pplt.subplots(nrows=2, ncols=2, figwidth=10)

# Journal format
fig, axs = pplt.subplots(ncols=3, journal='nature2')

Advanced Subplot Layouts

# Custom arrangement with array
array = [[1, 1, 2], [3, 4, 4]]
fig, axs = pplt.subplots(array=array, figwidth=12)

# Physical unit spacing
fig, axs = pplt.subplots(
    nrows=2, ncols=3,
    wspace='1cm', hspace='15mm',
    refwidth='2in', refaspect=1.2
)

# Advanced sharing and spanning
fig, axs = pplt.subplots(
    nrows=2, ncols=3,
    share='limits',      # Share axis limits
    span=True,           # Span axis labels
    align=True           # Align axis labels
)

Panel Integration

# Figure-level colorbar
fig, axs = pplt.subplots(ncols=2)
m = axs[0].contourf(data)
fig.colorbar(m, loc='right', span=True)

# Multiple panels
fig, axs = pplt.subplots(nrows=2, ncols=2)
fig.colorbar(mappable1, loc='bottom', col=1)
fig.legend(handles, loc='right', span=True)

Dynamic Formatting

# Format entire figure
fig.format(
    suptitle='Main Title',
    leftlabels=['Treatment A', 'Treatment B'],
    bottomlabels=['Day 1', 'Day 2', 'Day 3']
)

# Format all subplots
axs.format(
    xlim=(0, 100),
    ylim=(0, 50),
    grid=True,
    xlabel='Time (seconds)',
    ylabel='Response'
)

This comprehensive figure and subplot system enables sophisticated layouts with minimal code while maintaining full matplotlib compatibility and providing powerful enhancements for scientific publication.

Install with Tessl CLI

npx tessl i tessl/pypi-proplot

docs

axes-plotting.md

colors-colormaps.md

configuration.md

demonstrations.md

figure-subplots.md

index.md

projections.md

scales.md

tick-control.md

utilities.md

tile.json