0
# Plotting Interface
1

2
The high-level plotting interface centered around the `figure()` function, providing the primary API for creating interactive visualizations in Bokeh. This interface includes 70+ glyph methods for different chart types, built-in interaction tools, and automatic styling and legend management.
3

4
## Capabilities
5

6
### Figure Creation
7

8
The main entry point for creating plots with customizable dimensions, tools, styling, and axis configuration.
9

10
```python { .api }
11
def figure(x_range=None, y_range=None, x_axis_type='auto', y_axis_type='auto',
12
           x_axis_location='below', y_axis_location='left', x_axis_label=None, y_axis_label=None,
13
           width=600, height=600, title=None, title_location='above',
14
           tools=None, toolbar_location='above', toolbar_sticky=True,
15
           left=None, right=None, above=None, below=None,
16
           min_border=5, min_border_left=None, min_border_right=None,
17
           min_border_top=None, min_border_bottom=None,
18
           lod_factor=10, lod_threshold=2000, lod_interval=300, lod_timeout=500,
19
           hidpi=True, output_backend='canvas', match_aspect=False, aspect_scale=1,
20
           sizing_mode='fixed', **kwargs):
21
    """
22
    Create a new Figure for plotting.
23
    
24
    Parameters:
25
    - x_range, y_range: Range objects or tuples for axis ranges
26
    - x_axis_type, y_axis_type: 'auto', 'linear', 'log', 'datetime', 'mercator'
27
    - width, height: Plot dimensions in pixels
28
    - title: Plot title string
29
    - tools: String or list of tool names/objects
30
    - toolbar_location: 'above', 'below', 'left', 'right', None
31
    - sizing_mode: 'fixed', 'stretch_width', 'stretch_height', 'stretch_both', 'scale_width', 'scale_height', 'scale_both'
32
    
33
    Returns:
34
    Figure object with glyph methods
35
    """
36

37
def markers():
38
    """Print available marker types."""
39

40
DEFAULT_TOOLS: str  # "pan,wheel_zoom,box_zoom,save,reset,help"
41
```
42

43
### Line and Path Glyphs
44

45
Methods for creating line-based visualizations including simple lines, multi-line plots, and step plots.
46

47
```python { .api }
48
def line(self, x='x', y='y', line_width=1, line_color='black', line_alpha=1.0,
49
         line_join='bevel', line_cap='butt', line_dash=[], line_dash_offset=0,
50
         **kwargs):
51
    """
52
    Plot lines connecting data points.
53
    
54
    Parameters:
55
    - x, y: Field names or arrays for coordinates
56
    - line_width: Line thickness in pixels
57
    - line_color: Line color
58
    - line_alpha: Line transparency (0-1)
59
    - line_join: 'miter', 'round', 'bevel'
60
    - line_cap: 'butt', 'round', 'square'
61
    - line_dash: Dash pattern as list of integers
62
    """
63

64
def multi_line(self, xs='xs', ys='ys', line_width=1, line_color='black',
65
               line_alpha=1.0, line_join='bevel', line_cap='butt',
66
               line_dash=[], line_dash_offset=0, **kwargs):
67
    """
68
    Plot multiple disconnected lines.
69
    
70
    Parameters:
71
    - xs, ys: Field names or lists of arrays for multiple line coordinates
72
    """
73

74
def step(self, x='x', y='y', mode='before', line_width=1, line_color='black',
75
         line_alpha=1.0, **kwargs):
76
    """
77
    Plot step lines.
78
    
79
    Parameters:
80
    - mode: 'before', 'after', 'center' - step positioning
81
    """
82

83
def segment(self, x0='x0', y0='y0', x1='x1', y1='y1', **kwargs):
84
    """Plot line segments between point pairs."""
85

86
def ray(self, x='x', y='y', length='length', angle='angle', **kwargs):
87
    """Plot rays from points with specified length and angle."""
88

89
def bezier(self, x0='x0', y0='y0', x1='x1', y1='y1', cx0='cx0', cy0='cy0',
90
           cx1='cx1', cy1='cy1', **kwargs):
91
    """Plot Bezier curves."""
92

93
def quadratic(self, x0='x0', y0='y0', x1='x1', y1='y1', cx='cx', cy='cy', **kwargs):
94
    """Plot quadratic curves."""
95
```
96

97
### Marker and Scatter Glyphs
98

99
Methods for creating scatter plots and marker-based visualizations with 25+ marker types.
100

