tessl/pypi-proplot

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

—

Pending

Overview

Eval results

Files

Colors and Colormaps

Name: tessl/pypi-proplot
Author: tessl

Advanced color handling system with perceptual color spaces, flexible colormap creation, enhanced color cycles, and seamless integration with matplotlib's color infrastructure. Proplot provides a comprehensive color system that extends matplotlib's capabilities with perceptual color spaces, enhanced colormap creation, and intelligent color management.

Capabilities

Colormap Classes

Enhanced colormap classes providing superior color handling with perceptual uniformity and flexible customization options.

class DiscreteColormap:
    """
    Replacement for matplotlib's ListedColormap with enhanced features.
    
    Enhanced discrete colormap with:
    - Perceptual color space support
    - Automatic color interpolation
    - Flexible color specification
    - Seamless matplotlib integration
    """
    
    def __init__(self, colors, name=None, **kwargs):
        """
        Create discrete colormap from color list.
        
        Parameters:
        - colors (sequence): List of color specifications
        - name (str): Colormap name for registration
        - **kwargs: Additional colormap parameters
        """

class ContinuousColormap:
    """
    Replacement for matplotlib's LinearSegmentedColormap.
    
    Enhanced continuous colormap with:
    - Smooth color transitions
    - Multiple interpolation methods
    - Perceptual color space support
    - Advanced segmentation control
    """
    
    def __init__(self, colors, name=None, **kwargs):
        """
        Create continuous colormap from color specifications.
        
        Parameters:
        - colors (sequence): Color specifications for interpolation
        - name (str): Colormap name for registration
        - **kwargs: Additional interpolation parameters
        """

class PerceptualColormap:
    """
    Colormap with linear transitions across hue, saturation, luminance.
    
    Perceptually uniform colormap providing:
    - Linear transitions in perceptual color spaces
    - Hue, saturation, and luminance control
    - Automatic color space optimization
    - Superior visual uniformity
    """
    
    def __init__(self, colors, space='hcl', **kwargs):
        """
        Create perceptually uniform colormap.
        
        Parameters:
        - colors (sequence): Color specifications for transitions
        - space (str): Perceptual color space ('hcl', 'hsl', 'hsv')
        - **kwargs: Color space and interpolation parameters
        """

Normalization Classes

Advanced normalization classes for flexible data-to-color mapping with support for discrete levels, diverging data, and segmented scaling.

class DiscreteNorm:
    """
    Meta-normalizer that discretizes continuous normalizers.
    
    Provides discrete color mapping with:
    - Flexible level specification
    - Automatic level generation
    - Integration with continuous normalizers
    - Enhanced categorical visualization
    """
    
    def __init__(self, levels, norm=None, **kwargs):
        """
        Create discrete normalization.
        
        Parameters:
        - levels (int/array): Number of levels or explicit level values
        - norm (Normalize): Base normalizer to discretize
        - **kwargs: Additional normalization parameters
        """

class DivergingNorm:
    """
    Normalizer ensuring central data value lies at central colormap color.
    
    Diverging normalization with:
    - Automatic center detection
    - Symmetric scaling around center
    - Enhanced diverging colormap integration
    - Flexible center value specification
    """
    
    def __init__(self, vcenter=0, vmin=None, vmax=None):
        """
        Create diverging normalization.
        
        Parameters:
        - vcenter (float): Central value for colormap center
        - vmin (float): Minimum data value
        - vmax (float): Maximum data value
        """

class SegmentedNorm:
    """
    Normalizer that scales data linearly with respect to level sequence.
    
    Segmented normalization providing:
    - Non-uniform level spacing
    - Linear scaling within segments
    - Flexible breakpoint specification
    - Enhanced contour plot integration
    """
    
    def __init__(self, levels, **kwargs):
        """
        Create segmented normalization.
        
        Parameters:
        - levels (array): Level boundaries for segmentation
        - **kwargs: Additional segmentation parameters
        """

Constructor Functions

Flexible factory functions for creating colormaps, normalizers, and color cycles from various input specifications.

