Axes and Plotting

class Axes:
    """
    Base proplot axes class with enhanced formatting capabilities.
    
    Enhanced replacement for matplotlib.axes.Axes providing:
    - Universal format() method for all visual properties
    - Physical unit support throughout
    - Enhanced spine, tick, and grid control
    - Integrated panel and inset management
    """
    
    def format(self, **kwargs):
        """
        Universal formatting method for all visual properties.
        
        Parameters:
        - title (str): Axes title
        - xlabel (str): X-axis label  
        - ylabel (str): Y-axis label
        - xlim (tuple): X-axis limits
        - ylim (tuple): Y-axis limits
        - color (color-spec): Universal color for spines, ticks, labels
        - grid (bool): Grid visibility toggle
        - **kwargs: Additional formatting parameters specific to axes type
        """
    
    def panel_axes(self, side, **kwargs):
        """
        Create panel axes for colorbars or legends.
        
        Parameters:
        - side (str): Panel location ('left', 'right', 'top', 'bottom')
        - space (unit-spec): Space between panel and axes
        - width (unit-spec): Panel width
        - **kwargs: Additional panel parameters
        
        Returns:
        proplot.axes.Axes: Created panel axes
        """
    
    def inset_axes(self, **kwargs):
        """
        Create inset axes within current axes.
        
        Parameters:
        - bounds (tuple): Inset bounds as (x, y, width, height)
        - loc (str/int): Inset location specification
        - **kwargs: Additional inset parameters
        
        Returns:
        proplot.axes.Axes: Created inset axes
        """

class PlotAxes:
    """
    Mixin class providing enhanced plotting methods.
    
    Enhancements over matplotlib include:
    - Automatic color cycling with proplot colormaps
    - Integrated colorbar and legend management
    - Enhanced argument processing and validation
    - Improved styling and formatting options
    """
    
    def plot(self, *args, **kwargs):
        """
        Enhanced line plotting with proplot features.
        
        Parameters:
        - *args: x, y data arrays or y data with automatic x
        - color (color-spec): Line color with proplot color support
        - cycle (str/Cycle): Color cycle for multiple lines  
        - legend (bool): Add to legend automatically
        - legend_kw (dict): Legend formatting parameters
        - **kwargs: Additional matplotlib plot parameters
        
        Returns:
        list: Line2D objects
        """
    
    def scatter(self, *args, **kwargs):
        """
        Enhanced scatter plots with additional options.
        
        Parameters:
        - x, y: Data point coordinates
        - s (scalar/array): Marker size(s)
        - c (color-spec/array): Marker color(s) with proplot support
        - colorbar (bool): Create colorbar automatically
        - colorbar_kw (dict): Colorbar formatting parameters
        - **kwargs: Additional matplotlib scatter parameters
        
        Returns:
        matplotlib.collections.PathCollection: Scatter plot collection
        """
    
    def bar(self, *args, **kwargs):
        """
        Enhanced bar charts with styling improvements.
        
        Parameters:
        - x: Bar positions or categories
        - height: Bar heights
        - color (color-spec): Bar colors with proplot support
        - cycle (str/Cycle): Color cycle for multiple series
        - **kwargs: Additional matplotlib bar parameters
        
        Returns:
        matplotlib.container.BarContainer: Bar chart container
        """
    
    def contour(self, *args, **kwargs):
        """
        Enhanced contour plots with improved integration.
        
        Parameters:
        - X, Y, Z: 2D coordinate and data arrays
        - levels (int/array): Contour levels
        - cmap (colormap-spec): Colormap with proplot support
        - colorbar (bool): Create colorbar automatically
        - **kwargs: Additional matplotlib contour parameters
        
        Returns:
        matplotlib.contour.QuadContourSet: Contour set object
        """
    
    def contourf(self, *args, **kwargs):
        """
        Enhanced filled contour plots.
        
        Parameters:
        - X, Y, Z: 2D coordinate and data arrays
        - levels (int/array): Contour levels
        - cmap (colormap-spec): Colormap with proplot support
        - colorbar (bool): Create colorbar automatically
        - extend (str): Colorbar extension ('neither', 'both', 'min', 'max')
        - **kwargs: Additional matplotlib contourf parameters
        
        Returns:
        matplotlib.contour.QuadContourSet: Filled contour set object
        """
    
    def pcolormesh(self, *args, **kwargs):
        """
        Enhanced pseudocolor mesh plots.
        
        Parameters:
        - X, Y, C: Coordinate and color arrays
        - cmap (colormap-spec): Colormap with proplot support
        - colorbar (bool): Create colorbar automatically
        - **kwargs: Additional matplotlib pcolormesh parameters
        
        Returns:
        matplotlib.collections.QuadMesh: Mesh collection object
        """
    
    def imshow(self, *args, **kwargs):
        """
        Enhanced image display with proplot integration.
        
        Parameters:
        - X: Image data array
        - cmap (colormap-spec): Colormap with proplot support
        - colorbar (bool): Create colorbar automatically
        - aspect (str/float): Image aspect ratio
        - **kwargs: Additional matplotlib imshow parameters
        
        Returns:
        matplotlib.image.AxesImage: Image object
        """

