Bar Charts¶

The barchart{} keyword draws a bar chart: a set of discrete, labelled categories, each rendered as a vertical bar whose height encodes its value. (This is distinct from a histogram, whose contiguous bars span numeric classes.)

As for the other keywords, values are separated by ;, and options follow a | separator; multiple options are separated by ;. The series must hold an even number of values: the first half are the X-axis labels and the second half are the matching bar heights (so there are as many heights as labels). A baseline (X) axis and a graduated (Y) axis are always drawn, the heights are reported on the Y axis and the labels are centred under each bar. A label may contain a literal \n (backslash + n) to span several lines — handy to keep long labels narrow so the bars stay close together.

By default the Y axis starts at 0 and runs up to a "nice" round value just above the tallest bar, graduated with a "nice" step (1, 2 or 5 times a power of ten). For example a tallest bar of 4 gives an axis 0…5 stepped by 1, whereas a tallest bar of 47 gives an axis 0…50 stepped by 10.

The barchart{} keyword has several options:

• y_min — bottom of the Y axis. Default: 0.
• y_max — top of the Y axis. Default: the smallest "nice" value strictly above the tallest bar. When y_min/y_max are given, every height must lie within [y_min, y_max]. The axis is graduated up to y_max, but its value is only written when it is a multiple of the label step (otherwise the top simply stays unlabelled).
• y_step — step between Y-axis graduations (the tick marks, and the grid lines when y_grid is on). Default: a "nice" step targeting a readable number of graduations.
• y_labels_step — step between the Y graduations whose value is actually written. Default: the same "nice" step as the automatic graduations, so the numbers stay readable even when y_step makes the graduations finer. Set it lower (e.g. 1) to write every value, or higher to write fewer. When this forces the written values close together, the chart grows taller so they never overlap.
• x_title — caption drawn to the right of the X axis (e.g. the nature or unit of the categories). A literal \n (backslash + n) inserts a line break, e.g. x_title=Number of shooting\nstars observed.
• y_title — caption drawn at the top left of the Y axis (e.g. the nature or unit of the values). Supports \n line breaks like x_title.
• x_grid — set to true to draw light vertical grid lines, placed midway between consecutive bars.
• y_grid — set to true to draw light horizontal grid lines, one per Y graduation, behind the bars.
• swap_axes — set to true to transpose the chart: the bars become horizontal, the value axis is drawn horizontally (still controlled by y_min/y_max/y_step/y_labels_step), and the category labels are written horizontally to the left of the (now vertical) category axis. Every x_*/y_* option keeps controlling the same data dimension; only the on-screen orientation changes.
• from_bottom — set to true to place the first category at the bottom of the (vertical) category axis instead of the top. Only meaningful together with swap_axes (ignored otherwise).
• grid_opacity — opacity of the grid lines (0–1). Default from the configuration.
• grid_secondary_opacity — opacity of the y_grid lines that fall on a graduation with no written value (the secondary lines, lighter than the main ones). Default from the configuration. Only visible when y_step makes the graduations finer than the written values.
• color — inner colour applied to every bar (overrides the configured default).
• bar_colors — comma-separated list of per-bar inner colours (one per bar, same convention as barmodel's fill). Use _ (or none) to keep the default (or color=) colour for a given bar.
• baseline (top, middle or bottom) — sets the vertical alignment of the chart with surrounding text. By default text sits on the category (X) axis; middle aligns it to the chart's vertical centre (handy for a caption beside the chart), top/bottom to its edges.

The default bar width, the minimum spacing between bars, the maximum bar width, the default bar colour and the default grid opacity are all set in the configuration (under rendering.barchart). The horizontal spacing widens automatically when a label is too wide to fit, keeping bar_spacing as a minimum so labels never overlap.

Any of these rendering.barchart defaults can also be overridden for a single chart by passing an option of the same name: bar_width_ratio, bar_spacing_ratio, max_bar_width_ratio, chart_height_ratio, axis_thickness, grid_thickness, tick_len_ratio, major_tick_len_ratio, tick_spacing_ratio, label_gap_ratio and target_ticks (the *_ratio values are multiples of the font size). For example barchart{… | bar_width_ratio=2.5 ; bar_spacing_ratio=2}.

tick_spacing_ratio sets a minimum spacing between consecutive graduations: the value axis is lengthened so each y_step interval is at least that wide (handy to spread out fine graduations). It defaults to 0 (disabled).

Examples :