Terminal Line Plot
Use this skill to turn numeric sequences into terminal-readable line charts.
It is task-agnostic: do not assume any domain, metric direction, filtering rule,
or data layout unless the user or artifacts define it.
Workflow
- Identify the series to plot:
- x values are usually ordered steps, dates, versions, generations, epochs, or run ids.
- y values must be numeric.
- If multiple plausible metrics exist, choose the one the user asked for; otherwise state the selected metric before plotting.
- Preserve metric semantics:
- Use exact metric names from artifacts when available.
- Label whether higher or lower is better if known.
- Do not mix partial and complete points silently; mark provisional or incomplete points in the title, notes, or point list.
- Use
scripts/plot_series.py for deterministic plotting.
- Print a compact table or point list when it prevents misreading the curve.
- Do not write image files unless the user explicitly asks. Prefer stdout.
Script Usage
Run the bundled script from the skill directory:
python /path/to/terminal-line-plot/scripts/plot_series.py \
--points "0:-4.49,1:-4.53,2:-4.87,3:-4.77,4:-3.23" \
--title "Best future_fitness by generation" \
--x-label generation \
--y-label future_fitness \
--higher-better
Input options:
--points "x:y,x:y,..." for quick point lists.
--csv FILE --x-field FIELD --y-field FIELD for CSV.
--json FILE --x-field FIELD --y-field FIELD for JSON arrays of objects, arrays of pairs, or mappings.
--stdin csv|json|points to read data from stdin.
Useful options:
--height N controls chart height.
--x-step N controls horizontal spacing between points.
--provisional-x X may be repeated to mark incomplete points with ○.
--value-table prints the plotted values below the chart.
--invert-y-note only changes the note; it does not invert the axis.
Plotting Guidelines
- Prefer line drawing characters
●, ○, ╱, ╲, and ─.
- Keep the x-axis readable. If labels collide, increase
--x-step or plot fewer points.
- Use a taller chart for noisy or close-valued curves.
- For negative scores where "higher is better", the visually higher point should still mean numerically larger.
- If the active/final point is incomplete, mark it provisional and do not draw conclusions from it.
- For dense data, aggregate intentionally: best per generation, mean per epoch bucket, rolling median, or another stated rule.
Example Patterns
Manual points:
python /path/to/terminal-line-plot/scripts/plot_series.py \
--points "0:7.88,1:7.78,2:8.45,3:8.61,4:9.28" \
--title "Mean objective value by generation" \
--y-label "objective" \
--value-table
CSV:
python /path/to/terminal-line-plot/scripts/plot_series.py \
--csv metrics.csv \
--x-field generation \
--y-field score \
--title "Score by generation"
JSON:
python /path/to/terminal-line-plot/scripts/plot_series.py \
--json metrics.json \
--x-field gen \
--y-field best_score
1---2name: terminal-line-plot3description: Draw readable ASCII line charts directly in the terminal from numeric series, command output, CSV, JSON, or manually extracted points. Use when the user asks for a curve, trend line, score progression, leaderboard trend, metric history, or any plot that should be visible in a CLI/chat transcript without opening a GUI or writing image files.4metadata:5 source: https://skillmd.com/skills/sapientinc/terminal-line-plot6---78# Terminal Line Plot910Use this skill to turn numeric sequences into terminal-readable line charts.11It is task-agnostic: do not assume any domain, metric direction, filtering rule,12or data layout unless the user or artifacts define it.1314## Workflow15161. Identify the series to plot:17 - x values are usually ordered steps, dates, versions, generations, epochs, or run ids.18 - y values must be numeric.19 - If multiple plausible metrics exist, choose the one the user asked for; otherwise state the selected metric before plotting.202. Preserve metric semantics:21 - Use exact metric names from artifacts when available.22 - Label whether higher or lower is better if known.23 - Do not mix partial and complete points silently; mark provisional or incomplete points in the title, notes, or point list.243. Use `scripts/plot_series.py` for deterministic plotting.254. Print a compact table or point list when it prevents misreading the curve.265. Do not write image files unless the user explicitly asks. Prefer stdout.2728## Script Usage2930Run the bundled script from the skill directory:3132```bash33python /path/to/terminal-line-plot/scripts/plot_series.py \34 --points "0:-4.49,1:-4.53,2:-4.87,3:-4.77,4:-3.23" \35 --title "Best future_fitness by generation" \36 --x-label generation \37 --y-label future_fitness \38 --higher-better39```4041Input options:4243- `--points "x:y,x:y,..."` for quick point lists.44- `--csv FILE --x-field FIELD --y-field FIELD` for CSV.45- `--json FILE --x-field FIELD --y-field FIELD` for JSON arrays of objects, arrays of pairs, or mappings.46- `--stdin csv|json|points` to read data from stdin.4748Useful options:4950- `--height N` controls chart height.51- `--x-step N` controls horizontal spacing between points.52- `--provisional-x X` may be repeated to mark incomplete points with `○`.53- `--value-table` prints the plotted values below the chart.54- `--invert-y-note` only changes the note; it does not invert the axis.5556## Plotting Guidelines5758- Prefer line drawing characters `●`, `○`, `╱`, `╲`, and `─`.59- Keep the x-axis readable. If labels collide, increase `--x-step` or plot fewer points.60- Use a taller chart for noisy or close-valued curves.61- For negative scores where "higher is better", the visually higher point should still mean numerically larger.62- If the active/final point is incomplete, mark it provisional and do not draw conclusions from it.63- For dense data, aggregate intentionally: best per generation, mean per epoch bucket, rolling median, or another stated rule.6465## Example Patterns6667Manual points:6869```bash70python /path/to/terminal-line-plot/scripts/plot_series.py \71 --points "0:7.88,1:7.78,2:8.45,3:8.61,4:9.28" \72 --title "Mean objective value by generation" \73 --y-label "objective" \74 --value-table75```7677CSV:7879```bash80python /path/to/terminal-line-plot/scripts/plot_series.py \81 --csv metrics.csv \82 --x-field generation \83 --y-field score \84 --title "Score by generation"85```8687JSON:8889```bash90python /path/to/terminal-line-plot/scripts/plot_series.py \91 --json metrics.json \92 --x-field gen \93 --y-field best_score94```