整理查看器 (tv)

整理查看器 (tv) 是一个跨平台的 CSV 美化打印器，使用列样式来最大化观看体验。

美化打印

内容

• 功能
• 安装
• 示例
• 有效数字定义与规则
• 与 tv 配对的工具
• 配置点文件
• 常见问题解答
• 帮助
• 灵感

功能

1. 开箱即用的漂亮颜色
2. 有效数字打印（不再有十进制灰尘占用宝贵的终端空间）
3. NA 理解和着色（不再因为缺失数据而导致数据单元格错位）
4. 首先打印尺寸（不再需要猜测数据中有多少行和列）
5. 列溢出逻辑（不再因为终端尺寸而错位）
6. 长字符串/Unicode 截断（不再有长字符串推其他数据）
7. 可通过点文件配置自定义（带来您自己的主题）

安装

以下安装选项可通过包管理器获得

• Cargo
• Debian
• AUR
• Snap
• Homebrew

我们目前为以下架构提供版本。从 版本页面 下载。

• MacOS
• ARM
• Windows
• 从源码构建（最通用）

上述所有说明都非常相似，以下是一些通用步骤。

1. 从 版本页面 下载您希望下载的版本
2. tar -xvzf <RELEASE_FILE_NAME>
3. cd 进入解压缩文件夹
4. 找到二进制文件 tidy-viewer

完成以上步骤后，强烈建议您为 tidy-viewer 创建别名，如下所示。

Cargo

以下将从 crates.io 源安装。为了方便，请将别名 alias tv='tidy-viewer' 添加到 .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

以下说明适用于此处找到的最新版本 <VERSION>，可在发布页面找到。

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

由 @yigitsever 维护

paru -S tidy-viewer

Snap

sudo snap install --edge tidy-viewer

Homebrew

brew install tidy-viewer

示例

享受以下数据集带来的乐趣吧！

钻石

# 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 argument
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

有效数字定义和规则

前三位数字表示大于99.9%的数值。 -- GNU-R Pillar

选择有效数字相当于希望数值包含多少有效信息。下表展示了带有可变有效数字的示例计算。

tv 使用与 R 包 pillar 相同的有效数字（sigfig）规则。

tv 中有效数字规则的目的是引导用户关注数值中最重要的信息。本节定义了术语以及计算最终显示值时使用的决策树。

定义

     ┌─────┐      ┌─────┐     ─┐
     │     │      │     │      │
     │     │      │     │      │
     │     │      │     │      │
     │     │      │     │      │
     │     │  ┌┐  │     │      │
     └─────┘  └┘  └─────┘    ──┴─
   │        │    │                │
   └────────┘  ▲ └────────────────┘
left hand side │  right hand side
     (lhs)     │       (rhs)

            decimal

左侧（lhs）：小数点左侧的数字。

右侧（rhs）：小数点右侧的数字。

 ┌─────┐      ┌─────┐     ─┐     ┌─────┐
 │     │      │     │      │     │     │
 │     │      │     │      │     │     │
 │     │      │     │      │     │     │
 │     │      │     │      │     │     │
 │     │  ┌┐  │     │      │     │     │
 └─────┘  └┘  └─────┘    ──┴─    └─────┘

│                     │         │       │
└─────────────────────┘         └───────┘
       leading 0s              trailing 0s

前导零：位于非零数字左侧的零。

尾随零：位于非零数字右侧的零。在500m中的零以及0.500km中的零都是尾随零。

 ─┐     ┌─────┐       ─┐
  │     │     │        │
  │     │     │        │
  │     │     │        │
  │     │     │        │
  │     │     │  ┌┐    │
──┴─    └─────┘  └┘  ──┴─

                   │        │
                   └────────┘
              fractional digit(s)

分数数字：小数点右侧的数字。它们代表数字的非整数部分。

规则

只有四种可能的输出。显示的有效数字由用户设置。假设 sigfig = 3

1. 仅左侧（lhs）12345.0 -> 12345：如果没有分数数字，并且左侧 >= 有效数字，则返回左侧。
2. 左侧 + 点（1234.5 -> 1234.：如果存在分数数字，并且左侧 >= 有效数字，则返回带有点的左侧。这是为了让用户知道有些小数位数超出了数字的主要部分。
3. 左侧 + 点 + 右侧（1.2345 -> 1.23：如果存在分数数字，并且左侧 < sigfig，则返回数字的前三位。
4. 长右侧（0.00001 -> 0.00001：这为具有右侧前导零的数值保留。

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

与 tv 配对的工具

tv 是命令行数据处理工具的良好补充。以下是我喜欢与 tv 一起使用的工具列表。

qsv - xsv 的分支。具有更多命令/子命令，并允许用户在数据上评估 lua/python。 [Rust | CLI]

xsv - 命令行 csv 数据处理。 [Rust | CLI]

SQLite - 具有CLU、shell和库接口的数据库引擎。 [C | CLI/shell/lib]

DuckDB - 带有CLU、shell和库界面的数据库引擎。[C++ | CLI/shell/lib]

csvtk - 命令行csv数据处理。[Go | CLI]

tsv-utils - 命令行csv数据处理工具包。[D | CLI]

q - 类似查询的命令行csv数据处理。[Python | CLI]

miller - 命令行数据处理、统计等。[C | CLI]

VisiData - 一个交互式终端用户界面，旨在探索和整理数据。[Python | TUI]

与tv类似的工具

column 是Linux的标准工具。要获得类似的功能，请运行 column file.csv -ts,

尽管 column 类似，但我确实认为 tv 是一个更好的工具。

