RustKmer

高性能的k-mer计数和查询工具，使用Rust实现，专为现代生物信息学应用设计。

🚀 主要特性

🏆 性能优势

高性能查询: 优化的查询引擎，支持22,703+ queries/sec
排序数据库优化: 二分搜索提供384-1526倍性能提升
内存优化: 高效的内存管理和缓存友好的数据结构
大规模处理: 支持>100M k-mers的大型基因组数据集

🛠️ 核心功能

高性能计数: 顺序k-mer计数
批量查询: 高效的批量k-mer查询处理
🔥 模糊查询: 通配符和突变容忍搜索，支持复杂模式匹配
排序数据库: 二分搜索优化，无需预加载
标准兼容: 遵循k-mer计数的行业标准
Python集成: 完整的Python API和示例代码
压缩文件支持: 自动处理.gz压缩的FASTA/FASTQ文件
跨平台: 支持Linux、macOS和Windows
内存映射: 高效的文件I/O操作

🔬 科学验证

准确性验证: 经过大规模真实数据测试验证
大规模测试: 基于OSA1 r7 assembly (381MB)的真实数据测试
性能分析: 详细的性能基准测试和优化建议

📦 安装

Python包 + 虚拟环境 (强烈推荐)

使用虚拟环境安装，避免与系统包冲突：

# 1. 创建虚拟环境
python3 -m venv .venv

# 2. 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate
# Windows (Command Prompt):
.venv\Scripts\activate.bat
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# 3. 安装RustKmer
pip install rustkmer

# 4. 验证安装
python -c "from pyrustkmer import PyCounter; print('✅ 安装成功!')"

# 5. 完成后退出虚拟环境
deactivate

使用虚拟环境的优势:

🛡️ 隔离性: 避免与系统Python包冲突
🔄 可重现: 确保项目环境一致性
🧹 清洁: 易于删除或重建环境
👥 协作: 可与团队成员共享确切环境

现代Python + uv (超快安装) ⚡

uv 是下一代Python包管理器，比pip快10-100倍：

# 1. 安装uv
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 创建新项目并安装RustKmer
uv init rustkmer-analysis
cd rustkmer-analysis
uv add rustkmer

# 3. 立即开始使用！
uv run python -c "from pyrustkmer import PyCounter; print('✅ RustKmer就绪!')"

# 4. 创建分析脚本
echo 'from pyrustkmer import PyCounter
counter = PyCounter(21, canonical=True)
print("🧬 开始k-mer分析!")' > analysis.py

# 5. 运行分析
uv run python analysis.py

选择uv的优势:

🚀 极速: 比pip快10-100倍
🎯 简单: 一条命令完成环境设置
📦 现代: 内置项目管理和依赖管理
🔄 可靠: 更好的缓存和依赖解析

📦 Conda环境安装 🐍

使用Conda创建隔离的Python环境，非常适合生物信息学工作流：

方法一：使用conda-forge频道 (推荐)

# 1. 安装Miniconda (如果没有conda)
# 下载: https://docs.conda.io/en/latest/miniconda.html

# 2. 创建新环境并安装RustKmer
conda create -n rustkmer-env python=3.11 -c conda-forge
conda activate rustkmer-env

# 3. 安装RustKmer及其依赖
conda install -c conda-forge rustkmer numpy matplotlib pytest

# 4. 验证安装
python -c "from pyrustkmer import PyCounter; print('✅ Conda安装成功!')"

# 5. 安装额外的数据科学工具 (可选)
conda install -c conda-forge pandas seaborn jupyter

方法二：从PyPI安装到Conda环境

# 1. 创建环境
conda create -n rustkmer-env python=3.11
conda activate rustkmer-env

# 2. 安装RustKmer及开发依赖
pip install rustkmer
pip install pytest numpy matplotlib pandas

# 3. 验证安装
python -c "from pyrustkmer import PyCounter; print('✅ 安装成功!')"

方法三：开发环境设置 (完整版)

# 1. 创建完整开发环境
conda create -n rustkmer-dev python=3.11 -c conda-forge rust numpy matplotlib pytest pandas seaborn jupyterlab

# 2. 激活环境
conda activate rustkmer-dev

# 3. 克隆源码并安装开发版本
git clone https://github.com/your-username/rustkmer.git
cd rustkmer

# 4. 安装为可编辑包
pip install -e .

# 5. 安装开发工具
pip install pytest-benchmark hypothesis

# 6. 运行测试验证
python -m pytest tests/python/ -v

常用Conda命令参考

# 查看环境列表
conda env list

# 导出环境配置
conda env export > rustkmer-environment.yml

# 从配置文件创建环境
conda env create -f rustkmer-environment.yml

# 删除环境
conda env remove -n rustkmer-env

# 在环境中安装额外包
conda activate rustkmer-env
conda install -c conda-forge scipy scikit-learn

# 查看已安装包
conda list

# 更新conda和所有包
conda update conda
conda update --all

环境配置文件示例

创建 environment.yml 文件以快速设置环境：

name: rustkmer-env
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.11
  - numpy>=1.21
  - matplotlib>=3.5
  - pytest>=7.0
  - pandas
  - pip
  - pip:
    - rustkmer

使用方法：

conda env create -f environment.yml
conda activate rustkmer-env

Conda + Jupyter集成

# 1. 安装ipykernel
conda install -c conda-forge ipykernel

# 2. 将环境添加到Jupyter
python -m ipykernel install --user --name rustkmer-env --display-name "RustKmer Environment"

# 3. 启动Jupyter并选择RustKmer环境
jupyter lab

选择Conda的优势:

🔬 生物信息学标准: 科研领域广泛使用的环境管理工具
📦 依赖管理: 强大的包依赖解析和二进制分发
🔄 环境隔离: 完全隔离的环境，避免包冲突
🌍 跨平台: 统一的安装体验 (Windows/macOS/Linux)
🧪 实验重现: 轻松分享和重现分析环境

系统级Python安装

# 直接安装到系统（不推荐用于开发）
pip install rustkmer

