Tidy Viewer (tv) is a cross-platform csv pretty printer that uses column styling to maximize viewer enjoyment.

• Features
• Installation
• Examples
• Significant Figure Definitions & Rules
• Tools to pair with tv
• Configuration Dotfile (Coming Soon!)
• Help
• Inspiration

1. Nice colors out of the box
2. Significant digit printing (no more decimal dust taking valuable terminal space)
3. NA comprehension and coloring (no more misaligned data cells due to missing data)
4. Dimensions printed first (no more guessing how many rows and columns are in the data)
5. Column overflow logic (no more misalignment due to terminal dimensions)
6. Long string/Unicode truncation (no more long strings pushing other data around)
7. Customizable with a dotfile config (bring your own theme)

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.

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

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

Kindly maintained by @yigitsever

paru -S tidy-viewer

sudo snap install --edge tidy-viewer

brew install tidy-viewer

Have some fun with the following datasets!

# Download the diamonds data
wget https://raw.githubusercontent.com/tidyverse/ggplot2/master/data-raw/diamonds.csv

# pipe to tv
cat diamonds.csv | tv

wget https://raw.githubusercontent.com/tidyverse/dplyr/master/data-raw/starwars.csv

# Pass as agrument
tv starwars.csv

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

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

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.

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.

     ┌─────┐      ┌─────┐     ─┐
     │     │      │     │      │
     │     │      │     │      │
     │     │      │     │      │
     │     │      │     │      │
     │     │  ┌┐  │     │      │
     └─────┘  └┘  └─────┘    ──┴─
   │        │    │                │
   └────────┘  ▲ └────────────────┘
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.

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.

# Psuedo 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)

tv is a good complement to command line data manipulation tools. I have listed some tools that I like to use with tv.

xsv - Command line csv data manipulation. [Rust | CLI]

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]

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.

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.

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.

For information on dotfile configuration see tv --help. This allows users to set their own color palette, rows to print, max column width, etc.

tv --help

tv 1.4.4
Tidy Viewer (tv) is a csv pretty printer that uses column styling to maximize viewer enjoyment.✨✨📺✨✨

    Example Usage:
    wget https://raw.githubusercontent.com/tidyverse/ggplot2/master/data-raw/diamonds.csv
    cat diamonds.csv | head -n 35 | tv

    Configuration File Support:
    An example config is printed to make it easy to copy/paste to `tv.toml`.
    The config (tv.toml) location is dependent on OS:
        * Linux: $XDG_CONFIG_HOME or $HOME/.config/tv.toml
        * macOS: $HOME/Library/Application Support/tv.toml
        * Windows: {FOLDERID_RoamingAppData}\tv.toml

        ## ==Tidy-Viewer Config Example==
        ## Remove the first column of comments for valid toml file
        ## The delimiter separating the columns. [default: ,]
        #delimiter = ","
        ## Add a title to your tv. Example 'Test Data' [default: NA ("")]
        #title = ""
        ## Add a footer to your tv. Example 'footer info' [default: NA ("")]
        #footer = ""
        ## The upper (maximum) width of columns. [default: 20]
        #upper_column_width = 20
        ## The minimum width of columns. Must be 2 or larger. [default: 2]
        #lower_column_width = 2
        ## head number of rows to output <row-display> [default: 25]
        #number = 35
        ## extend rows beyond term width (do not trucate) [default: false]
        # extend_rows = true
        ## meta_color = [R,G,B] color for row index and "tv dim: rowsxcols"
        #meta_color = [64, 179, 162]
        ## header_color = [R,G,B] color for column headers
        #header_color = [232, 168, 124]
        ## std_color = [R,G,B] color for standard cell data values
        #std_color = [133, 205, 202]
        ## na_color = [R,G,B] color for NA values
        #na_color = [226, 125, 95]
        ## neg_num_color = [R,G,B] color for negative values
        #neg_num_color = [226, 125, 95]

USAGE:
    tidy-viewer [FLAGS] [OPTIONS] [FILE]

FLAGS:
    -d, --debug-mode      Print object details to make it easier for the maintainer to find and resolve bugs.
    -e, --extend-rows     Extended row beyond term width (do not truncate). Useful with `less -S`.
    -a, --color-always    Always force color output. Example `tv -a starwars.csv | less -R` or `tv -a starwars.csv | bat
                          -p`. The `less` cli has the `-R` flag to parse colored output.
    -h, --help            Prints help information
    -V, --version         Prints version information

OPTIONS:
    -c, --color <color>
            There are 5 preconfigured color palettes:
                            (1)nord
                            (2)one_dark
                            (3)gruvbox
                            (4)dracula
                            (5)uncolor (Coming Soon)
            An input of (5)uncolor will remove color properties. Note that colors will make it difficult to pipe output
            to other utilities.The default value of (0) is reserved to make config/option coloring logic easier.
            [default: 0]
    -s, --delimiter <delimiter>                      The delimiter separating the columns.
    -f, --footer <footer>                            Add a footer to your tv. Example 'footer info' [default: NA]
    -l, --lower-column-width <lower-column-width>
            The lower (minimum) width of columns. Must be 2 or larger. [default: 2]

    -n, --number of rows to output <row-display>     Show how many rows to display. [default: 25]
    -g, --sigfig <sigfig>                            Significant Digits. Default 3. Max is 7 [default: 3]
    -t, --title <title>                              Add a title to your tv. Example 'Test Data' [default: NA]
    -u, --upper-column-width <upper-column-width>    The upper (maximum) width of columns. [default: 20]

ARGS:
    <FILE>    File to process

pillar - R's tibble like formatting. Fantastic original work by Kirill Müller and Hadley Wickham. tv makes an attempt to port their ideas to the terminal.