class CartesianAxes:
    """
    Enhanced Cartesian coordinate axes with scientific formatting.
    
    Provides comprehensive control over:
    - X and Y axis limits, scales, and transformations
    - Tick mark positioning and formatting
    - Spine positioning and styling
    - Grid customization and control
    - Dual and twin axis creation
    """
    
    def format(self, *,
               # Aspect and labels
               aspect=None, xlabel=None, ylabel=None,
               xlabel_kw=None, ylabel_kw=None,
               
               # Limits and scales
               xlim=None, ylim=None, xmin=None, ymin=None, xmax=None, ymax=None,
               xreverse=None, yreverse=None, xscale=None, yscale=None,
               xscale_kw=None, yscale_kw=None,
               xmargin=None, ymargin=None, xbounds=None, ybounds=None,
               
               # Spine and tick locations
               xloc=None, yloc=None, xspineloc=None, yspineloc=None,
               xtickloc=None, ytickloc=None, xticklabelloc=None, yticklabelloc=None,
               xlabelloc=None, ylabelloc=None, xoffsetloc=None, yoffsetloc=None,
               
               # Tick properties
               xtickdir=None, ytickdir=None, xrotation=None, yrotation=None,
               xticks=None, yticks=None, xlocator=None, ylocator=None,
               xminorticks=None, yminorticks=None, xminorlocator=None, yminorlocator=None,
               xlocator_kw=None, ylocator_kw=None,
               xminorlocator_kw=None, yminorlocator_kw=None,
               
               # Tick labels and formatters
               xticklabels=None, yticklabels=None,
               xformatter=None, yformatter=None,
               xformatter_kw=None, yformatter_kw=None,
               xtickrange=None, ytickrange=None,
               xwraprange=None, ywraprange=None,
               
               # Colors and styling
               xcolor=None, ycolor=None, color=None,
               xlinewidth=None, ylinewidth=None, linewidth=None,
               xtickcolor=None, ytickcolor=None, tickcolor=None,
               xticklabelcolor=None, yticklabelcolor=None, ticklabelcolor=None,
               xlabelcolor=None, ylabelcolor=None, labelcolor=None,
               
               # Grid properties
               xgrid=None, ygrid=None, grid=None,
               xgridminor=None, ygridminor=None, gridminor=None,
               xgridcolor=None, ygridcolor=None, gridcolor=None,
               
               **kwargs):
        """
        Format Cartesian axes with comprehensive control options.
        
        Parameters:
        - aspect (float/str): Axes aspect ratio ('equal', 'auto', numeric)
        - xlabel/ylabel (str): Axis labels
        - xlim/ylim (tuple): Axis limits as (min, max)
        - xscale/yscale (str): Axis scales ('linear', 'log', 'symlog', etc.)
        - xspineloc/yspineloc (str): Spine locations ('bottom', 'top', 'zero', etc.)
        - xticks/yticks (array): Explicit tick positions
        - xlocator/ylocator (Locator): Tick locator instances
        - xformatter/yformatter (Formatter): Tick formatter instances
        - xcolor/ycolor/color (color-spec): Axis colors
        - xgrid/ygrid/grid (bool): Grid visibility
        - **kwargs: Additional formatting parameters
        """
    
    def altx(self, **kwargs):
        """
        Create alternate x-axis with independent scale.
        
        Parameters:
        - **kwargs: Formatting parameters for alternate axis
        
        Returns:
        CartesianAxes: Alternate x-axis sharing y-axis
        """
    
    def alty(self, **kwargs):
        """
        Create alternate y-axis with independent scale.
        
        Parameters:
        - **kwargs: Formatting parameters for alternate axis
        
        Returns:
        CartesianAxes: Alternate y-axis sharing x-axis
        """
    
    def twinx(self, **kwargs):
        """
        Create twin x-axis (alias for alty).
        
        Returns:
        CartesianAxes: Twin x-axis instance
        """
    
    def twiny(self, **kwargs):
        """
        Create twin y-axis (alias for altx).
        
        Returns:
        CartesianAxes: Twin y-axis instance
        """
    
    def dualx(self, funcscale, **kwargs):
        """
        Create dual x-axis with unit conversion.
        
        Parameters:
        - funcscale (FuncScale/function): Scale transformation function
        - **kwargs: Additional formatting parameters
        
        Returns:
        CartesianAxes: Dual x-axis with unit conversion
        """
    
    def dualy(self, funcscale, **kwargs):
        """
        Create dual y-axis with unit conversion.
        
        Parameters:
        - funcscale (FuncScale/function): Scale transformation function
        - **kwargs: Additional formatting parameters
        
        Returns:
        CartesianAxes: Dual y-axis with unit conversion
        """