# 或从源码构建
git clone https://github.com/your-username/rustkmer.git
cd rustkmer
pip install .

从源码编译 (CLI工具) 🦀

git clone https://github.com/your-username/rustkmer.git
cd rustkmer
cargo build --release

编译后的可执行文件位于 target/release/rustkmer。

系统要求

Python 3.8+
Rust 1.80+ (推荐使用stable版本)
足够的内存处理大型数据集
对于大型基因组文件，建议使用SSD存储

🔧 快速开始

基本用法

# 创建排序数据库（推荐，获得最佳性能）
rustkmer count -k 21 -t 8 --sort -o genome.rkdb genome.fa

# 单个查询
rustkmer query genome.rkdb ATGCGATGCTAGCGCTAGCTA

# 批量查询（高性能）
rustkmer query genome.rkdb --sequence queries.fa -o results.txt

# 🔥 模糊查询 - 通配符和突变容忍
rustkmer fuzzy-query -d genome.rkdb -q "ATNNGTA"                    # 通配符查询 (N=任意碱基)
rustkmer fuzzy-query -d genome.rkdb -q "ATCGATCGATCGATCGATCGA" -m 2  # 突变容忍搜索

# 数据库信息
rustkmer info genome.rkdb

# 合并数据库
rustkmer merge -i genome1.rkdb genome2.rkdb -o merged.rkdb

🆕 大k-mer支持 (k > 32)

rustkmer现在支持大k-mer（k=33到64），使用u128编码：

# 使用k=33创建数据库
rustkmer count -k 33 -o large_kmer.rkdb sequences.fa

# 查询大k-mer
rustkmer query large_kmer.rkdb ACGTACGTACGTACGTACGTACGTACGTACGTG

# k=64（最大支持）
rustkmer count -k 64 -o k64_database.rkdb genome.fa

# Python API中使用大k-mer
python3 -c "
from pyrustkmer import PyCounter
counter = PyCounter(kmer_length=48, canonical=True)
counter.add_sequence('ACGT' * 12)
counter.save_database('k48_database.rkdb')
"

大k-mer特性：

支持范围: k = 1 到 64
存储格式: 使用16字节条目（k≤32为12字节），数据库大小增加约33%
性能影响: 编码性能损失<10%，查询性能损失<5%
内存使用: 用户可配置，无系统限制

性能关键发现

✅ 性能建议: 使用批量查询获得最佳性能：

# 推荐：高性能批量查询
rustkmer query database.rkdb --sequence queries.fa -o results.txt
# 结果：22,703 queries/sec

# 单个查询（较慢，适合少量查询）
rustkmer query database.rkdb ATGCGATGCTAGCGCTAGCTA

Python集成

方式一：纯Python API（推荐）

# 导入RustKmer Python模块
from pyrustkmer import PyCounter, PyDatabase, LoadMode

# 创建k-mer计数器
counter = PyCounter(21, canonical=True)

# 处理文件（自动支持压缩格式）
counter.add_from_fasta("genome.fa")     # 常规FASTA文件
counter.add_from_fasta("genome.fa.gz")  # 压缩FASTA文件
counter.add_sequence("ACGTACGT")  # 从字符串计数

# 获取统计信息
stats = counter.get_stats()
print(f"k-mer count: {stats.total_kmers}")

# 加载数据库
db = PyDatabase("output.rkdb", LoadMode.Preload)

# 查询k-mer
result = db.query_exact("ATGCGATGCTAGCGCTAGCTA")
print(f"Query result: {result.count}, found: {result.found}")

方式二：PyO3高性能扩展 ⚡

# 导入PyO3扩展
from pyrustkmer import PyDatabase, PyPrefixQuery, LoadMode

# 加载数据库（高性能模式）
db = PyDatabase("genome.rkdb", LoadMode.Preload)

# 🔥 前缀搜索（全新功能）
result = db.query_prefix("ATG")
print(f"找到 {len(result)} 个前缀匹配")

# 🔥 混合搜索模式
from pyrustkmer import PyFuzzyQuery
fuzzy = PyFuzzyQuery(db)
hybrid_result = fuzzy.query_fuzzy("ATCGNNN", max_mutations=2)

# 使用专用查询引擎
query_engine = PyPrefixQuery("genome.rkdb", LoadMode.Preload)
results = query_engine.query_prefix("ATG")

🔥 模糊查询功能 (Wildcard & Mutation Tolerance)

RustKmer提供强大的模糊查询功能，支持通配符搜索和突变容忍匹配：

from pyrustkmer import PyDatabase, PyFuzzyQuery, LoadMode

# 加载数据库
db = PyDatabase("genome.rkdb", LoadMode.Preload)

# 创建模糊查询器
fuzzy = PyFuzzyQuery(db)

# 通配符查询 (N = 任意碱基: A,T,C,G)
wildcard_results = fuzzy.query_fuzzy("ATNNGTA", max_mutations=0)
print(f"通配符查询找到 {len(wildcard_results.get_top_matches(1000))} 个匹配")

# 突变容忍搜索 (汉明距离)
mutation_results = fuzzy.query_fuzzy("ATCGATCGATCGATCGATCGA", max_mutations=2)
print(f"突变容忍搜索找到 {len(mutation_results.get_top_matches(1000))} 个变体")

# 批量模糊查询
patterns = ["ATNNGTA", "ANNNNNNGT", "GTCGATCNN"]
for pattern in patterns:
    result = fuzzy.query_fuzzy(pattern, max_mutations=1)
    print(f"模式 '{pattern}': {len(result.get_top_matches(1000))} 个匹配")

# 结果处理
top_matches = wildcard_results.get_top_matches(5)
for match in top_matches:
    print(f"  {match.kmer}: {match.count}")

命令行模糊查询:

# 通配符搜索
rustkmer fuzzy-query -d genome.rkdb -q "ATNNGTA"

# 突变容忍搜索
rustkmer fuzzy-query -d genome.rkdb -q "ATCGATCGATCGATCGATCGA" -m 2

# 批量查询并导出
rustkmer fuzzy-query -d genome.rkdb -f patterns.txt -o results.csv --format csv

