---
product: "AG Studio"
title: "Statistical Charts"
description: "Build histogram, box plot, range bar, range column and range area charts in AG Studio to show distributions and ranges, and their Format settings."
framework: react
version: "3.1.0"
related:
    - title: "Bar and Column Charts"
      url: "https://www.ag-grid.com/studio/analysts/bar-and-column-charts/"
    - title: "Line and Area Charts"
      url: "https://www.ag-grid.com/studio/analysts/line-and-area-charts/"
    - title: "Combo Charts"
      url: "https://www.ag-grid.com/studio/analysts/combo-charts/"
    - title: "Scatter Charts"
      url: "https://www.ag-grid.com/studio/analysts/scatter-charts/"
    - title: "Polar Charts"
      url: "https://www.ag-grid.com/studio/analysts/polar-charts/"
    - title: "Proportional Charts"
      url: "https://www.ag-grid.com/studio/analysts/proportional-charts/"
    - title: "Progression Charts"
      url: "https://www.ag-grid.com/studio/analysts/progression-charts/"
    - title: "Hierarchical Charts"
      url: "https://www.ag-grid.com/studio/analysts/hierarchical-charts/"
llms: "https://www.ag-grid.com/studio/llms.txt"
---

# Statistical Charts

Statistical Charts show how the values of a field are distributed, or how a value ranges between a low and a high point across categories.

These Widgets work from every individual value of a field rather than from a total, so the fields in their slots are left unaggregated and the Widget works out the bins, ranges or spread for each category itself.

## Histogram Chart

**Histogram Chart** groups a field's values into bins and plots the count of values falling into each bin, so the shape of the distribution becomes visible at a glance.

The number of bins is chosen automatically, but you can set a fixed number with **Bin Count** on the Format tab. Clear Bin Count to return to Auto.

The example below plots the delivery time of every shipment twice: on the left with bins chosen automatically, and on the right with Bin Count set to 5.

