0
# Proplot
1

2
A succinct matplotlib wrapper for making beautiful, publication-quality graphics. Proplot provides enhanced functionality for creating scientific visualizations with less code and more intuitive syntax, including simplified subplot creation, automatic legend and colorbar placement, improved color and font handling, and seamless integration with cartopy and basemap for geographic plotting.
3

4
## Package Information
5

6
- **Package Name**: proplot
7
- **Language**: Python
8
- **Installation**: `pip install proplot` or `conda install -c conda-forge proplot`
9

10
## Core Imports
11

12
```python
13
import proplot as pplt
14
```
15

16
All public APIs are available at the top level:
17

18
```python
19
import proplot as pplt
20

21
# Main functions for figure creation
22
fig, axes = pplt.subplots()
23
fig = pplt.figure()
24

25
# Display and close functions
26
pplt.show()
27
pplt.close()
28

29
# Configuration
30
pplt.rc['font.size'] = 12
31

32
# Utilities and constructors
33
cmap = pplt.Colormap('viridis')
34
colors = pplt.get_colors('tab10', 5)
35
```
36

37
## Basic Usage
38

39
```python
40
import proplot as pplt
41
import numpy as np
42

43
# Create sample data
44
x = np.linspace(0, 2*np.pi, 100)
45
y = np.sin(x)
46

47
# Create a simple plot with proplot
48
fig, ax = pplt.subplots(figsize=(8, 6))
49
ax.plot(x, y, color='red', linewidth=2)
50
ax.format(xlabel='X values', ylabel='Y values', title='Sine Wave')
51
pplt.show()
52

53
# Create subplots with enhanced grid layout
54
fig, axes = pplt.subplots(ncols=2, nrows=2, figwidth=10)
55
for i, ax in enumerate(axes):
56
    ax.plot(x, np.sin(x + i*np.pi/4))
57
    ax.format(title=f'Plot {i+1}')
58
fig.format(suptitle='Multiple Subplots')
59
pplt.show()
60

61
# Geographic plotting with cartopy integration
62
fig, ax = pplt.subplots(proj='robin')
63
ax.coastlines()
64
ax.format(title='World Map - Robinson Projection')
65
pplt.show()
66
```
67

68
## Architecture
69

70
Proplot enhances matplotlib's architecture while maintaining full compatibility:
71

72
- **Figure**: Enhanced Figure class with automatic sizing and layout management
73
- **Axes**: Specialized axes classes (CartesianAxes, PolarAxes, GeoAxes, ThreeAxes) with extended formatting capabilities
74
- **GridSpec**: Improved subplot arrangement with automatic spacing and alignment
75
- **Configuration**: Centralized rc settings management for both matplotlib and proplot parameters
76
- **Constructors**: Flexible factory functions for creating colormaps, projections, scales, formatters, and locators
77
- **Color System**: Advanced color handling with perceptual color spaces and seamless colormap integration
78

79
## Capabilities
80

81
### Figure and Subplot Creation
82

83
Core functionality for creating figures and subplot arrangements with enhanced grid layouts, automatic sizing, and publication-ready formatting options.
84

85
```python { .api }
86
def figure(**kwargs):
87
    """
88
    Create a proplot figure with enhanced features.
89
    
90
    Parameters:
91
    - figwidth (unit-spec): Figure width in physical units
92
    - figheight (unit-spec): Figure height in physical units
93
    - figsize (tuple): Figure size as (width, height) tuple
94
    - journal (str): Preset journal size ('aaas1', 'agu1', 'nat1', etc.)
95
    - tight (bool): Enable tight layout algorithm
96
    - **kwargs: Additional figure parameters
97
    
98
    Returns:
99
    proplot.figure.Figure: Enhanced figure instance
100
    """
101

102
def subplots(*args, **kwargs):
103
    """
104
    Create figure with subplots using proplot's enhanced grid system.
105
    
106
    Parameters:
107
    - nrows (int): Number of subplot rows (default: 1)
108
    - ncols (int): Number of subplot columns (default: 1)
109
    - array (array-like): 2D array specifying subplot arrangement
110
    - proj (str): Map projection name for all subplots
111
    - sharex (int/bool/str): X-axis sharing level (0-4)
112
    - sharey (int/bool/str): Y-axis sharing level (0-4)
113
    - share (int/bool/str): Both axes sharing level
114
    - refwidth (unit-spec): Reference subplot width
115
    - refheight (unit-spec): Reference subplot height
116
    - **kwargs: Additional figure parameters
117
    
118
    Returns:
119
    tuple: (fig, axes) where fig is Figure and axes is SubplotGrid
120
    """
121

122
def show():
123
    """Display all open figures."""
124

125
def close(*args):
126
    """Close matplotlib figures."""
127

128
class Figure:
129
    """
130
    Main proplot figure class with automatic layout management.
131
    
132
    Enhanced matplotlib Figure with:
133
    - Physical unit support for sizing
134
    - Automatic layout management
135
    - Built-in colorbar and legend placement
136
    - Journal preset sizing
137
    """
138

139
class SubplotGrid:
140
    """
141
    Container for proplot subplot axes with array-like indexing.
142
    
143
    Provides iteration and bulk formatting capabilities.
144
    """
145
```
146

147
[Figure and Subplots](./figure-subplots.md)
148

149
### Axes and Plotting
150

151
Enhanced axes classes with extended formatting capabilities, seamless integration with multiple coordinate systems, and comprehensive plotting methods for scientific visualization.
152