class PolarAxes:
    """
    Polar coordinate axes with improved angular formatting.
    
    Enhanced polar plotting with:
    - Configurable theta direction and origin
    - Flexible radial scaling and limits
    - Enhanced grid control for both angular and radial components
    - Improved label positioning and formatting
    """
    
    def format(self, *,
               # Polar coordinate system
               r0=None, theta0=None, thetadir=None,
               thetamin=None, thetamax=None, thetalim=None,
               rmin=None, rmax=None, rlim=None,
               
               # Grid properties
               thetagrid=None, rgrid=None,
               thetagridminor=None, rgridminor=None,
               thetagridcolor=None, rgridcolor=None,
               
               # Locators and formatters
               thetalocator=None, rlocator=None,
               thetalines=None, rlines=None,
               thetalocator_kw=None, rlocator_kw=None,
               thetaminorlocator=None, rminorlocator=None,
               thetaminorlines=None, rminorlines=None,
               thetaminorlocator_kw=None, rminorlocator_kw=None,
               
               # Label formatting
               thetaformatter=None, rformatter=None,
               thetalabels=None, rlabels=None,
               thetaformatter_kw=None, rformatter_kw=None,
               
               # Styling
               rlabelpos=None, rscale=None, rborder=None,
               labelpad=None, labelsize=None, labelcolor=None, labelweight=None,
               **kwargs):
        """
        Format polar axes with comprehensive control.
        
        Parameters:
        - r0 (float): Radial origin offset
        - theta0 (str/float): Angular origin ('N', 'E', 'S', 'W', or degrees)
        - thetadir (int): Angular direction (1 for counterclockwise, -1 for clockwise)
        - thetalim (tuple): Angular limits in degrees
        - rlim (tuple): Radial limits
        - thetagrid/rgrid (bool): Grid visibility for angular/radial components
        - thetalocator (Locator): Angular tick locator
        - rlocator (Locator): Radial tick locator
        - thetaformatter (Formatter): Angular label formatter
        - rformatter (Formatter): Radial label formatter
        - rlabelpos (float): Radial label position (angle in degrees)
        - rscale (str): Radial axis scale ('linear', 'log', etc.)
        - **kwargs: Additional formatting parameters
        """