101
```python { .api }
102
def scatter(self, x='x', y='y', size='size', marker='circle', color='color',
103
            alpha=1.0, **kwargs):
104
    """
105
    General scatter plot with configurable marker types.
106
    
107
    Parameters:
108
    - x, y: Field names or arrays for coordinates
109
    - size: Marker size in screen units
110
    - marker: Marker type ('circle', 'square', 'triangle', etc.)
111
    - color: Marker fill color
112
    - alpha: Marker transparency (0-1)
113
    """
114

115
def circle(self, x='x', y='y', size=4, radius=None, radius_dimension='x',
116
           fill_color='gray', fill_alpha=1.0, line_color='black',
117
           line_width=1, line_alpha=1.0, **kwargs):
118
    """
119
    Circle markers.
120
    
121
    Parameters:
122
    - size: Marker diameter in screen units (if radius not specified)
123
    - radius: Circle radius in data units
124
    - radius_dimension: 'x', 'y', 'max', 'min' - scaling dimension for radius
125
    """
126

127
# Specific marker methods
128
def asterisk(self, x='x', y='y', size=4, **kwargs): ...
129
def circle_cross(self, x='x', y='y', size=4, **kwargs): ...
130
def circle_dot(self, x='x', y='y', size=4, **kwargs): ...
131
def circle_x(self, x='x', y='y', size=4, **kwargs): ...
132
def circle_y(self, x='x', y='y', size=4, **kwargs): ...
133
def cross(self, x='x', y='y', size=4, **kwargs): ...
134
def dash(self, x='x', y='y', size=4, **kwargs): ...
135
def diamond(self, x='x', y='y', size=4, **kwargs): ...
136
def diamond_cross(self, x='x', y='y', size=4, **kwargs): ...
137
def diamond_dot(self, x='x', y='y', size=4, **kwargs): ...
138
def dot(self, x='x', y='y', size=4, **kwargs): ...
139
def hex(self, x='x', y='y', size=4, **kwargs): ...
140
def hex_dot(self, x='x', y='y', size=4, **kwargs): ...
141
def inverted_triangle(self, x='x', y='y', size=4, **kwargs): ...
142
def plus(self, x='x', y='y', size=4, **kwargs): ...
143
def square(self, x='x', y='y', size=4, **kwargs): ...
144
def square_cross(self, x='x', y='y', size=4, **kwargs): ...
145
def square_dot(self, x='x', y='y', size=4, **kwargs): ...
146
def square_pin(self, x='x', y='y', size=4, **kwargs): ...
147
def square_x(self, x='x', y='y', size=4, **kwargs): ...
148
def star(self, x='x', y='y', size=4, **kwargs): ...
149
def star_dot(self, x='x', y='y', size=4, **kwargs): ...
150
def triangle(self, x='x', y='y', size=4, **kwargs): ...
151
def triangle_dot(self, x='x', y='y', size=4, **kwargs): ...
152
def triangle_pin(self, x='x', y='y', size=4, **kwargs): ...
153
def x(self, x='x', y='y', size=4, **kwargs): ...
154
def y(self, x='x', y='y', size=4, **kwargs): ...
155
```
156

157
### Shape and Area Glyphs
158

159
Methods for creating geometric shapes, bars, and filled areas.
160

161
```python { .api }
162
def rect(self, x='x', y='y', width='width', height='height', angle=0.0,
163
         dilate=False, **kwargs):
164
    """
165
    Rectangular glyphs.
166
    
167
    Parameters:
168
    - x, y: Center coordinates
169
    - width, height: Dimensions in data units
170
    - angle: Rotation angle in radians
171
    - dilate: Whether to dilate pixel boundaries
172
    """
173

174
def quad(self, left='left', right='right', top='top', bottom='bottom', **kwargs):
175
    """
176
    Quadrilateral glyphs using explicit boundaries.
177
    
178
    Parameters:
179
    - left, right, top, bottom: Boundary coordinates
180
    """
181

182
def ellipse(self, x='x', y='y', width='width', height='height', angle=0.0, **kwargs):
183
    """Elliptical shapes."""
184

185
def wedge(self, x='x', y='y', radius='radius', start_angle='start_angle',
186
          end_angle='end_angle', direction='anticlock', **kwargs):
187
    """
188
    Wedge/pie slice shapes.
189
    
190
    Parameters:
191
    - direction: 'clock', 'anticlock'
192
    """
193

194
def annular_wedge(self, x='x', y='y', inner_radius='inner_radius',
195
                  outer_radius='outer_radius', start_angle='start_angle',
196
                  end_angle='end_angle', direction='anticlock', **kwargs):
197
    """Annular wedge shapes (ring segments)."""
198

199
def annulus(self, x='x', y='y', inner_radius='inner_radius',
200
            outer_radius='outer_radius', **kwargs):
201
    """Ring/annulus shapes."""
202

203
def arc(self, x='x', y='y', radius='radius', start_angle='start_angle',
204
        end_angle='end_angle', direction='anticlock', **kwargs):
205
    """Arc shapes."""
206
```
207

