0
# Configuration and Settings
1

2
Centralized configuration system for managing matplotlib and proplot settings, including fonts, colors, sizes, and default behaviors across plotting sessions. Proplot provides a comprehensive configuration system that unifies control over both proplot-specific features and underlying matplotlib parameters through a single, intuitive interface.
3

4
## Capabilities
5

6
### Main Configuration Class
7

8
Central configuration management class that provides dictionary-like access to all plotting settings with intelligent parameter synchronization and validation.
9

10
```python { .api }
11
class Configurator:
12
    """
13
    Main configuration class for managing matplotlib and proplot settings.
14
    
15
    Features:
16
    - Dictionary-like and attribute-style parameter access
17
    - Automatic synchronization of related parameters
18
    - Context management for temporary settings
19
    - File loading and saving capabilities
20
    - Intelligent parameter validation and conversion
21
    """
22
    
23
    def __init__(self, local=True, user=True, default=True, **kwargs):
24
        """
25
        Initialize configurator with settings from multiple sources.
26
        
27
        Parameters:
28
        - local (bool): Load settings from local .proplotrc files
29
        - user (bool): Load settings from user home directory config
30
        - default (bool): Load built-in default proplot settings
31
        - **kwargs: Initial parameter settings
32
        """
33
    
34
    def __getitem__(self, key):
35
        """Get configuration parameter value."""
36
    
37
    def __setitem__(self, key, value):
38
        """Set configuration parameter value with validation."""
39
    
40
    def context(self, *args, mode=0, file=None, **kwargs):
41
        """
42
        Create temporary configuration context for settings changes.
43
        
44
        Parameters:
45
        - *args: Parameter dictionaries to temporarily apply
46
        - mode (int): Context behavior (0=all, 1=proplot-only, 2=changed-only)
47
        - file (str): Configuration file to temporarily load
48
        - **kwargs: Parameter settings to temporarily apply
49
        
50
        Returns:
51
        Context manager for temporary configuration changes
52
        
53
        Usage:
54
        with rc.context(fontsize=14, style='seaborn'):
55
            # Plot with temporary settings
56
            fig, ax = pplt.subplots()
57
        """
58
    
59
    def load(self, path):
60
        """
61
        Load configuration settings from file.
62
        
63
        Parameters:
64
        - path (str): Path to configuration file (.proplotrc format)
65
        """
66
    
67
    def save(self, path=None, user=True, comment=None, backup=True, description=False):
68
        """
69
        Save current configuration settings to file.
70
        
71
        Parameters:
72
        - path (str): Output file path (default: user config file)
73
        - user (bool): Save to user configuration directory
74
        - comment (str): Header comment for file
75
        - backup (bool): Create backup of existing file
76
        - description (bool): Include parameter descriptions in file
77
        """
78
    
79
    def update(self, *args, **kwargs):
80
        """
81
        Update multiple configuration parameters.
82
        
83
        Parameters:
84
        - *args: Parameter dictionaries to update
85
        - **kwargs: Individual parameter updates
86
        """
87
    
88
    def reset(self, local=True, user=True, default=True):
89
        """
90
        Reset configuration to initial state.
91
        
92
        Parameters:
93
        - local (bool): Reload local configuration files
94
        - user (bool): Reload user configuration file
95
        - default (bool): Reload default proplot settings
96
        """
97
    
98
    def category(self, cat, trimcat=True, context=False):
99
        """
100
        Get all settings in a category.
101
        
102
        Parameters:
103
        - cat (str): Category name ('font', 'grid', 'axes', etc.)
104
        - trimcat (bool): Remove category prefix from keys
105
        - context (bool): Include context-specific parameters
106
        
107
        Returns:
108
        dict: Settings dictionary for the category
109
        """
110
    
111
    def find(self, key, context=False):
112
        """
113
        Find configuration parameter by partial key match.
114
        
115
        Parameters:
116
        - key (str): Partial parameter name to search for
117
        - context (bool): Include context-specific parameters
118
        
119
        Returns:
120
        dict: Matching parameters and their values
121
        """
122
    
123
    def fill(self, props, context=False):
124
        """
125
        Fill dictionary with configuration values.
126
        
127
        Parameters:
128
        - props (dict): Dictionary to fill with configuration values
129
        - context (bool): Include context-specific parameters
130
        
131
        Returns:
132
        dict: Input dictionary updated with configuration values
133
        """
134
    
135
    @property
136
    def changed(self):
137
        """dict: Settings that differ from defaults."""
138
    
139
    @staticmethod
140
    def local_files():
141
        """list: Local configuration file paths in priority order."""
142
    
143
    @staticmethod
144
    def user_file():
145
        """str: User configuration file path."""
146
    
147
    @staticmethod
148
    def user_folder(subfolder=None):
149
        """str: User configuration directory path."""
150
```
151

