> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truemath.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authoring charts

> Display a table-valued variable as a bar or pie chart, and configure its series, labels, and slices.

A chart is a **presentation of a [table](https://docs.truemath.ai/authoring/tables.md)**, not a value of its own. You display a table variable as a chart by giving it the `bar_chart` or `pie_chart` kind (see [Defining variables](https://docs.truemath.ai/authoring/defining-variables.md)). The variable's value stays a table — the chart only changes how that table is shown.

## Bar charts

A `bar_chart` plots a table's values as bars. Each **series** is one column or one row of the table, drawn as a set of bars, and the table's shape is what decides how many series there are.

You configure:

* **Series orientation** — whether one series is a **column** or a **row** of the table. See [Series orientation](#series-orientation).
* **Stacking** — whether the series are drawn side by side or stacked into a single bar per group.
* **Axis title** — the label shown under the x-axis.
* **Labels** — whether the x-axis labels are a running number or the table's first series. See [X-axis labels](#x-axis-labels).
* **Series format** — for each series, a name, a kind, and a format. The name labels that series in the legend; the kind and format apply to its values, the same scalar formatting a [column](https://docs.truemath.ai/authoring/tables.md#configuring-columns) uses.

### Series orientation

The orientation setting says what **one series** is. Under column series, each column of the table is plotted as a series and each **row** is an x-axis category. Under row series, each row is plotted and each **column** is a category.

Column series are the common case, because that is how most tables are shaped. An [amortization schedule](https://docs.truemath.ai/math/functions/finance.md#amortization-table-amortization), or a [`columns`](https://docs.truemath.ai/math/functions/tables#column-column-columns) slice of one, has a period per row and a measure per column, so a schedule sliced to a payment column and a balance column, plotted by column, is two series with one x-axis category per period.

Choose row series only for a table laid out the other way: one row per measure, one column per period.

### X-axis labels

The x-axis labels come from a running number or from the table's first series.

When the labels are a running number, they are integers counting up from a starting number you set, and every series in the table is plotted.

When the labels come from the first series, you build the table with a series of label values in front — a column of dates, or of period names — and the chart draws the axis from that series instead of plotting it. The labels take their kind and format from it, so a `date` series gives an axis of dates. Where a label value is empty, the axis falls back to a positional name for that category, `Row 3` under column series or `Column 3` under row series, numbered from the same starting number.

## Pie charts

A `pie_chart` plots one series as slices of a whole.

A pie plots a **single row**. Give it a flat list of values, or a table of one row. Where the table has more than one row, only the first is plotted.

You configure:

* **Slice names** — a label per slice, paired with the values in order. Where a name is missing or empty, that slice reads `Slice 3`.
* **Kind and format** — the scalar kind and format applied to slice values. Unlike a bar chart, which formats each series separately, a pie takes one setting for every slice.

A pie chart is suited to parts of a single total — principal versus interest, a budget split across categories — where a bar chart is suited to comparing values across a series.

## Charting dates and durations

A chart series and a pie slice take the same kinds a [column](https://docs.truemath.ai/authoring/tables.md#configuring-columns) does, the four time kinds included, and the axis labels, tooltips, and legend format through whichever token you give them.

A pie of durations — time spent per activity, as proportions of a whole — is the everyday case. Plotting instants works too, though a bar's height is then measured from 1970, which rarely makes a readable chart. Dates are usually more useful as the axis labels than as the bars.

## Mixed units in a chart

When the column behind a chart holds values in **different units of the same dimension** — `3 ft`, `4 in`, and `5 yd` in one column, say — the chart draws every bar or slice to a single common unit, so their sizes are proportioned honestly rather than taken from the raw numbers. Each label and tooltip still shows the value's original unit, so the `4 in` bar reads `4 in` even though it is drawn on a `ft` axis. The common unit is the first cell's unit, and a pie chart's percentages are taken from those common-unit magnitudes. This needs no authoring action — a mixed-unit column charts correctly on its own.

To pin the axis to a particular unit instead of the first cell's, [cast](https://docs.truemath.ai/math/units.md#casting-to-a-specific-unit) the column to that unit in the chart variable's equation; casting converts the data, so the labels then show the unit you chose.

If a column instead mixes **different dimensions** — a length and a mass, say — there is no common axis to draw against, so the chart shows a short message naming the conflicting unit types rather than a misleading chart. Keep a chart's column to a single dimension.

## The chart is a view of the table

Because a chart is display configuration over a table, the data behind it is authored, supplied, and returned as a table in every case: you build it from a [table variable](https://docs.truemath.ai/authoring/tables.md), users provide its values through [structured-text input](https://docs.truemath.ai/concepts/input-formats.md#tables), and a calculation returns it as a table in the [result](https://docs.truemath.ai/api/calculate.md). Choosing a chart over a grid is purely a presentation decision — the math is unchanged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.