153
```python { .api }
154
class CartesianAxes:
155
    """Enhanced Cartesian coordinate axes with scientific formatting."""
156

157
class PolarAxes:
158
    """Polar coordinate axes with improved angular formatting."""
159

160
class GeoAxes:
161
    """Geographic projection axes with cartopy integration."""
162

163
class PlotAxes:
164
    """Mixin class providing enhanced plotting methods."""
165
```
166

167
[Axes and Plotting](./axes-plotting.md)
168

169
### Configuration and Settings
170

171
Centralized configuration system for managing matplotlib and proplot settings, including fonts, colors, sizes, and default behaviors across plotting sessions.
172

173
```python { .api }
174
class Configurator:
175
    """Main configuration class for managing settings."""
176

177
rc: Configurator
178
"""Global configuration instance."""
179

180
rc_proplot: dict
181
"""Dictionary-like container of proplot settings."""
182

183
rc_matplotlib: dict
184
"""Dictionary-like container of matplotlib settings."""
185

186
def use_style(style):
187
    """Apply matplotlib styles."""
188

189
def config_inline_backend(fmt=None):
190
    """Set up ipython inline backend."""
191
```
192

193
[Configuration](./configuration.md)
194

195
### Colors and Colormaps
196

197
Advanced color handling system with perceptual color spaces, flexible colormap creation, enhanced color cycles, and seamless integration with matplotlib's color infrastructure.
198

199
```python { .api }
200
class DiscreteColormap:
201
    """Replacement for matplotlib's ListedColormap with enhanced features."""
202

203
class ContinuousColormap:
204
    """Replacement for matplotlib's LinearSegmentedColormap."""
205

206
class PerceptualColormap:
207
    """Colormap with linear transitions across hue, saturation, luminance."""
208

209
def Colormap(*args, **kwargs):
210
    """Construct colormap instances from various inputs."""
211

212
def Cycle(*args, **kwargs):
213
    """Construct color cycle instances."""
214

215
def Norm(*args, **kwargs):
216
    """Construct color normalization instances."""
217

218
def get_colors(*args, **kwargs):
219
    """Get colors from registered or on-the-fly color cycle."""
220
```
221

222
[Colors and Colormaps](./colors-colormaps.md)
223

224
### Scales and Transformations
225

226
Comprehensive axis scaling system including logarithmic, power, inverse, and custom scales with seamless integration into matplotlib's transformation pipeline.
227

228
```python { .api }
229
class CutoffScale:
230
    """Scale with arbitrary cutoff points."""
231

232
class ExpScale:
233
    """Exponential scale."""
234

235
class FuncScale:
236
    """Scale with arbitrary forward and inverse functions."""
237

238
class PowerScale:
239
    """Power scale."""
240

241
def Scale(*args, **kwargs):
242
    """Construct axis scale instances."""
243
```
244

245
[Scales](./scales.md)
246

247
### Tick Formatting and Localization
248

249
Advanced tick locator and formatter system with support for scientific notation, fractions, geographic coordinates, and custom number formatting patterns.
250

251
```python { .api }
252
class AutoFormatter:
253
    """Automatic number formatting with flexible precision."""
254

255
class SciFormatter:
256
    """Format numbers with scientific notation."""
257

258
class DegreeFormatter:
259
    """Format numbers as geographic coordinates."""
260

261
def Locator(*args, **kwargs):
262
    """Construct tick locator instances."""
263

264
def Formatter(*args, **kwargs):
265
    """Construct tick formatter instances."""
266
```
267

268
[Tick Control](./tick-control.md)
269

270
### Geographic Projections
271

272
Extended collection of cartographic projections beyond matplotlib and cartopy defaults, with specialized polar projections and support for custom coordinate reference systems.
273

274
```python { .api }
275
class Aitoff:
276
    """Aitoff projection."""
277

278
class Hammer:
279
    """Hammer projection."""
280

281
class WinkelTripel:
282
    """Winkel tripel (Winkel III) projection."""
283

284
def Proj(*args, **kwargs):
285
    """Construct projection instances."""
286
```
287

288
[Geographic Projections](./projections.md)
289

290
### Utility Functions
291

292
Collection of utility functions for color manipulation, unit conversion, array operations, and data processing tasks commonly needed in scientific visualization workflows.
293

294
```python { .api }
295
def arange(min_, *args):
296
    """Identical to numpy.arange but with inclusive endpoints."""
297

298
def edges(z, axis=-1):
299
    """Calculate edge values from center values along an axis."""
300

301
def units(value, **kwargs):
302
    """Convert between physical units."""
303

304
def set_hue(color, hue, space='hcl'):
305
    """Return color with different hue."""
306

307
def to_hex(color, **kwargs):
308
    """Translate color to HEX string."""
309
```
310

311
[Utilities](./utilities.md)
312

313
### Demonstrations and Exploration
314

315
Built-in functions for exploring and demonstrating proplot's capabilities, including colormap galleries, color space visualizations, and font collections.
316

317
```python { .api }
318
def show_cmaps(*args, **kwargs):
319
    """Display available colormaps."""
320

321
def show_colors(*args, **kwargs):
322
    """Display available colors."""
323

324
def show_cycles(*args, **kwargs):  
325
    """Display available color cycles."""
326

327
def show_fonts(*args, **kwargs):
328
    """Display available fonts."""
329
```
330

331
[Demonstrations](./demonstrations.md)
332

333
## Complete API Coverage
334

335
This Knowledge Tile documents all public APIs from proplot v0.9.7, including 89+ classes, 50+ functions, and extensive customization options. All functionality is accessible through the top-level `proplot` import, maintaining full backward compatibility with matplotlib while providing enhanced scientific visualization capabilities.