Overview

Vars are small data snippets you can attach to any novem plot. Each var has a raw value, a format, a type and a description — novem takes care of formatting and rendering them for you.

A single plot can hold many vars, each identified by a short id. Vars are great for surfacing the most important numbers alongside a visualisation: a top performer, a date, a return, a record high.

Structure #

plot_name                       => Name
├── data                        => Plot data
├── config                      => Configuration options
...
├── vars                        => Plot variables
│   └── :var_id                 => A single variable
│       ├── value               => Raw value (max 50 characters)
│       ├── about               => Description (max 250 characters)
│       ├── format              => Format string
│       ├── type                => Type indicator
│       └── threshold            => Threshold value (relative type only)
...

Each var lives under vars/:var_id where :var_id is a short identifier consisting of lowercase letters, digits, dashes and underscores (max 50 characters). For example top-ret, date, or hydro_pct.

Quick start #

Creating a var is a two step process: first create it with a PUT, then write its fields with POST.

# Create the var
curl -X PUT  .../vis/plots/my-plot/vars/top-ret

# Write fields
curl -X POST .../vis/plots/my-plot/vars/top-ret/value  -d "0.0589"
curl -X POST .../vis/plots/my-plot/vars/top-ret/about  -d "Return of top performer"
curl -X POST .../vis/plots/my-plot/vars/top-ret/format -d "+,.1%"
curl -X POST .../vis/plots/my-plot/vars/top-ret/type   -d "relative"

Once the value is written novem will format it and store the computed result. The formatted text is available at the uservis read endpoint:

curl .../users/trt/vis/plots/my-plot/vars/top-ret
# => ↑ +5.9%

Fields #

value #

The raw value of the variable as a plain string (max 50 characters). This is the value that gets formatted and colored.

0.0589

The value can be a number, a date string, a text label — whatever makes sense for your use case.

about #

A short human-readable description of what the variable represents (max 250 characters).

Return of the top performing S&P 500 stock

format #

The format string controls how the raw value is displayed. Novem supports several format families:

Text #

Use st to display the raw value as-is, without any formatting. Good for labels, names, tickers.

st

Numbers #

Novem supports the python format mini-language for numeric values.

The + prefix adds a sign character for positive values, which is useful for return or change values.

Scientific / SI #

Use the s suffix for SI notation. A single integer before the s controls precision.

Money #

Use the m suffix for monetary values. An optional currency symbol can be placed before or after the precision.

Dates #

Date values are formatted using strftime directives. The value should be a parseable date string.

type #

The type controls the directional indicator prepended to the formatted value. This is most useful for change or return values where you want a visual cue for positive vs. negative.

The indicator is chosen based on the numeric sign of the raw value.

For static values (prices, weights, temperatures, counts) use a non-indicator type like number. For labels use text, for dates use date. Any type not listed above simply means no indicator is prepended.

Example: a var with value 0.041, format +,.1% and type relative renders as ↑ +4.1%. The same var with type number renders as +4.1% without the indicator.

threshold #

The threshold field defines the reference point for the variable’s value. This field is only available when the var’s type is relative.

0

The threshold is used by the rendering layer to determine how to scale and color the value relative to this reference point.

The default threshold is 0.

Reading vars #

Listing #

To list all vars on a plot, read the vars/ directory:

# Own plots
GET /v1/vis/plots/:plot/vars/

# Other users' public/shared plots
GET /v1/users/:user/vis/plots/:plot/vars/

Reading a single var #

The uservis endpoint returns the formatted value_text:

GET /v1/users/:user/vis/plots/:plot/vars/:var
# => ↑ +5.9%

To read individual fields on your own plots:

GET /v1/vis/plots/:plot/vars/:var/value
GET /v1/vis/plots/:plot/vars/:var/about
GET /v1/vis/plots/:plot/vars/:var/format
GET /v1/vis/plots/:plot/vars/:var/type
GET /v1/vis/plots/:plot/vars/:var/threshold

Deleting a var #

DELETE /v1/vis/plots/:plot/vars/:var

This removes the var and all its history.

History #

Every time the value field is updated, novem takes a snapshot of the var’s computed metadata and appends it to a history log. This lets you track how a var changes over time — useful for daily returns, rolling metrics, or any value that gets updated periodically.

History is automatic; no extra configuration is needed. Writing to fields other than value (like about or format) does not create a history entry.

Examples #

Below are a few examples showing common var patterns.

Returns and changes #

For values that represent a directional change, use the relative type with a percentage format:

Static numbers #

For values that are measurements rather than changes, use number to omit the indicator:

Labels and dates #