标准使用示例

# 计数参数
rustkmer count -k 31 -m 4G -t 16 -s 100M -L 5 -U 1000 -C -o counts.rkdb reads.fastq

# 查询多个k-mers
rustkmer query counts.rkdb ATGCGATGCTAGCGCTAGCTA CGATCGATCGATCGATCGATCG

# 交互式查询
rustkmer query --interactive counts.rkdb

📚 详细文档

完整文档和示例

📖 用户指南 - 完整的使用指南和最佳实践
🚀 快速示例 - 命令行和Python集成示例
📊 性能分析 - 详细的性能测试报告
🔥 前缀查询实现报告 - 前缀和混合搜索实现详情
⚡ 混合搜索指南 - 前缀和混合搜索使用说明

命令参考

`count` - k-mer计数

rustkmer count -k <KMER_SIZE> -o <OUTPUT> [OPTIONS] <INPUT>

核心参数:

-k, --kmer-size <SIZE>: k-mer大小 (推荐: 21)
-t, --threads <THREADS>: 线程数 (默认: CPU核心数)
-o, --output <FILE>: 输出数据库文件 (必须)
--sort: 创建排序数据库 (强烈推荐)
-C, --canonical: 规范化k-mer计数
-s, --hash-size <SIZE>: 哈希表大小 (例如: 2G, 500M)

使用示例:

# 基本计数
rustkmer count -k 21 -o genome.rkdb genome.fa

# 高性能排序数据库（推荐）
rustkmer count -k 21 -t 8 --sort -o genome_sorted.rkdb genome.fa

# 规范化计数
rustkmer count -k 21 -C --sort -o genome_canonical.rkdb genome.fa

`query` - k-mer查询（高性能推荐）

rustkmer query <DATABASE> [OPTIONS] [KMERS]...

核心参数:

--sequence <FILE>: 从FASTA文件批量查询
-o, --output <FILE>: 输出文件 (默认: stdout)
-i, --interactive: 交互式查询模式
-l, --load: 强制预加载数据库 (小数据库)
-L, --no-load: 禁用预加载 (大数据库推荐)

使用示例:

# 单个查询
rustkmer query genome.rkdb ATGCGATGCTAGCGCTAGCTA

# 批量查询（高性能）
rustkmer query genome.rkdb --sequence queries.fa -o results.txt

# 交互式查询
rustkmer query genome.rkdb -i

`info` - 数据库信息

rustkmer info <DATABASE>

`dump` - 数据库导出

rustkmer dump [OPTIONS] <DATABASE>

`merge` - 数据库合并

rustkmer merge -i <DB1> <DB2> [...] -o <OUTPUT> [OPTIONS]

核心参数:

-i, --input <FILES>: 输入数据库文件 (至少2个)
-o, --output <FILE>: 输出合并数据库文件 (必须)
-t, --threads <THREADS>: 合并线程数 (默认: 自动检测)
--check-compatibility: 仅检查兼容性，不执行合并
--temp-dir <DIR>: 临时文件目录 (默认: 系统临时目录)

兼容性要求:

所有数据库必须具有相同的k-mer大小
所有数据库必须具有相同的canonical模式
不支持强制合并不兼容的数据库

使用示例:

# 基本合并
rustkmer merge -i db1.rkdb db2.rkdb -o merged.rkdb

# 多数据库合并
rustkmer merge -i *.rkdb -o all_merged.rkdb

# 检查兼容性
rustkmer merge -i db1.rkdb db2.rkdb --check-compatibility --verbose

# 详细输出合并
rustkmer merge -i db1.rkdb db2.rkdb -o merged.rkdb --verbose

性能优化指南

🏆 最佳性能配置

使用排序数据库（最重要）:

rustkmer count -k 21 --sort -o sorted.rkdb input.fa

批量查询而非单个查询:

# ✅ 推荐：批量处理
rustkmer query database.rkdb --sequence queries.fa

# ❌ 避免：单个查询循环
for kmer in $(cat queries.txt); do
    rustkmer query database.rkdb "$kmer"
done

内存管理:

# 小数据库 (<2GB): 预加载
rustkmer query small_db.rkdb --load --sequence queries.fa

# 大数据库 (>2GB): 内存映射
rustkmer query large_db.rkdb --no-load --sequence queries.fa

RKDB数据库格式

RustKmer使用自定义的RKDB (RustKmer Database) 二进制格式：

文件结构:

+------------------+
| Header (42 bytes)|
+------------------+
| K-mer Entry 1    |
| - 8 bytes: k-mer |
| - 4 bytes: count |
+------------------+
| K-mer Entry 2    |
| ...              |
+------------------+

Header格式:

Magic Number (4 bytes): "RKDB"
Version (2 bytes): 数据库版本
K-mer Size (1 byte): k-mer长度
Total K-mers (8 bytes): k-mer总数
Flags (1 byte): 数据库标志 (排序、canonical等)
Data Offset (8 bytes): 数据起始偏移
Index Offset (8 bytes): 索引偏移 (将来使用)

性能特点:

排序数据库: 支持磁盘二分搜索，无需预加载
未排序数据库: 需要预加载到内存，适合频繁查询
内存映射: 使用mmap高效访问大型文件

性能优化

🏆 性能基准测试结果

大规模测试 (50,000 21-mers):

工具	查询速度	处理时间	性能提升
RustKmer	22,703 queries/sec	2.20秒	基准

数据库优化效果:

数据库类型	查询速度	性能提升
排序数据库	22,703 queries/sec	384-1526x
非排序数据库	45 queries/sec	基准

关键发现:

✅ 排序数据库提供巨大性能提升
✅ 批量查询比单个查询效率高数千倍
✅ 高性能 Rust 实现

🚀 快速示例

基本使用示例

# 运行基本示例
chmod +x examples/basic_usage.sh
./examples/basic_usage.sh

# 性能基准测试
chmod +x examples/performance_benchmark.sh
./examples/performance_benchmark.sh

# Python集成示例
python3 examples/python_integration.py

