0
# Data Visualization
1

2
Advanced data visualization capabilities for displaying and styling geospatial data including GeoJSON rendering, choropleth maps, TopoJSON support, and integration with Vega/Vega-Lite for embedded analytical charts.
3

4
## Capabilities
5

6
### GeoJSON Rendering
7

8
Display and style GeoJSON data with interactive features and data-driven styling.
9

10
```python { .api }
11
class GeoJson:
12
    """
13
    Display GeoJSON data on the map with customizable styling.
14
    
15
    Parameters:
16
    - data: dict or str, GeoJSON data or URL to GeoJSON
17
    - style_function: callable, function to style features based on properties
18
    - highlight_function: callable, function for hover styling
19
    - name: str, layer name for layer control
20
    - overlay: bool, treat as overlay layer (default True)
21
    - control: bool, show in layer control (default True)
22
    - show: bool, show layer initially (default True)
23
    - smooth_factor: float, path smoothing factor (default 1.0)
24
    - tooltip: Tooltip, tooltip for features
25
    - popup: Popup, popup for features
26
    - marker: callable, function to create custom markers for point features
27
    - zoom_on_click: bool, zoom to feature on click (default True)
28
    - embed: bool, embed data in map HTML (default True)
29
    
30
    Returns:
31
    GeoJson instance
32
    """
33
    def __init__(
34
        self,
35
        data,
36
        style_function=None,
37
        highlight_function=None,
38
        name=None,
39
        overlay=True,
40
        control=True,
41
        show=True,
42
        smooth_factor=1.0,
43
        tooltip=None,
44
        popup=None,
45
        marker=None,
46
        zoom_on_click=True,
47
        embed=True,
48
        **kwargs
49
    ): ...
50

51
class TopoJson:
52
    """
53
    Display TopoJSON topological data with efficient rendering.
54
    
55
    Parameters:
56
    - data: dict or str, TopoJSON data or URL
57
    - object_path: str, path to geometry object in TopoJSON
58
    - style_function: callable, function to style features
59
    - name: str, layer name for layer control
60
    - overlay: bool, treat as overlay layer (default True)
61
    - control: bool, show in layer control (default True)
62
    - show: bool, show layer initially (default True)
63
    - smooth_factor: float, path smoothing factor (default 1.0)
64
    - tooltip: Tooltip, tooltip for features
65
    - popup: Popup, popup for features
66
    
67
    Returns:
68
    TopoJSON instance
69
    """
70
    def __init__(
71
        self,
72
        data,
73
        object_path,
74
        style_function=None,
75
        name=None,
76
        overlay=True,
77
        control=True,
78
        show=True,
79
        smooth_factor=1.0,
80
        tooltip=None,
81
        popup=None,
82
        **kwargs
83
    ): ...
84
```
85

86
### Choropleth Maps
87

88
Create thematic maps with data-driven coloring for statistical visualization.
89

90
```python { .api }
91
class Choropleth:
92
    """
93
    Create a choropleth (thematic) map with data-driven coloring.
94
    
95
    Parameters:
96
    - geo_data: dict or str, GeoJSON data or URL
97
    - data: DataFrame, data for choropleth coloring
98
    - columns: list, column names [key_column, value_column]
99
    - key_on: str, property path in GeoJSON to match with data
100
    - bins: int or list, number of bins or bin edges for color scale
101
    - fill_color: str, color scale name or list of colors
102
    - nan_fill_color: str, color for missing data (default 'black')
103
    - fill_opacity: float, fill opacity (default 0.7)
104
    - nan_fill_opacity: float, opacity for missing data (default 0.4)
105
    - line_color: str, border color (default 'black')
106
    - line_weight: float, border width (default 1)
107
    - line_opacity: float, border opacity (default 1)
108
    - name: str, layer name for layer control
109
    - legend_name: str, legend title
110
    - overlay: bool, treat as overlay layer (default True)
111
    - control: bool, show in layer control (default True)
112
    - show: bool, show layer initially (default True)
113
    - topojson: str, path to object in TopoJSON (if using TopoJSON)
114
    - smooth_factor: float, path smoothing factor (default 1.0)
115
    - highlight: bool, enable hover highlighting (default False)
116
    - reset: bool, reset style on mouse out (default False)
117
    - popup_keep_highlighted: bool, keep highlighting during popup (default False)
118
    - use_jenks: bool, use Jenks natural breaks (default False)
119
    
120
    Returns:
121
    Choropleth instance
122
    """
123
    def __init__(
124
        self,
125
        geo_data,
126
        data=None,
127
        columns=None,
128
        key_on=None,
129
        bins=6,
130
        fill_color='blue',
131
        nan_fill_color='black',
132
        fill_opacity=0.7,
133
        nan_fill_opacity=0.4,
134
        line_color='black',
135
        line_weight=1,
136
        line_opacity=1,
137
        name=None,
138
        legend_name='',
139
        overlay=True,
140
        control=True,
141
        show=True,
142
        topojson=None,
143
        smooth_factor=1.0,
144
        highlight=False,
145
        reset=False,
146
        popup_keep_highlighted=False,
147
        use_jenks=False,
148
        **kwargs
149
    ): ...
150
```
151

