CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-dearpygui

DearPyGui is a modern, fast and powerful GUI framework for Python that provides an easy-to-use, dynamic, GPU-accelerated, cross-platform graphical user interface toolkit.

—

Pending
Overview
Eval results
Files

plotting.mddocs/

Plotting & Data Visualization

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.

Capabilities

Plot Creation

Core plotting infrastructure for creating plot containers and managing axes.

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]:
    """
    Creates a plot container for data visualization.
    
    Parameters:
    - no_title (bool): Hide plot title
    - no_menus (bool): Disable context menus
    - no_box_select (bool): Disable box selection
    - no_mouse_pos (bool): Hide mouse coordinates
    - no_highlight (bool): Disable series highlighting
    - no_child (bool): Don't use child window
    - query (bool): Enable plot queries
    - crosshairs (bool): Show crosshair cursor
    - equal_aspects (bool): Maintain equal aspect ratio
    - anti_aliased (bool): Enable anti-aliasing
    
    Returns:
    Union[int, str]: Plot ID
    """

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]:
    """
    Adds an axis to a plot.
    
    Parameters:
    - axis (int): Axis type (mvXAxis, mvYAxis, mvYAxis2, mvYAxis3)
    - no_gridlines (bool): Hide grid lines
    - no_tick_marks (bool): Hide tick marks
    - no_tick_labels (bool): Hide tick labels
    - log_scale (bool): Use logarithmic scale
    - invert (bool): Invert axis direction
    - lock_min, lock_max (bool): Lock axis limits
    - time (bool): Format as time axis
    - auto_fit (bool): Auto-fit data bounds
    
    Returns:
    Union[int, str]: Axis ID
    """

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]:
    """
    Creates a subplot grid for multiple plots.
    
    Parameters:
    - rows, columns (int): Grid dimensions
    - row_ratios, column_ratios (tuple): Size ratios for rows/columns
    - no_resize (bool): Disable subplot resizing
    - no_align (bool): Disable subplot alignment
    - link_rows, link_columns (bool): Link axis ranges
    - link_all_x, link_all_y (bool): Link all axes
    - column_major (bool): Column-major ordering
    
    Returns:
    Union[int, str]: Subplot container ID
    """

Basic Plot Series

Fundamental plot types for common data visualization needs.

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]:
    """
    Adds a line series connecting data points.
    
    Parameters:
    - x, y (list): Data arrays for x and y coordinates
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds a scatter plot series with individual points.
    
    Parameters:
    - x, y (list): Data arrays for point coordinates
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds a bar chart series.
    
    Parameters:
    - x, y (list): Data arrays
    - weight (float): Bar width
    - horizontal (bool): Horizontal bar orientation
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds an area plot series with filled regions.
    
    Parameters:
    - x, y (list): Data arrays
    - fill (tuple): Fill color as (r, g, b, a)
    - contribute_to_bounds (bool): Include in axis auto-fitting
    
    Returns:
    Union[int, str]: Series ID
    """

Statistical Plot Series

Specialized series for statistical data visualization and analysis.

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]:
    """
    Adds a histogram series for data distribution visualization.
    
    Parameters:
    - x (list): Data array to histogram
    - bins (int): Number of histogram bins
    - bar_scale (float): Bar width scaling
    - min_range, max_range (float): Data range limits
    - cumlative (bool): Cumulative histogram
    - density (bool): Normalize to density
    - outliers (bool): Include outliers
    - contribute_to_bounds (bool): Include in axis bounds
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds a 2D histogram for bivariate data distribution.
    
    Parameters:
    - x, y (list): Data arrays
    - xbins, ybins (int): Number of bins per axis
    - xmin_range, xmax_range (float): X-axis range
    - ymin_range, ymax_range (float): Y-axis range
    - density (bool): Normalize to density
    - outliers (bool): Include outliers
    - col_major (bool): Column-major data ordering
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds error bars to show data uncertainty.
    
    Parameters:
    - x, y (list): Data point coordinates
    - negative, positive (list): Error bar sizes
    - contribute_to_bounds (bool): Include in axis bounds
    - horizontal (bool): Horizontal error bars
    
    Returns:
    Union[int, str]: Series ID
    """

Financial Plot Series

Specialized series for financial data visualization.

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]:
    """
    Adds candlestick chart for financial data.
    
    Parameters:
    - dates (list): Time stamps
    - opens, closes, lows, highs (list): OHLC price data
    - bull_color, bear_color (tuple): Colors for up/down candles
    - weight (float): Candle width
    - tooltip (bool): Show value tooltip
    - time_unit (int): Time unit for formatting
    
    Returns:
    Union[int, str]: Series ID
    """

Advanced Plot Series

