Visualizing Data in Terminal with Termgraph
Introduction
Termgraph is a Python-based command-line tool that creates basic graphs directly in your terminal. Designed for developers and data enthusiasts, it supports various chart types including:
- Bar graphs (horizontal/vertical)
- Multi-variable charts
- Stacked bar charts
- Histograms
- Calendar heatmaps
Installation & Setup
Install using pip:
Paste the following code on your terminal
pip3 install termgraph
Install fom PyPI project
Requirements:
- Python 3.7+
- colorama package
To check if termgraph has been installed correctly on your system
Paste the following code on your terminal:
termgraph --version
And if something like this comes in the output, you are good to go!
Usage
Create data file with two columns either comma(.csv) or space(.dat) separated. The first column is your labels, the second column is a numeric data
After that run the following code on command line.
termgraph [datafile]
For help:
termgraph -h
Key Features
Core Visualization Capabilities
- Bar Charts: Implements proportional scaling algorithms for dynamic width adjustment.
- Histograms: Uses binning algorithms with Sturges' formula or manual bin settings (--bins parameter) for flexible data grouping.
- Stacked Graphs: Supports layered composition with Unicode block elements, offering absolute and percentage-based accumulation.
- Heatmap Calendars: Processes date-stamped data into grid layouts, using Julian day calculations for structured alignment (--start-dt).
Input Processing Subsystem
- File-Based Parsing: Supports space/comma-delimited formats, automatic type inference, categorical labeling, and NaN handling.
- STDIN Pipeline: Buffered stream reader enables real-time plotting and integration with the watch command.
- Robust Error Handling: Implements 23 validation checks to ensure format consistency and value bounds.
Customization Framework
- Aesthetic Modifiers: Unicode/emoji tick replacements (--custom-tick), ANSI color mapping (--color), and vertical spacing controls (--space-between).
- Layout Controllers: Adjustable width (--width), vertical orientation toggles, and multi-column formatting for datasets with disparate ranges (--different-scale).
- Performance Optimization: Efficient rendering, with bar charts processing 10,000 data points in 87ms and heatmaps in 220ms.
Code Examples
Bar Chart
Basic Bar Chart:
termgraph student_marks.txt
Some common arguments -
- '--title' TITLE: Used to give a title to the graph
-
'--space-between' : Adds a blank line between bars for better readability.
For example
termgraph --title 'Student Marks' --space-between student_marks.txt
And for the given dataset the following output will be shown
More common arguments -
- '--suffix' SUFFIX: Adds a suffix to all the values at the end of the bars eg. %,kg,m etc.
-
'--color [COLOR ...]': It is used to set the colors of the bars.You can specify multiple colors for different categories. Available colors are 'red', 'blue', 'green', 'magenta', 'yellow', 'black', 'cyan'.
For example
termgraph student_marks.txt --color [blue] --suffix '%'
And for the above given dataset the following output will be shown
Optional Arguments -
-
--format FORMAT: Sets the format specifier for the labels (e.g., decimal places).Example the format specifier "{:.1f}" rounds off all the values to first decimal place.
-
--label-before: Displays values before the bars instead of after
-
--no-values: Hides the values displayed at the end of bars.
-
--width WIDTH : Used to adjust the width of the graph (default width is 50)
Custon Ticks and DELIM-
-
--custom-tick CUSTOM_TICK: Used to create custom ticks instead of the bars in the graph. These ticks can also be emojis.
-
--delim DELIM: It specifies the delimiter in the data file. The default delimiter is space or comma.
termgraph --delim '|' --custom-tick '😀' vowel_data.txt
And for the given dataset the following output will be shown
Stacked
--stacked: It creates a stacked bar graph in which all the categories of a single field are summed and represented by a single bar.
For example
termgraph website_data.txt --color [yellow,green]
And in the above code --stacked has not been used so, for the given dataset the following output will be shown
And with using stacked
termgraph --stacked --space-between website_data.txt
Histogram
- --histogram: Creates a histogram from the given data instead of a simple bar graph
- --bins BINS :It takes an integer n and classifies the data into n equal intervals for making the histogram.
For example
termgraph --histogram --color 'magenta' --bins 6 histogram_data.txt
And for the given dataset the following output will be shown
Calendar
- --calendar: It displays the data as a calendar heatmap in which months are displayed on the horizontal axis and days of week on vertical axis. The first column of the data file should contain dates in the yyyy-mm-dd format.
- --start-dt START_DT: It sets the start date for the calendar heatmap.
termgraph --calendar --start-dt 2024-01-05 cal_data.txt
And for the given dataset the following output will be shown
Use Cases
Using To Quickly Visualize:
- Monthly or quarterly sales figures
- Comparing budget allocations
- Comparing different experimental conditions
Quick Visualization Of Performance Metrics: Termgraph can be used to visualize performance metrics directly in the terminal. For example
- Displaying CPU or memory usage over time
- Illustrating disk I/O statistics
Conclusion
Termgraph fills a unique niche for terminal-based data visualization, offering surprising flexibility through its various chart types and customization options. While not a replacement for GUI tools, it excels in quick debugging and server environments.
References