hammer_csv

一个用于生物序列组合（N1/N2/N3…）的 CSV 处理与比较工具。提供两个子命令：

• filter：清洗和预处理组合序列列，支持按关键字筛选文件并对指定 N 区块进行互补（A↔T，C↔G）。
• compare：比较两个时间点（如 T0 与 T12）同一样本的组合序列计数与频率，计算 fold change 与 log2fc，并整合样本注释。

功能特性

• 自动识别组合序列列（包含 N1/N2/... 或 T*_N*_combo 的列）。
• 可选对指定 Nx 区块的碱基执行互补转换（如 N3）。
• 支持通过关键字文件筛选待处理的输入 CSV 文件。
• 结合样本注释文件（SampleID、Sample_Annotation）进行结果汇总输出。
• 完整的错误提示与日志输出（基于 log + env_logger）。

环境与安装

• Rust 版本：Edition 2021
• 依赖：clap、csv、regex、glob、serde、anyhow、thiserror、hashbrown、env_logger

构建：

cargo build

运行帮助：

cargo run -- --help
cargo run -- filter --help
cargo run -- compare --help

快速开始（示例数据）

仓库包含示例测试数据位于 testdata/：

• testdata/filter/input/：示例输入 CSV
• testdata/filter/output/：filter 运行后的输出位置
• testdata/filter/patterns.txt：按文件名筛选关键字
• testdata/compare/T0/ 与 testdata/compare/T12/：两个时间点的样本数据
• testdata/compare/info.csv：样本注释文件（SampleID,Sample_Annotation）

示例运行：

# 1) 过滤并对 N3 区块互补
cargo run -- filter \
  --input-folder testdata/filter/input \
  --output-folder testdata/filter/output \
  --file-pattern-file testdata/filter/patterns.txt \
  --modify-position N3

# 2) 比较两个时间点并输出合并结果
cargo run -- compare \
  --input1 testdata/compare/T0 \
  --input2 testdata/compare/T12 \
  --info testdata/compare/info.csv \
  --output testdata/compare/output/merged.csv

输入与列要求

filter 子命令

• 输入目录下每个 CSV 至少包含一个组合列，列名包含 N\d+（如：N1、N2、N3）。
• 组合列的值应形如 AT-CG-TT（由 ATCG 字符组成、以 - 分隔）。
• 可选参数 --modify-position Nx 用于对指定 Nx 的序列执行互补（A↔T，C↔G）。
• 可选参数 --file-pattern-file：纯文本文件，每行一个关键字，按文件名包含关系筛选要处理的 CSV。

compare 子命令

• 两个输入目录（如 T0 与 T12），下的文件名需含样本 ID：SX-数字（如 SX-001）。
• 每个数据 CSV 需包含以下列：
  • 组合列：匹配 T\d+_N\d+(?:_N\d+)*_combo（大小写不敏感），例如：T0_N1_N2_N3_combo。
  • Count
  • Frequency (%)
• 注释文件 info.csv 需包含：SampleID、Sample_Annotation 两列。

输出示例

• filter 输出示例（testdata/filter/output/SX-001_filtered.csv）：

Count,Frequency (%),N1,N2,N3
10,5.0,AT,CG,TT
20,10.0,TA,GC,AA

• compare 输出示例（testdata/compare/output/merged.csv）：

SampleID,Sample_Annotation,Time_Comparison,N_combo,T0_Count,T0_Frequency,T1_Count,T1_Frequency,foldchange,log2fc
SX-001,TestSample,T1_vs_T0,AT-CG-TT,10.0,5.0,20.0,8.0,1.6,0.6780719051126377
SX-001,TestSample,T1_vs_T0,TA-GC-AA,20.0,10.0,40.0,16.0,1.6,0.6780719051126377

日志与错误

• 默认日志级别为 info，可通过环境变量控制：

RUST_LOG=debug cargo run -- filter ...

• 常见错误类型：
  • 找不到组合列（ComboColumnNotFound）
  • 文件名无法提取样本 ID（SampleIdNotFound）
  • 两个时间点无共同样本（NoCommonSamples）
  • 注释文件缺少必需列（InvalidInfoFile）

性能与建议

• 大量文件时建议先按 --file-pattern-file 进行筛选。
• compare 过程中会将每个 CSV 读入内存的 HashMap，建议按样本分批处理并使用发布构建：

cargo build --release

开发与测试

• 代码入口：src/main.rs
• 主要函数位置：
  • CLI 定义：src/main.rs:40-62
  • filter 入口：src/main.rs:134-168
  • compare 入口：src/main.rs:290-368
• 可使用 testdata 目录快速验证功能。

许可证

• 若用于科研与教学，请保留作者署名。可根据实际需要补充 LICENSE。