0
# Interactive Color Palette Widgets
1

2
Interactive Jupyter widgets for creating and customizing color palettes in real-time. These functions provide GUI controls for palette selection and customization, enabling experimentation and fine-tuning of color schemes within notebook environments.
3

4
**Requirements**: IPython 2+ and `ipywidgets` package. Must be used in Jupyter notebooks.
5

6
## Capabilities
7

8
### ColorBrewer Palette Selection
9

10
Interactive widget for selecting from predefined ColorBrewer palettes.
11

12
```python { .api }
13
def choose_colorbrewer_palette(data_type, as_cmap=False):
14
    """
15
    Select a palette from the ColorBrewer set using interactive controls.
16
    
17
    Parameters:
18
    - data_type: str, type of data visualization
19
      * "sequential" - ordered data from low to high  
20
      * "diverging" - data with meaningful midpoint
21
      * "qualitative" - categorical data without order
22
    - as_cmap: bool, return matplotlib colormap if True, list of colors if False
23
    
24
    Returns:
25
    List of colors or matplotlib colormap
26
    """
27
```
28

29
### Dark Sequential Palette Creation
30

31
Interactive widget for creating dark sequential palettes with custom color parameters.
32

33
```python { .api }
34
def choose_dark_palette(input="husl", as_cmap=False):
35
    """
36
    Launch interactive widget to create dark sequential palette.
37
    
38
    Dark palettes transition from dark colors to a specified bright color,
39
    suitable for data ranging from uninteresting low to interesting high values.
40
    
41
    Parameters:
42
    - input: str, color space for seed value
43
      * "husl" - perceptually uniform color space (default)
44
      * "hls" - hue, lightness, saturation
45
      * "rgb" - red, green, blue
46
    - as_cmap: bool, return matplotlib colormap if True, list of colors if False
47
    
48
    Returns:
49
    List of colors or matplotlib colormap
50
    """
51
```
52

53
### Light Sequential Palette Creation
54

55
Interactive widget for creating light sequential palettes with custom color parameters.
56

57
```python { .api }
58
def choose_light_palette(input="husl", as_cmap=False):
59
    """
60
    Launch interactive widget to create light sequential palette.
61
    
62
    Light palettes transition from light colors to a specified dark color,
63
    suitable for data ranging from uninteresting low to interesting high values.
64
    
65
    Parameters:
66
    - input: str, color space for seed value  
67
      * "husl" - perceptually uniform color space (default)
68
      * "hls" - hue, lightness, saturation
69
      * "rgb" - red, green, blue
70
    - as_cmap: bool, return matplotlib colormap if True, list of colors if False
71
    
72
    Returns:
73
    List of colors or matplotlib colormap
74
    """
75
```
76

77
### Diverging Palette Creation
78

79
Interactive widget for creating custom diverging palettes with adjustable endpoints and midpoint.
80

81
```python { .api }
82
def choose_diverging_palette(as_cmap=False):
83
    """
84
    Launch interactive widget to create diverging color palette.
85
    
86
    Diverging palettes have two distinct colors at the extremes with a neutral
87
    midpoint, ideal for data with meaningful center values (e.g., change scores).
88
    
89
    Parameters:
90
    - as_cmap: bool, return matplotlib colormap if True, list of colors if False
91
    
92
    Widget Controls:
93
    - h_neg: negative endpoint hue (0-359)
94
    - h_pos: positive endpoint hue (0-359) 
95
    - s: saturation level (0-99)
96
    - l: lightness level (0-99)
97
    - sep: color separation (1-50)
98
    - n: number of colors (2-16)
99
    - center: midpoint style ("light" or "dark")
100
    
101
    Returns:
102
    List of colors or matplotlib colormap
103
    """
104
```
105

106
### Cubehelix Palette Creation
107

108
Interactive widget for creating sequential cubehelix palettes with extensive parameter control.
109

110
```python { .api }
111
def choose_cubehelix_palette(as_cmap=False):
112
    """
113
    Launch interactive widget to create sequential cubehelix palette.
114
    
115
    Cubehelix palettes provide sequential color progression with more hue variance,
116
    helping distinguish wider ranges of values while maintaining perceptual ordering.
117
    
118
    Parameters:
119
    - as_cmap: bool, return matplotlib colormap if True, list of colors if False
120
    
121
    Widget Controls:
122
    - n_colors: number of colors (2-16)
123
    - start: starting hue position (0-3)
124
    - rot: hue rotation, positive=clockwise (-1 to 1)
125
    - gamma: nonlinearity factor (0-5)
126
    - hue: saturation intensity (0-1)
127
    - light: lightest color intensity (0-1)
128
    - dark: darkest color intensity (0-1)
129
    - reverse: reverse color order (boolean)
130
    
131
    Returns:
132
    List of colors or matplotlib colormap
133
    """
134
```
135