def Colormap(*args, **kwargs):
    """
    Construct colormap instances from various inputs.
    
    Parameters:
    - *args: Colormap specifications (names, files, colors, arrays)
    - space (str): Color space for interpolation ('rgb', 'hcl', 'hsl')
    - discrete (bool): Create discrete vs. continuous colormap
    - cyclic (bool): Create cyclic colormap
    - **kwargs: Additional colormap creation parameters
    
    Input Types:
    - Colormap names: 'viridis', 'plasma', 'Blues'
    - Color lists: ['red', 'blue', 'green']
    - Color arrays: numpy arrays of RGB values
    - File paths: .json, .hex, .rgb colormap files
    - matplotlib colormaps: Existing colormap objects
    
    Returns:
    Colormap: DiscreteColormap or ContinuousColormap instance
    """

def Norm(*args, **kwargs):
    """
    Construct normalizer instances from specifications.
    
    Parameters:
    - *args: Normalization specifications
    - levels (int/array): Discrete levels for discretization
    - vcenter (float): Center value for diverging normalization
    - **kwargs: Additional normalization parameters
    
    Normalization Types:
    - 'linear': Linear normalization
    - 'log': Logarithmic normalization
    - 'symlog': Symmetric logarithmic normalization
    - 'discrete': Discrete level normalization
    - 'diverging': Diverging (centered) normalization
    - 'segmented': Segmented level normalization
    
    Returns:
    Normalize: Appropriate normalization instance
    """

def Cycle(*args, **kwargs):
    """
    Construct color cycle instances from various inputs.
    
    Parameters:
    - *args: Color cycle specifications (names, colors, files)
    - samples (int): Number of colors to sample from continuous source
    - **kwargs: Additional cycle creation parameters
    
    Input Types:
    - Cycle names: 'colorblind', 'tab10', 'Set1'
    - Color lists: ['red', 'blue', 'green']
    - Colormap sampling: ('viridis', 5) for 5 colors from viridis
    - File paths: .hex, .rgb color cycle files
    
    Returns:
    DiscreteColormap: Color cycle as discrete colormap
    """

Color Utility Functions

Comprehensive collection of color manipulation functions for converting between color spaces, adjusting color properties, and working with color specifications.

def get_colors(*args, **kwargs):
    """
    Get colors from registered or on-the-fly color cycle.
    
    Parameters:
    - *args: Color cycle specification
    - samples (int): Number of colors to retrieve
    - **kwargs: Additional color retrieval parameters
    
    Returns:
    list: List of color specifications
    """

def set_hue(color, hue, space='hcl'):
    """
    Return color with different hue channel value.
    
    Parameters:
    - color (color-spec): Input color specification
    - hue (float): New hue value (0-360 for hcl/hsl)
    - space (str): Color space for hue adjustment
    
    Returns:
    str: Color specification with modified hue
    """

def set_saturation(color, saturation, space='hcl'):
    """
    Return color with different saturation channel value.
    
    Parameters:
    - color (color-spec): Input color specification
    - saturation (float): New saturation value (0-100 for hcl/hsl)
    - space (str): Color space for saturation adjustment
    
    Returns:
    str: Color specification with modified saturation
    """

def set_luminance(color, luminance, space='hcl'):
    """
    Return color with different luminance channel value.
    
    Parameters:
    - color (color-spec): Input color specification
    - luminance (float): New luminance value (0-100 for hcl/hsl)
    - space (str): Color space for luminance adjustment
    
    Returns:
    str: Color specification with modified luminance
    """

def set_alpha(color, alpha):
    """
    Return color with specified opacity channel value.
    
    Parameters:
    - color (color-spec): Input color specification
    - alpha (float): Opacity value (0-1, 0=transparent, 1=opaque)
    
    Returns:
    str: Color specification with modified alpha channel
    """

