Skip to content
Examples
Radial & polar
Gauge

Gauge

A gauge chart: a single value shown as a needle or arc against a min/max range, mimicking an analog dial. Reaches for the familiar speedometer metaphor for one KPI, though bullet() packs the same information into far less space.

Gauge

Usage 

from dataviz import gauge
from dataviz import save

def main() raises:
    var cpu_usage = 67.0

    var c = gauge(
        cpu_usage,
        title="Illustrative CPU Utilization (%)",
    )
    save(c, "docs/src/examples/out_gauge.svg")

See Data shapes for shared input conventions.

Args:

  • value: The reading to show, clamped (not rejected) to [min_value, max_value] – an out-of-range value pins visibly at the end of the dial.
  • min_value: The dial’s low end; defaults to 0.0.
  • max_value: The dial’s high end; defaults to 100.0, giving a plain percentage-style gauge with the default value.
  • breakpoints: Ascending fractions of the full [min_value, max_value] span (e.g. [0.5, 1.0] for a low/high split); left empty (the default), reproduces ECharts’ fixed 20%/80%/100% bands unchanged.
  • band_colors: One color per breakpoints band, same length; left empty (the default), reproduces ECharts’ fixed green/blue/red bands unchanged.
  • band_inner_fraction: The band ring’s inner radius as a fraction of the dial radius; defaults to 0.7.
  • needle_fraction: The needle’s length as a fraction of the dial radius; defaults to 0.9.
  • start_angle: Where the dial begins, in radians; defaults to 3*pi/4.
  • sweep_angle: How far the dial sweeps, in radians; defaults to 3*pi/2 (270 degrees).
  • theme: Full styling knobs beyond this function’s own parameters (colors, margins, fonts, gridlines, …) – see Theme’s docstring.
  • width: Pixel width of the returned Plot (.size()).
  • height: Pixel height of the returned Plot (.size()).
  • title: The chart’s title, shown above the plot.
  • subtitle: A secondary line shown under the title.
  • x_title: The x-axis caption.
  • y_title: The y-axis caption.

Related

Related charts: Radar

Relevant API: gauge

Radar