Specialized series for advanced visualization techniques.

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]:
    """
    Adds a heat map series for matrix data visualization.
    
    Parameters:
    - values (list): 2D data flattened to 1D array
    - rows, cols (int): Matrix dimensions
    - scale_min, scale_max (float): Color mapping range
    - format (str): Value display format
    - bounds_min, bounds_max (tuple): Plot bounds
    - contribute_to_bounds (bool): Include in axis bounds
    - col_major (bool): Column-major data ordering
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds a pie chart series.
    
    Parameters:
    - values (list): Pie slice values
    - labels (list): Slice labels
    - x, y (float): Center coordinates
    - radius (float): Pie radius
    - normalize (bool): Normalize values to 100%
    - angle0 (float): Starting angle
    - fmt (str): Value format string
    
    Returns:
    Union[int, str]: Series ID
    """

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]:
    """
    Adds a stem plot series with vertical lines to a reference.
    
    Parameters:
    - x, y (list): Data coordinates
    - indent (int): Visual indentation
    - orientation (int): Stem orientation
    - ref (float): Reference line value
    
    Returns:
    Union[int, str]: Series ID
    """

Plot Interactions and Annotations

Interactive elements and annotation tools for enhanced plot functionality.

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]:
    """
    Adds an interactive draggable line.
    
    Parameters:
    - default_value (float): Initial position
    - color (tuple): Line color
    - thickness (float): Line thickness
    - y_line (bool): Horizontal line (default is vertical)
    - show_label (bool): Show value label
    - callback (Callable): Drag callback function
    
    Returns:
    Union[int, str]: Drag line ID
    """

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]:
    """
    Adds an interactive draggable point.
    
    Parameters:
    - default_value (tuple): Initial position (x, y)
    - color (tuple): Point color
    - radius (float): Point size
    - show_label (bool): Show coordinate label
    - callback (Callable): Drag callback function
    
    Returns:
    Union[int, str]: Drag point ID
    """

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]:
    """
    Adds a text annotation to the plot.
    
    Parameters:
    - default_value (tuple): Annotation position (x, y)
    - offset (tuple): Text offset from position
    - color (tuple): Text color
    - clamped (bool): Clamp to plot area
    
    Returns:
    Union[int, str]: Annotation ID
    """

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]:
    """
    Adds a legend to the plot.
    
    Parameters:
    - location (int): Legend position (mvPlot_Location_* constants)
    - horizontal (bool): Horizontal layout
    - outside (bool): Place outside plot area
    
    Returns:
    Union[int, str]: Legend ID
    """

Axis Management

Advanced axis configuration and management functions.

def fit_axis_data(axis: Union[int, str]) -> None:
    """
    Auto-fits axis to data bounds.
    
    Parameters:
    - axis: Axis ID to fit
    """

def set_axis_limits(axis: Union[int, str], ymin: float, ymax: float) -> None:
    """
    Sets axis range limits.
    
    Parameters:
    - axis: Axis ID
    - ymin, ymax (float): Range limits
    """

def set_axis_limits_auto(axis: Union[int, str]) -> None:
    """
    Enables automatic axis limit fitting.
    
    Parameters:
    - axis: Axis ID
    """

def get_axis_limits(axis: Union[int, str]) -> Union[List[float], Tuple[float, ...]]:
    """
    Gets current axis limits.
    
    Parameters:
    - axis: Axis ID
    
    Returns:
    tuple: (min, max) axis limits
    """

def set_axis_ticks(axis: Union[int, str], label_pairs: Union[List[Union[List[str], Tuple[str, ...]]], Tuple[Union[List[str], Tuple[str, ...]], ...]]) -> None:
    """
    Sets custom axis tick labels.
    
    Parameters:
    - axis: Axis ID
    - label_pairs (list): List of [value, label] pairs
    """

def reset_axis_ticks(axis: Union[int, str]) -> None:
    """
    Resets axis ticks to automatic.
    
    Parameters:
    - axis: Axis ID
    """

Usage Examples

Basic Line Plot

import dearpygui.dearpygui as dpg
import math

# Sample data
x_data = [i * 0.1 for i in range(100)]
y_data = [math.sin(x) for x in x_data]

with dpg.window(label="Line Plot", width=600, height=400):
    with dpg.plot(label="Sine Wave", height=300, width=500):
        dpg.add_plot_axis(dpg.mvXAxis, label="X")
        dpg.add_plot_axis(dpg.mvYAxis, label="Y")
        
        dpg.add_line_series(x_data, y_data, label="sin(x)", parent=dpg.mvYAxis)
        dpg.add_plot_legend()

Multi-Series Plot

import dearpygui.dearpygui as dpg
import math

