Recipes/Cookbook

This chapter collects practical workflows that combine uplot with common shell tools. Each recipe shows a complete pipeline you can adapt to your own data.

Plotting a CSV file

The most common task is visualizing columns from a CSV file. Use -H for headers and -d, for comma delimiters:

uplot hist -H -d, < data.csv
uplot lines -H -d, < data.csv
uplot box -H -d, < data.csv

For tab-separated files, you can omit the -d flag entirely since tab is the default delimiter:

uplot line < measurements.tsv

Combining with awk and cut

Shell tools like awk and cut are useful for selecting and transforming columns before plotting. For example, to plot only the second and fourth columns of a CSV:

cut -d, -f2,4 data.csv | uplot line -d,

Or to compute a derived value and plot it:

awk -F, '{print $1, $2 * $3}' data.csv | uplot line

You can generate data entirely from shell arithmetic:

seq 100 | awk '{print sin($1/10)}' | uplot line -t "Sine wave"

Multi-series overlay

When your data has a shared x column and multiple y columns, lines overlays all series with automatic color assignment:

uplot lines -H -d, -t "All Variables" < iris.csv

Each column gets its own color and appears in the legend with its header name. To compare specific columns, use cut or awk to select only the ones you want:

cut -d, -f1,2,3 iris.csv | uplot lines -H -d, -t "Sepal vs Petal Length"

Customizing appearance

Combine layout flags to produce a plot tailored to your terminal width and presentation needs:

uplot line -w 60 -h 20 -b corners -m 5 --padding 2 \
    -t "CPU Temperature" --xlabel "Time (s)" --ylabel "Temp (C)" \
    < temperatures.tsv

To use a specific canvas type and disable grid lines for a cleaner look:

uplot scatter --canvas block --no-grid -H -d, < measurements.csv

For histograms, you can control the number of bins and use a custom fill character:

uplot hist -n 20 --symbol '#' -H -d, < data.csv

Using output routing for scripts

In scripted workflows, you often want to both visualize data and pass it along for further processing. The -O flag enables this tee-like behavior:

generate-data | uplot line -O | aggregate-results

Here, the plot appears on stderr (visible in your terminal) while the raw data passes through stdout to the next pipeline stage.

To save a plot to a file for later review while still seeing it on the terminal:

cat data.tsv | uplot line -o plot.txt

This writes the rendered plot (including ANSI color codes by default) to plot.txt. Use -M to strip colors for a plain-text version:

cat data.tsv | uplot line -o plot.txt -M

To save both the plot and the data to separate files:

cat data.tsv | uplot line -o plot.txt -O data-copy.tsv

Counting and sorting categorical data

The count command is useful for quick frequency analysis of log files, command output, or any categorical data:

# Count HTTP status codes from an access log
awk '{print $9}' access.log | uplot c -t "HTTP Status Codes"

# Count file extensions in a directory tree
find . -type f | awk -F. '{print $NF}' | uplot c -t "File Extensions"

# Reverse sort to see least common values first
awk '{print $1}' data.tsv | uplot c -r

Transposed data

When your data is arranged with series in rows rather than columns, use -T to transpose before plotting:

# Input: each row is a named series
# temperature  22  24  23  25  26
# humidity     45  50  48  52  55
uplot lines -T -H < wide-format.tsv

The -T flag swaps rows and columns, and -H uses the first column as series names after transposing.

Encoding conversion

For non-UTF-8 files, specify the encoding directly:

uplot scatter -H -d, --encoding UTF-16 < data-utf16.csv
uplot hist -H -d, --encoding Shift_JIS < japanese-data.csv

The input is decoded to UTF-8 before parsing, so all delimiter and header handling works as expected regardless of the source encoding.