Tidy Viewer (tv) is a cross-platform data pretty printer that uses column styling to maximize viewer enjoyment. Supports CSV, TSV, PSV, and Parquet files with streaming for large datasets.
Pretty Printing
Contents
- Features
- Installation
- Examples
- Documentation
- Significant Figure Definitions & Rules
- Tools to pair with
tv - Configuration Dotfile
- FAQ
- Help
- Inspiration
Features
- Multi-format support:
csv,parquet,feather,ipc - Automatic large file streaming: Automatic memory-efficient loading for large files (>5MB) 🚀
- Colors: Nice colors out of the box
- Significant digit printing: No more decimal dust taking valuable terminal space
- NA comprehension & coloring: Missing data is clearly marked as
NAfor easy identification. No more misaligned data cells due to missing data. - Dimensions printed first: No more guessing how many rows and columns are in the data
- Column overflow logic: No more misalignment due to terminal dimensions
- Long string/Unicode truncation: No more long strings pushing other data around
- Customizable with a dotfile config: Bring your own theme.
Installation
The following install options are available via package managers:
We currently cut releases for the following architectures. Download from the release page.
- MacOS
- ARM
- Windows
- Build from source (Most general)
The instructions for all of the above are very similar with the following general steps.
- Download your desired release from the release page
tar -xvzf <RELEASE_FILE_NAME>cdinto uncompressed folder- Find binary
tidy-viewer
After the above steps I would highly recommend you make an alias for tidy-viewer as shown for other builds.
Documentation
📚 Comprehensive documentation is available:
- 📖 API Documentation - Rust API reference with examples
- 🏗️ Contributing Guide - Architecture overview and development guidelines
- 🐍 Python Documentation - Python bindings usage and examples
Architecture Overview
Tidy-Viewer is organized as a Cargo workspace with three main components:
tidy-viewer-core- Shared core library with data type inference and formatting logictidy-viewer-cli- Command-line interface for direct file processingtidy-viewer-py- Python bindings using PyO3 for integration with Python workflows
This architecture ensures consistent behavior across all interfaces while maintaining clean separation of concerns.
Cargo
The following will install from the crates.io source. For convenience add the alas alias tv='tidy-viewer' to .bashrc.
cargo install tidy-viewer sudo cp /home/$USER/.cargo/bin/tidy-viewer /usr/local/bin/. echo "alias tv='tidy-viewer'" >> ~/.bashrc source ~/.bashrc
Debian
The below instructions work with the most recent release <VERSION> found here release page.
wget https://github.com/alexhallam/tv/releases/download/<VERSION>/tidy-viewer_<VERSION>_amd64.deb sudo dpkg -i tidy-viewer_<VERSION>_amd64.deb echo "alias tv='tidy-viewer'" >> ~/.bashrc source ~/.bashrc
AUR
Kindly maintained by @yigitsever
paru -S tidy-viewer
Snap
sudo snap install --edge tidy-viewer
Homebrew
brew install tidy-viewer
Examples
Have some fun with the following datasets!
CSV Data Examples
Diamonds
# Download the diamonds data wget https://raw.githubusercontent.com/tidyverse/ggplot2/master/data-raw/diamonds.csv # Note Powershell wget would look like this # Invoke-WebRequest https://raw.githubusercontent.com/tidyverse/ggplot2/master/data-raw/diamonds.csv -OutFile diamonds.csv # pipe to tv cat diamonds.csv | tv
Starwars
wget https://raw.githubusercontent.com/tidyverse/dplyr/master/data-raw/starwars.csv
# Pass as argument
tv starwars.csvPigeon Racing
wget https://raw.githubusercontent.com/joanby/python-ml-course/master/datasets/pigeon-race/pigeon-racing.csv
cat pigeon-racing.csv | tvTitanic
wget https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv # send to pager with color # less tv titanic.csv -ea | less -R # bat tv titanic.csv -a -n 1000 | bat -p
Parquet Data Examples
tv now supports Apache Parquet files!
NYC Taxi Data (Parquet)
# Download NYC taxi parquet data (small sample)
wget https://github.com/apache/arrow/raw/main/python/pyarrow/tests/data/v0.7.1.parquet
tv v0.7.1.parquetSignificant Figure Definitions And Rules
The first three digits represent > 99.9% the value of a number. -- GNU-R Pillar
Choosing the sigfigs amounts to how much of the value of a number is desired. The table below shows an example calculation with variable sigfigs.
| sigfigs | value | sigfiged_value | %value_of_the_number_explained_by_sigfiged_vale |
|---|---|---|---|
| 1 | 0.1119 | 0.1 | >89% |
| 2 | 0.1119 | 0.11 | >98% |
| 3 | 0.1119 | 0.111 | >99% |
tv uses the same significant figure (sigfig) rules that the R package pillar uses.
The purpose of the sigfig rules in tv is to guide the eye to the most important information in a number. This section defines terms and the decision tree used in the calculation of the final value displayed.
Definitions
┌─────┐ ┌─────┐ ─┐
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ │ ┌┐ │ │ │
└─────┘ └┘ └─────┘ ──┴─
│ │ │ │
└────────┘ ▲ └────────────────┘
left hand side │ right hand side
(lhs) │ (rhs)
decimal
left hand side (lhs): digits on the left hand side of the decimal.
right hand side (rhs): digits on the right hand side of the decimal.
┌─────┐ ┌─────┐ ─┐ ┌─────┐
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ │ ┌┐ │ │ │ │ │
└─────┘ └┘ └─────┘ ──┴─ └─────┘
│ │ │ │
└─────────────────────┘ └───────┘
leading 0s trailing 0s
leading 0s: 0s to the left of a non-zero.
trailing 0s: 0s to the right of a non-zero. The zeros in 500m are trailing as well as the 0s in 0.500km.
─┐ ┌─────┐ ─┐
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ ┌┐ │
──┴─ └─────┘ └┘ ──┴─
│ │
└────────┘
fractional digit(s)
fractional digits: Digits on the rhs of the decimal. The represent the non-integer part of a number.
Rules
There are only 4 outputs possible. The significant figures to display are set by the user. Assume sigfig = 3:
- lhs only (
12345.0 -> 12345): If no fractional digits are present and lhs >= sigfig then return lhs - lhs + point (
1234.5 -> 1234.): If fractional digits are present and lhs >= sigfig then return lhs with point. This is to let the user know that some decimal dust is beyond the main mass of the number. - lhs + point + rhs (
1.2345 -> 1.23): If fractional digits are present and lhs < sigfig return the first three digits of the number. - long rhs (
0.00001 -> 0.00001): This is reserved for values with leading 0s in the rhs.
# Pseudo Code: Sigfig logic assuming sigfig = 3
if lhs == 0:
n = ((floor(log10(abs(x))) + 1 - sigfig)
r =(10^n) * round(x / (10^n))
return r
// (0.12345 -> 0.123)
else:
if log10(lhs) + 1 > sigfig:
if rhs > 0:
//concatenate:
//(lhs)
//(point)
//(123.45 -> 123.)
else:
//concatenate:
//(lhs)
//(1234.0 -> 1234)
//(100.0 -> 100)
else:
//concatenate:
//(lhs)
//(point)
//sigfig - log10(lhs) from rhs
//(12.345 -> 12.3)
//(1.2345 -> 1.23)
Tools to pair with tv
tv is a good complement to command line data manipulation tools. I have listed some tools that I like to use with tv.
qsv - Fork of xsv. Has more commands/subcommands and allows users to evaluate lua/python on data. [Rust | CLI]
xsv - Command line csv data manipulation. [Rust | CLI]
SQLite - Database engine with CLU, shell, and library interfaces . [C | CLI/shell/lib]
DuckDB - Database engine with CLU, shell, and library interfaces . [C++ | CLI/shell/lib]
csvtk - Command line csv data manipulation. [Go | CLI]
tsv-utils - Command line csv data manipulation toolkit. [D | CLI]
q - Command line csv data manipulation query-like. [Python | CLI]
miller - Command line data manipulation, statistics, and more. [C | CLI]
VisiData - An interactive terminal user interface that is built to explore and wrangle data. [Python | TUI]
Tools similar to tv
column Comes standard with Linux. To get similar functionality run column file.csv -ts,
Though column is similar I do think there are some reasons tv is a better tool.
1. NA comprehension
NA values are very important! Viewers should have their attention drawn to these empty cells. In the image below NA values are not only invisible, but it seems to be causing incorrect alignment in other columns.
There are many ways that programs will designate missing values. Some use none, others use NaN, and many more "", NA, null, n/a etc. tv searches for these strings and replaces them with NA. This is similar in spirit to the significant digit calculations and the truncation of columns with long strings. The purpose of tv is not to show the complete literal value, but to guide the eye.
2. Column Overflow Logic
In cases where the terminal width can't fit all of the columns in a dataframe, column will try to smush data on the rows below. This results in an unpleasant viewing experience.
tv can automatically tell when there will be too many columns to print. When this occurs it will only print the columns that fit in the terminal and mention the extras in the footer below the table.
Configuration Dotfile
For information on dotfile configuration see tv --help. This allows users to set their own color palette, rows to print, max column width, etc.
FAQ
- Does
tvhave a light theme?
Yes, solorized light is added out of the box. This was added in version
1.4.6. You may also define your own themes in the config.
- The
~/.config/tv.tomlfile is having no effect on the output. What am I doing wrong?
Every key/value pair must exist or the toml will not be read. If even one key/value is missing then the config will not work.
- It would be nice to be able to scroll vertically/horizontally through tall/wide csv file. Does
tvallow for this functionality?
Yes, pipe the output to
lessorbat.tvallows for this with the-eflag. To extend to the full csv width and length and keep color try the followingtv diamonds.csv -ea | less -SRTo extend to the full csv width and length and remove all color try the followingtv diamonds.csv -e | less -S
Help
tv --help