0
# Plotting & Data Visualization
1
2
Comprehensive plotting system with multiple series types, axes management, and interactive features. DearPyGui's plotting capabilities are optimized for high-performance rendering of large datasets with smooth zoom, pan, and real-time updates.
3
4
## Capabilities
5
6
### Plot Creation
7
8
Core plotting infrastructure for creating plot containers and managing axes.
9
10
```python { .api }
11
def add_plot(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', width: int = '', height: int = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', callback: Callable = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', no_title: bool = '', no_menus: bool = '', no_box_select: bool = '', no_mouse_pos: bool = '', no_highlight: bool = '', no_child: bool = '', query: bool = '', crosshairs: bool = '', equal_aspects: bool = '', anti_aliased: bool = '') -> Union[int, str]:
12
"""
13
Creates a plot container for data visualization.
14
15
Parameters:
16
- no_title (bool): Hide plot title
17
- no_menus (bool): Disable context menus
18
- no_box_select (bool): Disable box selection
19
- no_mouse_pos (bool): Hide mouse coordinates
20
- no_highlight (bool): Disable series highlighting
21
- no_child (bool): Don't use child window
22
- query (bool): Enable plot queries
23
- crosshairs (bool): Show crosshair cursor
24
- equal_aspects (bool): Maintain equal aspect ratio
25
- anti_aliased (bool): Enable anti-aliasing
26
27
Returns:
28
Union[int, str]: Plot ID
29
"""
30
31
def add_plot_axis(axis: int, *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', no_gridlines: bool = '', no_tick_marks: bool = '', no_tick_labels: bool = '', log_scale: bool = '', invert: bool = '', lock_min: bool = '', lock_max: bool = '', time: bool = '', auto_fit: bool = '') -> Union[int, str]:
32
"""
33
Adds an axis to a plot.
34
35
Parameters:
36
- axis (int): Axis type (mvXAxis, mvYAxis, mvYAxis2, mvYAxis3)
37
- no_gridlines (bool): Hide grid lines
38
- no_tick_marks (bool): Hide tick marks
39
- no_tick_labels (bool): Hide tick labels
40
- log_scale (bool): Use logarithmic scale
41
- invert (bool): Invert axis direction
42
- lock_min, lock_max (bool): Lock axis limits
43
- time (bool): Format as time axis
44
- auto_fit (bool): Auto-fit data bounds
45
46
Returns:
47
Union[int, str]: Axis ID
48
"""
49
50
def add_subplots(rows: int, columns: int, *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', width: int = '', height: int = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', row_ratios: Union[List[float], Tuple[float, ...]] = '', column_ratios: Union[List[float], Tuple[float, ...]] = '', no_title: bool = '', no_menus: bool = '', no_resize: bool = '', no_align: bool = '', link_rows: bool = '', link_columns: bool = '', link_all_x: bool = '', link_all_y: bool = '', column_major: bool = '') -> Union[int, str]:
51
"""
52
Creates a subplot grid for multiple plots.
53
54
Parameters:
55
- rows, columns (int): Grid dimensions
56
- row_ratios, column_ratios (tuple): Size ratios for rows/columns
57
- no_resize (bool): Disable subplot resizing
58
- no_align (bool): Disable subplot alignment
59
- link_rows, link_columns (bool): Link axis ranges
60
- link_all_x, link_all_y (bool): Link all axes
61
- column_major (bool): Column-major ordering
62
63
Returns:
64
Union[int, str]: Subplot container ID
65
"""
66
```
67
68
### Basic Plot Series
69
70
Fundamental plot types for common data visualization needs.
71
72
```python { .api }
73
def add_line_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '') -> Union[int, str]:
74
"""
75
Adds a line series connecting data points.
76
77
Parameters:
78
- x, y (list): Data arrays for x and y coordinates
79
80
Returns:
81
Union[int, str]: Series ID
82
"""
83
84
def add_scatter_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '') -> Union[int, str]:
85
"""
86
Adds a scatter plot series with individual points.
87
88
Parameters:
89
- x, y (list): Data arrays for point coordinates
90
91
Returns:
92
Union[int, str]: Series ID
93
"""
94
95
def add_bar_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', weight: float = '', horizontal: bool = '') -> Union[int, str]:
96
"""
97
Adds a bar chart series.
98
99
Parameters:
100
- x, y (list): Data arrays
101
- weight (float): Bar width
102
- horizontal (bool): Horizontal bar orientation
103
104
Returns:
105
Union[int, str]: Series ID
106
"""
107
108
def add_area_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', fill: Union[List[int], Tuple[int, ...]] = '', contribute_to_bounds: bool = '') -> Union[int, str]:
109
"""
110
Adds an area plot series with filled regions.
111
112
Parameters:
113
- x, y (list): Data arrays
114
- fill (tuple): Fill color as (r, g, b, a)
115
- contribute_to_bounds (bool): Include in axis auto-fitting
116
117
Returns:
118
Union[int, str]: Series ID
119
"""
120
```
121
122
### Statistical Plot Series
123
124
Specialized series for statistical data visualization and analysis.
125
126
```python { .api }
127
def add_histogram_series(x: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', bins: int = '', bar_scale: float = '', min_range: float = '', max_range: float = '', cumlative: bool = '', density: bool = '', outliers: bool = '', contribute_to_bounds: bool = '') -> Union[int, str]:
128
"""
129
Adds a histogram series for data distribution visualization.
130
131
Parameters:
132
- x (list): Data array to histogram
133
- bins (int): Number of histogram bins
134
- bar_scale (float): Bar width scaling
135
- min_range, max_range (float): Data range limits
136
- cumlative (bool): Cumulative histogram
137
- density (bool): Normalize to density
138
- outliers (bool): Include outliers
139
- contribute_to_bounds (bool): Include in axis bounds
140
141
Returns:
142
Union[int, str]: Series ID
143
"""
144
145
def add_2d_histogram_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', xbins: int = '', ybins: int = '', xmin_range: float = '', xmax_range: float = '', ymin_range: float = '', ymax_range: float = '', density: bool = '', outliers: bool = '', col_major: bool = '') -> Union[int, str]:
146
"""
147
Adds a 2D histogram for bivariate data distribution.
148
149
Parameters:
150
- x, y (list): Data arrays
151
- xbins, ybins (int): Number of bins per axis
152
- xmin_range, xmax_range (float): X-axis range
153
- ymin_range, ymax_range (float): Y-axis range
154
- density (bool): Normalize to density
155
- outliers (bool): Include outliers
156
- col_major (bool): Column-major data ordering
157
158
Returns:
159
Union[int, str]: Series ID
160
"""
161
162
def add_error_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], negative: Union[List[float], Tuple[float, ...]], positive: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', contribute_to_bounds: bool = '', horizontal: bool = '') -> Union[int, str]:
163
"""
164
Adds error bars to show data uncertainty.
165
166
Parameters:
167
- x, y (list): Data point coordinates
168
- negative, positive (list): Error bar sizes
169
- contribute_to_bounds (bool): Include in axis bounds
170
- horizontal (bool): Horizontal error bars
171
172
Returns:
173
Union[int, str]: Series ID
174
"""
175
```
176
177
### Financial Plot Series
178
179
Specialized series for financial data visualization.
180
181
```python { .api }
182
def add_candle_series(dates: Union[List[float], Tuple[float, ...]], opens: Union[List[float], Tuple[float, ...]], closes: Union[List[float], Tuple[float, ...]], lows: Union[List[float], Tuple[float, ...]], highs: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', bull_color: Union[List[int], Tuple[int, ...]] = '', bear_color: Union[List[int], Tuple[int, ...]] = '', weight: float = '', tooltip: bool = '', time_unit: int = '') -> Union[int, str]:
183
"""
184
Adds candlestick chart for financial data.
185
186
Parameters:
187
- dates (list): Time stamps
188
- opens, closes, lows, highs (list): OHLC price data
189
- bull_color, bear_color (tuple): Colors for up/down candles
190
- weight (float): Candle width
191
- tooltip (bool): Show value tooltip
192
- time_unit (int): Time unit for formatting
193
194
Returns:
195
Union[int, str]: Series ID
196
"""
197
```
198
199
### Advanced Plot Series
200
201
Specialized series for advanced visualization techniques.
202
203
```python { .api }
204
def add_heat_series(values: Union[List[float], Tuple[float, ...]], rows: int, cols: int, scale_min: float, scale_max: float, *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', format: str = '', bounds_min: Union[List[float], Tuple[float, ...]] = '', bounds_max: Union[List[float], Tuple[float, ...]] = '', contribute_to_bounds: bool = '', col_major: bool = '') -> Union[int, str]:
205
"""
206
Adds a heat map series for matrix data visualization.
207
208
Parameters:
209
- values (list): 2D data flattened to 1D array
210
- rows, cols (int): Matrix dimensions
211
- scale_min, scale_max (float): Color mapping range
212
- format (str): Value display format
213
- bounds_min, bounds_max (tuple): Plot bounds
214
- contribute_to_bounds (bool): Include in axis bounds
215
- col_major (bool): Column-major data ordering
216
217
Returns:
218
Union[int, str]: Series ID
219
"""
220
221
def add_pie_series(values: Union[List[float], Tuple[float, ...]], labels: Union[List[str], Tuple[str, ...]], x: float, y: float, radius: float, *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', normalize: bool = '', angle0: float = '', fmt: str = '') -> Union[int, str]:
222
"""
223
Adds a pie chart series.
224
225
Parameters:
226
- values (list): Pie slice values
227
- labels (list): Slice labels
228
- x, y (float): Center coordinates
229
- radius (float): Pie radius
230
- normalize (bool): Normalize values to 100%
231
- angle0 (float): Starting angle
232
- fmt (str): Value format string
233
234
Returns:
235
Union[int, str]: Series ID
236
"""
237
238
def add_stem_series(x: Union[List[float], Tuple[float, ...]], y: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', indent: int = '', orientation: int = '', ref: float = '') -> Union[int, str]:
239
"""
240
Adds a stem plot series with vertical lines to a reference.
241
242
Parameters:
243
- x, y (list): Data coordinates
244
- indent (int): Visual indentation
245
- orientation (int): Stem orientation
246
- ref (float): Reference line value
247
248
Returns:
249
Union[int, str]: Series ID
250
"""
251
```
252
253
### Plot Interactions and Annotations
254
255
Interactive elements and annotation tools for enhanced plot functionality.
256
257
```python { .api }
258
def add_drag_line(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', default_value: float = '', color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', y_line: bool = '', show_label: bool = '', callback: Callable = '') -> Union[int, str]:
259
"""
260
Adds an interactive draggable line.
261
262
Parameters:
263
- default_value (float): Initial position
264
- color (tuple): Line color
265
- thickness (float): Line thickness
266
- y_line (bool): Horizontal line (default is vertical)
267
- show_label (bool): Show value label
268
- callback (Callable): Drag callback function
269
270
Returns:
271
Union[int, str]: Drag line ID
272
"""
273
274
def add_drag_point(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', default_value: Union[List[float], Tuple[float, ...]] = '', color: Union[List[int], Tuple[int, ...]] = '', radius: float = '', show_label: bool = '', callback: Callable = '') -> Union[int, str]:
275
"""
276
Adds an interactive draggable point.
277
278
Parameters:
279
- default_value (tuple): Initial position (x, y)
280
- color (tuple): Point color
281
- radius (float): Point size
282
- show_label (bool): Show coordinate label
283
- callback (Callable): Drag callback function
284
285
Returns:
286
Union[int, str]: Drag point ID
287
"""
288
289
def add_plot_annotation(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', source: Union[int, str] = '', show: bool = '', default_value: Union[List[float], Tuple[float, ...]] = '', offset: Union[List[float], Tuple[float, ...]] = '', color: Union[List[int], Tuple[int, ...]] = '', clamped: bool = '') -> Union[int, str]:
290
"""
291
Adds a text annotation to the plot.
292
293
Parameters:
294
- default_value (tuple): Annotation position (x, y)
295
- offset (tuple): Text offset from position
296
- color (tuple): Text color
297
- clamped (bool): Clamp to plot area
298
299
Returns:
300
Union[int, str]: Annotation ID
301
"""
302
303
def add_plot_legend(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', location: int = '', horizontal: bool = '', outside: bool = '') -> Union[int, str]:
304
"""
305
Adds a legend to the plot.
306
307
Parameters:
308
- location (int): Legend position (mvPlot_Location_* constants)
309
- horizontal (bool): Horizontal layout
310
- outside (bool): Place outside plot area
311
312
Returns:
313
Union[int, str]: Legend ID
314
"""
315
```
316
317
### Axis Management
318
319
Advanced axis configuration and management functions.
320
321
```python { .api }
322
def fit_axis_data(axis: Union[int, str]) -> None:
323
"""
324
Auto-fits axis to data bounds.
325
326
Parameters:
327
- axis: Axis ID to fit
328
"""
329
330
def set_axis_limits(axis: Union[int, str], ymin: float, ymax: float) -> None:
331
"""
332
Sets axis range limits.
333
334
Parameters:
335
- axis: Axis ID
336
- ymin, ymax (float): Range limits
337
"""
338
339
def set_axis_limits_auto(axis: Union[int, str]) -> None:
340
"""
341
Enables automatic axis limit fitting.
342
343
Parameters:
344
- axis: Axis ID
345
"""
346
347
def get_axis_limits(axis: Union[int, str]) -> Union[List[float], Tuple[float, ...]]:
348
"""
349
Gets current axis limits.
350
351
Parameters:
352
- axis: Axis ID
353
354
Returns:
355
tuple: (min, max) axis limits
356
"""
357
358
def set_axis_ticks(axis: Union[int, str], label_pairs: Union[List[Union[List[str], Tuple[str, ...]]], Tuple[Union[List[str], Tuple[str, ...]], ...]]) -> None:
359
"""
360
Sets custom axis tick labels.
361
362
Parameters:
363
- axis: Axis ID
364
- label_pairs (list): List of [value, label] pairs
365
"""
366
367
def reset_axis_ticks(axis: Union[int, str]) -> None:
368
"""
369
Resets axis ticks to automatic.
370
371
Parameters:
372
- axis: Axis ID
373
"""
374
```
375
376
## Usage Examples
377
378
### Basic Line Plot
379
380
```python
381
import dearpygui.dearpygui as dpg
382
import math
383
384
# Sample data
385
x_data = [i * 0.1 for i in range(100)]
386
y_data = [math.sin(x) for x in x_data]
387
388
with dpg.window(label="Line Plot", width=600, height=400):
389
with dpg.plot(label="Sine Wave", height=300, width=500):
390
dpg.add_plot_axis(dpg.mvXAxis, label="X")
391
dpg.add_plot_axis(dpg.mvYAxis, label="Y")
392
393
dpg.add_line_series(x_data, y_data, label="sin(x)", parent=dpg.mvYAxis)
394
dpg.add_plot_legend()
395
```
396
397
### Multi-Series Plot
398
399
```python
400
import dearpygui.dearpygui as dpg
401
import math
402
403
# Generate data
404
x = [i * 0.1 for i in range(100)]
405
sin_y = [math.sin(x_val) for x_val in x]
406
cos_y = [math.cos(x_val) for x_val in x]
407
408
with dpg.window(label="Multi-Series Plot", width=700, height=500):
409
with dpg.plot(label="Trigonometric Functions", height=400, width=600):
410
x_axis = dpg.add_plot_axis(dpg.mvXAxis, label="Angle (radians)")
411
y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Value")
412
413
dpg.add_line_series(x, sin_y, label="sin(x)", parent=y_axis)
414
dpg.add_line_series(x, cos_y, label="cos(x)", parent=y_axis)
415
416
dpg.add_plot_legend()
417
```
418
419
### Real-Time Plot
420
421
```python
422
import dearpygui.dearpygui as dpg
423
import math
424
import time
425
426
# Data storage
427
plot_data = {"x": [], "y": []}
428
max_points = 1000
429
430
def update_plot():
431
current_time = time.time()
432
plot_data["x"].append(current_time)
433
plot_data["y"].append(math.sin(current_time * 2))
434
435
# Keep only recent data
436
if len(plot_data["x"]) > max_points:
437
plot_data["x"].pop(0)
438
plot_data["y"].pop(0)
439
440
# Update series
441
dpg.set_value("real_time_series", [plot_data["x"], plot_data["y"]])
442
443
with dpg.window(label="Real-Time Plot", width=800, height=600):
444
with dpg.plot(label="Live Data", height=400, width=700):
445
x_axis = dpg.add_plot_axis(dpg.mvXAxis, label="Time", time=True)
446
y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Value", auto_fit=True)
447
448
dpg.add_line_series([], [], label="Live Signal",
449
parent=y_axis, tag="real_time_series")
450
451
# Set up timer for updates
452
def frame_callback():
453
update_plot()
454
455
dpg.set_frame_callback(1, frame_callback)
456
```
457
458
### Subplot Example
459
460
```python
461
import dearpygui.dearpygui as dpg
462
import math
463
import random
464
465
# Sample data
466
x = list(range(50))
467
y1 = [math.sin(i * 0.2) for i in x]
468
y2 = [random.random() for _ in x]
469
hist_data = [random.gauss(0, 1) for _ in range(1000)]
470
471
with dpg.window(label="Subplots", width=900, height=700):
472
with dpg.subplots(2, 2, label="Data Analysis", width=800, height=600):
473
474
# Subplot 1: Line plot
475
with dpg.plot():
476
dpg.add_plot_axis(dpg.mvXAxis, label="X")
477
y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Y")
478
dpg.add_line_series(x, y1, label="Sine", parent=y_axis)
479
480
# Subplot 2: Scatter plot
481
with dpg.plot():
482
dpg.add_plot_axis(dpg.mvXAxis, label="X")
483
y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Y")
484
dpg.add_scatter_series(x, y2, label="Random", parent=y_axis)
485
486
# Subplot 3: Histogram
487
with dpg.plot():
488
dpg.add_plot_axis(dpg.mvXAxis, label="Value")
489
y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Frequency")
490
dpg.add_histogram_series(hist_data, label="Distribution", parent=y_axis)
491
492
# Subplot 4: Bar chart
493
with dpg.plot():
494
dpg.add_plot_axis(dpg.mvXAxis, label="Category")
495
y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Count")
496
dpg.add_bar_series([1, 2, 3, 4, 5], [10, 15, 8, 12, 20],
497
label="Data", parent=y_axis)
498
```
499
500
## Constants
501
502
Plot-related constants for configuration:
503
504
```python { .api }
505
# Axis types
506
mvXAxis: int
507
mvYAxis: int
508
mvYAxis2: int
509
mvYAxis3: int
510
511
# Plot locations
512
mvPlot_Location_Center: int
513
mvPlot_Location_North: int
514
mvPlot_Location_South: int
515
mvPlot_Location_West: int
516
mvPlot_Location_East: int
517
mvPlot_Location_NorthWest: int
518
mvPlot_Location_NorthEast: int
519
mvPlot_Location_SouthWest: int
520
mvPlot_Location_SouthEast: int
521
522
# Time units
523
mvTimeUnit_Us: int
524
mvTimeUnit_Ms: int
525
mvTimeUnit_S: int
526
mvTimeUnit_Min: int
527
mvTimeUnit_Hr: int
528
mvTimeUnit_Day: int
529
mvTimeUnit_Mo: int
530
mvTimeUnit_Yr: int
531
532
# Plot markers
533
mvPlotMarker_None: int
534
mvPlotMarker_Circle: int
535
mvPlotMarker_Square: int
536
mvPlotMarker_Diamond: int
537
mvPlotMarker_Up: int
538
mvPlotMarker_Down: int
539
mvPlotMarker_Left: int
540
mvPlotMarker_Right: int
541
mvPlotMarker_Cross: int
542
mvPlotMarker_Plus: int
543
mvPlotMarker_Asterisk: int
544
```