alnkit 0.2.0__py3-none-any.whl

alnkit/core/bam_segments.py

@@ -0,0 +1,183 @@
+"""BAM -> 规范 ``Segment``（D2）：CIGAR 解析、简化视图、read 轴归正。
+
+来源：``upstream/scripts/alignment_table.py``（276 行）的移植。与移植前保持三件事不变：
+
+* 参考坐标 0-based 半开，取 pysam 的 ``reference_start/reference_end``；
+* read 坐标统一到**正向 read 轴**（反向记录做 ``read_length - stored`` 镜像），
+  这样同一条 read 的基因组段与外源段才能直接比距离；
+* ``cigar`` 是**简化视图**（两个 M 之间总长 <= 5 bp 的 I/D 并入 M），
+  因此它的 M 之和可能小于 ``ref_aln_len`` 的真实跨度。
+
+历史表头（``ref_pos_start`` 等 14 列）不在这里写，见 ``alnkit.cli.seg`` 的 legacy 写出器。
+"""
+
+from __future__ import annotations
+
+import os
+
+import pysam
+
+from .coords import flip_read_interval
+from .errors import UsageError
+from .segments import Segment
+
+__all__ = [
+    "ABSORBABLE_GAP_MAX_LENGTH",
+    "cigar_ops_from_pysam",
+    "format_cigar_ops",
+    "load_alignment_segments",
+    "load_fai_lengths",
+    "simplify_cigar_ops",
+]
+
+#: 被吸进 M 的小 I/D 总长上限
+ABSORBABLE_GAP_MAX_LENGTH = 5
+
+_OPERATION_BY_CODE = {0: "M", 1: "I", 2: "D", 3: "N", 4: "S", 5: "H", 6: "P", 7: "=", 8: "X"}
+
+
+def cigar_ops_from_pysam(read: pysam.AlignedSegment) -> list[tuple[int, str]]:
+    """pysam ``cigartuples`` -> ``[(长度, 操作符)]``。"""
+    return [(length, _OPERATION_BY_CODE[code]) for code, length in (read.cigartuples or [])]
+
+
+def simplify_cigar_ops(cigar_ops: list[tuple[int, str]]) -> list[tuple[int, str]]:
+    """把“夹在两个 M 之间、总长 <= 5”的 I/D 并进 M。
+
+    例：``[(39,'M'),(1,'D'),(66,'M'),(1,'D'),(92,'M'),(1,'I'),(445,'M')]`` -> ``[(645,'M')]``。
+    S/H/N/P 与首尾的 I/D 一律不动；相邻同类型操作合并。
+    """
+    match_length = 0
+    pending_ops: list[tuple[int, str]] = []
+    pending_bases = 0
+    simplified: list[tuple[int, str]] = []
+
+    def close_match_run() -> None:
+        nonlocal match_length, pending_ops, pending_bases
+        if match_length:
+            simplified.append((match_length, "M"))
+            match_length = 0
+        if pending_ops:
+            simplified.extend(pending_ops)
+            pending_ops = []
+            pending_bases = 0
+
+    for length, operation in cigar_ops:
+        if operation in ("M", "=", "X"):
+            if match_length:
+                match_length += pending_bases + length
+            else:
+                close_match_run()
+                match_length = length
+            pending_ops = []
+            pending_bases = 0
+            continue
+        if (
+            operation in ("I", "D")
+            and match_length
+            and pending_bases + length <= ABSORBABLE_GAP_MAX_LENGTH
+        ):
+            pending_ops.append((length, operation))
+            pending_bases += length
+            continue
+        close_match_run()
+        simplified.append((length, operation))
+
+    close_match_run()
+    merged: list[tuple[int, str]] = []
+    for length, operation in simplified:
+        if merged and merged[-1][1] == operation:
+            merged[-1] = (merged[-1][0] + length, operation)
+        else:
+            merged.append((length, operation))
+    return merged
+
+
+def format_cigar_ops(cigar_ops: list[tuple[int, str]]) -> str:
+    """``[(418,'S'),(1358,'M'),(10151,'S')]`` -> ``"418S1358M10151S"``。"""
+    return "".join(f"{length}{operation}" for length, operation in cigar_ops)
+
+
+def load_fai_lengths(fai_path: str | os.PathLike[str]) -> dict[str, int]:
+    """读 ``.fai``，返回 ``{序列名: 长度}``。"""
+    lengths: dict[str, int] = {}
+    try:
+        with open(fai_path, encoding="utf-8") as handle:
+            for line in handle:
+                if not line.strip():
+                    continue
+                fields = line.rstrip("\n").split("\t")
+                if len(fields) >= 2:
+                    lengths[fields[0]] = int(fields[1])
+    except FileNotFoundError:
+        raise UsageError(f"找不到 .fai：{os.fspath(fai_path)}（用 samtools faidx 生成）") from None
+    return lengths
+
+
+def load_alignment_segments(
+    bam_path: str | os.PathLike[str],
+    chrom_lengths: dict[str, int] | None = None,
+    selected_read_names: set[str] | None = None,
+    skip_secondary: bool = False,
+) -> list[Segment]:
+    """读 BAM 的每条比对，转成规范 ``Segment``。
+
+    ``selected_read_names`` 给定时只解析这些 read（“先找目标 read、再只处理目标”，
+    大 BAM 上省内存）；``skip_secondary`` 在解析 CIGAR 之前就跳过 secondary 记录。
+    """
+    if not os.path.exists(bam_path):
+        raise UsageError(f"找不到 BAM：{os.fspath(bam_path)}")
+
+    segments: list[Segment] = []
+    with pysam.AlignmentFile(os.fspath(bam_path), "rb") as bam_file:
+        for read in bam_file:
+            if read.is_unmapped:
+                continue
+            if skip_secondary and read.is_secondary:
+                continue
+            if selected_read_names is not None and read.query_name not in selected_read_names:
+                continue
+            # 优先 infer_read_length：含硬剪切，否则反向记录的镜像换算会偏
+            read_length = read.infer_read_length() or read.query_length
+            if not read_length:
+                # 无 SEQ 的 BAM（samtools view --no-seq）算不出 read 轴坐标，宁可报错也不写 0
+                raise UsageError(
+                    f"{read.query_name}: 无法确定 read 长度（BAM 缺 SEQ？用原始 BAM 重跑）"
+                )
+            cigar_ops = cigar_ops_from_pysam(read)
+            match_columns = sum(length for length, op in cigar_ops if op in ("M", "=", "X"))
+            inserted_bases = sum(length for length, op in cigar_ops if op == "I")
+            deleted_bases = sum(length for length, op in cigar_ops if op == "D")
+            alignment_start = read.query_alignment_start or 0
+            alignment_end = read.query_alignment_end or 0
+            if read.is_reverse:
+                read_start, read_end = flip_read_interval(
+                    read_length, alignment_start, alignment_end
+                )
+            else:
+                read_start, read_end = alignment_start, alignment_end
+            nm_value = read.get_tag("NM") if read.has_tag("NM") else None
+            segments.append(
+                Segment(
+                    read_name=read.query_name or "",
+                    chrom=read.reference_name or "",
+                    ref_start_0based=read.reference_start,
+                    ref_end_0based=read.reference_end or read.reference_start,
+                    read_start_0based=read_start,
+                    read_end_0based=read_end,
+                    strand="-" if read.is_reverse else "+",
+                    mapq=read.mapping_quality,
+                    read_length=read_length,
+                    chrom_length=(chrom_lengths or {}).get(read.reference_name or "", None),
+                    ref_aln_len=(read.reference_end or 0) - read.reference_start,
+                    read_aln_len=alignment_end - alignment_start,
+                    cigar=format_cigar_ops(simplify_cigar_ops(cigar_ops)),
+                    is_secondary=bool(read.is_secondary),
+                    is_supplementary=bool(read.is_supplementary),
+                    nm=int(nm_value) if isinstance(nm_value, (int, float)) else None,
+                    match_columns=match_columns,
+                    inserted_bases=inserted_bases,
+                    deleted_bases=deleted_bases,
+                )
+            )
+    return segments