def shift_hue(color, shift=0, space='hcl'):
    """
    Shift hue channel of color by specified amount.
    
    Parameters:
    - color (color-spec): Input color specification
    - shift (float): Hue shift amount in degrees
    - space (str): Color space for hue shifting
    
    Returns:
    str: Color specification with shifted hue
    """

def scale_saturation(color, scale=1, space='hcl'):
    """
    Scale saturation channel of color by specified factor.
    
    Parameters:
    - color (color-spec): Input color specification
    - scale (float): Saturation scaling factor (1=no change)
    - space (str): Color space for saturation scaling
    
    Returns:
    str: Color specification with scaled saturation
    """

def scale_luminance(color, scale=1, space='hcl'):
    """
    Scale luminance channel of color by specified factor.
    
    Parameters:
    - color (color-spec): Input color specification
    - scale (float): Luminance scaling factor (1=no change)
    - space (str): Color space for luminance scaling
    
    Returns:
    str: Color specification with scaled luminance
    """

def to_hex(color, space='rgb', cycle=None, keep_alpha=True):
    """
    Translate color specification to HEX string format.
    
    Parameters:
    - color (color-spec): Input color specification
    - space (str): Source color space for conversion
    - cycle (str/Cycle): Color cycle for named color resolution
    - keep_alpha (bool): Preserve alpha channel in output
    
    Returns:
    str: Hexadecimal color string (#RRGGBB or #RRGGBBAA)
    """

def to_rgb(color, space='rgb', cycle=None):
    """
    Translate color specification to RGB tuple.
    
    Parameters:
    - color (color-spec): Input color specification
    - space (str): Source color space for conversion
    - cycle (str/Cycle): Color cycle for named color resolution
    
    Returns:
    tuple: RGB color tuple (r, g, b) with values 0-1
    """

def to_rgba(color, space='rgb', cycle=None, clip=True):
    """
    Translate color specification to RGBA tuple.
    
    Parameters:
    - color (color-spec): Input color specification
    - space (str): Source color space for conversion
    - cycle (str/Cycle): Color cycle for named color resolution
    - clip (bool): Clip values to valid range
    
    Returns:
    tuple: RGBA color tuple (r, g, b, a) with values 0-1
    """

def to_xyz(color, space='hcl'):
    """
    Translate color to channel values in specified colorspace.
    
    Parameters:
    - color (color-spec): Input color specification
    - space (str): Target color space ('hcl', 'hsl', 'hsv', 'rgb')
    
    Returns:
    tuple: Color channel values in specified space
    """

def to_xyza(color, space='hcl'):
    """
    Translate color to channel values with alpha in specified colorspace.
    
    Parameters:
    - color (color-spec): Input color specification
    - space (str): Target color space ('hcl', 'hsl', 'hsv', 'rgb')
    
    Returns:
    tuple: Color channel values with alpha in specified space
    """

Color Spaces

Proplot supports multiple color spaces for perceptually uniform color manipulation:

COLOR_SPACES = {
    'rgb': "Red-Green-Blue (standard display colors)",
    'hcl': "Hue-Chroma-Luminance (perceptually uniform)",
    'hsl': "Hue-Saturation-Lightness (intuitive adjustments)",
    'hsv': "Hue-Saturation-Value (brightness-based)",
    'lab': "CIE LAB (perceptually uniform)",
    'luv': "CIE LUV (chromaticity-based)",
    'xyz': "CIE XYZ (color matching functions)"
}

Built-in Colormaps

Proplot includes extensive colormap collections organized by type:

COLORMAP_CATEGORIES = {
    'sequential': "Colormaps for ordered data (viridis, plasma, Blues, etc.)",
    'diverging': "Colormaps for data with meaningful center (RdBu, BrBG, etc.)",
    'cyclic': "Colormaps for circular data (twilight, hsv, etc.)",
    'qualitative': "Colormaps for categorical data (tab10, Set1, etc.)",
    'monochrome': "Single-hue colormaps (Greys, Blues, Reds, etc.)",
    'geographic': "Colormaps for topographic data (terrain, ocean, etc.)"
}

Usage Examples

Basic Colormap Creation