# Generate data
x = [i * 0.1 for i in range(100)]
sin_y = [math.sin(x_val) for x_val in x]
cos_y = [math.cos(x_val) for x_val in x]

with dpg.window(label="Multi-Series Plot", width=700, height=500):
    with dpg.plot(label="Trigonometric Functions", height=400, width=600):
        x_axis = dpg.add_plot_axis(dpg.mvXAxis, label="Angle (radians)")
        y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Value")
        
        dpg.add_line_series(x, sin_y, label="sin(x)", parent=y_axis)
        dpg.add_line_series(x, cos_y, label="cos(x)", parent=y_axis)
        
        dpg.add_plot_legend()

Real-Time Plot

import dearpygui.dearpygui as dpg
import math
import time

# Data storage
plot_data = {"x": [], "y": []}
max_points = 1000

def update_plot():
    current_time = time.time()
    plot_data["x"].append(current_time)
    plot_data["y"].append(math.sin(current_time * 2))
    
    # Keep only recent data
    if len(plot_data["x"]) > max_points:
        plot_data["x"].pop(0)
        plot_data["y"].pop(0)
    
    # Update series
    dpg.set_value("real_time_series", [plot_data["x"], plot_data["y"]])

with dpg.window(label="Real-Time Plot", width=800, height=600):
    with dpg.plot(label="Live Data", height=400, width=700):
        x_axis = dpg.add_plot_axis(dpg.mvXAxis, label="Time", time=True)
        y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Value", auto_fit=True)
        
        dpg.add_line_series([], [], label="Live Signal", 
                          parent=y_axis, tag="real_time_series")

# Set up timer for updates
def frame_callback():
    update_plot()

dpg.set_frame_callback(1, frame_callback)

Subplot Example

import dearpygui.dearpygui as dpg
import math
import random

# Sample data
x = list(range(50))
y1 = [math.sin(i * 0.2) for i in x]
y2 = [random.random() for _ in x]
hist_data = [random.gauss(0, 1) for _ in range(1000)]

with dpg.window(label="Subplots", width=900, height=700):
    with dpg.subplots(2, 2, label="Data Analysis", width=800, height=600):
        
        # Subplot 1: Line plot
        with dpg.plot():
            dpg.add_plot_axis(dpg.mvXAxis, label="X")
            y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Y")
            dpg.add_line_series(x, y1, label="Sine", parent=y_axis)
        
        # Subplot 2: Scatter plot  
        with dpg.plot():
            dpg.add_plot_axis(dpg.mvXAxis, label="X")
            y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Y")
            dpg.add_scatter_series(x, y2, label="Random", parent=y_axis)
        
        # Subplot 3: Histogram
        with dpg.plot():
            dpg.add_plot_axis(dpg.mvXAxis, label="Value")
            y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Frequency")
            dpg.add_histogram_series(hist_data, label="Distribution", parent=y_axis)
        
        # Subplot 4: Bar chart
        with dpg.plot():
            dpg.add_plot_axis(dpg.mvXAxis, label="Category")
            y_axis = dpg.add_plot_axis(dpg.mvYAxis, label="Count")
            dpg.add_bar_series([1, 2, 3, 4, 5], [10, 15, 8, 12, 20], 
                             label="Data", parent=y_axis)

Constants

Plot-related constants for configuration:

# Axis types
mvXAxis: int
mvYAxis: int  
mvYAxis2: int
mvYAxis3: int

# Plot locations
mvPlot_Location_Center: int
mvPlot_Location_North: int
mvPlot_Location_South: int
mvPlot_Location_West: int
mvPlot_Location_East: int
mvPlot_Location_NorthWest: int
mvPlot_Location_NorthEast: int
mvPlot_Location_SouthWest: int
mvPlot_Location_SouthEast: int

# Time units
mvTimeUnit_Us: int
mvTimeUnit_Ms: int
mvTimeUnit_S: int
mvTimeUnit_Min: int
mvTimeUnit_Hr: int
mvTimeUnit_Day: int
mvTimeUnit_Mo: int
mvTimeUnit_Yr: int

# Plot markers
mvPlotMarker_None: int
mvPlotMarker_Circle: int
mvPlotMarker_Square: int
mvPlotMarker_Diamond: int
mvPlotMarker_Up: int
mvPlotMarker_Down: int
mvPlotMarker_Left: int
mvPlotMarker_Right: int
mvPlotMarker_Cross: int
mvPlotMarker_Plus: int
mvPlotMarker_Asterisk: int

Install with Tessl CLI

npx tessl i tessl/pypi-dearpygui

docs

advanced.md

application-lifecycle.md

drawing.md

events.md

index.md

layout.md

plotting.md

tables.md

widgets.md

tile.json