152
### Global Configuration Objects
153

154
Primary configuration objects providing access to all plotting settings with seamless matplotlib integration.
155

156
```python { .api }
157
rc: Configurator
158
"""
159
Global configuration instance for all proplot and matplotlib settings.
160

161
Main interface for configuration management with support for:
162
- Dictionary access: rc['font.size'] = 12
163
- Attribute access: rc.fontsize = 12  
164
- Context management: with rc.context(fontsize=14): ...
165
- Category access: rc.category('font')
166
"""
167

168
rc_proplot: dict
169
"""
170
Dictionary-like container of proplot-specific settings.
171

172
Contains 183 proplot-specific parameters organized by category:
173
- Style and appearance settings
174
- Axes and layout configuration  
175
- Color and colormap defaults
176
- Geographic feature controls
177
- Grid and tick formatting
178
- Text and label styling
179
"""
180

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

185
Direct reference to matplotlib.rcParams with proplot enhancements:
186
- All matplotlib parameters accessible
187
- Synchronized with proplot settings where applicable
188
- Enhanced with proplot-specific validators
189
"""
190
```
191

192
### Registration Functions
193

194
Functions for registering custom visual assets including colormaps, color cycles, named colors, and fonts.
195

196
```python { .api }
197
def register_cmaps(*args, user=None, default=False):
198
    """
199
    Register named colormaps from files or objects.
200
    
201
    Parameters:
202
    - *args: Colormap specifications (files, arrays, Colormap objects)
203
    - user (bool): Save to user directory vs. proplot installation
204
    - default (bool): Use when rebuilding proplot colormaps
205
    
206
    Supported Formats:
207
    - .json: JSON colormap definition files
208
    - .hex: Hex color lists (one per line)
209
    - .rgb: RGB color lists (comma or space separated)
210
    - .txt: Generic text color files
211
    - Arrays: Color data arrays
212
    - Colormap objects: Matplotlib/proplot colormap instances
213
    
214
    Usage:
215
    register_cmaps('my_colormap.json')
216
    register_cmaps(colormap_array, name='custom')
217
    """
218

219
def register_cycles(*args, user=None, default=False):
220
    """
221
    Register named color cycles from files or objects.
222
    
223
    Parameters:
224
    - *args: Color cycle specifications (files, lists, Cycle objects)
225
    - user (bool): Save to user directory vs. proplot installation
226
    - default (bool): Use when rebuilding proplot cycles
227
    
228
    Supported Formats:
229
    - .hex: Hex color lists
230
    - .rgb: RGB color lists  
231
    - .txt: Generic color text files
232
    - Lists: Color name/specification lists
233
    - Cycle objects: Proplot Cycle instances
234
    
235
    Usage:
236
    register_cycles('my_colors.hex')
237
    register_cycles(['red', 'blue', 'green'], name='rgb')
238
    """
239

240
def register_colors(*args, user=None, default=False, space=None, margin=None, **kwargs):
241
    """
242
    Register named colors from files or dictionaries.
243
    
244
    Parameters:
245
    - *args: Color specifications (files, dictionaries)
246
    - user (bool): Save to user directory vs. proplot installation  
247
    - default (bool): Use when rebuilding proplot colors
248
    - space (str): Colorspace for perceptual filtering ('hcl', 'hsl', etc.)
249
    - margin (float): Minimum perceptual distance for color filtering
250
    - **kwargs: Direct color name-value pairs
251
    
252
    Supported Formats:
253
    - Files: Text files with 'name : hex' pairs
254
    - Dictionaries: {name: color_spec} mappings
255
    - Built-in databases: XKCD colors with filtering
256
    
257
    Usage:
258
    register_colors('my_colors.txt')
259
    register_colors({'myred': '#FF0000', 'myblue': '#0000FF'})
260
    register_colors(mygreen='#00FF00')
261
    """
262

263
def register_fonts(*args, user=True, default=False):
264
    """
265
    Register font files for use in plotting.
266
    
267
    Parameters:
268
    - *args: Font file paths (.ttf, .otf formats)
269
    - user (bool): Install to user directory vs. system
270
    - default (bool): Use when rebuilding proplot fonts
271
    
272
    Supported Formats:
273
    - .ttf: TrueType font files
274
    - .otf: OpenType font files
275
    - Automatic font family detection and registration
276
    - Font cache rebuilding for immediate availability
277
    
278
    Usage:
279
    register_fonts('my_font.ttf')
280
    register_fonts('/path/to/font/directory/*.ttf')
281
    """
282
```
283

284
### Style and Backend Configuration
285

286
Functions for applying visual styles and configuring display backends for different environments.
287

