Charting a Simulation

This guide is a set of recipes for turning a random sample into a chart a reader can watch change: counting draws into categories, binning them into intervals, summarizing a sample, and comparing two samples side by side. It assumes you already know how to write a <chart> — see the <chart> reference for its attributes and properties.

Count draws into named categories

<tally> counts how many values fall into each category, and <chart> draws the counts. The pieces are: draw the sample, map each draw onto a category, count, chart.

Five tags hold the whole simulation: <sampleRandomNumbers> draws the sample, <cumulativeSum> accumulates the subpopulation sizes, <searchSorted> maps every draw onto the subpopulation it landed in, <tally> counts them, and <chart> draws the counts.

Give <tally> its categories rather than leaving it to discover them. A subpopulation that draws nothing then still counts zero and keeps its bar, instead of dropping out and shifting the others along — which would make the chart jump every time the reader resamples.

<callAction> redraws the sample, and everything downstream follows.

Bin a continuous sample into intervals

For a measurement rather than a category, type="histogram" bins the sample itself: its bins are the cut points, and each bar is as tall as the number of draws that fall between one pair of them.

Write the cut points out rather than leaving them to the chart, and give them room: a bin the sample sometimes reaches and sometimes does not still keeps its place, so the picture stands still while the reader resamples and only the bars move. Leave bins off and the chart chooses cut points from the sample it has, which is what you want for a fixed set of data and not for one that is redrawn.

$h.binCounts is what the bars are, and $h.binEdges the cut points, so the histogram does the counting and hands the counts back. <binCounts> counts the same way when you want the numbers without a picture — in a table, or as the values of a bar chart whose bars you want named by something other than their cut points.

Compare two samples in one chart

Give the chart a <series> per sample. Each is counted separately and drawn in its own color, and its <label> names it in the legend.

Both series are binned against the same cut points, which is what makes the bars comparable: a bar in one series stands next to the bar for the same interval in the other. Counting the samples separately and drawing bars is what puts two of them in one picture — a histogram bins and draws one sample, so two of them would be two charts.

Use layout="stacked" instead when the two samples make up a whole and the total is what a reader should read.

Compare two samples by their summaries

A box plot asks a different question of a sample than a histogram does. A histogram shows the shape of the distribution; a box plot reduces it to five numbers and draws those — one box per <series>, running from the first quartile to the third with the median across it — so two samples side by side are compared by where their middles and their spreads sit.

Naming each <series> is what makes its summary readable: minimum, quartile1, median, quartile3, maximum and outliers are all reported per series, so the sentence under the chart is drawn from the same numbers the boxes are. Resampling moves both.

Chart two sampled variables against each other

A scatter plot needs a pair of numbers per point: the series holds the vertical coordinates and its x the horizontal ones. Sample one variable, derive the other from it, and the relationship between them is what the reader sees.

<repeat> is what pairs the two: it walks the sampled heights, and $i reaches the draw of noise that belongs with each. Both lists are the same length, so every point has both of its coordinates.

Ask about what the chart shows

Because the counts are numbers the document can read, the same numbers that drew the chart can be asked about.

$c.binCounts is one number per bar, in the order the bars are drawn, so the answer and the sentence are both computed from the picture and stay right when the reader resamples. $c.values is the sample itself, for a summary the bins do not answer.