在终端里查看序列、测序质量和变异

sq 是一个轻量的生物序列与变异浏览器，支持核酸和蛋白质 FASTA、FASTQ、SAM/BAM 和 VCF。可直接打开 gzip、BGZF 压缩文件，也可以把多种格式放在同一窗口的不同标签中浏览。适用于 macOS 和 Linux。

sq genome.fa variants.vcf.gz

支持的文件

以上格式均可直接读取 gzip 和 BGZF 压缩文件。FASTQ 接受跨行的序列与质量字段，能解析 Illumina、Nanopore、PacBio 和 SRA header，并保留原始 header。

从这里开始

安装

支持 macOS（Apple Silicon、Intel）和 Linux x86_64。安装后的命令为 sq。

brew install Georicl/tap/seqviz-rs
sq --version

brew upgrade Georicl/tap/seqviz-rs

mkdir -p "$HOME/.local/bin"
install -m 755 sq "$HOME/.local/bin/sq"
export PATH="$HOME/.local/bin:$PATH"
sq --version

git clone https://github.com/Georicl/seqviz-rs.git
cd seqviz-rs
cargo install --path . --locked
sq --version

cargo run --release --locked -- test/test.fa test/alignments.bam test/variants.vcf

快速开始

把一个或多个文件作为参数传给 sq。每个文件打开为一个标签，格式按内容自动识别。

打开文件

# 单个文件
sq genome.fa
sq reads.fastq.gz

# 多个文件，每个占一个标签
sq genome.fa variants.vcf.gz

# 文件名以 - 开头时，用 -- 结束选项
sq -- "-sample.fa"

命令行选项

打开之后

按 ? 查看当前格式的全部按键，Tab 切换文件，q 退出。底部状态栏会显示格式、记录位置和索引进度。

sq reads.fastq reference.fa proteins.faa

全局操作

这些按键在所有格式中都可用。

鼠标滚轮滚动指针所在的区域。

序列浏览

适用于 FASTA、FASTQ、SAM 和 BAM。左侧是记录列表，右侧是序列视图。

按键

换行与选区

序列随窗口宽度自动换行。FASTA/FASTQ 可以跨行拖选，指针停在边缘时会继续滚动；调整窗口大小后，选中的序列坐标保持不变。

统计页

F4 显示记录数、总长度、最短/最长/平均长度，适用的格式还会给出 N50。SAM/BAM 按比对记录计数。

FASTQ 质量颜色

默认按 Phred 分数分为四档，阈值可在 content.toml 中修改。

VCF 浏览

支持普通 VCF 4.0–4.5。上方是变异主表，下方是当前变异的详情。

变异主表

主表显示 CHROM、POS、ID、REF、ALT、TYPE、QUAL、FILTER。窗口较窄时优先保留 CHROM、POS、REF、ALT。多个 ALT 属于不同变异类型时，TYPE 显示 MIXED。

按键

样本与颜色

Samples 视图保留 FORMAT 字段的原始顺序，只解析屏幕上可见的样本。

• REF/ALT 使用与序列相同的碱基颜色。
• GT 颜色代表等位基因编号，AD 条使用同样的顺序和颜色。
• QUAL、GQ 显示原始数值。
• PASS、过滤失败和缺失值各有颜色；FILTER 为 . 时与 PASS 分开显示。

复制内容

y 按光标所在位置决定复制什么。

按位置的结果

在 VCF 主表或 Raw 中，Y 复制原始 header 与当前记录；VCF 的其他位置中，Y 与 y 相同。

剪贴板

本地复制优先使用 pbcopy（macOS），或 wl-copy、xclip、xsel（Linux）。通过 SSH 使用时走 OSC 52，需要终端支持。复制完整记录时会读取并暂存整条记录。

从 yazi 打开

把对应版本的配置合并到 ~/.config/yazi/yazi.toml，并确保 sq 在 PATH 中。

yazi 25.4 配置

[opener]
sq = [
  { run = 'sq -- "$@"', block = true, desc = "Sequence and variant browser", for = "unix" },
]