208
### Bar Charts
209

210
Methods for creating vertical and horizontal bar charts.
211

212
```python { .api }
213
def vbar(self, x='x', top='top', width=0.8, bottom=0, **kwargs):
214
    """
215
    Vertical bars.
216
    
217
    Parameters:
218
    - x: Bar center x-coordinates
219
    - top: Bar top y-coordinates
220
    - width: Bar width in data units
221
    - bottom: Bar bottom y-coordinates (default: 0)
222
    """
223

224
def hbar(self, y='y', right='right', height=0.8, left=0, **kwargs):
225
    """
226
    Horizontal bars.
227
    
228
    Parameters:
229
    - y: Bar center y-coordinates
230
    - right: Bar right x-coordinates
231
    - height: Bar height in data units
232
    - left: Bar left x-coordinates (default: 0)
233
    """
234
```
235

236
### Area Plots
237

238
Methods for creating filled area plots and spans.
239

240
```python { .api }
241
def varea(self, x='x', y1='y1', y2='y2', **kwargs):
242
    """
243
    Vertical area between two y-coordinates.
244
    
245
    Parameters:
246
    - x: X-coordinates
247
    - y1, y2: Bottom and top y-coordinates
248
    """
249

250
def harea(self, y='y', x1='x1', x2='x2', **kwargs):
251
    """Horizontal area between two x-coordinates."""
252

253
def varea_step(self, x='x', y1='y1', y2='y2', step_mode='before', **kwargs):
254
    """Step-wise vertical area."""
255

256
def harea_step(self, y='y', x1='x1', x2='x2', step_mode='before', **kwargs):
257
    """Step-wise horizontal area."""
258

259
def vspan(self, x='x', line_width=1, line_color='black', **kwargs):
260
    """Vertical spans across entire plot height."""
261

262
def hspan(self, y='y', line_width=1, line_color='black', **kwargs):
263
    """Horizontal spans across entire plot width."""
264

265
def vstrip(self, x0='x0', x1='x1', **kwargs):
266
    """Vertical strips between x-coordinates."""
267

268
def hstrip(self, y0='y0', y1='y1', **kwargs):
269
    """Horizontal strips between y-coordinates."""
270
```
271

272
### Image and Patch Glyphs
273

274
Methods for displaying images and complex polygonal shapes.
275

276
```python { .api }
277
def image(self, image='image', x='x', y='y', dw='dw', dh='dh',
278
          palette=None, dilate=False, **kwargs):
279
    """
280
    Display 2D image data.
281
    
282
    Parameters:
283
    - image: 2D array of image data
284
    - x, y: Lower-left corner coordinates
285
    - dw, dh: Image dimensions in data units
286
    - palette: Color palette for scalar data
287
    """
288

289
def image_rgba(self, image='image', x='x', y='y', dw='dw', dh='dh',
290
               dilate=False, **kwargs):
291
    """Display RGBA image data (uint32 array)."""
292

293
def image_stack(self, image='image', x='x', y='y', dw='dw', dh='dh',
294
                palette=None, **kwargs):
295
    """Display stacked images."""
296

297
def image_url(self, url='url', x='x', y='y', w='w', h='h', angle=0.0,
298
              dilate=False, anchor='top_left', retry_attempts=0,
299
              retry_timeout=0, **kwargs):
300
    """
301
    Display images from URLs.
302
    
303
    Parameters:
304
    - url: Image URL
305
    - w, h: Image dimensions in screen units
306
    - anchor: 'top_left', 'top_center', 'top_right', etc.
307
    """
308

309
def patch(self, x='x', y='y', **kwargs):
310
    """Single polygon patch."""
311

312
def patches(self, xs='xs', ys='ys', **kwargs):
313
    """Multiple polygon patches."""
314

315
def multi_polygons(self, xs='xs', ys='ys', **kwargs):
316
    """Complex polygonal shapes with holes."""
317

318
def hex_tile(self, q='q', r='r', size=1.0, aspect_scale=1.0,
319
             scale=1.0, orientation='pointytop', **kwargs):
320
    """
321
    Hexagonal tiles for hex mapping.
322
    
323
    Parameters:
324
    - q, r: Hex grid coordinates
325
    - orientation: 'pointytop', 'flattop'
326
    """
327
```
328

329
### Text and Mathematical Notation
330

331
Methods for adding text annotations and mathematical expressions.
332

