Specifiers

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

Reading just 10 under the label ‘Carrots sold’ doesn’t relly 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, that you can communicate via Toucan’s specifiers.

Specifiers types

Available specifiers are:

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

Specifiers configuration

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.

A good explanation for this would be to imagine representing the same data with two different visualizations. The values would stay the same in the two charts, and so would their unit, precision and so on.

Specifiers are applied by column.

In the studio, when editing a story, click on the column header to view or set specifiers:

Specifiers for a column

Specifiers for a column

Note

Only unit and precision are available for now in the studio.

Clicking on Configure <specifier type> will allow you to specify the specifier for this column:

Entering a unit for a column

Entering a unit for a column

Saving your changes will update how the data is displayed:

Visualizing the unit

Visualizing the unit

In code mode, this is equivalent to adding the block units to the dataset block, and specifying on which column it applies.

datasets:
  my_dataset:
    query:
      domain: "my_domain"
    units:
      value: " cm"

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)

Note

Currencies are not units! Use the precision specifier (see below) to format your values in a financial way.

Precision

Precision controls how to display a value without lying about how it has been measured.

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 idea is to indicate how the value should be assessed against some breakpoints.

Note

This is only available in code mode for now!

Available sentiments

Four sentiments are avalaible:

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

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:

sentiment:
  value:
    domain: [ 0 ]
    range: ["negative", "positive"]

The domain represents the breakpoint of the sentiment, and the range the sentiments that span around this point.

Here is a visual representation of this: Simple sentiment scale

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 in the domain.

sentiment:
  grade:
    domain: ["target"]
    range: ["negative", "positive"]
person grade target value sentiment
Alice 12 10 -> positive
Bob 13 15 -> negative

It’s also possible to indicate small computations on column values:

sentiment:
  grade:
    domain: ["0.5 * target", "0.8 * target", "target"]
    range: ["negative", "warning", "neutral", "positive"]
person grade target grade sentiment
Alice 12 10 -> positive
Bob 13 15 -> neutral

More complex rules

Some datasets, particularly when they contain multiple data types, must have different specifiers in the same column.

To achieve this, click “Switch to advanced configuration”: Advanced configuration button

Depending on another column

An example would be a dataset where a value column corresponds to different metrics:

label value value_type
Alice 3 volume
Alice -0.1 rate

In this example, we would like to associate the unit " u" to the volume and no unit to the rate.

Unit depending of a column

Unit depending of a column

label value value_type value unit
Alice 3 volume -> u
Alice -0.1 rate ->

In code mode, this corresponds to:

query:
  domain: "sample-value-types"
units:
  value:
    value_type:
      volume: " u"
      rate: "" # This last line is optional, as the default is no unit

Depending on multiple columns

Given this data:

label value value_type
Alice 3 volume
Alice -0.1 rate
Bob 2 volume
Bob 0.1 rate

In this example, we would like to associate the unit " uA" to Alice’s volume and " uA" to Bob’s volume.

Unit depending of multiple columns

Unit depending of multiple columns

label value value_type value unit
Alice 3 volume -> uA
Alice -0.1 rate ->
Bob 2 volume -> uB
Bob 0.1 rate ->

In code mode, this corresponds to:

query:
  domain: "sample-value-types"
units:
  value: [
    {
      where:
        value_type: "volume"
        label: "Alice"
      unit: " uA"
    }
    {
      where:
        value_type: "volume"
        label: "Bob"
      unit: "uB"
    }
  ]

Is written in another column

When the specifier is directly embedded in a column, with the data, it’s enough to just specify this column:

label value value_type value_unit
Alice 3 volume uA
Alice -0.1 rate  
Bob 2 volume uB
Bob 0.1 rate  
Unit written in another column

Unit written in another column

In code mode, this corresponds to:

query:
  domain: "sample-value-types"
units:
  value: "value_unit"