152
### Interactive Popups and Tooltips for Data
153

154
Specialized popup and tooltip components for displaying feature properties from GeoJSON data.
155

156
```python { .api }
157
class GeoJsonPopup:
158
    """
159
    Create popups specifically for GeoJSON features showing properties.
160
    
161
    Parameters:
162
    - fields: list, property names to display
163
    - aliases: list, display names for fields (same order as fields)
164
    - labels: bool, show field labels (default True)
165
    - style: str, CSS styles for popup
166
    - localize: bool, localize numbers and dates (default False)
167
    - sticky: bool, keep popup open on mouse out (default True)
168
    - max_width: int, maximum popup width (default 300)
169
    
170
    Returns:
171
    GeoJsonPopup instance
172
    """
173
    def __init__(
174
        self,
175
        fields=None,
176
        aliases=None,
177
        labels=True,
178
        style=None,
179
        localize=False,
180
        sticky=True,
181
        max_width=300,
182
        **kwargs
183
    ): ...
184

185
class GeoJsonTooltip:
186
    """
187
    Create tooltips for GeoJSON features displaying properties.
188
    
189
    Parameters:
190
    - fields: list, property names to display
191
    - aliases: list, display names for fields (same order as fields)  
192
    - labels: bool, show field labels (default True)
193
    - style: str, CSS styles for tooltip
194
    - localize: bool, localize numbers and dates (default False)
195
    - sticky: bool, follow mouse cursor (default True)
196
    - opacity: float, tooltip opacity (default 0.9)
197
    
198
    Returns:
199
    GeoJsonTooltip instance
200
    """
201
    def __init__(
202
        self,
203
        fields=None,
204
        aliases=None,
205
        labels=True,
206
        style=None,
207
        localize=False,
208
        sticky=True,
209
        opacity=0.9,
210
        **kwargs
211
    ): ...
212

213
class LatLngPopup:
214
    """
215
    Display latitude/longitude coordinates in a popup when clicking on the map.
216
    
217
    Parameters:
218
    - None (automatically shows coordinates of clicked location)
219
    
220
    Returns:
221
    LatLngPopup instance
222
    """
223
    def __init__(self): ...
224
```
225

226
### Vega/Vega-Lite Integration
227

228
Embed analytical visualizations using Vega and Vega-Lite grammar within map popups or overlays.
229

230
```python { .api }
231
class Vega:
232
    """
233
    Embed Vega visualizations in map popups or overlays.
234
    
235
    Parameters:
236
    - json: dict, Vega specification as dictionary
237
    - width: int, visualization width
238
    - height: int, visualization height
239
    - left: str, left position (default '0%')
240
    - top: str, top position (default '0%')
241
    - position: str, CSS positioning (default 'relative')
242
    
243
    Returns:
244
    Vega instance
245
    """
246
    def __init__(
247
        self,
248
        json,
249
        width=None,
250
        height=None,
251
        left='0%',
252
        top='0%',
253
        position='relative'
254
    ): ...
255

256
class VegaLite:
257
    """
258
    Embed Vega-Lite visualizations in map popups or overlays.
259
    
260
    Parameters:
261
    - json: dict, Vega-Lite specification as dictionary
262
    - width: int, visualization width
263
    - height: int, visualization height  
264
    - left: str, left position (default '0%')
265
    - top: str, top position (default '0%')
266
    - position: str, CSS positioning (default 'relative')
267
    
268
    Returns:
269
    VegaLite instance
270
    """
271
    def __init__(
272
        self,
273
        json,
274
        width=None,
275
        height=None,
276
        left='0%',
277
        top='0%',
278
        position='relative'
279
    ): ...
280
```
281

282
### Specialized Markers
283

284
Enhanced marker types for data visualization and directional display.
285

286
```python { .api }
287
class RegularPolygonMarker:
288
    """
289
    Create geometric shape markers (triangles, squares, stars, etc.).
290
    
291
    Parameters:
292
    - location: tuple, marker coordinates [lat, lon]
293
    - popup: str or Popup, popup content
294
    - tooltip: str or Tooltip, tooltip content
295
    - radius: int, marker radius in pixels (default 15)
296
    - number_of_sides: int, number of polygon sides (default 4 for square)
297
    - rotation: int, rotation angle in degrees (default 0)
298
    - fill_color: str, fill color (default 'blue')
299
    - fill_opacity: float, fill opacity (default 0.6)
300
    - color: str, border color (default 'black')
301
    - weight: int, border width (default 2)
302
    - opacity: float, border opacity (default 1.0)
303
    
304
    Returns:
305
    RegularPolygonMarker instance
306
    """
307
    def __init__(
308
        self,
309
        location,
310
        popup=None,
311
        tooltip=None,
312
        radius=15,
313
        number_of_sides=4,
314
        rotation=0,
315
        fill_color='blue',
316
        fill_opacity=0.6,
317
        color='black',
318
        weight=2,
319
        opacity=1.0,
320
        **kwargs
321
    ): ...
322
```
323

