seqtkrs 0.1.1

# seqtkrs

[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**seqtkrs** 是 [seqtk](https://github.com/lh3/seqtk) 的 Rust 重新实现，seqtk 是一个快速轻量的生物序列（FASTA/FASTQ格式）处理工具集。

## 特性

- 🚀 **高性能**：利用 Rust 的零成本抽象和内存安全特性
- 🔄 **完全兼容**：与原始 C 语言实现的算法保持兼容
- 📦 **易于安装**：通过 Cargo 一键安装，无需额外依赖
- 🗜️ **自动压缩检测**：无缝支持 gzip 和 bzip2 压缩文件
- 🧬 **全功能**：实现了原版 seqtk 的全部 24 个命令

## 安装

### 从源码构建

```bash
git clone https://github.com/sheny-bio/seqtkrs.git
cd seqtkrs
cargo build --release
```

编译后的二进制文件位于 `target/release/seqtkrs`。

### 使用 Cargo 安装

```bash
cargo install --path .
```

## 快速开始

### 基本用法

```bash
# 查看帮助信息
seqtkrs --help

# 查看特定命令的帮助
seqtkrs seq --help
```

### 常用示例

#### 序列格式转换

```bash
# 将 FASTQ 转换为 FASTA
seqtkrs seq -a input.fq.gz > output.fa

# 将 Illumina 1.3+ FASTQ 转换为 FASTA，并将质量值低于 20 的碱基转为小写
seqtkrs seq -aQ64 -q20 input.fq > output.fa

# 将多行 FASTQ 转换为 4 行格式
seqtkrs seq -l0 input.fq > output.fq

# 折叠长序列行并移除注释
seqtkrs seq -Cl60 input.fa > output.fa
```

#### 序列操作

```bash
# 反向互补
seqtkrs seq -r input.fq > output.fq

# 提取指定名称的序列（每行一个序列名）
seqtkrs subseq input.fq names.txt > output.fq

# 提取 BED 文件指定区域的序列
seqtkrs subseq input.fa regions.bed > output.fa

# 将 BED 区域的碱基转为小写
seqtkrs seq -M regions.bed input.fa > output.fa
```

#### 序列采样

```bash
# 从双端测序文件中随机采样 10000 对读段（使用相同的随机种子保持配对）
seqtkrs sample -s100 read1.fq 10000 > sub1.fq
seqtkrs sample -s100 read2.fq 10000 > sub2.fq
```

#### 质量控制

```bash
# 使用 Phred 算法修剪低质量碱基
seqtkrs trimfq input.fq > output.fq

# 从左端修剪 5bp，从右端修剪 10bp
seqtkrs trimfq -b5 -e10 input.fa > output.fa

# 生成 FASTQ 质量统计报告
seqtkrs fqchk input.fq > report.txt
```

#### 序列分析

```bash
# 计算 GC 含量
seqtkrs gc input.fa > gc_content.txt

# 查找端粒重复序列 (TTAGGG)n
seqtkrs telo seq.fa > telo.bed 2> telo.count

# 统计序列长度
seqtkrs size input.fa
```

## 支持的命令

seqtkrs 实现了原版 seqtk 的全部 24 个命令：

| 命令 | 功能描述 |
|------|---------|
| `seq` | 常见的序列格式转换和操作 |
| `sample` | 随机采样序列 |
| `subseq` | 提取指定名称或区域的序列 |
| `trimfq` | 修剪 FASTQ 文件的低质量碱基 |
| `fqchk` | FASTQ 质量统计 |
| `comp` | 计算序列组成 |
| `mergepe` | 合并双端测序的两个 FASTQ 文件 |
| `dropse` | 从双端数据中删除单端读段 |
| `split` | 将序列文件分割为多个文件 |
| `rename` | 重命名序列 |
| `mutfa` | 在 FASTA 序列中引入随机突变 |
| `mergefa` | 合并两个 FASTA 文件 |
| `famask` | 使用 BED 文件掩码 FASTA 序列 |
| `gc` | 计算 GC 含量 |
| `hety` | 计算杂合度 |
| `cutN` | 在 N 碱基处切割序列 |
| `gap` | 查找序列中的 gap（N 区域） |
| `hpc` | 同聚物压缩 |
| `hrun` | 查找同聚物 |
| `telo` | 查找端粒重复序列 |
| `kfreq` | k-mer 频率统计 |
| `listhet` | 列出杂合位点 |
| `randbase` | 生成随机碱基序列 |
| `size` | 统计序列长度 |

## 性能

seqtkrs 在保持与原版 seqtk 算法兼容的同时，利用 Rust 的性能优势：

- **内存安全**：无需担心缓冲区溢出或内存泄漏
- **零成本抽象**：高级抽象不会带来运行时开销
- **并行处理**：部分命令支持多线程并行处理
- **优化的 I/O**：16KB 缓冲区提供最佳吞吐量

## 开发

### 运行测试

```bash
# 运行所有测试
cargo test

# 运行特定测试
cargo test test_name

# 显示测试输出
cargo test -- --nocapture
```

### 代码检查

```bash
# 格式化代码
cargo fmt

# 运行 Clippy 静态检查
cargo clippy -- -D warnings

# 生成文档
cargo doc --open
```

### 性能基准测试

```bash
cargo bench
```

## 项目结构

```
src/
├── core/           # 基础层：I/O、数据结构、查找表
│   ├── seq_reader.rs   # FASTA/FASTQ 读取器
│   ├── seq_writer.rs   # FASTA/FASTQ 写入器
│   ├── seq_record.rs   # 序列记录数据结构
│   └── tables.rs       # 碱基转换查找表
├── utils/          # 工具层：随机数、区域解析、质量值处理
├── algorithms/     # 算法层：Mott 修剪、采样、X-dropoff
└── commands/       # 命令层：24 个 CLI 命令实现
```

## 与原版 seqtk 的差异

- **命令行接口**：使用 `clap` 提供更现代的 CLI 体验
- **错误处理**：使用 Rust 的 `Result` 类型提供更清晰的错误信息
- **代码组织**：模块化设计，便于维护和扩展

## 贡献

欢迎贡献！请随时提交 Issue 或 Pull Request。

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 致谢

- 原始 [seqtk](https://github.com/lh3/seqtk) 项目由 Heng Li 开发
- 感谢 Rust 社区提供的优秀工具和库

## 参考

- 原版 seqtk: https://github.com/lh3/seqtk
- FASTA 格式: https://en.wikipedia.org/wiki/FASTA_format
- FASTQ 格式: https://en.wikipedia.org/wiki/FASTQ_format