Histogram Widget

Visualize data distributions across numerical ranges

Using Sample Data: The examples on this page use fields from our sample dataset. Download it and create an evaluation with it to follow along with this tutorial.

When to Use

Use histogram widgets to:

• Show value distributions (groups data by distinct values)
• Visualize frequency counts or aggregated metrics
• Identify patterns in numerical data
• Display aggregated data in a distribution format

Configuration

Required Fields

title · string · required

Widget display name shown on the dashboard

type · string · required

Must be set to “histogram”

query · object · required

SeriesQuery selecting the column

X-Axis Configuration (One Required)

You must provide either x_column or x_column_group, but not both:

config.x_column · string

Single column name to group by for the x-axis. The histogram displays distinct values from this column.

Example: "overall_score" - groups by each score value (75, 80, 85, etc.)

config.x_column_group · string[]

Array of column names for multi-dimensional grouping. Creates separate distributions for each combination.

Example: ["agent_name"] - creates separate distributions for each agent

Note: Multi-dimensional grouping creates overlaid or stacked distributions for comparison.

Optional Config Fields

config.stacked · boolean · default: "true"

Controls whether multiple distributions are stacked or overlaid.

• true (default): Stack distributions on top of each other
• false: Overlay distributions for easier comparison

Query Requirements

Histogram widgets require a SeriesQuery with:

• Select the column you want to group by (becomes the x-axis)
• Can include aggregations (COUNT, SUM, AVG, etc.) for the y-axis
• If no aggregation is specified, COUNT is used by default
• Can include filter to narrow the dataset

Creating in the UI

1. Open Widget Creator

   From your dashboard, click “Add Widget” and select “Histogram”

2. Enter Title

   Give your histogram a descriptive name (e.g., “Score Distribution”)

3. Select Column

   Choose the column to group by (this will be the x-axis)

4. Add Aggregations (Optional)

   

   Add aggregations for the y-axis. If none specified, COUNT is used by default.

5. Add Filters (Optional)

   

   Optionally filter to specific subsets of data

6. Create Widget

   Click “Add” to generate the histogram

   

Output Format

Histogram widgets return grouped data:

{
  "type": "series",
  "data": [
    {"score": 75, "count": 12},
    {"score": 80, "count": 45},
    {"score": 85, "count": 89},
    {"score": 90, "count": 156},
    ...
  ]
}

Each data point represents a distinct value from the grouped column and its corresponding count or aggregated metric.

Example Use Cases

Use Case 1: Overall Score Distribution

Visualize how overall scores are distributed across all evaluations. This will by default show the count of evaluations for each score value.

Python

widget = client.evaluation_dashboards.widgets.create(
    dashboard_id=dashboard.id,
    title="Overall Score Distribution",
    type="histogram",
    query={
        "select": [
            {
                "expression": {
                    "type": "COLUMN",
                    "column": "overall_score",
                    "source": "data"
                }
            },
            {"expression": {"type": "AGGREGATION", "function": "COUNT", "column": "*"}}
        ]
        "groupBy": ["overall_score"]
    },
    config={
        "x_column": "overall_score"
    }
)

---

Use Case 2: Technical Task Score Distribution

Show distribution for evaluations in the technical category only.

Python

widget = client.evaluation_dashboards.widgets.create(
    dashboard_id=dashboard.id,
    title="Technical Task Score Distribution",
    type="histogram",
    query={
        "select": [
            {"expression": {"type": "COLUMN", "column": "overall_score", "source": "data"}},
            {"expression": {"type": "AGGREGATION", "function": "COUNT", "column": "*"}}
        ],
        "filter": {
            "conditions": [
                {"column": "prompt_category", "source": "data", "operator": "=", "value": "technical"}
            ]
        },
        "groupBy": ["overall_score"]
    },
    config={"x_column": "overall_score"}
)

---

Use Case 3: Comparing Distributions Across Categories

Create overlaid histograms to compare score distributions across different scores.

Python

widget = client.evaluation_dashboards.widgets.create(
    dashboard_id=dashboard.id,
    title="Score Distribution by Score",
    type="histogram",
    query={
        "select": [
            {"expression": {"type": "COLUMN", "column": "overall_score", "source": "data"}},
            {"expression": {"type": "AGGREGATION", "function": "AVG", "column": "fluency_score", "source": "data"}},
            {"expression": {"type": "AGGREGATION", "function": "AVG", "column": "relevance_score", "source": "data"}}
        ],
        "groupBy": ["overall_score"]
    },
    config={
        "x_column": "overall_score",
        "stacked": True
    }
)

Stacked vs Overlaid Distributions

When comparing distributions across groups, you can control visualization style:

Overlaid Distributions (Unstacked)

Multiple distributions shown with transparency, overlapping each other. Best for:

• Comparing distribution shapes directly
• Identifying differences in peaks and spread
• Seeing all distributions simultaneously

config={"x_column": "overall_score", "stacked": False}

Stacked Distributions

Distributions stacked vertically to show combined totals. Best for:

• Showing total counts across all groups
• Part-to-whole relationships
• When cumulative view is meaningful

config={"x_column": "overall_score", "stacked": True}  # Default

Related Documentation

• Bar Chart Widget - For categorical distributions
• Metric Widget - Show percentiles and statistical measures
• Table Widget - Detailed numerical breakdowns
• Query Language - Filter and column syntax