# Histogram Widget ## Overview ### Video {% embed url="" %} ### What Is the Histogram Widget? The Histogram Widget is Datacake’s new, multi-purpose chart component for summarising numeric telemetry across many devices.\ It combines: * **Bar charts** – classic column view of each data source. * **Interactive statistics table** – min | max | average with live highlighting. * **Pie charts** – *first time ever on Datacake!* – for quick distribution insights. * **Value Ranges** – rule-based colouring (and optional grouping in Pie mode). Use it to visualise anything from city-by-city temperatures to battery-level bands across your fleet. *** ### Quick Start | Step | Action | | ---- | -------------------------------------------------------------------- | | 1 | **Add Widget** → choose **Histogram** | | 2 | Give it a title (e.g. *Temperature Histogram*) | | 3 | Open **Data** tab → add the telemetry fields you want to compare | | 4 | (Optional) set a **Unit** (°C, %, V, …) | | 5 | Fine-tune look & behaviour under **Appearance** and **Value Ranges** | | 6 | **Save** and resize the widget on your dashboard | *** ## Data Configuration ### Adding Data Sources Each bar (or pie slice) starts with a **Data Source**: pick one or more device fields.\ Future releases will support *semantic shortcuts* (e.g. “All temperatures”) – for now, select manually. ### Naming & Units * Rename each source for a readable legend label. * Add a **Unit** so the y-axis, tooltips and statistics table share a consistent suffix. *** ## Appearance Options ### Chart Type | Option | Use-case | Notes | | ----------------------- | ------------------------------------------------- | -------------------------------------------- | | **Bar Chart** (default) | Compare absolute values between sources | Shows value labels above each bar if enabled | | **Pie Chart** | Show distribution (source-based *or* range-based) | First appearance on Datacake | Switch type anytime in **Appearance → Chart Type**. ### Display Toggles * **Show Statistics Table** – reveals interactive Min/Max/Avg grid. * **Show Values on Bars** – numeric labels directly on bars. * **Hide Background** – transparent widget for dark dashboards. ### Decimal Places Control global rounding (0 – 4 decimals) for bars, tooltips and table cells. ## Value Ranges Value Ranges let you: 1. **Colorise** bars or slices according to thresholds. 2. **Group** devices into bands when Pie Chart mode is active. | Field | Description | | ------------- | ----------------------------------------------- | | **Name** | Friendly label (e.g. *Cold*, *Warm*, *Extreme*) | | **From / To** | Inclusive numeric limits | | **Color** | Hex picker for range colour | Enable them under **Value Ranges → “Enable Value Ranges”**. ### **Range Colouring (Bar Mode)** Bars keep their individual height (device value) but adopt the colour of the range they fall into – fast visual QA of outliers. ### **Range Grouping (Pie Mode) – *****Key Concept*** *Without* ranges, a pie shows one slice per **data source**.\ \&#xNAN;*With* ranges **enabled**, the pie swaps to **distribution mode**: * Each slice is a **range**, not a device. * Slice size = *number of devices* inside that range (percentage shown on hover & in legend). This turns the same telemetry into an instant “how many devices are cold / warm / hot?” insight. *** ## Interactivity * **Hover a bar** → highlights corresponding row in the statistics table. * **Hover a table row** → flashes the matching bar. * **Hover a pie slice** → tooltip with range name + device count + percentage. * Supports real-time updates when the dashboard is in *Live Data* mode. *** ## Best Practices & Tips | Scenario | Recommendation | | -------------------------------- | ----------------------------------------------------------------------------- | | Fleet health distribution | Use **Pie + Value Ranges** to spot clusters (e.g. battery 0–20 %, 20–50 %, …) | | Comparing absolute sensor values | Stick to **Bar** with value labels and stats table | | Many devices (> 20) | Ranges become essential – otherwise the legend gets crowded | | Dark dashboards | Enable **Hide Background** and pick high-contrast range colours | | Multi-metric page | Duplicate the widget, then edit Data tab only – ranges & styling carry over | *** ## FAQ #### Q: Why does my pie chart still show device names instead of ranges? A: Make sure **Enable Value Ranges** is toggled **on** *and* at least one range is defined. #### Q: How are slice percentages calculated? A: *(Device count in range ÷ Total device count) × 100 %*.\ Individual values are **not** summed in range mode. #### Q: Can I disable the statistics table? A: Yes – Appearance → toggle **Show Statistics Table**. #### Q: Will semantic data selection be available? A: Yes, upcoming releases will auto-suggest fields (e.g. *all “temperature” sensors*). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.datacake.de/dashboards/widgets/histogram-widget.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.