324
### Dynamic Styling
325

326
Advanced styling capabilities for data-driven visualization.
327

328
```python { .api }
329
class ColorLine:
330
    """
331
    Create lines with color gradients based on data values.
332
    
333
    Parameters:
334
    - positions: list, line coordinates with optional data values
335
    - colors: list, colors corresponding to positions
336
    - nb_steps: int, number of interpolation steps (default 100)
337
    - weight: int, line width (default 5)
338
    - opacity: float, line opacity (default 1.0)
339
    - popup: str or Popup, popup content
340
    - tooltip: str or Tooltip, tooltip content
341
    
342
    Returns:
343
    ColorLine instance
344
    """
345
    def __init__(
346
        self,
347
        positions,
348
        colors=None,
349
        nb_steps=100,
350
        weight=5,
351
        opacity=1.0,
352
        popup=None,
353
        tooltip=None,
354
        **kwargs
355
    ): ...
356
```
357

358
## Usage Examples
359

360
### Basic GeoJSON with Styling
361

362
```python
363
import folium
364
import json
365

366
# Load GeoJSON data
367
with open('counties.geojson', 'r') as f:
368
    counties_data = json.load(f)
369

370
# Create map
371
m = folium.Map(location=[39.8283, -98.5795], zoom_start=5)
372

373
# Style function based on properties
374
def style_function(feature):
375
    return {
376
        'fillColor': '#ffff00',
377
        'color': 'black',
378
        'weight': 2,
379
        'fillOpacity': 0.7,
380
    }
381

382
# Highlight function for hover effect
383
def highlight_function(feature):
384
    return {
385
        'fillColor': '#ff0000',
386
        'color': 'black', 
387
        'weight': 3,
388
        'fillOpacity': 0.9,
389
    }
390

391
# Add GeoJSON with styling
392
folium.GeoJson(
393
    counties_data,
394
    style_function=style_function,
395
    highlight_function=highlight_function,
396
    popup=folium.GeoJsonPopup(fields=['NAME', 'POPULATION']),
397
    tooltip=folium.GeoJsonTooltip(fields=['NAME'])
398
).add_to(m)
399

400
m.save('styled_geojson.html')
401
```
402

403
### Choropleth Map with Pandas Data
404

405
```python
406
import folium
407
import pandas as pd
408
import json
409

410
# Load data
411
df = pd.read_csv('unemployment_data.csv')
412
with open('us_states.geojson', 'r') as f:
413
    state_geo = json.load(f)
414

415
# Create map
416
m = folium.Map(location=[48, -102], zoom_start=3)
417

418
# Create choropleth
419
folium.Choropleth(
420
    geo_data=state_geo,
421
    name='Unemployment Rate',
422
    data=df,
423
    columns=['State', 'Unemployment'],
424
    key_on='feature.properties.NAME',
425
    fill_color='YlOrRd',
426
    fill_opacity=0.7,
427
    line_opacity=0.2,
428
    legend_name='Unemployment Rate (%)',
429
    bins=5,
430
    highlight=True
431
).add_to(m)
432

433
folium.LayerControl().add_to(m)
434
m.save('choropleth.html')
435
```
436

437
### Vega-Lite Chart in Popup
438

439
```python
440
import folium
441

442
# Vega-Lite chart specification
443
chart_spec = {
444
    "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
445
    "data": {"values": [
446
        {"a": "A", "b": 28}, {"a": "B", "b": 55},
447
        {"a": "C", "b": 43}, {"a": "D", "b": 91}
448
    ]},
449
    "mark": "bar",
450
    "encoding": {
451
        "x": {"field": "a", "type": "nominal"},
452
        "y": {"field": "b", "type": "quantitative"}
453
    }
454
}
455

456
# Create map
457
m = folium.Map(location=[45.52, -122.67], zoom_start=11)
458

459
# Create Vega-Lite visualization
460
chart = folium.VegaLite(chart_spec, width=300, height=200)
461

462
# Add marker with chart in popup
463
folium.Marker(
464
    [45.52, -122.67],
465
    popup=folium.Popup().add_child(chart)
466
).add_to(m)
467

468
m.save('vega_popup.html')
469
```
470

471
### Dynamic Color Lines
472

473
```python
474
import folium
475
import numpy as np
476

477
# Generate path data with values
478
path_coords = [[45.5, -122.7], [45.51, -122.69], [45.52, -122.68]]
479
path_values = [10, 25, 40]  # Data values for coloring
480

481
# Create color gradient from values
482
colors = ['blue', 'yellow', 'red']
483

484
m = folium.Map(location=[45.51, -122.69], zoom_start=13)
485

486
# Add color line
487
folium.ColorLine(
488
    positions=list(zip(path_coords, path_values)),
489
    colors=colors,
490
    weight=8,
491
    opacity=0.8,
492
    tooltip='Dynamic colored path'
493
).add_to(m)
494

495
m.save('color_line.html')
496
```