class GeoAxes:
    """
    Geographic projection axes with cartopy integration.
    
    Enhanced geographic plotting with:
    - Automatic coordinate system transformations
    - Comprehensive map feature integration
    - Flexible longitude/latitude grid control
    - Support for all cartopy and custom projections
    """
    
    def format(self, *,
               # Map extent
               lonlim=None, latlim=None, boundinglat=None,
               
               # Grid lines
               longrid=None, latgrid=None,
               longridminor=None, latgridminor=None,
               
               # Locators
               lonlocator=None, lonlines=None,
               latlocator=None, latlines=None, latmax=None,
               lonminorlocator=None, lonminorlines=None,
               latminorlocator=None, latminorlines=None,
               lonlocator_kw=None, lonlines_kw=None,
               latlocator_kw=None, latlines_kw=None,
               lonminorlocator_kw=None, lonminorlines_kw=None,
               latminorlocator_kw=None, latminorlines_kw=None,
               
               # Formatters and labels
               lonformatter=None, latformatter=None,
               lonformatter_kw=None, latformatter_kw=None,
               labels=None, latlabels=None, lonlabels=None,
               loninline=None, latinline=None, inlinelabels=None,
               rotatelabels=None, labelpad=None, labelcolor=None,
               labelsize=None, labelweight=None,
               
               # Advanced options
               dms=None, nsteps=None,
               **kwargs):
        """
        Format geographic axes with map-specific controls.
        
        Parameters:
        - lonlim (tuple): Longitude limits in degrees
        - latlim (tuple): Latitude limits in degrees
        - boundinglat (float): Bounding latitude for polar projections
        - longrid/latgrid (bool): Grid line visibility
        - lonlocator/latlocator (Locator): Coordinate grid locators
        - lonformatter/latformatter (Formatter): Coordinate label formatters
        - labels (bool): Enable coordinate labels
        - loninline/latinline (bool): Inline coordinate labels
        - rotatelabels (bool): Rotate labels to follow grid lines
        - dms (bool): Use degrees-minutes-seconds formatting
        - **kwargs: Additional formatting parameters
        """
    
    # Geographic feature methods (configured via rc settings)
    # Access via: ax.format(land=True, ocean=True, coast=True, etc.)
    # Available features: land, ocean, coast, rivers, lakes, borders, innerborders

class ThreeAxes:
    """
    3D axes with matplotlib's Axes3D integration.
    
    Provides 3D plotting capabilities while maintaining
    proplot's consistent formatting interface and
    enhanced styling options.
    """
    
    def format(self, **kwargs):
        """
        Format 3D axes with extended control options.
        
        Parameters include all standard axes formatting
        plus 3D-specific options for viewing angles,
        axis limits, and 3D styling.
        """

SPINE_LOCATIONS = {
    'left': "Left side of axes",
    'right': "Right side of axes", 
    'bottom': "Bottom of axes",
    'top': "Top of axes",
    'both': "Both relevant sides",
    'neither': "Hide spines",
    'zero': "At coordinate zero",
    'center': "At axes center"
}

SUPPORTED_SCALES = {
    'linear': "Linear scaling",
    'log': "Logarithmic scaling", 
    'symlog': "Symmetric logarithmic scaling",
    'logit': "Logit scaling",
    'power': "Power law scaling",
    'inverse': "Inverse scaling",
    'exp': "Exponential scaling",
    'cutoff': "Cutoff scaling with arbitrary points",
    'sine': "Sine latitude scaling",
    'mercator': "Mercator latitude scaling",
    'func': "Custom function scaling"
}