#### Histogram Chart

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "histogram-automatic": {
          type: "histogram-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Histogram: Automatic Bins",
            },
            subtitle: {
              enabled: true,
              text: "Statistical Chart > Bin Count not set",
            },
          },
        },
        "histogram-bin-count": {
          type: "histogram-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Histogram: 5 Bins",
            },
            subtitle: {
              enabled: true,
              text: "Statistical Chart > Bin Count 5",
            },
            style: {
              theme: {
                histogram: {
                  series: {
                    binCount: 5,
                  },
                },
              },
            },
          },
        },
      },
      widgetLayout: {
        "histogram-automatic": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "histogram-bin-count": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Histogram Chart](https://www.ag-grid.com/studio/examples/statistical-charts/histogram-chart/typescript/)

## Range Charts

**Range Column Chart** draws a vertical column per category, spanning from the lowest to the highest value for that category.

**Range Bar Chart** draws the same range as a horizontal bar. This suits categories with long names, since the labels run alongside the bars rather than underneath them.

**Range Area Chart** shows the same low-to-high range as a shaded band running across the axis, rather than a separate bar or column per category.

The example below shows the fastest to slowest delivery for each carrier as a column and as a bar, and the same range for each month as an area.

#### Range Charts

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "range-column-chart": {
          type: "range-column-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.carrier" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Range Column Chart",
            },
            subtitle: {
              enabled: true,
              text: "Fastest to slowest delivery time in days by carrier",
            },
          },
        },
        "range-bar-chart": {
          type: "range-bar-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.carrier" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Range Bar Chart",
            },
            subtitle: {
              enabled: true,
              text: "Fastest to slowest delivery time in days by carrier",
            },
          },
        },
        "range-area-chart": {
          type: "range-area-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.month" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Range Area Chart",
            },
            subtitle: {
              enabled: true,
              text: "Fastest to slowest delivery time in days by month",
            },
          },
        },
      },
      widgetLayout: {
        "range-column-chart": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "range-bar-chart": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
        "range-area-chart": { xTrack: 0, yTrack: 22, xSpan: 24, ySpan: 22 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Range Charts](https://www.ag-grid.com/studio/examples/statistical-charts/range-chart/typescript/)

## Box Plot Chart

**Box Plot Chart** draws a box per category showing how the values of a numeric field are spread within it. Each box covers the middle half of the values for that category, the line inside it marks the median, and the whiskers reach the lowest and the highest value.

Each numeric field in the Y Axis slot adds its own box to every category. The example below shows the spread of delivery times for each carrier. The chart on the right adds Handling Time, the days before the carrier collects an order, with the legend turned on to tell the two series apart.

#### Box Plot Chart

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "box-plot-one-field": {
          type: "box-plot-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.carrier" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Box Plot: One Field",
            },
            subtitle: {
              enabled: true,
              text: "Y Axis: Delivery Time",
            },
          },
        },
        "box-plot-two-fields": {
          type: "box-plot-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.carrier" }],
            valueKey: [
              { id: "shipments.handling_days" },
              { id: "shipments.delivery_days" },
            ],
          },
          format: {
            title: {
              enabled: true,
              text: "Box Plot: Two Fields",
            },
            subtitle: {
              enabled: true,
              text: "Y Axis: Handling Time and Delivery Time, legend on",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    enabled: true,
                  },
                },
              },
            },
          },
        },
      },
      widgetLayout: {
        "box-plot-one-field": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "box-plot-two-fields": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Box Plot Chart](https://www.ag-grid.com/studio/examples/statistical-charts/box-plot-chart/typescript/)

## Setup

### Histogram Chart

| Slot | Required | Accepts | What it does |
| --- | --- | --- | --- |
| X Axis | Yes | One numeric field | Groups the field's values into bins and counts the values in each. |

### Range Bar, Range Column and Range Area Charts

| Slot | Required | Accepts | What it does |
| --- | --- | --- | --- |
| X Axis (Range Bar Chart: Y Axis) | Yes | One category | Draws one category along the axis for each value of the field. |
| Value | Yes | One numeric field | Draws a range from the field's lowest to its highest value within each category. |

### Box Plot Chart

| Slot | Required | Accepts | What it does |
| --- | --- | --- | --- |
| X Axis | Yes | One category | Draws one box for each value of the field. |
| Y Axis | Yes | One or more numeric fields | Works out the spread of each field's values within each category. Each field adds its own box. |

## Format

Statistical Charts have these settings of their own on the Format tab, beside the title, axis and appearance settings every chart has. Your developer can change the defaults shown.

| Setting | Where | Default | What it does |
| --- | --- | --- | --- |
| Bin Count | Statistical Chart section | Automatic | Sets the number of bins in a Histogram, from 1 to 100. |
| Legend | Elements | Off | Shows the legend on Range and Box Plot Charts. **Position** places it around the chart, at the bottom by default. |
| Data Labels | Elements | Off | Shows the low and high value of each range on Range Charts. **Font** and **Color** change the label text. |
| Segment Borders | Elements | Off | Draws a border around each bar of a Histogram, Range Bar or Range Column Chart. **Width** and **Color** change it. |

The example in [Histogram Chart](https://www.ag-grid.com/studio/analysts/statistical-charts/#histogram-chart) above shows Bin Count. The example below shows each of the other settings turned on in its own chart.

#### Format

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "range-column-labels": {
          type: "range-column-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.carrier" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Data Labels: Range Column",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels on",
            },
            style: {
              theme: {
                "range-bar": {
                  series: {
                    label: {
                      enabled: true,
                    },
                  },
                },
              },
            },
          },
        },
        "range-area-labels": {
          type: "range-area-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.month" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Data Labels: Range Area",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Data Labels on",
            },
            style: {
              theme: {
                "range-area": {
                  series: {
                    label: {
                      enabled: true,
                    },
                  },
                },
              },
            },
          },
        },
        "histogram-borders": {
          type: "histogram-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Segment Borders: Histogram",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Segment Borders on, Width 2",
            },
            style: {
              custom: {
                seriesStroke: {
                  enabled: true,
                  strokeWidth: 2,
                },
              },
            },
          },
        },
        "box-plot-legend": {
          type: "box-plot-chart",
          dataMapping: {
            categoryKey: [{ id: "shipments.carrier" }],
            valueKey: [{ id: "shipments.delivery_days" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Legend: Box Plot",
            },
            subtitle: {
              enabled: true,
              text: "Elements > Legend on, Position Right",
            },
            style: {
              theme: {
                common: {
                  legend: {
                    enabled: true,
                    position: "right",
                  },
                },
              },
            },
          },
        },
      },
      widgetLayout: {
        "range-column-labels": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "range-area-labels": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
        "histogram-borders": { xTrack: 0, yTrack: 22, xSpan: 12, ySpan: 22 },
        "box-plot-legend": { xTrack: 12, yTrack: 22, xSpan: 12, ySpan: 22 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Format](https://www.ag-grid.com/studio/examples/statistical-charts/statistical-format/typescript/)