Skip to content

Describing figures

A study produces figures faster than anyone can name them. Once there are more than a screenful, finding the one you want means describing them, and IronLAB stores two kinds of description with a figure for exactly that: tags and parameters. Neither affects drawing. Both are saved with the figure, in either format, and both are what the viewer's figure browser filters, sorts and groups a collection by.

The viewer works nothing out for itself

One rule governs everything on this page: a figure is found by what its author wrote on it, and by nothing else.

The viewer reads no properties off a figure of its own accord. It does not decide that a figure is three-dimensional, or that it draws a surface, or that it carries a million data values, and it does not offer any of those as something to filter by. The program that builds a figure is the only thing that knows which of that figure's properties matter — usually none of the structural ones — and a program that does care about a structural property can write it down in a line.

The practical consequence is short: whatever you might later want to search by, write it down. A collection of figures carrying no tags and no parameters can be searched by title and listed, and nothing else.

Tags

A tag is a free word describing a figure, such as surface, piv or stalled. A figure carries any number of them, and none of them is a name with a value under it.

let fig = Figure::new()
    .title("Wake behind a cylinder")
    .tag("wake")
    .tag("piv")
    .tag("quiver");

Tags are kept in the order they were given, which is the order the viewer lists them in. A tag must not be empty, and adding the same tag twice is an error that validate reports. Tags are compared exactly, so Wake and wake are two tags and neither is a repeat of the other; picking one case and keeping to it saves a reader guessing.

A tag need not be shared with another figure to be worth adding. The browser lists every tag it finds, with the number of figures behind each, so a tag carried by a single figure is how that figure is found rather than a tag wasted. The list of tags is itself what tells a reader what a collection can be narrowed by.

A tag is never drawn on the figure, which is what distinguishes it from a label: in IronLAB a label is text drawn beside what it identifies, such as an axis label or the label of a plot in a legend. Tags were called labels in earlier versions, and the vocabulary of titles, labels, names and tags is recorded in ADR 0023.

Parameters

A parameter is a named value describing a figure, such as the Reynolds number of the flow it shows or the solver that produced its data. A value may be a boolean, an integer, a number or a string, and it keeps that kind when the figure is saved.

let fig = Figure::new()
    .title("Wake behind a cylinder")
    .parameter("reynolds_number", 3900.0)
    .parameter("angle_of_attack_deg", 4.0)
    .parameter("solver", "LES")
    .parameter("converged", true);

A name occurs at most once, so setting a parameter again replaces its value. A name must not be empty, and a number must be finite. Names are compared exactly, and a name without spaces in it can be asked about in the browser's search field, so reynolds_number can be searched for where reynolds number cannot.

Choosing between them

The two answer different questions, and the question you expect to ask is what decides.

Use a tag Use a parameter
The question Is the figure one of these? Which value does the figure have?
Values The word is the whole of the answer A name with a value under it
How many Any number per figure One value per name
In the browser Chosen from a list of words Chosen from a list of values, or narrowed by a range
Ordering None Sorted and grouped by value; numbers compared with > and <

A useful test is whether you would ever want a range or an order. An angle of attack is a parameter, because angle_of_attack_deg>=8 is a question worth asking and stalled is not the same question. A rig is a parameter if you expect to group by it and read the groups in order; it is a tag if you only ever want to say which figures came from it.

The second test is how many answers a figure can have at once. A figure is two-dimensional or three-dimensional and never both, so dimensionality is a parameter with the values 2D and 3D, and a collection can be grouped by it into two runs. A figure may draw a surface and an image, so the kinds it draws are tags, and a figure carries one for each.

Write each fact one way only. Having decided which a fact is, resist describing it the other way as well: a figure that is tagged 3d and carries dimensionality: 3D leaves a reader unable to tell whether the two mean the same thing, and the browser offers them separately as though they did not. This repository's own gallery is the worked example. Its entries carry dimensionality as a parameter and no 2d or 3d tag, and they carry a tag for each artist kind they draw and no parameter naming one — because a figure drawing an image over a surface is genuinely both, and choosing which of them it is "really" would be a judgement nobody asked for.

Something that is simply true or false can be either, and the difference is what absence means. As the parameter converged: false a figure is positively marked as not having converged, and the browser can group the converged against the rest. As the tag converged, a figure without it is either one that did not converge or one nobody checked, and the browser cannot tell those apart. Prefer the parameter when the opposite is meaningful.

What to write down

Write what someone would search for, including facts about the figure's own structure when those are among them. The viewer will not add them for you, and a collection is easier to browse for having them: surface and subplots are perfectly good tags, and how many data values a figure holds is a perfectly good parameter, sorted by when you want to know which figure is making the viewer work.

Beyond that, the descriptions worth carrying are the ones that separate one figure from its neighbours: the conditions of the run, the campaign it belongs to, the quantity plotted, whether it is a result or a diagnostic. A description that is the same on every figure divides nothing, and the browser ranks it last accordingly.

Write each of them once, as a tag or as a parameter, and never as both.

Descriptions cost nothing to draw and very little to store, so the error worth avoiding is writing too few.

Using them

In the viewer, the figure browser narrows a collection by both. Its search field takes words and, for parameters, comparisons: rig:CFD, angle_of_attack_deg>=8, -stalled, tag:piv. Tags and parameters are also edited in the property editor without going back to the code.

Both are stored with the figure in Protocol Buffers and in JSON; how they are encoded is described in the figure schema.