0
# Utility Functions
1

2
Collection of utility functions for color manipulation, unit conversion, array operations, and data processing tasks commonly needed in scientific visualization workflows. Proplot provides numerous helper functions to simplify common plotting tasks.
3

4
## Capabilities
5

6
### Array and Data Utilities
7

8
```python { .api }
9
def arange(min_, *args):
10
    """
11
    Identical to numpy.arange but with inclusive endpoints.
12
    
13
    Parameters:
14
    - min_ (float): Start value
15
    - *args: Stop value and optional step
16
    
17
    Returns:
18
    ndarray: Array with inclusive endpoints
19
    """
20

21
def edges(z, axis=-1):
22
    """
23
    Calculate edge values from center values along an axis.
24
    
25
    Parameters:
26
    - z (array): Center values
27
    - axis (int): Axis along which to calculate edges
28
    
29
    Returns:
30
    ndarray: Edge values for pcolormesh/contour plotting
31
    """
32

33
def edges2d(z):
34
    """
35
    Calculate edge values from 2D center values.
36
    
37
    Parameters:
38
    - z (array): 2D center values
39
    
40
    Returns:
41
    ndarray: 2D edge values
42
    """
43
```
44

45
### Unit Conversion
46

47
```python { .api }
48
def units(value, numeric=None, dest=None, *, fontsize=None, figure=None, axes=None, width=None):
49
    """
50
    Convert between physical units for plotting dimensions.
51
    
52
    Parameters:
53
    - value (unit-spec): Value with unit specification
54
    - numeric (bool): Return numeric value only
55
    - dest (str): Destination unit ('in', 'cm', 'mm', 'pt', 'em')
56
    - fontsize (float): Font size for em/ex units
57
    - figure (Figure): Figure for relative units
58
    - axes (Axes): Axes for relative units
59
    - width (bool): Use width vs height for relative calculations
60
    
61
    Returns:
62
    float: Converted value in specified units
63
    """
64
```
65

66
### Color Manipulation (see colors-colormaps.md for full list)
67

68
```python { .api }
69
def get_colors(*args, **kwargs):
70
    """Get colors from color cycles."""
71

72
def set_hue(color, hue, space='hcl'):
73
    """Set color hue in specified color space."""
74

75
def shift_hue(color, shift=0, space='hcl'):
76
    """Shift color hue by specified amount."""
77

78
def scale_luminance(color, scale=1, space='hcl'):
79
    """Scale color luminance by specified factor."""
80
```
81

82
## Usage Examples
83

84
```python
85
import proplot as pplt
86
import numpy as np
87

88
# Inclusive arange
89
levels = pplt.arange(0, 10, 1)  # Includes 10
90

91
# Edge calculation for pcolormesh
92
x_centers = np.linspace(0, 10, 11)
93
y_centers = np.linspace(0, 5, 6)
94
z = np.random.randn(6, 11)
95

96
x_edges = pplt.edges(x_centers)
97
y_edges = pplt.edges(y_centers)
98

99
fig, ax = pplt.subplots()
100
ax.pcolormesh(x_edges, y_edges, z)
101

102
# Unit conversion
103
width_inches = pplt.units('5cm', dest='in')
104
fontsize_points = pplt.units('12pt')
105

106
# Color manipulation
107
colors = pplt.get_colors('colorblind', 5)
108
lighter_red = pplt.scale_luminance('red', 1.2)
109
```