alnkit/core/coords.py

@@ -0,0 +1,129 @@
+"""坐标换算与区间字符串：全包唯一的 1-based / 0-based 转换入口。
+
+约定：
+
+* 内部计算一律 **0-based 半开** ``[start, end)``；
+* 区间展示串一律 **1-based 闭区间** ``chrom:start-end``（IGV/samtools/VCF 习惯）；
+* 断点这类“单点”用 ``*_pos_1based`` 表示**边界左侧碱基**的 1-based 坐标，
+  其 0-based 边界值与之数值相同（历史巧合，见 ``left_base_*``）。
+
+任何模块都不得手写 ``+1`` / ``-1``，只能调用本模块。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+__all__ = [
+    "REGION_PATTERN",
+    "merge_intervals",
+    "flip_read_interval",
+    "format_region_1based",
+    "interval_0based_to_1based",
+    "interval_1based_to_0based",
+    "left_base_0based",
+    "left_base_1based",
+    "parse_region_1based",
+    "to_0based",
+    "to_1based",
+]
+
+# 数字允许千分位逗号，但只在正确位置：1,000 合法，1,5 不合法
+REGION_PATTERN = re.compile(
+    r"^(?P<chrom>[^:\s]+):(?P<start>\d{1,3}(?:,\d{3})*|\d+)-(?P<end>\d{1,3}(?:,\d{3})*|\d+)$"
+)
+
+
+def to_1based(position_0based: int) -> int:
+    """碱基坐标：0-based -> 1-based。"""
+    if position_0based < 0:
+        raise ValueError(f"0-based 坐标不能为负：{position_0based}")
+    return position_0based + 1
+
+
+def to_0based(position_1based: int) -> int:
+    """碱基坐标：1-based -> 0-based。"""
+    if position_1based < 1:
+        raise ValueError(f"1-based 坐标必须 >= 1：{position_1based}")
+    return position_1based - 1
+
+
+def interval_0based_to_1based(start_0based: int, end_0based: int) -> tuple[int, int]:
+    """半开区间 ``[s, e)`` -> 1-based 闭区间 ``(s+1, e)``。"""
+    if start_0based < 0:
+        raise ValueError(f"0-based 起点不能为负：{start_0based}")
+    if end_0based < start_0based:
+        raise ValueError(f"区间终点小于起点：[{start_0based}, {end_0based})")
+    if end_0based == start_0based:
+        # 零长区间无法表示为 1-based 闭区间（start+1 > end），直接拒绝而不是产出解析不回去的串
+        raise ValueError(f"零长区间无法表示：{start_0based}")
+    return start_0based + 1, end_0based
+
+
+def interval_1based_to_0based(start_1based: int, end_1based: int) -> tuple[int, int]:
+    """1-based 闭区间 ``(s, e)`` -> 半开区间 ``[s-1, e)``。"""
+    if start_1based < 1:
+        raise ValueError(f"1-based 起点必须 >= 1：{start_1based}")
+    if end_1based < start_1based:
+        raise ValueError(f"区间终点小于起点：{start_1based}-{end_1based}")
+    return start_1based - 1, end_1based
+
+
+def left_base_1based(boundary_0based: int) -> int:
+    """边界左侧碱基的 1-based 坐标（= legacy ``Insert_Position`` 的口径）。
+
+    0-based 边界 B 表示“其左侧有 B 个碱基”，故左侧碱基的 1-based 编号恰为 B。
+    """
+    if boundary_0based < 0:
+        raise ValueError(f"边界不能为负：{boundary_0based}")
+    return boundary_0based
+
+
+def left_base_0based(boundary_0based: int) -> int:
+    """边界左侧碱基的 0-based 坐标（= 1-based 值 - 1）。
+
+    边界为 0 表示插入发生在第一个碱基之前，没有“左侧碱基”，抛 ``ValueError``。
+    """
+    if boundary_0based < 1:
+        raise ValueError(f"边界 {boundary_0based} 没有左侧碱基")
+    return left_base_1based(boundary_0based) - 1
+
+
+def flip_read_interval(read_length: int, start: int, end: int) -> tuple[int, int]:
+    """把反向链比对段的 read 区间翻到正向 read 轴（0-based 半开）。"""
+    if start < 0 or end > read_length or end < start:
+        raise ValueError(f"read 区间越界：[{start}, {end}) / 长度 {read_length}")
+    return read_length - end, read_length - start
+
+
+def parse_region_1based(text: str) -> tuple[str, int, int]:
+    """``"chr1:1,000-2,000"`` -> ``("chr1", 999, 2000)``（0-based 半开）。"""
+    match = REGION_PATTERN.match(text.strip())
+    if not match:
+        raise ValueError(f"区间格式应为 chrom:start-end（1-based）：{text!r}")
+    chrom = match.group("chrom")
+    start_1based = int(match.group("start").replace(",", ""))
+    end_1based = int(match.group("end").replace(",", ""))
+    start_0based, end_0based = interval_1based_to_0based(start_1based, end_1based)
+    return chrom, start_0based, end_0based
+
+
+def format_region_1based(chrom: str, start_0based: int, end_0based: int) -> str:
+    """``("chr1", 999, 2000)`` -> ``"chr1:1000-2000"``（0-based 半开输入）。"""
+    start_1based, end_1based = interval_0based_to_1based(start_0based, end_0based)
+    return f"{chrom}:{start_1based}-{end_1based}"
+
+
+def merge_intervals(intervals: Iterable[tuple[int, int]]) -> list[tuple[int, int]]:
+    """合并重叠或相邻的半开区间（0-based）。
+
+    例：``[(0, 10), (5, 20), (30, 40)]`` -> ``[(0, 20), (30, 40)]``。
+    """
+    merged: list[list[int]] = []
+    for start, end in sorted(intervals):
+        if merged and start <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], end)
+        else:
+            merged.append([start, end])
+    return [(start, end) for start, end in merged]

alnkit/core/errors.py

@@ -0,0 +1,25 @@
+"""异常类型与退出码约定。
+
+退出码沿用被重构脚本的既有约定：
+0 成功（可有警告）/ 1 运行期错误 / 2 参数或前置校验失败。
+"""
+
+from __future__ import annotations
+
+
+class AlnkitError(Exception):
+    """所有可预期错误的基类；``exit_code`` 决定进程退出码。"""
+
+    exit_code = 1
+
+
+class UsageError(AlnkitError):
+    """参数错误或前置条件不满足（退出码 2）。"""
+
+    exit_code = 2
+
+
+class RunError(AlnkitError):
+    """运行期失败：读文件、外部命令、写盘（退出码 1）。"""
+
+    exit_code = 1

alnkit/core/external.py

@@ -0,0 +1,63 @@
+"""外部命令探测（minimap2 / samtools / bwa）。
+
+只负责“找得到吗、什么版本”，命令拼装与执行留给各自的分析模块，
+避免核心层耦合具体流程。
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+__all__ = ["Tool", "ALIGNERS", "REFERENCE_TOOLS", "find_tool"]
+
+#: 比对器（至少装一个）
+ALIGNERS = ("minimap2", "bwa")
+#: 参考/比对文件处理
+REFERENCE_TOOLS = ("samtools",)
+
+_TIMEOUT_SECONDS = 10
+
+
+@dataclass(slots=True, frozen=True)
+class Tool:
+    """一个外部命令的探测结果。"""
+
+    name: str
+    path: str | None
+    version: str | None
+
+    @property
+    def available(self) -> bool:
+        return self.path is not None
+
+    def describe(self) -> str:
+        if not self.available:
+            return "未安装"
+        return self.version or "已安装（版本未知）"
+
+
+def _read_version(name: str, path: str) -> str | None:
+    try:
+        completed = subprocess.run(
+            [path, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    for line in (completed.stdout + completed.stderr).splitlines():
+        if line.strip():
+            return line.strip()[:120]
+    return None
+
+
+def find_tool(name: str) -> Tool:
+    """探测一个命令；找不到时返回 ``available=False`` 而不是抛异常。"""
+    path = shutil.which(name)
+    if path is None:
+        return Tool(name=name, path=None, version=None)
+    return Tool(name=name, path=path, version=_read_version(name, path))

alnkit/core/fasta.py

@@ -0,0 +1,83 @@
+"""FASTA/FASTQ 的小工具（D1）：反向互补、按 60 bp 折行写出、FAI 长度。
+
+只放多个步骤都要用的最小函数；参考基因组的随机访问请直接用 ``pysam.FastaFile``。
+"""
+
+from __future__ import annotations
+
+import gzip
+import os
+from collections.abc import Mapping
+
+import pysam
+
+from .errors import UsageError
+
+__all__ = [
+    "read_fasta_records",
+    "read_fastq_sequences",
+    "reverse_complement",
+    "write_fasta_records",
+]
+
+_COMPLEMENT = str.maketrans("ACGTNacgtn", "TGCANtgcan")
+LINE_WIDTH = 60
+
+
+def read_fasta_records(path: str | os.PathLike[str]) -> dict[str, str]:
+    """读小 FASTA（支持 ``.gz``），返回 ``{记录名: 大写序列}``。
+
+    只用于外源序列 / 组装片段这类小文件；参考基因组请用 ``pysam.FastaFile`` 随机访问。
+    记录名取 ``>`` 后的第一个字段；CRLF 与空行都已处理。
+    """
+    opener = gzip.open if str(path).endswith((".gz", ".bgz")) else open
+    records: dict[str, str] = {}
+    name: str | None = None
+    chunks: list[str] = []
+    try:
+        with opener(path, "rt", encoding="utf-8") as handle:
+            for line in handle:
+                line = line.rstrip("\r\n")
+                if line.startswith(">"):
+                    if name is not None:
+                        records[name] = "".join(chunks).upper()
+                    name = line[1:].split()[0] if line[1:].split() else ""
+                    chunks = []
+                elif line:
+                    chunks.append(line)
+    except FileNotFoundError:
+        raise UsageError(f"找不到 FASTA：{os.fspath(path)}") from None
+    if name is not None:
+        records[name] = "".join(chunks).upper()
+    return records
+
+
+def reverse_complement(sequence: str) -> str:
+    """反向互补（保留大小写）。"""
+    return sequence.translate(_COMPLEMENT)[::-1]
+
+
+def write_fasta_records(
+    records: Mapping[str, str], path: str | os.PathLike[str], width: int = LINE_WIDTH
+) -> int:
+    """按输入顺序写 FASTA，每行 ``width`` bp；返回写入的记录数。"""
+    target = os.fspath(path)
+    os.makedirs(os.path.dirname(os.path.abspath(target)), exist_ok=True)
+    with open(target, "w", encoding="utf-8", newline="") as handle:
+        for name, sequence in records.items():
+            handle.write(f">{name}\n")
+            for start in range(0, len(sequence), width):
+                handle.write(sequence[start : start + width] + "\n")
+    return len(records)
+
+
+def read_fastq_sequences(path: str | os.PathLike[str]) -> dict[str, str]:
+    """读 FASTQ，返回 ``{read_name: 大写序列}``（用 ``pysam.FastxFile``，与旧脚本一致）。"""
+    if not os.path.exists(path):
+        raise UsageError(f"找不到 FASTQ：{os.fspath(path)}")
+    sequences: dict[str, str] = {}
+    with pysam.FastxFile(os.fspath(path)) as handle:
+        for record in handle:
+            if record.name:
+                sequences[record.name] = (record.sequence or "").upper()
+    return sequences

alnkit/core/logging.py

@@ -0,0 +1,25 @@
+"""统一日志：单点配置，避免各模块自建 handler。"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+LOGGER_NAME = "alnkit"
+_FORMAT = "%(levelname)s %(name)s: %(message)s"
+
+
+def configure(level: str = "INFO", quiet: bool = False) -> None:
+    """配置 alnkit 根 logger。重复调用只更新级别，不叠加 handler。"""
+    logger = logging.getLogger(LOGGER_NAME)
+    logger.setLevel(logging.ERROR if quiet else level.upper())
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(logging.Formatter(_FORMAT))
+        logger.addHandler(handler)
+    logger.propagate = False
+
+
+def get_logger(name: str) -> logging.Logger:
+    """取 ``alnkit.<name>`` 子 logger。"""
+    return logging.getLogger(f"{LOGGER_NAME}.{name}")

alnkit/core/paf.py

@@ -0,0 +1,52 @@
+"""PAF 解析（D2）：minimap2 原生格式，坐标一律 0-based 半开。
+
+与绘图模块里的 PAF 解析保持同一语义，但这里保留全部 12 列（含 ``matches`` / ``mapq``），
+组装与 overlap 图需要一致率与比对长度。
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["PAF_MIN_FIELDS", "parse_paf"]
+
+PAF_MIN_FIELDS = 12
+
+
+def parse_paf(path: str | os.PathLike[str]) -> list[dict[str, object]]:
+    """读 PAF（需要 ``-c`` 才有第 10/11 列的匹配数与比对长度）。
+
+    返回每个比对块的字段：``query, query_length, query_start, query_end, strand,
+    target, target_length, target_start, target_end, matches, block_bp, identity, mapq``。
+    空行、``#`` 注释、列数不足、比对长度为 0 的行会被跳过。
+    """
+    blocks: list[dict[str, object]] = []
+    with open(path, encoding="utf-8") as handle:
+        for line in handle:
+            if not line.strip() or line.startswith("#"):
+                continue
+            fields = line.rstrip("\n").split("\t")
+            if len(fields) < PAF_MIN_FIELDS:
+                continue
+            aligned_length = int(fields[10])
+            if aligned_length <= 0:
+                continue
+            matches = int(fields[9])
+            blocks.append(
+                {
+                    "query": fields[0],
+                    "query_length": int(fields[1]),
+                    "query_start": int(fields[2]),
+                    "query_end": int(fields[3]),
+                    "strand": fields[4],
+                    "target": fields[5],
+                    "target_length": int(fields[6]),
+                    "target_start": int(fields[7]),
+                    "target_end": int(fields[8]),
+                    "matches": matches,
+                    "block_bp": aligned_length,
+                    "identity": matches / aligned_length,
+                    "mapq": int(fields[11]),
+                }
+            )
+    return blocks