[open]
prepend_rules = [
  { name = "*.{fa,fasta,fna,fas,fsa,faa,pep,fq,fastq,sam,bam,vcf}", use = "sq" },
  { name = "*.{fa,fasta,fna,fas,fsa,faa,pep,fq,fastq,sam,vcf}.{gz,bgz,bgzf}", use = "sq" },
]

opener 使用 block = true。在 yazi 中选中文件按 Enter 打开，按 q 退出后回到 yazi。

大文件与缓存

sq 先显示首屏，再分块建立索引，打开大文件不需要等待全部读完。

按需读取

可见的记录与内容按窗口读取。VCF 只保留当前选中的原始记录，样本按需解析。浏览界面中按 Esc 可以取消任务并暂停索引。

索引缓存

索引与解压检查点保存在 $XDG_CACHE_HOME/seqviz-rs/，默认是 ~/.cache/seqviz-rs/。再次打开同一文件会复用索引，源文件变化后旧索引自动失效。

普通 gzip 使用解压检查点，不会生成完整的解压副本。第一次跳到尚未索引的远处位置时，仍需要扫描或解压到那里。

配置主题

默认主题开箱可用。要自定义，把 config.toml 与 content.toml 复制到 ~/.config/seqviz-rs/。

设置了绝对路径的 XDG_CONFIG_HOME 时，放到 $XDG_CONFIG_HOME/seqviz-rs/。所有字段都是可选的，省略的字段使用内置默认值；旧配置无需新增字段即可继续使用。

config.toml

界面颜色，以及可选的 [vcf] 设置：过滤状态、等位基因颜色、AD 条和详情高度。

[display]
show_quality = true

[vcf]
pass_color = "#7ed397"
filter_color = "#f0c674"
missing_color = "#8f9bb3"
# ALT1, ALT2, ... use these colours in both GT and AD; REF keeps the foreground.
allele_colors = ["#7ab7ff", "#be9bf3", "#78d5d4", "#f0c674", "#f18594"]
show_ad_bars = true
detail_rows = 10

[theme]
# Relative paths are resolved against this configuration file's directory.
content = "content.toml"
background = "#181b23"
foreground = "#e0e5ef"
muted = "#8f9bb3"
border = "#47546e"
focus = "#7ab7ff"
selection = "#3e4d6c"

content.toml

碱基、氨基酸和 FASTQ 质量颜色。颜色可写名称（如 green）或 RGB（如 #7ed397）。默认碱基配色如下，序列内容和 VCF 的 REF/ALT 共用这一组：

[amino_acids]
nonpolar = "#f0c674"  # A I L M V
polar = "#7ed397"     # S T N Q C U
acidic = "#f18594"    # D E
basic = "#7ab7ff"     # K R H O
aromatic = "#be9bf3"  # F W Y
special = "#78d5d4"   # G P

# Inclusive minimum Phred scores. Include min=0; thresholds must be unique and lie between 0 and 93.
[[quality]]
min = 0
color = "#f18594"

[[quality]]
min = 30
color = "#7ed397"

v0.2.0 更新

这一版加入 VCF 支持，并重新组织了代码结构。

VCF 浏览

变异主表、可搜索的 contig 选择器、坐标跳转，以及 INFO、Samples、Raw 三种详情。见 VCF 浏览。

变异与样本配色

REF/ALT 沿用碱基颜色，GT 按等位基因编号着色，AD 条展示对应等位基因的深度；区分 PASS、过滤失败与缺失值。

按上下文复制

复制当前变异原始行、INFO 字段、样本及字段标题，或带原始 header 的完整记录；支持详情文字拖选。见 复制内容。

混合文件标签

在序列与 VCF 之间切换，各文件保留浏览位置。现有配置继续可用，新增可选的 [vcf] 设置。

参与开发

欢迎提交问题报告、文档修正和代码。

代码结构

如何参与

开发入口、检查命令和问题反馈方式见 CONTRIBUTING.md。新增文件格式或较大的行为改动，请先开 issue 说明预期效果。

项目采用 MIT 许可。