333
```python { .api }
334
def text(self, x='x', y='y', text='text', angle=0.0, x_offset=0, y_offset=0,
335
         text_font='helvetica', text_font_size='16px', text_font_style='normal',
336
         text_color='black', text_alpha=1.0, text_align='left',
337
         text_baseline='bottom', **kwargs):
338
    """
339
    Text annotations.
340
    
341
    Parameters:
342
    - text: Text strings
343
    - angle: Rotation angle in radians
344
    - x_offset, y_offset: Offset in screen units
345
    - text_align: 'left', 'right', 'center'
346
    - text_baseline: 'top', 'middle', 'bottom', 'alphabetic', 'hanging'
347
    """
348

349
def mathml(self, x='x', y='y', text='text', **kwargs):
350
    """MathML mathematical notation."""
351

352
def tex(self, x='x', y='y', text='text', **kwargs):
353
    """TeX/LaTeX mathematical notation."""
354
```
355

356
### Special Glyphs
357

358
Additional specialized glyph methods.
359

360
```python { .api }
361
def ngon(self, x='x', y='y', size='size', n=5, **kwargs):
362
    """
363
    N-sided regular polygons.
364
    
365
    Parameters:
366
    - n: Number of sides
367
    """
368

369
def block(self, x='x', y='y', width='width', height='height', **kwargs):
370
    """Block markers for heatmaps and categorical data."""
371
```
372

373
### Re-exported Functions
374

375
Common functions re-exported from other modules for convenience.
376

377
```python { .api }
378
# From bokeh.io
379
def show(obj, browser=None, new=None):
380
    """Display plot in browser or notebook."""
381

382
def save(obj, filename=None, resources=None, title=None):
383
    """Save plot to HTML file."""
384

385
def output_file(filename, title=None, mode=None, root_dir=None):
386
    """Direct output to HTML file."""
387

388
def output_notebook(hide_banner=None, load_timeout=5000, notebook_type='jupyter'):
389
    """Direct output to Jupyter notebook."""
390

391
def reset_output():
392
    """Reset output mode."""
393

394
def curdoc():
395
    """Get current document."""
396

397
# From bokeh.layouts
398
def column(*children, **kwargs):
399
    """Arrange plots/widgets vertically."""
400

401
def row(*children, **kwargs):
402
    """Arrange plots/widgets horizontally."""
403

404
def gridplot(children, **kwargs):
405
    """Create grid of plots with shared tools."""
406

407
# From bokeh.models
408
class ColumnDataSource:
409
    """Primary data source."""
410
    def __init__(self, data=None, **kwargs): ...
411

412
class Document:
413
    """Document container."""
414

415
# Layout containers
416
class Row: ...
417
class Column: ...
418
```
419

420
## Usage Examples
421

422
### Line Plot with Multiple Series
423

424
```python
425
from bokeh.plotting import figure, show
426
import numpy as np
427

428
x = np.linspace(0, 4*np.pi, 100)
429

430
p = figure(width=400, height=400, title="Multiple Lines")
431

432
# Multiple line series with different styles
433
p.line(x, np.sin(x), legend_label="sin(x)", line_width=2, color='blue')
434
p.line(x, np.cos(x), legend_label="cos(x)", line_width=2, color='red', line_dash='dashed')
435

436
p.legend.location = "top_right"
437
show(p)
438
```
439

440
### Customized Scatter Plot
441

442
```python
443
from bokeh.plotting import figure, show
444
from bokeh.models import HoverTool
445

446
# Sample data
447
n = 500
448
x = np.random.random(n) * 100
449
y = np.random.random(n) * 100
450
colors = np.random.choice(['red', 'green', 'blue', 'orange', 'purple'], n)
451
sizes = np.random.randint(10, 30, n)
452

453
# Create figure with hover tool
454
p = figure(width=600, height=600, title="Customized Scatter Plot",
455
           tools="pan,wheel_zoom,box_zoom,reset,save")
456

457
# Add hover tool
458
hover = HoverTool(tooltips=[("Index", "$index"), ("(X,Y)", "($x, $y)"), ("Size", "@size")])
459
p.add_tools(hover)
460

461
# Create scatter plot
462
p.circle(x, y, size=sizes, color=colors, alpha=0.6)
463

464
show(p)
465
```
466

467
### Bar Chart
468

469
```python
470
from bokeh.plotting import figure, show
471

472
categories = ['Q1', 'Q2', 'Q3', 'Q4']  
473
values = [20, 25, 30, 35]
474

475
p = figure(x_range=categories, width=400, height=400, title="Quarterly Sales")
476

477
p.vbar(x=categories, top=values, width=0.5, color='navy', alpha=0.8)
478

479
p.xgrid.grid_line_color = None
480
p.y_range.start = 0
481

482
show(p)
483
```