import proplot as pplt
import numpy as np

# Create custom colormap from colors
colors = ['red', 'white', 'blue']
cmap = pplt.Colormap(colors, name='rwb')

# Create from matplotlib colormap
cmap = pplt.Colormap('viridis', discrete=True, N=10)

# Perceptually uniform colormap
cmap = pplt.Colormap(['red', 'blue'], space='hcl')

Color Manipulation

# Adjust color properties
red = '#FF0000'
darker_red = pplt.scale_luminance(red, 0.7)
shifted_hue = pplt.shift_hue(red, 30)  # Shift 30 degrees
less_saturated = pplt.scale_saturation(red, 0.5)

# Convert between formats
hex_color = pplt.to_hex((1, 0, 0))  # RGB to hex
rgba = pplt.to_rgba('red', space='rgb')
hcl = pplt.to_xyz('red', space='hcl')

Color Cycles

# Get colors from cycle
colors = pplt.get_colors('colorblind', 5)

# Create custom cycle
cycle = pplt.Cycle(['red', 'blue', 'green'], name='rgb')

# Sample from colormap
viridis_colors = pplt.get_colors('viridis', 8)

Advanced Colormap Usage

# Plotting with custom colormap
fig, axes = pplt.subplots(ncols=2)

# Continuous colormap
data = np.random.randn(20, 20)
cmap = pplt.Colormap(['navy', 'white', 'red'], space='hcl')
m = axes[0].contourf(data, cmap=cmap, levels=15)
axes[0].colorbar(m, loc='b')

# Discrete colormap with custom normalization
levels = [0, 2, 4, 8, 16, 32]
norm = pplt.Norm('segmented', levels=levels)
cmap_discrete = pplt.Colormap('plasma', discrete=True, N=len(levels)-1)
m2 = axes[1].contourf(data**2, cmap=cmap_discrete, norm=norm, levels=levels)
axes[1].colorbar(m2, loc='b')

Colormap Registration and Management

# Register custom colormap
colors = ['#440154', '#31688e', '#35b779', '#fde725']
pplt.register_cmaps(colors, name='custom_viridis')

# Use registered colormap
fig, ax = pplt.subplots()
ax.contourf(data, cmap='custom_viridis')

# Register from file
pplt.register_cmaps('scientific_colormap.json')

Normalization Examples

# Diverging normalization
data = np.random.randn(20, 20)
norm = pplt.Norm('diverging', vcenter=0)
ax.contourf(data, cmap='RdBu_r', norm=norm)

# Discrete levels
norm = pplt.Norm('discrete', levels=10)
ax.contourf(data, cmap='viridis', norm=norm)

# Segmented normalization
levels = [-2, -1, -0.5, 0, 0.5, 1, 2]
norm = pplt.Norm('segmented', levels=levels)
ax.contourf(data, cmap='RdBu_r', norm=norm, levels=levels)

Color Space Exploration

# Compare color adjustments in different spaces
base_color = 'red'

# HCL space (perceptually uniform)
hcl_lighter = pplt.set_luminance(base_color, 70, space='hcl')
hcl_desaturated = pplt.set_saturation(base_color, 30, space='hcl')

# HSL space (intuitive)
hsl_lighter = pplt.set_luminance(base_color, 70, space='hsl')
hsl_desaturated = pplt.set_saturation(base_color, 30, space='hsl')

# Plot comparison
colors_hcl = [base_color, hcl_lighter, hcl_desaturated]
colors_hsl = [base_color, hsl_lighter, hsl_desaturated]

fig, axes = pplt.subplots(ncols=2)
axes[0].bar(range(3), [1, 1, 1], color=colors_hcl)
axes[0].format(title='HCL Space Adjustments')
axes[1].bar(range(3), [1, 1, 1], color=colors_hsl)
axes[1].format(title='HSL Space Adjustments')

This comprehensive color system provides powerful tools for creating visually appealing and perceptually uniform visualizations while maintaining compatibility with matplotlib's existing color infrastructure.

Install with Tessl CLI