Chart

The chart file allows you to add horizontal bar charts inside table cells. This is useful for visualizing relative values, progress indicators, or diverging data directly within your table.

Chart instructions follow the standard novem slicing syntax with additional parameters for chart type and scale configuration.

Note: Bar charts completely replace the cell content. The numeric value is not displayed alongside the bar - only the bar itself is shown. If you need to display values, consider using a separate column.

Instruction Format

row_slice col_slice chart_type [scale_spec] [opts]

Where:

• row_slice: Row selector (standard slicing syntax)
• col_slice: Column selector (standard slicing syntax)
• chart_type: Currently only hbar (horizontal bar) is supported
• scale_spec: Optional scale configuration in the format (min,max)^scale or (min,mid,max)^scale
• opts: Optional flags:
  • l - display value labels
  • h - hide center divider (for diverging bars)

Scale Specification

The scale specification defines how values are mapped to bar widths:

 (0,100)^lin      -- Simple scale from 0 to 100, linear
 (_,_)^lin        -- Auto-detect min and max from data
 (_,0,_)^lin      -- Diverging scale with 0 as midpoint (auto min/max)
 (-50,0,50)^lin   -- Explicit diverging scale

Special values:

• _ - Auto-detect from data (min, max, or both)
• Any number - Explicit value for that position

Scale types:

• lin - Linear scale (currently the only supported scale type)

Simple Horizontal Bars

Simple bars grow from left to right based on the value's position within the specified range.

 1:   1   hbar  (0,100)^lin   -- Add bars to data rows, column 2
                               -- Scale from 0 to 100

Values are normalized to the range:

• A value of 0 produces no bar
• A value of 100 produces a full-width bar
• Values outside the range are clamped

Auto-Range Bars

Let novem automatically determine the range from your data:

 1:   1:  hbar  (_,_)^lin     -- Auto-detect min and max from the data
                               -- Applies to all data rows and columns

This is useful when you don't know the data range in advance or want bars to always fill the available space proportionally.

Diverging Bars

Diverging bars are ideal for showing positive and negative values, year-over-year changes, or any data with a meaningful midpoint.

When a midpoint is specified, bars grow in opposite directions:

• Values below the midpoint grow left from center
• Values above the midpoint grow right from center
• A vertical divider marks the midpoint

 1:   1   hbar  (_,0,_)^lin   -- Diverging bars with 0 as midpoint
                               -- Min and max auto-detected from data

This is particularly effective for displaying:

• Year-over-year percentage changes
• Profit/loss figures
• Sentiment scores
• Any metric with positive and negative values

Combining with Colors

Chart bars inherit colors from the dynamic color configuration. When both chart and color instructions target the same cells, the bar will be rendered in the foreground color specified by the color config.

 1:   1:  hbar  (_,0,_)^lin   -- Add diverging bars

 1:   1:  fg  bad,neutral,good(_,0,_)^lin  -- Color bars by value

This creates bars that are colored based on their value - red for negative, gray for neutral, and green for positive (using the bad/neutral/good palette).

Multiple Chart Instructions

You can apply different chart configurations to different parts of your table:

 1:   1   hbar  (0,100)^lin   -- Progress bars for column 2
 1:   2   hbar  (_,0,_)^lin   -- Diverging bars for column 3

Instructions are processed in order from top to bottom. Later instructions override earlier ones for overlapping cells.

Labels

You can display the formatted cell value as a label within the bar by adding the l flag after the scale specification:

 1:   1   hbar  (0,100)^lin  l    -- Bars with value labels
 1:   2   hbar  (_,0,_)^lin  l    -- Diverging bars with labels

Label positioning:

• By default, labels appear outside the bar for small bars (< 50%) and inside the bar for larger bars (>= 50%)
• Labels inherit text formatting (font, size, bold, etc.) from the cell
• Labels use color: inherit to work with any background

Alignment overrides:

When alignment is applied to the cell, it controls label positioning:

Labels respect the cell's overflow rules - use ellipsis/truncation as needed.

Hiding the Center Divider

Diverging bar charts display a 1-pixel vertical line at the midpoint (center) to visually separate positive and negative values. You can hide this divider by adding the h flag:

 1:   1   hbar  (_,0,_)^lin  h     -- Diverging bars without center divider
 1:   2   hbar  (_,0,_)^lin  lh    -- Diverging bars with labels, no divider

The h flag only affects diverging bars (those with a midpoint). Simple bars don't have a center divider, so the flag has no effect on them.

You can combine l and h in any order: lh, hl, or as separate words l h all work the same way.

Hiding labels with blank text style:

If you want bar charts with the l flag but need to hide specific labels, use the - (blank) text style. This hides the formatted value while preserving the bar chart calculation:

 1:   1   hbar  (0,100)^lin  l    -- Bars with labels

 1:   1   -                       -- Hide labels in column 2

This shows the bar but not the numeric label - useful when space is limited or you want a cleaner visual appearance.

Terminal Output

Bar charts are fully supported in terminal/ANSI output. When viewing tables via novem -p plot_name -x or through the API's ANSI endpoint, bars are rendered using Unicode block characters for half-character precision. Note that labels are only supported in HTML output, not terminal output.

Complex Layout

Combining charts with merging, colors, width constraints, and text formatting allows for sophisticated dashboard-style tables.