生产环境示例

# 1. 创建高性能排序数据库
rustkmer count -k 21 -t 8 --sort -o genome_k21.rkdb genome.fa

# 2. 批量查询分析
rustkmer query genome_k21.rkdb --sequence research_queries.fa -o results.txt

# 3. 结果统计分析
awk '$2 > 0' results.txt | wc -l  # 非零计数
sort -k2,2nr results.txt | head -10  # 最丰富k-mers

# 4. 合并多个数据库
rustkmer merge -i genome_k21_part1.rkdb genome_k21_part2.rkdb -o genome_k21_merged.rkdb

🧪 测试和验证

运行测试

# 编译和运行示例
cargo build --release
./examples/basic_usage.sh

# Python依赖安装
pip install -r examples/requirements.txt
python3 examples/python_integration.py

性能验证

我们进行了大规模性能测试，验证了以下关键发现：

高性能查询: 22,703+ queries/sec
排序数据库优化: 384-1526倍性能提升
准确性验证: 经过大规模测试验证
批量查询优化: 批量查询比单个查询效率高数千倍

详细测试报告见: 性能分析文档

🐍 Python集成示例

基本Python API

from pyrustkmer import PyCounter, PyDatabase, LoadMode

# 创建k-mer计数器
counter = PyCounter(21, canonical=True)

# 处理文件（自动支持压缩格式）
counter.add_from_fasta("genome.fa")     # 常规FASTA文件
counter.add_from_fasta("genome.fa.gz")  # 压缩FASTA文件
counter.add_sequence("ACGTACGT")    # 从字符串计数

# 获取统计信息
stats = counter.get_stats()
print(f"Unique k-mers: {stats.unique_kmers}")
print(f"Total k-mers: {stats.total_kmers}")

# 保存到数据库
counter.save_database("output.rkdb")

# 加载数据库
db = PyDatabase("output.rkdb", LoadMode.Preload)

# 查询k-mer
result = db.query_exact("ATGCGATGCTAGCGCTAGCTA")
print(f"Query result: {result.count}, found: {result.found}")

高级分析示例

from examples.python_integration import RustKmerAnalyzer

# 初始化分析器
analyzer = RustKmerAnalyzer('genome_k21.rkdb')

# 分布分析
df = analyzer.analyze_kmer_distribution(test_queries)

# 最丰富k-mers
top_kmers = analyzer.find_most_abundant_kmers(test_queries, top_n=10)

# 序列属性分析
properties = analyzer.analyze_sequence_properties(test_queries)

# 性能基准测试
performance = analyzer.benchmark_query_performance([100, 500, 1000])

安装Python依赖

pip install -r examples/requirements.txt

Python依赖包括: pandas, numpy, matplotlib (可选), seaborn (可选)

🔬 技术细节

算法实现

哈希表: 使用自定义的高性能哈希表实现
并行处理: 基于Rayon的work-stealing并行算法
内存管理: 智能的内存分配和回收策略
文件I/O: 内存映射和缓冲I/O优化

内存效率

k-mer编码: 2-bit编码压缩DNA序列
紧凑存储: 优化的数据结构布局
流式处理: 支持超大文件的流式读取
垃圾回收优化: 减少内存碎片

性能配置

# Cargo.toml 性能配置
[profile.release]
lto = true
codegen-units = 1
panic = "abort"
opt-level = 3

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

Fork本项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建Pull Request

开发环境设置

# 安装开发依赖
cargo install cargo-watch cargo-flamegraph

# 运行开发服务器
cargo watch -x run

# 性能分析
cargo flamegraph --bin rustkmer -- count -k 21 input.fa

📄 许可证

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

🙏 致谢

Rust社区: 提供了高性能的系统和生物信息学库
Rayon: 出色的并行计算框架

📂 项目结构

rustkmer/
├── src/                    # Rust源代码
├── examples/               # 示例和教程
│   ├── basic_usage.sh      # 基本使用示例
│   ├── performance_benchmark.sh  # 性能基准测试
│   ├── python_integration.py    # Python API示例
│   └── requirements.txt    # Python依赖
├── specs/                  # 技术规范和性能分析
│   └── 003-parallel-query/ # 21-mer性能测试报告
├── USER_GUIDE.md          # 完整用户指南
└── README.md              # 项目说明

📞 联系方式

项目主页: https://github.com/your-username/rustkmer
问题报告: https://github.com/your-username/rustkmer/issues
文档: USER_GUIDE.md

🐍 Python API

RustKmer 提供了完整的Python API，让您可以直接在Python脚本中进行高性能的k-mer分析。

安装方式

RustKmer 提供两种 Python 集成方式：

方式一：纯 Python Stubs（推荐，最稳定）✅

适用于所有环境，包括 Python 3.13：

# 1. 确保 RustKmer CLI 已安装（在 PATH 中）
which rustkmer  # 应该输出路径

# 2. 安装纯 Python 包
pip install rustkmer

# 3. 验证安装
python -c "from pyrustkmer import PyDatabase, LoadMode; print('✅ RustKmer Python API 就绪!')"

工作原理:

Python 代码作为存根（stubs）
实际 k-mer 操作通过调用 rustkmer CLI 完成
100% 兼容所有 Python 版本（包括 3.13）
零编译，安装即用

方式二：可编辑开发安装（开发/修改代码）⚠️

适用于开发者或需要修改 RustKmer 代码的情况：

# 1. 克隆源码
git clone https://github.com/your-username/rustkmer.git
cd rustkmer

# 2. 构建 Rust CLI 工具
cargo build --release

# 3. 设置环境变量（重要！）
# 注意：将 /path/to/rustkmer 替换为实际的 rustkmer 项目路径
echo 'export PATH="/path/to/rustkmer/target/release:$PATH"' >> ~/.zshrc
source ~/.zshrc  # 重新加载 shell 配置

# 4. 安装 Python 包（可编辑模式）
cd python  # 进入 Python 子目录
pip install -e .

# 5. 验证安装
python -c "from pyrustkmer import PyDatabase, LoadMode; print('✅ 可编辑安装就绪!')"