1. NA理解

NA 值非常重要！观众应该注意到这些空单元格。在下面的图像中，NA 值不仅不可见，而且似乎还导致其他列的排列不正确。

程序有很多种方式来指定缺失值。有些使用 none，有些使用 NaN，还有很多使用 ""、NA、null、n/a 等。 tv 会搜索这些字符串并将它们替换为 NA。这与显著的数字计算和截断长字符串类似。 tv 的目的不是显示完整的文本值，而是引导眼睛。

2. 列溢出逻辑

在终端宽度无法容纳数据框中所有列的情况下，column 将试图将数据挤压到下面的行中。这导致了一个不愉快的观看体验。

tv 可以自动判断是否会有太多列需要打印。当发生这种情况时，它只会打印适合终端的列，并在表格下方的页脚中提及额外的列。

配置点文件

有关点文件配置的信息，请参阅 tv --help。这允许用户设置自己的调色板、要打印的行、最大列宽等。

常见问题解答

• tv 有浅色主题吗？

是的，solarized light是默认添加的。这是在版本 1.4.6 中添加的。您也可以在配置中定义自己的主题。

• 文件 ~/.config/tv.toml 对输出没有影响。我犯了什么错误？

每个键值对都必须存在，否则toml将不会读取。如果缺少任何一个键值对，则配置将不起作用。

• 能够垂直/水平滚动高/宽数据表文件会很好。 tv 允许此功能吗？

是的，可以将输出管道传输到 less 或 bat。使用 -e 标志，tv 允许这样做。要扩展到完整的csv宽度和长度并保持颜色，请尝试以下命令：tv diamonds.csv -ea | less -SR 要扩展到完整的csv宽度和长度并移除所有颜色，请尝试以下命令：tv diamonds.csv -e | less -S

帮助

tv--帮助

tv 1.5.2
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
    tv diamonds.csv

    Configuration File Support:
    An example config is printed to make it easy to copy/paste to `tv.toml`.
    Check the parameters you have changed with `tv --config-details`.
    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
        ## All fields must be defined. Partial files will not be read.
        ## 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 width and length in terms of the number of rows and columns displayed beyond term width [default: false]
        # extend_width_length = true
        ## meta_color = [R,G,B] color for row index and "tv dim: rows x cols"
        #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:
    -C, --config-details             Show the current config details
    -d, --debug-mode                 Print object details to make it easier for the maintainer to find and resolve bugs.
    -e, --extend-width-and-length    Extended width beyond term width (do not truncate). Useful with `less -S`.
    -f, --force-all-rows             Print all rows in file. May be piped to 'less -S'. Example `tidy-viewer
                                     data/diamonds.csv -f -a | less -R`
    -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
    -D, --no-dimensions              Turns off dimensions of the data
    -R, --no-row-numbering           Turns off row numbering
    -V, --version                    Prints version information

OPTIONS:
    -c, --color <color>
            There are 5 preconfigured color palettes (Defaults to nord):
                            (1)nord
                            (2)one_dark
                            (3)gruvbox
                            (4)dracula
                            (5)solarized light [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

与数据库引擎一起使用

这里展示了如何使用 tv 与几个数据库引擎（SQLite，DuckDB）一起使用。

与SQLite一起使用

SQLite 是一个了不起的程序！如果它不是部署最广泛的软件，那么它可能接近这个水平。有关SQLite的更多信息，请参阅他们的 执行摘要

对于此示例，您需要下载和解压出租车数据

wget https://github.com/multiprocessio/dsq/blob/43e72ff1d2c871082fed0ae401dd59e2ff9f6cfe/testdata/taxi.csv.7z?raw=true -O taxi.csv.7z
7z x taxi.csv.7z
cd testdata
ls -l --block-size=M # the data is farily large at 192MB

SQLite 单行命令

sqlite3 :memory: -csv -header -cmd '.import taxi.csv taxi' 'SELECT passenger_count, COUNT(*), AVG(total_amount) FROM taxi GROUP BY passenger_count' | tv

上面的单行命令将csv作为内存数据库进行查询。也可以查询一个现有的 sqlite 数据库，并将输出作为csv管道传输，以便 tv 捕获。以下是一个单行命令示例。

sqlite3 -csv -header <file_name.sqlite> 'select * from <table>;' | tv

与DuckDB一起使用

DuckDB 与SQLite有很多共同之处。作为个人轶事，我确实喜欢在csv上运行时需要的CLI标志更少。我也喜欢它的速度。虽然它不如SQLite通用，但我认为它非常适合命令行数据操作。

对于此示例，您需要下载和解压出租车数据

wget https://github.com/multiprocessio/dsq/blob/43e72ff1d2c871082fed0ae401dd59e2ff9f6cfe/testdata/taxi.csv.7z?raw=true -O taxi.csv.7z
7z x taxi.csv.7z
cd testdata
ls -l --block-size=M # the data is fairly large at 192MB

tv 的乐趣

使用 duckdb 和 less 与 tv 一起使用SQL语法操作数据，并在滚动窗口中查看结果。

duckdb --csv -c "select norm1 from norms.csv" | ../target/release/tidy-viewer -f -a | less -R

DuckDB 单行命令

duckdb --csv -c "SELECT passenger_count, COUNT(*), AVG(total_amount) FROM taxi.csv GROUP BY passenger_count ORDER BY passenger_count" | tv

灵感

pillar - R的tibble类似格式。由 Kirill Müller 和 Hadley Wickham 进行了惊人的原创工作。tv 尝试将这些想法移植到终端。