288
```python { .api }
289
def use_style(style):
290
    """
291
    Apply matplotlib styles with proplot parameter inference.
292
    
293
    Parameters:
294
    - style (str/sequence): Style name(s) to apply
295
    
296
    Supported Styles:
297
    - Built-in matplotlib styles: 'seaborn', 'ggplot', 'classic', etc.
298
    - Special proplot styles: 'default' (proplot defaults), 'original' (matplotlib defaults)
299
    - Style composition: Multiple styles applied in sequence
300
    - Automatic proplot parameter inference from matplotlib settings
301
    
302
    Usage:
303
    use_style('seaborn')
304
    use_style(['seaborn', 'whitegrid'])
305
    use_style('default')  # Reset to proplot defaults
306
    """
307

308
def config_inline_backend(fmt=None):
309
    """
310
    Configure IPython/Jupyter inline display backend.
311
    
312
    Parameters:
313
    - fmt (str): Output format for inline figures
314
    
315
    Supported Formats:
316
    - 'svg': Scalable vector graphics (default for high DPI)
317
    - 'pdf': Portable document format
318
    - 'png': Portable network graphics  
319
    - 'jpg'/'jpeg': JPEG compressed format
320
    - 'retina': High-resolution PNG for retina displays
321
    
322
    Features:
323
    - Automatic format detection from rc['inlinefmt']
324
    - Ensures consistency between inline and saved figures
325
    - Optimizes display quality for different environments
326
    
327
    Usage:
328
    config_inline_backend('svg')  # High quality vector output
329
    config_inline_backend('retina')  # High DPI displays
330
    """
331
```
332

333
## Configuration Categories
334

335
### Font and Text Settings
336

337
```python { .api }
338
FONT_SETTINGS = {
339
    'font.size': "Base font size for all text elements",
340
    'font.smallsize': "Small text (ticks, legends, etc.)",
341
    'font.largesize': "Large text (titles, abc labels, etc.)",
342
    'font.family': "Font family name or generic family",
343
    'font.name': "Specific font name (alias for font.family)",
344
    
345
    # Automatic size relationships
346
    'tick.labelsize': "Inherits from font.smallsize",
347
    'axes.labelsize': "Inherits from font.smallsize", 
348
    'legend.fontsize': "Inherits from font.smallsize",
349
    'title.size': "Inherits from font.largesize",
350
    'suptitle.size': "Inherits from font.largesize"
351
}
352
```
353

354
### Color and Visual Style
355

356
```python { .api }
357
COLOR_SETTINGS = {
358
    'meta.color': "Universal color affecting axes, ticks, labels",
359
    'cmap.sequential': "Default sequential colormap",
360
    'cmap.diverging': "Default diverging colormap", 
361
    'cmap.cyclic': "Default cyclic colormap",
362
    'cmap.qualitative': "Default qualitative colormap",
363
    'cycle': "Default color cycle for line plots",
364
    'negcolor': "Color for negative values",
365
    'poscolor': "Color for positive values"
366
}
367
```
368

369
### Layout and Spacing
370

371
```python { .api }
372
LAYOUT_SETTINGS = {
373
    'subplots.tight': "Enable tight layout by default",
374
    'subplots.pad': "Padding around subplot grid",
375
    'subplots.axpad': "Padding between individual subplots",
376
    'subplots.panelpad': "Padding around panels (colorbars, legends)",
377
    'axes.margin': "Default axes margin",
378
    'title.pad': "Title padding from axes",
379
    'title.above': "Place titles above rather than inside axes"
380
}
381
```
382

383
### Grid and Tick Control
384

385
```python { .api }
386
GRID_SETTINGS = {
387
    'grid': "Default grid visibility",
388
    'grid.alpha': "Grid line transparency",
389
    'grid.color': "Grid line color",
390
    'grid.linewidth': "Grid line width",
391
    'grid.linestyle': "Grid line style",
392
    'gridminor': "Minor grid visibility",
393
    'gridminor.alpha': "Minor grid transparency",
394
    'gridminor.color': "Minor grid color",
395
    'gridminor.linewidth': "Minor grid line width"
396
}
397
```
398

399
### Geographic Features
400

401
```python { .api }
402
GEOGRAPHIC_SETTINGS = {
403
    'land': "Land feature visibility and styling",
404
    'ocean': "Ocean feature visibility and styling", 
405
    'coast': "Coastline feature visibility and styling",
406
    'rivers': "River feature visibility and styling",
407
    'lakes': "Lake feature visibility and styling",
408
    'borders': "Border feature visibility and styling",
409
    'reso': "Geographic feature resolution ('110m', '50m', '10m')"
410
}
411
```
412

413
## Configuration Files
414

415
### File Format and Locations
416

