0
# Styling and Properties
1

2
Comprehensive styling system for Vincent visualizations using PropertySet and ValueRef classes. Provides full control over visual appearance, animations, and interactions through Vega's property system.
3

4
## Capabilities
5

6
### Property Sets
7

8
PropertySet defines visual properties for marks and axes, supporting all Vega visual properties for comprehensive styling control.
9

10
```python { .api }
11
class PropertySet(GrammarClass):
12
    """Visual property definitions for marks and axes"""
13
    
14
    # Position Properties
15
    @property
16
    def x(self):
17
        """ValueRef: Left-most x-coordinate position"""
18
    
19
    @property
20
    def x2(self):
21
        """ValueRef: Right-most x-coordinate position"""
22
    
23
    @property
24
    def y(self):
25
        """ValueRef: Bottom-most y-coordinate position"""
26
    
27
    @property
28
    def y2(self):
29
        """ValueRef: Top-most y-coordinate position"""
30
    
31
    @property
32
    def width(self):
33
        """ValueRef: Width of the mark"""
34
    
35
    @property
36
    def height(self):
37
        """ValueRef: Height of the mark"""
38
    
39
    # Style Properties
40
    @property
41
    def fill(self):
42
        """ValueRef: Fill color specification"""
43
    
44
    @property
45
    def fillOpacity(self):
46
        """ValueRef: Fill opacity (0-1)"""
47
    
48
    @property
49
    def stroke(self):
50
        """ValueRef: Stroke/outline color specification"""
51
    
52
    @property
53
    def strokeOpacity(self):
54
        """ValueRef: Stroke opacity (0-1)"""
55
    
56
    @property
57
    def strokeWidth(self):
58
        """ValueRef: Stroke width in pixels"""
59
    
60
    @property
61
    def opacity(self):
62
        """ValueRef: Overall opacity (0-1)"""
63
    
64
    # Text Properties
65
    @property
66
    def text(self):
67
        """ValueRef: Text content for text marks"""
68
    
69
    @property
70
    def fontSize(self):
71
        """ValueRef: Font size in pixels"""
72
    
73
    @property
74
    def fontWeight(self):
75
        """ValueRef: Font weight ('normal', 'bold', numeric values)"""
76
    
77
    @property
78
    def fontStyle(self):
79
        """ValueRef: Font style ('normal', 'italic')"""
80
    
81
    @property
82
    def align(self):
83
        """ValueRef: Text alignment ('left', 'center', 'right')"""
84
    
85
    @property
86
    def baseline(self):
87
        """ValueRef: Text baseline ('top', 'middle', 'bottom', 'alphabetic')"""
88
    
89
    # Line Properties
90
    @property
91
    def interpolate(self):
92
        """ValueRef: Line interpolation method ('linear', 'step', 'basis', etc.)"""
93
    
94
    @property
95
    def tension(self):
96
        """ValueRef: Tension parameter for curve interpolation (0-1)"""
97
    
98
    # Symbol Properties
99
    @property
100
    def size(self):
101
        """ValueRef: Symbol size in square pixels"""
102
    
103
    @property
104
    def shape(self):
105
        """ValueRef: Symbol shape ('circle', 'square', 'triangle', etc.)"""
106
```
107

108
**Usage Example:**
109

110
```python
111
import vincent
112

113
# Create PropertySet for mark styling
114
props = vincent.PropertySet()
115
props.fill = vincent.ValueRef(value='steelblue')
116
props.stroke = vincent.ValueRef(value='darkblue')  
117
props.strokeWidth = vincent.ValueRef(value=2)
118
props.opacity = vincent.ValueRef(value=0.8)
119

120
# Position properties using scale references
121
props.x = vincent.ValueRef(scale='x', field='data.x')
122
props.y = vincent.ValueRef(scale='y', field='data.y')
123
props.width = vincent.ValueRef(scale='x', band=True)
124
```
125

126
### Value References
127

128
ValueRef provides flexible value specification system supporting constants, data field references, scale mappings, and computed values.
129

130
```python { .api }
131
class ValueRef(GrammarClass):
132
    """Container for value-referencing properties of marks"""
133
    
134
    @property
135
    def value(self):
136
        """
137
        Constant value specification
138
        
139
        Can be int, float, or string for constant values.
140
        Ignored if field property is defined.
141
        
142
        Returns:
143
        int, float, or str: Constant value
144
        """
145
    
146
    @property
147
    def field(self):
148
        """
149
        Data field reference in dot-notation
150
        
151
        References data field like 'data.x' where first element
152
        is always 'data' regardless of actual data name.
153
        
154
        Returns:
155
        str: Field reference in dot-notation
156
        """
157
    
158
    @property
159
    def group(self):
160
        """
161
        Group property reference
162
        
163
        References enclosing group's data properties.
164
        Special values 'width' and 'height' return group dimensions.
165
        
166
        Returns:
167
        str or bool: Group property reference
168
        """
169
    
170
    @property
171
    def scale(self):
172
        """
173
        Scale name reference
174
        
175
        Scale is applied to value and field attributes.
176
        
177
        Returns:
178
        str: Scale name
179
        """
180
    
181
    @property
182
    def mult(self):
183
        """
184
        Multiplier applied after scaling
185
        
186
        Returns:
187
        int or float: Multiplication factor
188
        """
189
    
190
    @property
191
    def offset(self):
192
        """
193
        Additive offset applied after scaling and multipliers
194
        
195
        Returns:
196
        int or float: Offset value
197
        """
198
    
199
    @property
200
    def band(self):
201
        """
202
        Use scale range band
203
        
204
        If True and scale is defined, uses the range band of
205
        the referenced ordinal scale.
206
        
207
        Returns:
208
        bool: Whether to use scale band
209
        """
210
```
211