PROJECTION_TYPES = {
    # Cartesian
    'cart': "Standard Cartesian coordinates",
    'cartesian': "Standard Cartesian coordinates",
    'rect': "Rectangular coordinates (alias)",
    'rectilinear': "Rectilinear coordinates (alias)",
    
    # Polar
    'polar': "Polar coordinates (r, theta)",
    
    # Geographic (Cartopy)
    'platecarree': "Plate Carrée projection",
    'mercator': "Mercator projection", 
    'lambert': "Lambert Conformal Conic",
    'stereographic': "Stereographic projection",
    'orthographic': "Orthographic projection",
    'mollweide': "Mollweide projection",
    'robinson': "Robinson projection",
    'eckert4': "Eckert IV projection",
    'hammer': "Hammer projection",
    'aitoff': "Aitoff projection",
    'winkel3': "Winkel Tripel projection",
    # ... and many more cartopy projections
    
    # 3D
    '3d': "3D plotting with matplotlib's Axes3D",
    'three': "3D plotting (alias)"
}

import proplot as pplt
import numpy as np

# Create sample data
x = np.linspace(0, 10, 100)
y = np.sin(x)

# Basic formatting
fig, ax = pplt.subplots()
ax.plot(x, y)
ax.format(
    xlabel='Time (seconds)',
    ylabel='Amplitude',
    title='Sine Wave',
    grid=True,
    xlim=(0, 10),
    ylim=(-1.2, 1.2)
)

# Dual axes with unit conversion
fig, ax = pplt.subplots()
ax.plot(temp_celsius, pressure)

# Add Fahrenheit scale
ax2 = ax.dualx(lambda c: c * 9/5 + 32)
ax.format(
    xlabel='Temperature (°C)', 
    ylabel='Pressure (hPa)',
    grid=True
)
ax2.format(xlabel='Temperature (°F)')

# Twin axes for multiple datasets
ax3 = ax.twinx()
ax3.plot(temp_celsius, humidity, color='red')
ax3.format(ylabel='Humidity (%)', ycolor='red')

# Enhanced polar plotting
fig, ax = pplt.subplots(proj='polar')
theta = np.linspace(0, 2*np.pi, 100)
r = 1 + 0.3 * np.cos(5*theta)

ax.plot(theta, r)
ax.format(
    theta0='N',           # North at top
    thetadir=1,          # Counterclockwise
    rlim=(0, 2),         # Radial limits
    thetagrid=True,      # Angular grid
    rgrid=True,          # Radial grid
    title='Polar Rose'
)

# Geographic plotting with features
fig, ax = pplt.subplots(proj='robinson')
ax.contourf(lon, lat, temperature, cmap='RdBu_r')
ax.format(
    # Map features
    land=True, ocean=True, coast=True,
    
    # Grid and labels
    longrid=True, latgrid=True,
    lonlines=np.arange(-180, 181, 60),
    latlines=np.arange(-90, 91, 30),
    labels=True,
    
    title='Global Temperature'
)

# Automatic colorbar and legend
fig, ax = pplt.subplots()

# Contour plot with automatic colorbar
cs = ax.contourf(X, Y, Z, levels=10, cmap='viridis')
ax.colorbar(cs, loc='right', label='Values')

# Line plots with automatic legend
ax.plot(x, y1, label='Dataset 1')
ax.plot(x, y2, label='Dataset 2')
ax.legend(loc='upper left')

ax.format(
    xlabel='X coordinate', 
    ylabel='Y coordinate',
    title='Combined Plot'
)

# Complete visual customization
fig, axes = pplt.subplots(ncols=2)
for i, ax in enumerate(axes):
    ax.plot(x, data[i])
    ax.format(
        # Limits and scales
        xlim=(0, 100), xscale='linear',
        ylim=(0.1, 1000), yscale='log',
        
        # Tick customization
        xticks=[0, 25, 50, 75, 100],
        xticklabels=['Zero', 'Quarter', 'Half', 'Three-Quarter', 'Full'],
        yformatter='log',
        
        # Grid and spines
        grid=True, gridminor=True,
        xspineloc='bottom', yspineloc='left',
        
        # Colors and styling
        color='navy', gridcolor='gray',
        labelcolor='black', titlecolor='darkblue',
        
        # Labels
        xlabel='Progress (%)',
        ylabel='Response (units)',
        title=f'Experiment {i+1}'
    )