# 6. 测试从不同目录导入
cd /tmp
python -c "from pyrustkmer import PyDatabase, LoadMode; print('✅ 任意目录导入成功!')"

🔧 重要配置步骤：

PATH 设置: 确保 rustkmer 命令在系统 PATH 中
可编辑安装: 使用 pip install -e . 而不是普通安装
目录无关性: 修改后的代码支持从任何目录导入

✅ 已解决的问题:

路径依赖: 修复了只能在特定目录下工作的问题
PATH 查找: 优化了 Rust 二进制文件的查找逻辑
跨目录导入: 支持从任何工作目录导入 Database 类

⚠️ 注意事项:

开发环境: 适合需要修改 RustKmer 源码的场景
维护成本: 需要同时维护 Rust 和 Python 代码
兼容性: 仅在 Python 3.10+ 环境下测试过

方式三：PyO3 Rust 扩展（性能最高，功能最全）⚡

推荐用于高性能计算和完整功能访问：

# 1. 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 2. 克隆项目
git clone https://github.com/your-username/rustkmer.git
cd rustkmer

# 3. 构建 PyO3 扩展（推荐 Python 3.10-3.12）
cd pyo3
pip install maturin
maturin develop --release

# 4. 验证安装
python -c "from pyrustkmer import PyDatabase; print('✅ PyO3 扩展就绪!')"

✅ PyO3 扩展特性:

最高性能: 直接Rust绑定，无CLI开销
完整功能: 支持所有高级功能（模糊查询、前缀搜索、混合搜索）
内存效率: 直接内存访问，最小化数据复制
Python原生: 返回Python对象，无格式转换开销

⚠️ 环境要求:

Python版本: 推荐 3.10-3.12
Rust工具链: stable 1.80+
编译环境: 需要C/C++编译器
内存: 编译时需要额外内存

🔧 编译选项:

# 开发模式（快速编译）
maturin develop

# 发布模式（最优性能）
maturin develop --release

# 指定Python解释器
maturin develop --python python3.11

# 仅构建不安装
maturin build

✅ 兼容性状态:

Python 3.10: ✅ 完全支持
Python 3.11: ✅ 完全支持
Python 3.12: ✅ 完全支持
Python 3.13: ⚠️ 部分支持（PyO3版本相关）

🚀 性能对比:

# PyO3扩展 - 最高性能
from pyrustkmer import PyDatabase, LoadMode
db = PyDatabase("genome.rkdb", LoadMode.Preload)
result = db.query_prefix("ATG")  # 直接内存访问
print(f"Found {len(result)} matches")


**💡 使用建议**:
- **生产环境高性能**: PyO3扩展
- **开发调试**: 可编辑开发安装
- **环境兼容性**: 纯Python Stubs
- **特殊需求**: 根据性能要求选择

### 安装方式对比

| 方式 | Python 兼容性 | 安装难度 | 性能 | 稳定性 | 内存效率 | 推荐场景 |
|------|---------------|----------|------|--------|----------|----------|
| **纯 Python Stubs** | ✅ 3.8-3.13 | ⭐ 简单 | ⭐⭐⭐ CLI级 | ⭐⭐⭐⭐⭐ 极高 | ⭐⭐⭐ 进程隔离 | 生产环境、广泛兼容 |
| **可编辑开发安装** | ✅ 3.10+ | ⭐⭐⭐ 中等 | ⭐⭐⭐ CLI级 | ⭐⭐⭐⭐ 高 | ⭐⭐⭐ 进程隔离 | 开发调试、代码修改 |
| **PyO3 扩展** | ✅ 3.10-3.12 | ⭐⭐⭐⭐ 较复杂 | ⭐⭐⭐⭐⭐ 本地Rust | ⭐⭐⭐⭐ 高 | ⭐⭐⭐⭐⭐ 直接内存 | 高性能计算、内存敏感 |

### PyO3 扩展特性

PyO3扩展提供了最完整的RustKmer功能访问：