212
**Usage Examples:**
213

214
```python
215
import vincent
216

217
# Constant value
218
constant_ref = vincent.ValueRef(value=100)
219

220
# Data field reference with scale
221
field_ref = vincent.ValueRef(field='data.value', scale='y')
222

223
# Computed value with offset and multiplier  
224
computed_ref = vincent.ValueRef(
225
    field='data.x', 
226
    scale='x', 
227
    mult=1.5, 
228
    offset=10
229
)
230

231
# Band scale reference
232
band_ref = vincent.ValueRef(scale='x', band=True)
233

234
# Group dimension reference
235
group_ref = vincent.ValueRef(group='width')
236
```
237

238
### Mark Properties
239

240
MarkProperties defines property sets for different mark interaction states, enabling animations and dynamic styling.
241

242
```python { .api }
243
class MarkProperties(GrammarClass):
244
    """Property sets for different mark states"""
245
    
246
    @property
247
    def enter(self):
248
        """
249
        Properties applied when data is loaded
250
        
251
        Returns:
252
        PropertySet: Entry state properties
253
        """
254
    
255
    @property
256
    def exit(self):
257
        """
258
        Properties applied when data is removed
259
        
260
        Returns:
261
        PropertySet: Exit state properties
262
        """
263
    
264
    @property
265
    def update(self):
266
        """
267
        Properties applied for all non-exiting data
268
        
269
        Returns:
270
        PropertySet: Update state properties
271
        """
272
    
273
    @property
274
    def hover(self):
275
        """
276
        Properties applied on mouse-over
277
        
278
        On mouse out, update properties are applied.
279
        
280
        Returns:
281
        PropertySet: Hover state properties
282
        """
283
```
284

285
**Usage Example:**
286

287
```python
288
import vincent
289

290
# Create mark properties with different states
291
mark_props = vincent.MarkProperties()
292

293
# Entry state - initial appearance
294
mark_props.enter = vincent.PropertySet()
295
mark_props.enter.fill = vincent.ValueRef(value='lightblue')
296
mark_props.enter.opacity = vincent.ValueRef(value=0)
297

298
# Update state - normal appearance
299
mark_props.update = vincent.PropertySet()
300
mark_props.update.fill = vincent.ValueRef(value='steelblue')
301
mark_props.update.opacity = vincent.ValueRef(value=1)
302

303
# Hover state - interactive appearance
304
mark_props.hover = vincent.PropertySet()
305
mark_props.hover.fill = vincent.ValueRef(value='orange')
306
mark_props.hover.opacity = vincent.ValueRef(value=0.8)
307
```
308

309
## Color System Integration
310

311
Vincent integrates with ColorBrewer palettes for consistent and effective color schemes:
312

313
```python { .api }
314
from vincent.colors import brews
315

316
# brews dictionary contains all ColorBrewer palettes:
317
# Sequential palettes: YlGn, YlGnBu, GnBu, BuGn, PuBuGn, PuBu, BuPu, 
318
#                     RdPu, PuRd, OrRd, YlOrRd, YlOrBr, Purples, Blues, 
319
#                     Greens, Oranges, Reds, Greys
320
# 
321
# Diverging palettes: Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, 
322
#                    BrBG, RdGy, PuOr
323
#
324
# Qualitative palettes: Set2, Accent, Set1, Set3, Dark2, Paired, 
325
#                       Pastel2, Pastel1
326
```
327

328
**Usage Example:**
329

330
```python
331
from vincent.colors import brews
332
import vincent
333

334
# Use a ColorBrewer palette for fill colors
335
colors = brews['Set1']  # Gets a qualitative color palette
336

337
# Create ValueRef with palette color
338
fill_ref = vincent.ValueRef(value=colors[0])  # First color in palette
339

340
# Or use in a scale domain
341
color_scale = vincent.Scale()
342
color_scale.name = 'color'
343
color_scale.type = 'ordinal'
344
color_scale.range = colors[:5]  # Use first 5 colors
345
```
346

347
## Property System Patterns
348

349
### Responsive Properties
350

351
Properties can respond to data values and user interactions:
352

353
```python
354
# Color encoding based on data values
355
color_ref = vincent.ValueRef(
356
    field='data.category',
357
    scale='color'  # Maps categories to colors
358
)
359

360
# Size encoding based on data magnitude
361
size_ref = vincent.ValueRef(
362
    field='data.value',
363
    scale='size',
364
    mult=2  # Scale up the size
365
)
366
```
367

368
### Animation Properties
369

370
Properties support smooth transitions between states:
371

372
```python
373
# Entry animation - fade in
374
enter_props = vincent.PropertySet()
375
enter_props.opacity = vincent.ValueRef(value=0)
376

377
# Update animation - full opacity
378
update_props = vincent.PropertySet()  
379
update_props.opacity = vincent.ValueRef(value=1)
380
```
381

382
### Conditional Properties
383

384
Properties can be conditionally applied based on data or interaction state through the hover, enter, exit, and update property sets, enabling rich interactive visualizations.