417
```python { .api }
418
# Configuration file format (YAML-style)
419
CONFIG_FORMAT = """
420
# Proplot configuration file
421
# Comments are supported with #
422

423
# Font settings
424
font.size: 12
425
font.family: sans-serif
426

427
# Color settings  
428
cmap.sequential: viridis
429
cycle: colorblind
430

431
# Layout settings
432
subplots.tight: True
433
grid: True
434

435
# Style application
436
style: seaborn
437
"""
438

439
# File locations (in priority order)
440
CONFIG_LOCATIONS = [
441
    "./proplotrc",           # Current directory
442
    "./.proplotrc",          # Hidden file in current directory
443
    "../proplotrc",          # Parent directory
444
    "~/.proplotrc",          # User home directory
445
    "~/.proplot/proplotrc",  # User config directory
446
    # XDG config directory on Linux
447
]
448
```
449

450
### File Management
451

452
```python { .api }
453
# Save current configuration
454
rc.save('my_style.proplotrc', 
455
        comment='Custom plotting style',
456
        description=True)  # Include parameter descriptions
457

458
# Load configuration from file
459
rc.load('my_style.proplotrc')
460

461
# Reset to various states
462
rc.reset()                    # Reset to all defaults
463
rc.reset(user=False)         # Skip user config file
464
rc.reset(local=False)        # Skip local config files
465
```
466

467
## Usage Examples
468

469
### Basic Configuration
470

471
```python
472
import proplot as pplt
473

474
# View current settings
475
print(pplt.rc['font.size'])
476
print(pplt.rc.fontsize)  # Equivalent attribute access
477

478
# Modify settings
479
pplt.rc['font.size'] = 14
480
pplt.rc.update(fontsize=14, grid=True, style='seaborn')
481

482
# Category-based updates  
483
pplt.rc.update('font', size=12, family='serif')
484
```
485

486
### Context Management
487

488
```python
489
# Temporary configuration changes
490
with pplt.rc.context(fontsize=16, style='ggplot'):
491
    fig, ax = pplt.subplots()
492
    ax.plot([1, 2, 3], [1, 4, 9])
493
# Settings automatically restored after context
494

495
# Multiple parameter contexts
496
with pplt.rc.context({'font.size': 14, 'grid': True}, 
497
                     cmap='plasma'):
498
    # Create plots with temporary settings
499
    pass
500
```
501

502
### Style Application
503

504
```python
505
# Apply built-in styles
506
pplt.use_style('seaborn')
507
pplt.use_style(['seaborn', 'whitegrid'])
508

509
# Reset to defaults
510
pplt.use_style('default')      # Proplot defaults
511
pplt.use_style('original')     # Matplotlib defaults
512

513
# Custom style from file
514
pplt.rc.load('journal_style.proplotrc')
515
```
516

517
### Asset Registration
518

519
```python
520
# Register custom colormap
521
pplt.register_cmaps('scientific_colormap.json')
522
pplt.register_cmaps(custom_array, name='mymap')
523

524
# Register color cycle
525
pplt.register_cycles(['#FF0000', '#00FF00', '#0000FF'], 
526
                     name='rgb')
527

528
# Register named colors
529
pplt.register_colors({'corporate_blue': '#1f77b4',
530
                      'brand_red': '#d62728'})
531

532
# Register fonts
533
pplt.register_fonts('custom_font.ttf')
534
```
535

536
### Advanced Configuration
537

538
```python
539
# Comprehensive style setup
540
pplt.rc.update({
541
    # Font configuration
542
    'font.size': 11,
543
    'font.family': 'serif',
544
    
545
    # Color scheme
546
    'meta.color': 'black',
547
    'cmap.sequential': 'plasma',
548
    'cycle': 'colorblind',
549
    
550
    # Layout  
551
    'subplots.tight': True,
552
    'axes.margin': 0.05,
553
    'grid': True,
554
    'grid.alpha': 0.3,
555
    
556
    # Geographic features
557
    'land': True,
558
    'ocean': True,
559
    'coast': {'linewidth': 0.5, 'color': 'gray'},
560
    
561
    # Inline backend
562
    'inlinefmt': 'svg'
563
})
564

565
# Save custom configuration
566
pplt.rc.save('publication_style.proplotrc',
567
             comment='Settings for publication figures')
568
```
569

570
### Parameter Exploration
571

572
```python
573
# Find font-related settings
574
font_settings = pplt.rc.category('font')
575
print(font_settings)
576

577
# Search for grid parameters
578
grid_params = pplt.rc.find('grid')
579
print(grid_params)
580

581
# View changed settings
582
print(pplt.rc.changed)  # Only non-default values
583

584
# Get all colormap settings
585
cmap_settings = pplt.rc.category('cmap', trimcat=False)
586
```
587

588
This comprehensive configuration system provides fine-grained control over all aspects of plot appearance while maintaining simplicity for common use cases and powerful customization capabilities for advanced users.