#### 🔥 高级查询功能
```python
from pyrustkmer import PyDatabase, PyPrefixQuery, LoadMode

# 1. 高性能前缀搜索
db = PyDatabase("genome.rkdb", LoadMode.Preload)
result = db.query_prefix("ATG")
print(f"找到 {len(result)} 个前缀匹配")

# 2. 混合搜索模式
from pyrustkmer import PyFuzzyQuery
fuzzy = PyFuzzyQuery(db)
hybrid_result = fuzzy.query_fuzzy("ATCGNNN", max_mutations=2)

# 3. 专用查询引擎
query_engine = PyPrefixQuery("genome.rkdb", LoadMode.Preload)
prefix_results = query_engine.query_prefix("ATG")

# 4. 批量前缀查询
prefixes = ["ATG", "CTG", "GTG", "TTA", "TAA"]
for prefix in prefixes:
    result = db.query_prefix(prefix)
    print(f"{prefix}: {len(result)} matches")

📊 性能监控

# 获取详细性能指标
result = db.query_prefix("ATG")
print(f"前缀匹配数: {len(result)}")

# 模糊查询性能
fuzzy_result = fuzzy.query_fuzzy("ATCGNNN", max_mutations=2)
print(f"模糊匹配数: {len(fuzzy_result.get_top_matches(1000))}")

🔧 加载模式

from pyrustkmer import PyDatabase, LoadMode

# 预加载模式（最快查询，适合小数据库）
db = PyDatabase("small_genome.rkdb", LoadMode.Preload)

# 内存映射模式（平衡内存和性能）
db = PyDatabase("large_genome.rkdb", LoadMode.MemoryMapped)

# 延迟加载模式（最低内存，适合超大数据库）
db = PyDatabase("huge_genome.rkdb", LoadMode.Lazy)

快速示例

K-mer 计数

from pyrustkmer import PyCounter

# 创建k-mer计数器
counter = PyCounter(21, canonical=True)

# 从FASTA文件计数
counter.add_from_fasta("sequences.fasta")

# 从字符串计数
counter.add_sequence("ATCGATCGATCGATCGATCGATCG")

# 获取统计信息
stats = counter.get_stats()
print(f"Counts: {stats.total_kmers}")

# 保存数据库
counter.save_database("output.rkdb")

数据库查询

from pyrustkmer import PyDatabase, LoadMode

# 加载数据库
db = PyDatabase("genome.rkdb", LoadMode.Preload)

# 单个查询
result = db.query_exact("ATCGATCGATCGATCGATCGATCG")
print(f"K-mer count: {result.count}, found: {result.found}")

# 前缀查询
prefix_results = db.query_prefix("ATCG")
print(f"Prefix matches: {len(prefix_results)}")

# 检查k-mer是否存在
if result.found:
    print("K-mer found in database")

数据库统计

from pyrustkmer import PyDatabase, LoadMode

db = PyDatabase("genome.rkdb", LoadMode.Preload)
# 可以通过前缀查询来了解数据库大小
sample_results = db.query_prefix("A")
print(f"Sample prefix matches: {len(sample_results)}")

数据库导出

from pyrustkmer import PyDatabase, LoadMode

db = PyDatabase("genome.rkdb", LoadMode.Preload)

# 导出为文本格式（通过前缀查询并写入文件）
with open("output.txt", "w") as f:
    results = db.query_prefix("A")
    for result in results:
        f.write(f"{result.kmer}\t{result.count}\n")

数据库合并

# 使用命令行工具合并数据库
# rustkmer merge -i sample1.rkdb sample2.rkdb -o merged.rkdb

# 然后在Python中加载合并后的数据库
from pyrustkmer import PyDatabase, LoadMode
db = PyDatabase("merged.rkdb", LoadMode.Preload)
print(f"Merged database loaded successfully")

性能优势

高性能: Rust核心实现，比纯Python实现快100倍以上
内存效率: 支持大型数据库的内存映射访问
线程安全: 可以在多线程环境中安全使用
兼容性: 与CLI命令行工具完全兼容

更多详细信息请查看 pyrustkmer Python 包 (pyo3/)。

🛠️ 故障排除

常见导入问题

问题1: ImportError: cannot import name 'PyDatabase'

# 检查 pyrustkmer 是否安装
pip list | grep pyrustkmer

# 如果没有安装，重新安装
pip install rustkmer

问题2: 只能在特定目录下导入

# 确保使用了正确安装
pip uninstall rustkmer
pip install rustkmer

# 测试从不同目录导入
cd /tmp
python -c "from pyrustkmer import PyDatabase; print('✅ 导入成功')"

问题3: ImportError: No module named 'pyrustkmer'

# 检查包是否正确安装
pip list | grep pyrustkmer

# 如果没有安装，重新安装
pip install rustkmer

问题4: 无法找到 rustkmer 命令

# 检查 rustkmer 是否在 PATH 中
which rustkmer

# 如果没有，添加 rustkmer 到 PATH
echo 'export PATH="/path/to/rustkmer/target/release:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题5: PyO3 扩展编译失败

# 检查 Rust 工具链
rustc --version  # 需要 1.80+

# 检查 Python 开发头文件
python3 -c "import sysconfig; print(sysconfig.get_path('include'))"

# Ubuntu/Debian 安装开发依赖
sudo apt install python3-dev build-essential

# macOS 安装 Xcode 命令行工具
xcode-select --install

# 手动编译调试
cd /path/to/rustkmer/pyo3
maturin develop --verbose

问题5.1: VIRTUAL_ENV 和 CONDA_PREFIX 环境冲突

# 错误信息示例
# 💥 maturin failed
# Caused by: Both VIRTUAL_ENV and CONDA_PREFIX are set. Please unset one of them

# CondaError: Run 'conda init' before 'conda deactivate'
# CONDA_PREFIX: /Users/forrest/miniconda3

# 解决方案1: 停用 conda 环境（推荐）
conda deactivate
# 然后重新运行
maturin develop --release

# 解决方案2: 停用虚拟环境
deactivate
# 然后重新运行
maturin develop --release

# 解决方案3: 直接清理环境变量（最有效）
unset VIRTUAL_ENV
unset CONDA_PREFIX
# 验证清理结果
echo "VIRTUAL_ENV: $VIRTUAL_ENV"
echo "CONDA_PREFIX: $CONDA_PREFIX"
# 确认都为空后重新编译
maturin develop --release

# 解决方案4: 手动设置环境（完全控制）
# 临时禁用conda
export CONDA_PREFIX=""
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"
# 然后编译
maturin develop --release

# 解决方案5: 在新的干净shell中运行
# 打开新的终端窗口或标签页
# 确保没有激活任何环境
# 然后运行
cd rustkmer/pyo3
maturin develop --release

问题5.2: 清理环境后重新编译

# 清理之前的编译结果
cd rustkmer/pyo3
pip uninstall rustkmer-pyo3 -y  # 如果之前安装过
rm -rf target/ .pytest_cache/

# 确保环境干净
unset VIRTUAL_ENV
unset CONDA_PREFIX

# 重新编译
maturin develop --release

问题5.3: 环境隔离最佳实践

# 推荐做法1: 使用纯 conda 环境
conda create -n rustkmer-dev python=3.11
conda activate rustkmer-dev
cd rustkmer/pyo3
maturin develop --release

# 推荐做法2: 使用纯 virtualenv 环境
python3 -m venv rustkmer-env
source rustkmer-env/bin/activate
cd rustkmer/pyo3
maturin develop --release

# 推荐做法3: 使用系统Python（最简单）
# 确保没有激活任何虚拟环境
conda deactivate 2>/dev/null || true
deactivate 2>/dev/null || true
unset VIRTUAL_ENV
unset CONDA_PREFIX
# 使用系统Python直接编译
python3 -m pip install maturin
cd rustkmer/pyo3
maturin develop --release

# 避免混用环境
# ❌ 不要同时激活 virtualenv 和 conda
source myenv/bin/activate  # virtualenv
conda activate myenv       # conda - 这样会冲突！

问题5.4: conda 没有初始化时的解决方案

# 症状: CondaError: Run 'conda init' before 'conda deactivate'

# 解决方案1: 手动清理 conda 环境变量
unset CONDA_PREFIX
unset CONDA_DEFAULT_ENV
unset CONDA_ENV_PATH
# 清理 conda 相关的PATH
export PATH=$(echo $PATH | tr ':' '\n' | grep -v conda | tr '\n' ':' | sed 's/:$//')

# 解决方案2: 使用绝对路径运行Python
# 完全绕过虚拟环境
/usr/bin/python3 -m pip install maturin
cd rustkmer/pyo3
/usr/bin/python3 -m maturin develop --release

# 解决方案3: 重新初始化 conda（如果需要）
# 首先清理所有环境变量
unset CONDA_*
# 然后重新初始化
source ~/miniconda3/etc/profile.d/conda.sh
# 或
eval "$(/Users/forrest/miniconda3/bin/conda shell.bash hook)"
# 现在可以正常使用 conda
conda deactivate

问题5.5: PyO3 链接器错误解决方案

# 症状: ld: symbol(s) not found for architecture arm64
#       clang: error: linker command failed with exit code 1

# 解决方案1: 使用正确的链接器标志（macOS）
cd /path/to/rustkmer/pyo3
export RUSTFLAGS="-C link-arg=-undefined -C link-arg=dynamic_lookup"
maturin develop --release

# 解决方案2: 指定正确的Python解释器
cd /path/to/rustkmer/pyo3
PYO3_PYTHON=/usr/bin/python3 maturin develop --release

# 解决方案3: 结合使用（最可靠）
cd /path/to/rustkmer/pyo3
export RUSTFLAGS="-C link-arg=-undefined -C link-arg=dynamic_lookup"
export PYO3_PYTHON=/usr/bin/python3
maturin develop --release

# 解决方案4: 测试导入
python3 -c "from pyrustkmer import PyDatabase; print('Success!')"

问题6: PyO3 导入错误

# 验证 PyO3 扩展安装
try:
    from pyrustkmer import PyDatabase, LoadMode
    print("✅ PyO3 扩展导入成功")
    
    # 测试基本功能
    print("✅ PyDatabase 类可用")
    
except ImportError as e:
    print(f"❌ PyO3 扩展导入失败: {e}")
    print("请重新安装: pip install rustkmer")
except Exception as e:
    print(f"❌ 其他错误: {e}")

问题7: PyO3 性能不如预期

# 检查是否使用了正确的加载模式
from pyrustkmer import PyDatabase, LoadMode

# 对于小数据库，使用预加载
db = PyDatabase("small.rkdb", LoadMode.Preload)

# 对于大数据库，使用内存映射
db = PyDatabase("large.rkdb", LoadMode.MemoryMapped)

# 使用优化方法
# ✅ 优化方法
result = db.query_prefix("ATG")
print(f"Found {len(result)} matches")

问题8: Python 3.13 兼容性问题

# Python 3.13 用户建议使用 pyrustkmer
pip install rustkmer

# 或使用 Python 3.10-3.12 环境以获得完整功能
conda create -n rustkmer-py311 python=3.11
conda activate rustkmer-py311
pip install rustkmer

问题9: 防止环境冲突的最佳实践

# 1. 明确选择一种环境管理方式
# 方式A: 纯 conda
conda create -n rustkmer-env python=3.11
conda activate rustkmer-env
# 在此环境中进行所有操作

# 方式B: 纯 virtualenv
python3 -m venv rustkmer-env
source rustkmer-env/bin/activate
# 在此环境中进行所有操作

# 方式C: 系统Python（最简单，避免环境问题）
# 不激活任何环境，直接使用系统Python

# 2. 检查当前环境状态
env | grep -E "(VIRTUAL_ENV|CONDA_PREFIX)"

# 3. 一键清理环境脚本
cleanup_env() {
    echo "清理环境变量..."
    unset VIRTUAL_ENV
    unset CONDA_PREFIX
    unset CONDA_DEFAULT_ENV
    unset CONDA_ENV_PATH
    
    # 清理PATH中的conda路径
    export PATH=$(echo $PATH | tr ':' '\n' | grep -v conda | tr '\n' ':' | sed 's/:$//')
    
    echo "环境已清理"
    echo "VIRTUAL_ENV: $VIRTUAL_ENV"
    echo "CONDA_PREFIX: $CONDA_PREFIX"
}

# 使用方法
cleanup_env
# 然后运行编译
cd rustkmer/pyo3
maturin develop --release

# 4. 在项目目录中创建环境检查脚本
cat > check_env.sh << 'EOF'
#!/bin/bash
echo "=== 环境检查 ==="
echo "VIRTUAL_ENV: ${VIRTUAL_ENV:-'未设置'}"
echo "CONDA_PREFIX: ${CONDA_PREFIX:-'未设置'}"
echo "Python路径: $(which python3)"
echo "Python版本: $(python3 --version)"
echo "================="
EOF

chmod +x check_env.sh
./check_env.sh

# 5. PyO3 构建专用脚本
cat > build_pyo3.sh << 'EOF'
#!/bin/bash
echo "🔧 开始 PyO3 构建..."

# 清理环境变量
echo "🧹 清理环境变量..."
unset VIRTUAL_ENV
unset CONDA_PREFIX
unset CONDA_DEFAULT_ENV
unset CONDA_ENV_PATH

# 设置构建标志
echo "⚙️  设置构建标志..."
export RUSTFLAGS="-C link-arg=-undefined -C link-arg=dynamic_lookup"
export PYO3_PYTHON=/usr/bin/python3

# 构建
echo "🔨 开始构建..."
cd /path/to/rustkmer/pyo3
maturin develop --release

# 检查结果
if [ $? -eq 0 ]; then
    echo "✅ 构建成功!"
    echo "🧪 测试导入..."
    /usr/bin/python3 -c "from pyrustkmer import PyDatabase; print('🎉 PyO3 扩展导入成功!')" 2>/dev/null || echo "❌ 导入失败"
else
    echo "❌ 构建失败!"
    exit 1
fi
EOF

chmod +x build_pyo3.sh
echo "🚀 运行构建脚本: ./build_pyo3.sh"

验证安装完整性

# 完整的安装验证脚本
def verify_rustkmer_installation():
    """验证 RustKmer 安装的完整性"""
    
    print("🔍 开始验证 RustKmer 安装...")
    
    # 1. 验证 pyrustkmer
    try:
        from pyrustkmer import PyDatabase, PyCounter, LoadMode
        print("✅ pyrustkmer 导入成功")

        # 2. 测试基本功能
        print("✅ PyDatabase, PyCounter 类可用")

    except ImportError as e:
        print(f"❌ pyrustkmer 导入失败: {e}")
    except Exception as e:
        print(f"❌ pyrustkmer 其他错误: {e}")
    
    # 6. PyO3 扩展已经集成到 pyrustkmer 中，无需单独验证
    
    # 7. 系统信息检查
    import sys
    import platform
    
    print(f"\n📋 系统信息:")
    print(f"   Python 版本: {sys.version}")
    print(f"   操作系统: {platform.system()} {platform.release()}")
    print(f"   架构: {platform.machine()}")
    
    # 8. 性能建议
    print(f"\n💡 性能建议:")
    if sys.version_info >= (3, 10):
        print("   ✅ Python 版本适合 PyO3 扩展")
    else:
        print("   ⚠️ 建议升级到 Python 3.10+ 以获得最佳性能")
    
    print("   ✅ 使用排序数据库获得最佳查询性能")
    print("   ✅ 对于小数据库使用预加载模式")
    print("   ✅ 对于大数据库使用内存映射模式")
    
    print("\n🎉 RustKmer 安装验证完成！")
    return True

# 运行验证
verify_rustkmer_installation()

开发环境建议

如果您需要修改 RustKmer 的源代码，建议使用以下工作流：

# 1. 设置开发环境
git clone https://github.com/your-username/rustkmer.git
cd rustkmer

# 2. 创建开发分支
git checkout -b feature/your-modification

# 3. 进行修改
# ... 修改 Rust 和/或 Python 代码 ...

# 4. 构建和测试
cargo build --release
cd python && pip install -e .
python -m pytest tests/

# 5. 验证功能
python -c "from pyrustkmer import PyDatabase; print('✅ 开发版本正常工作')"

# 6. 提交更改
git add .
git commit -m "Your modification description"
git push origin feature/your-modification

🏆 项目状态

✅ 已完成功能:

高性能k-mer计数
批量k-mer查询
数据库合并功能
排序数据库优化
🔥 前缀查询和混合搜索
🔥 PyO3高性能Python扩展
Python API集成（多种方式）
完整的性能测试验证

🚀 性能指标:

高性能查询: 22,703+ queries/sec
排序数据库优化: 384-1526倍性能提升
支持>100M k-mers大规模数据
PyO3扩展：最高性能和完整功能访问

🛠️ Python集成选项:

纯Python Stubs: 广泛兼容，零编译
可编辑安装: 开发调试，代码修改
PyO3扩展: 最高性能，功能最全

RustKmer: 为现代生物信息学设计的高性能k-mer分析工具。通过大规模性能测试验证，相比传统工具实现显著性能提升，是生产环境k-mer分析的理想选择。

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
.cargo		.cargo
.github/workflows		.github/workflows
.opencode/command		.opencode/command
docs		docs
examples		examples
pyo3		pyo3
scripts		scripts
src		src
test_data		test_data
tests		tests
tools		tools
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.pydocstylerc		.pydocstylerc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Cargo.toml		Cargo.toml
INSTALL.md		INSTALL.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
USER_GUIDE.md		USER_GUIDE.md
VERSION.md		VERSION.md
fresh_test.py		fresh_test.py
mkdocs.yml		mkdocs.yml
precise_analysis.py		precise_analysis.py

License

zhangtaolab/rustkmer

Folders and files

Latest commit

History

Repository files navigation

RustKmer

🚀 主要特性

🏆 性能优势

🛠️ 核心功能

🔬 科学验证

📦 安装

Python包 + 虚拟环境 (强烈推荐)

现代Python + uv (超快安装) ⚡

📦 Conda环境安装 🐍

方法一：使用conda-forge频道 (推荐)

方法二：从PyPI安装到Conda环境

方法三：开发环境设置 (完整版)

常用Conda命令参考

环境配置文件示例

Conda + Jupyter集成

系统级Python安装

从源码编译 (CLI工具) 🦀

系统要求

🔧 快速开始

基本用法

🆕 大k-mer支持 (k > 32)

大k-mer特性：

性能关键发现

Python集成

方式一：纯Python API（推荐）

方式二：PyO3高性能扩展 ⚡

🔥 模糊查询功能 (Wildcard & Mutation Tolerance)

标准使用示例

📚 详细文档

完整文档和示例

命令参考

count - k-mer计数

query - k-mer查询（高性能推荐）

info - 数据库信息

dump - 数据库导出

merge - 数据库合并

性能优化指南

🏆 最佳性能配置

RKDB数据库格式

性能优化

🏆 性能基准测试结果

🚀 快速示例

基本使用示例

生产环境示例

🧪 测试和验证

运行测试

性能验证

🐍 Python集成示例

基本Python API

高级分析示例

安装Python依赖

🔬 技术细节

算法实现

内存效率

性能配置

🤝 贡献

开发环境设置

📄 许可证

🙏 致谢

📂 项目结构

📞 联系方式

🐍 Python API

安装方式

方式一：纯 Python Stubs（推荐，最稳定）✅

方式二：可编辑开发安装（开发/修改代码）⚠️

方式三：PyO3 Rust 扩展（性能最高，功能最全）⚡

📊 性能监控

🔧 加载模式

快速示例

K-mer 计数

数据库查询

数据库统计

数据库导出

数据库合并

`count` - k-mer计数

`query` - k-mer查询（高性能推荐）

`info` - 数据库信息

`dump` - 数据库导出

`merge` - 数据库合并

Packages