How to use specifiers :: units, precision and sentiment¶

Overview¶

Reading just 10 under the label Carrots sold doesn’t really help you understand anything. But knowing that this value is expressed in kg/day (unit), is precise to the gram 10.000 and that it’s better than expected (positive sentiment) makes it more understandable.

This is the type of info that you may know about the data but doesn’t appear in any file. You can use Toucan specifiers to communicate context about your value.

We call specifiers little pieces of info on a data cell that are necessary to understanding it.

Specifiers types Available specifiers are:

units: more precisely units of measurement
precision: how to format the value correctly
sentiment: a color coding associated to this value

Note

Specifiers are declared directly in the data. They live there because it’s a property of the data, not from a particular visualization of it.
When applying a sentiment and a precision on the same column, the sentiment will be based on the raw data (not the data after applying the precision).
Currencies are not units! Use the precision specifier (see below) to format your values in a financial way.
In a tile, you can set up a sentiment only for one of your columns

Units

Not much to say about them! Just input what you want displayed next to the unit.

Two tips though:

you can add a space before the unit if necessary
percentage is not a unit of measurement (see the precision specifier below to know how to display this correctly)

Precision

Precision controls how to display a value.

Precision configurations are text strings. They look like ",.2f" or ".0%". To know how to construct them, have a look at d3-format’s documentation.

A few examples for the value 1000:

".0f": Means no (0) decimal position, f for fixed precision. This is suited for integer quantities, and would be displayed like this: 1000.
",.2f": Means 2 decimal positions, and still fixed precision for float, with a character , to separate thousands. This is a nice format for currencies, displayed like this: 1,000.00. The symbols adapts with the chosen language. In French locale, that would be: 1 000,00.
".0%": Means no (0) decimal position, % for percentage format. A percentage of 100% is the value 1, so our value 1000 would be displayed 100000%. Note that the percentage symbol is added automatically.
"$" : Means that the currency symbol will be displayed along the value
".2K" : (from v58.1+) K means that locale currency abbreviations will be used (in english, K for thousands, M for millions, B for billions, T for trillions). 2 indicates the number of significant digits to keep

Recap:

Raw value	Precision specifier	Formatted value
`1000`	`".0f"`	`1000`
`1000`	`",.2f"`	`1,000.00` (en)
`1000`	`".0%"`	`100000%`
`1000`	`"$"`	`$ 1000`
`1000`	`"$.2f"`	`$ 1000.00`
`1000`	`"$.2K"`	`$ 1.0 K` (en)

Sentiment

Sentiment is a bit different, it’s not a small set of characters but it’s a scale. The scale will be represented by color coding. The idea is to indicate how the value should be assessed against some breakpoints.

Available sentiments Four sentiments are available:

"positive": generally associated to green
"negative": generally associated to red color
"neutral": generally associated to black or gray
"warning": generally associated to orange

Here we go Cow-boy/girl, in the nexts steps you are going to see how to use the specifiers like a Boss ;)

How to use specifiers :: units & precision

Step 1: In the studio, when editing a story, in Dataset viewer of Chart type menu, click on the column header to view or set specifiers:

Step 2: Clicking on Configure will allow you to specify the specifier for this column:

Saving your changes will update how the data is displayed:

How to use specifiers :: units & precision in advanced configuration mode

Step 1: In the studio, when editing a story, in Dataset viewer of Chart type menu, click on the column header to view or set specifiers:

Step 2: Clicking on Configure will allow you to specify the specifier for this column:

Step 3: Clicking on “Or switch to advanced configuration” will allow you to access in advanced configuration mode.

Step 4: Choose one of the options, here we are going to configure units from another column called “unit”:

Saving your changes will update how the data is displayed:

How to use specifiers :: sentiment

Step 1: In the studio, when editing a story, in Dataset viewer of Chart type menu, click on the column header to view or set specifiers:

Step 2: Clicking on Configure sentiment will allow you to specify the color coding for this column:

Step 3.1: Sentiment around a fixed value

A simple case would be to consider a value as positive if it’s above 0, and as negative under:

Step 3.2: Sentiment with multiple fixed values

A simple case would be to consider a value as positive if it’s above 1, a neutral step between 0 and 1, warning between 0 and -1, and negative under -1:

Then add a new “bound” by clicking on the line, repeat this step as many times as you wish.

Step 3.3: Sentiment towards another column

In other cases, we might want our breakpoints to vary depending on the data row. This can be done by setting our breakpoint to depend on a data column. Given this data:

person	grade	target
`Alice`	`12`	`10`
`Bob`	`13`	`15`

Comparing their value to their different targets, we want Alice to feel satisfied but not Bob. This can be expressed by indicating the column “target” as a breakpoint.

Saving your changes will update how the data is displayed:

How to use specifiers :: sentiment in advanced configuration mode

Note

In this exercise, I want to apply a sentiment on the “evolution” that will vary according to the values of “country” column. Because the value differs according to the country (demography, …).

Step 1: In the studio, when editing a story, in Dataset viewer of Chart type menu, click on the column header to view or set specifiers:

Step 2: Clicking on Configure sentiment will allow you to specify the sentiment for this column:

Note

I would like to add a sentiment for France with a bound at 50, for Italie at 45 and for others countries at 30.

Step 3: Clicking on “Or switch to advanced configuration” will give you access to the advanced configuration mode.

Saving your changes will update how the data is displayed:

Need more? Let us know!