Xamdst

Xamdst 是经典比对统计工具 Bamdst (v1.1.0) 的现代化 Fork 版本。

本项目在保留原版核心功能的基础上，通过引入 HTSLib 库并重构底层架构，显著提升了处理性能与文件格式兼容性，使其更能适应现代高通量测序数据的分析需求。

🚀 主要更新特性 (v2.0.0)

相比于原版 Bamdst，Xamdst 带来了以下关键改进：

底层架构现代化 弃用了老旧的 samlib 框架，全面迁移至行业标准的 HTSLib，提升了稳定性与维护性。
原生多线程支持 得益于 HTSLib 的集成，现已支持原生多线程解压与读取，大幅提升在大规模数据下的运行速度。
全面支持 CRAM 格式 新增对高压缩比 CRAM 文件的直接读取支持。

注意：处理 CRAM 文件时，需使用 -T 参数指定参考基因组文件。
新增相对深度统计指标 在原有的绝对深度（如 >10x, >30x）基础上，新增了基于平均深度的比例覆盖度统计。
- 例如：统计覆盖度达到平均深度 0.2 倍或 0.5 倍的区域占比。
机器可读的 JSON 报告 新增 JSON 格式输出，便于下游分析流程（Pipeline）直接解析与质控数据集成。

📄 输出示例 (JSON)

v2.0.0 版本生成的 JSON 报告包含详细的质控指标，涵盖比对统计、插入片段分布、Target 区域及 Flanking 区域覆盖度等信息：

{
  "version": "2.0.0",
  "files": ["02.Alignment/test.marked.cram"],
  "total": {
    "raw_reads": 4916994,
    "qc_fail_reads": 0,
    "raw_data_mb": 729.93,
    "paired_reads": 4916994,
    "mapped_reads": 4916790,
    "mapped_reads_fraction": 100.00,
    "mapped_data_mb": 729.92,
    "mapped_data_fraction": 100.00,
    "properly_paired": 4855432,
    "properly_paired_fraction": 98.75,
    "read_mate_paired": 4916690,
    "read_mate_paired_fraction": 99.99,
    "singletons": 100,
    "diff_chr": 15204,
    "read1": 2458497,
    "read2": 2458497,
    "read1_rmdup": 2200254,
    "read2_rmdup": 2200199,
    "forward_strand": 2458456,
    "backward_strand": 2458334,
    "pcr_duplicates": 516337,
    "pcr_duplicates_fraction": 10.50,
    "mapq_cutoff": 20,
    "mapq_reads": 4566427,
    "mapq_reads_fraction_all": 92.87,
    "mapq_reads_fraction_mapped": 92.87
  },
  "insert_size": {
    "average": 260.29,
    "median": 253
  },
  "target": {
    "target_reads": 3746965,
    "target_reads_fraction_all": 76.20,
    "target_reads_fraction_mapped": 76.21,
    "target_data_mb": 401.34,
    "target_data_rmdup_mb": 330.06,
    "target_data_fraction_all": 54.98,
    "target_data_fraction_mapped": 54.98,
    "region_length": 49735982,
    "average_depth": 8.07,
    "average_depth_rmdup": 6.64,
    "coverage": {
      "gt_0x": 84.22,
      "gte_4x": 68.70,
      "gte_10x": 32.79,
      "gte_30x": 1.68,
      "gte_100x": 0.12,
      "gt_0_2_avg": 84.22,
      "gt_0_5_avg": 68.70,
      "ratio_based": {
        "gt_0.2_avg": 79.90,
        "gt_0.5_avg": 62.38
      }
    },
    "coverage_rmdup": {
      "gt_0x": 82.42,
      "gte_4x": 64.78,
      "gte_10x": 25.87,
      "gte_30x": 0.69,
      "gte_100x": 0.02
    },
    "region_count": 238982,
    "region_coverage": {
      "gt_0x_count": 200958,
      "gt_0x_fraction": 84.09,
      "gte_4x_fraction": 64.93,
      "gte_10x_fraction": 24.81,
      "gte_30x_fraction": 0.95,
      "gte_100x_fraction": 0.03
    }
  },
  "flank": {
    "flank_size": 200,
    "region_length": 126297494,
    "average_depth": 4.88,
    "flank_reads": 4238766,
    "flank_reads_fraction_all": 86.21,
    "flank_reads_fraction_mapped": 86.21,
    "flank_data_mb": 616.65,
    "flank_data_fraction_all": 84.48,
    "flank_data_fraction_mapped": 84.48,
    "coverage": {
      "gt_0x": 72.65,
      "gte_4x": 43.44,
      "gte_10x": 16.76,
      "gte_30x": 0.81,
      "gte_100x": 0.05
    }
  }
}

🛠️ 安装与部署

Xamdst 提供了源码编译和 Docker 镜像两种部署方式。

1. 环境依赖 (Dependencies)

在编译源码前，请确保系统中已安装以下基础库：

htslib: 用于 BAM/CRAM/SAM 文件的核心读写支持
zlib: 用于数据压缩支持
pthread: 用于多线程支持

Debian/Ubuntu:

apt-get update
apt-get install libhts-dev zlib1g-dev

2. 源码编译(Build from Source)

git clone https://github.com/pzweuj/xamdst.git
cd xamdst
make

3. Docker 部署

如果您希望快速体验或集成到云流程中，可以直接拉取包含 Xamdst 的镜像：

docker pull ghcr.io/pzweuj/mapping:2026Jan