<h1 align="center">Tidy Viewer (tv)</h1> <p align="center">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.</p>

Pretty Printing

Contents

• Features
• Installation
• Examples
• Documentation
• Significant Figure Definitions & Rules
• Tools to pair with tv
• Configuration Dotfile
• FAQ
• Help
• Inspiration

Features

1. Multi-format support: csv, parquet, feather, ipc
2. Automatic large file streaming: Automatic memory-efficient loading for large files (>5MB) 🚀
3. Colors: Nice colors out of the box
4. Significant digit printing: No more decimal dust taking valuable terminal space
5. NA comprehension & coloring: Missing data is clearly marked as NA for easy identification. No more misaligned data cells due to missing data.
6. Dimensions printed first: No more guessing how many rows and columns are in the data
7. Column overflow logic: No more misalignment due to terminal dimensions
8. Long string/Unicode truncation: No more long strings pushing other data around
9. Customizable with a dotfile config: Bring your own theme.

Installation

The following install options are available via package managers:

• Cargo
• Debian
• AUR
• Snap
• Homebrew

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.

1. Download your desired release from the release page
2. tar -xvzf <RELEASE_FILE_NAME>
3. cd into uncompressed folder
4. 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 logic
• tidy-viewer-cli - Command-line interface for direct file processing
• tidy-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.csv

Pigeon Racing

wget https://raw.githubusercontent.com/joanby/python-ml-course/master/datasets/pigeon-race/pigeon-racing.csv
cat pigeon-racing.csv | tv

Titanic

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.parquet

Significant 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:

1. lhs only (12345.0 -> 12345): If no fractional digits are present and lhs >= sigfig then return lhs
2. 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.
3. lhs + point + rhs (1.2345 -> 1.23): If fractional digits are present and lhs < sigfig return the first three digits of the number.
4. 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 interfac