136
## Usage Examples
137

138
### ColorBrewer Sequential Palette
139

140
```python
141
import seaborn as sns
142

143
# Interactive sequential palette selection
144
pal = sns.choose_colorbrewer_palette("sequential")
145

146
# Use the selected palette
147
tips = sns.load_dataset("tips")
148
sns.scatterplot(data=tips, x="total_bill", y="tip", hue="size", palette=pal)
149
plt.show()
150
```
151

152
### Custom Dark Palette
153

154
```python
155
# Interactive dark palette creation
156
dark_pal = sns.choose_dark_palette()
157

158
# Apply to heatmap
159
flights = sns.load_dataset("flights")
160
flights_pivot = flights.pivot("month", "year", "passengers")
161
sns.heatmap(flights_pivot, cmap=dark_pal, cbar_kws={"shrink": 0.8})
162
plt.show()
163
```
164

165
### Diverging Palette for Change Data
166

167
```python
168
# Interactive diverging palette for change scores
169
div_pal = sns.choose_diverging_palette(as_cmap=True)
170

171
# Create sample change data
172
import numpy as np
173
np.random.seed(42)
174
change_data = np.random.randn(10, 10)
175

176
# Use diverging colormap
177
sns.heatmap(change_data, cmap=div_pal, center=0, 
178
           square=True, cbar_kws={"shrink": 0.8})
179
plt.title("Change Scores from Baseline")
180
plt.show()
181
```
182

183
### Cubehelix for Scientific Data
184

185
```python
186
# Interactive cubehelix palette
187
cube_pal = sns.choose_cubehelix_palette(as_cmap=True)
188

189
# Apply to scientific visualization
190
brain = sns.load_dataset("brain_networks")
191
sns.heatmap(brain.corr(), cmap=cube_pal, square=True)
192
plt.title("Brain Network Correlations")
193
plt.show()
194
```
195

196
### ColorBrewer Qualitative Palette
197

198
```python
199
# Interactive qualitative palette selection
200
qual_pal = sns.choose_colorbrewer_palette("qualitative")
201

202
# Use for categorical data
203
tips = sns.load_dataset("tips")
204
sns.boxplot(data=tips, x="day", y="total_bill", palette=qual_pal)
205
plt.show()
206
```
207

208
## Interactive Controls Description
209

210
### ColorBrewer Widget Controls
211
- **Palette Name**: Dropdown of available ColorBrewer palettes
212
- **Colors (n)**: Number of colors to include (2-18 for sequential/diverging, 2-16 for qualitative)
213
- **Desaturation**: Reduce color saturation (0-1 slider)
214
- **Variant**: Regular, reverse, or dark versions
215

216
### Dark/Light Palette Controls
217
- **Color Space Selection**: Choose between RGB, HLS, or HUSL color spaces
218
- **Color Components**: Sliders for R/G/B, H/L/S, or H/S/L values depending on color space
219
- **Number of Colors**: Adjust palette size (3-17 colors)
220

221
### Diverging Palette Controls
222
- **Negative Hue**: Hue for negative values (0-359 degrees)
223
- **Positive Hue**: Hue for positive values (0-359 degrees)  
224
- **Saturation/Lightness**: Overall color intensity and brightness
225
- **Separation**: Distance between endpoint colors
226
- **Center Style**: Light or dark midpoint
227

228
### Cubehelix Controls
229
- **Start Position**: Initial hue position in color space
230
- **Rotation**: Direction and amount of hue rotation
231
- **Gamma**: Nonlinear intensity scaling
232
- **Saturation**: Color vividness
233
- **Light/Dark Endpoints**: Brightness range limits
234
- **Reverse**: Flip color order
235

236
## Types
237

238
```python { .api }
239
# Color space options
240
ColorSpace = Literal["rgb", "hls", "husl"]
241

242
# Data type categories  
243
DataType = Literal["sequential", "diverging", "qualitative"]
244

245
# Center options for diverging palettes
246
CenterType = Literal["light", "dark"]
247

248
# Return types
249
ColorList = list[tuple[float, float, float]]  # List of RGB tuples
250
ColorMap = matplotlib.colors.Colormap  # Matplotlib colormap object
251
```