alnkit 0.2.0__py3-none-any.whl

alnkit/cli/selftest.py

@@ -0,0 +1,308 @@
+"""``alnkit selftest``：不依赖任何输入数据的断言集。
+
+M0 覆盖坐标换算与表/段契约；二代 B1 的 30+ 条口径断言在 P2 并入这里
+。任何一条失败 → 退出码 1。
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from typing import Any
+
+from ..core import coords, segments, tables
+from ..core.errors import UsageError
+from ._common import GLOBAL_OPTIONS
+
+_CHECKS: list[tuple[str, Callable[[], None]]] = []
+
+
+def check(name: str) -> Callable[[Callable[[], None]], Callable[[], None]]:
+    """把一个无参函数注册成一条自检（失败即抛异常）。"""
+
+    def register(func: Callable[[], None]) -> Callable[[], None]:
+        _CHECKS.append((name, func))
+        return func
+
+    return register
+
+
+def add_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "selftest",
+        parents=[GLOBAL_OPTIONS],
+        help="运行内置自检（不需要输入数据）",
+        description="校验坐标换算与表契约；任何一条失败则退出码为 1。",
+        epilog="例子：\n  alnkit selftest",
+    )
+    parser.set_defaults(handler=run)
+
+
+# ------------------------------------------------------------------ coords
+@check("coords: 1-based <-> 0-based 往返")
+def _coords_position_roundtrip() -> None:
+    for position_0based in (0, 1, 9424, 1_000_000, 10**9):
+        back = coords.to_0based(coords.to_1based(position_0based))
+        assert back == position_0based, (position_0based, back)
+
+
+@check("coords: 区间串往返（1-based 闭 <-> 0-based 半开）")
+def _coords_region_roundtrip() -> None:
+    text = coords.format_region_1based("chr1", 2_000_000, 2_000_050)
+    assert text == "chr1:2000001-2000050", text
+    assert coords.parse_region_1based(text) == ("chr1", 2_000_000, 2_000_050)
+    assert coords.parse_region_1based("chr1:1,000-2,000") == ("chr1", 999, 2000)
+
+
+@check("coords: 区间换算互逆")
+def _coords_interval_roundtrip() -> None:
+    for start_0based, end_0based in ((0, 1), (99, 200), (2_000_000, 2_000_050)):
+        start_1based, end_1based = coords.interval_0based_to_1based(start_0based, end_0based)
+        assert (start_1based, end_1based) == (start_0based + 1, end_0based)
+        assert coords.interval_1based_to_0based(start_1based, end_1based) == (
+            start_0based,
+            end_0based,
+        )
+
+
+@check("coords: 断点边界 / 左碱基恒等式（Insert_Position 口径）")
+def _coords_boundary_identity() -> None:
+    boundary = 1_000_001
+    assert coords.left_base_1based(boundary) == 1_000_001
+    assert coords.left_base_0based(boundary) == 1_000_000
+    assert coords.left_base_0based(boundary) + 1 == coords.left_base_1based(boundary)
+
+
+@check("coords: 反向链 read 区间翻转")
+def _coords_flip_read_interval() -> None:
+    assert coords.flip_read_interval(40_592, 9_424, 40_591) == (1, 31_168)
+    assert coords.flip_read_interval(150, 0, 150) == (0, 150)
+    try:
+        coords.flip_read_interval(100, 10, 200)
+    except ValueError:
+        pass
+    else:  # pragma: no cover - 防御式断言
+        raise AssertionError("越界区间应当报错")
+
+
+# ------------------------------------------------------------------ tables
+@check("tables: 所有注册表满足坐标后缀规则")
+def _tables_registry_valid() -> None:
+    for table in tables.COLUMNS:
+        tables.validate_columns(table)
+
+
+@check("tables: 坐标列缺少基准后缀会被拒绝")
+def _tables_reject_bare_coordinate() -> None:
+    try:
+        tables.validate_column_names("demo", ("ref_start", "read_end"))
+    except AssertionError:
+        return
+    raise AssertionError("裸坐标列名 ref_start/read_end 应当被拒绝")
+
+
+@check("tables: 写入的列序与注册表一致")
+def _tables_column_order() -> None:
+    columns = tables.columns_of("insert_sites")
+    assert columns[0] == "chrom"
+    assert columns[1] == "insert_pos_1based"
+    assert columns[3] == "insert_boundary_0based"
+
+
+# ---------------------------------------------------------------- segments
+_SAME_NUMBERS = {
+    "read_name": "r1",
+    "chrom": "chr1",
+    "ref_start": 9_000_000,
+    "ref_end": 9_031_165,
+    "read_start": 9_424,
+    "read_end": 40_591,
+    "strand": "-",
+    "mapq": 60,
+}
+
+
+@check("segments: 三套历史表头解析出同一组坐标")
+def _segments_three_legacy_headers() -> None:
+    alignment_table_header = [
+        "chrom",
+        "chrom_length",
+        "ref_pos_start",
+        "ref_pos_end",
+        "read_name",
+        "read_pos_start",
+        "read_pos_end",
+        "strand",
+        "mapping_quality",
+        "is_secondary",
+        "is_supplementary",
+        "ref_aln_len",
+        "read_aln_len",
+        "simplified_cigar",
+    ]
+    alignment_table_row = {
+        "chrom": "chr1",
+        "chrom_length": "100000000",
+        "ref_pos_start": "9000000",
+        "ref_pos_end": "9031165",
+        "read_name": "r1",
+        "read_pos_start": "9424",
+        "read_pos_end": "40591",
+        "strand": "-",
+        "mapping_quality": "60",
+        "is_secondary": "0",
+        "is_supplementary": "0",
+        "ref_aln_len": "31165",
+        "read_aln_len": "31167",
+        "simplified_cigar": "1S31204M9424S",
+    }
+    classify_header = [
+        "read_name",
+        "segment_role",
+        "chrom",
+        "chrom_length",
+        "ref_start",
+        "ref_end",
+        "read_start",
+        "read_end",
+        "strand",
+        "mapq",
+        "ref_aln_len",
+        "read_aln_len",
+        "simplified_cigar",
+        "kept",
+        "drop_reason",
+    ]
+    classify_row = {
+        "read_name": "r1",
+        "segment_role": "genome",
+        "chrom": "chr1",
+        "chrom_length": "100000000",
+        "ref_start": "9000000",
+        "ref_end": "9031165",
+        "read_start": "9424",
+        "read_end": "40591",
+        "strand": "-",
+        "mapq": "60",
+        "ref_aln_len": "31165",
+        "read_aln_len": "31167",
+        "simplified_cigar": "1S31204M9424S",
+        "kept": "1",
+        "drop_reason": "-",
+    }
+    tracks_header = [
+        "read_name",
+        "read_length",
+        "segment_type",
+        "target_name",
+        "target_start",
+        "target_end",
+        "read_start",
+        "read_end",
+        "strand",
+        "mapq",
+    ]
+    tracks_row = {
+        "read_name": "r1",
+        "read_length": "40592",
+        "segment_type": "genome",
+        "target_name": "chr1",
+        "target_start": "9000000",
+        "target_end": "9031165",
+        "read_start": "9424",
+        "read_end": "40591",
+        "strand": "-",
+        "mapq": "60",
+    }
+
+    parsed = [
+        segments.segments_from_rows(header, [row])[0]
+        for header, row in (
+            (alignment_table_header, alignment_table_row),
+            (classify_header, classify_row),
+            (tracks_header, tracks_row),
+        )
+    ]
+    expected = (
+        _SAME_NUMBERS["ref_start"],
+        _SAME_NUMBERS["ref_end"],
+        _SAME_NUMBERS["read_start"],
+        _SAME_NUMBERS["read_end"],
+    )
+    for segment in parsed:
+        got = (
+            segment.ref_start_0based,
+            segment.ref_end_0based,
+            segment.read_start_0based,
+            segment.read_end_0based,
+        )
+        assert got == expected, (got, expected)
+        assert segment.chrom == "chr1"
+        assert segment.strand == "-"
+        assert segment.mapq == 60
+
+
+@check("segments: 缺列 / 倒置区间 / 坏 strand 都报 UsageError")
+def _segments_error_paths() -> None:
+    good_header = [
+        "read_name",
+        "chrom",
+        "ref_start",
+        "ref_end",
+        "read_start",
+        "read_end",
+        "strand",
+        "mapq",
+    ]
+    good_row = {
+        "read_name": "r1",
+        "chrom": "chr1",
+        "ref_start": "1",
+        "ref_end": "2",
+        "read_start": "0",
+        "read_end": "1",
+        "strand": "+",
+        "mapq": "60",
+    }
+
+    cases: list[tuple[list[str], dict[str, Any]]] = [
+        (good_header, {**good_row, "ref_start": "10", "ref_end": "5"}),
+        (good_header, {**good_row, "read_start": "9", "read_end": "1"}),
+        (good_header, {**good_row, "strand": "?"}),
+        (["read_name", "chrom"], {"read_name": "r1", "chrom": "chr1"}),
+    ]
+    for header, row in cases:
+        try:
+            segments.segments_from_rows(header, [row])
+        except UsageError:
+            continue
+        raise AssertionError(f"应当报 UsageError：{header} {row}")
+
+
+@check("short scan: 断点坐标 / 归属 / 窗口合并口径（原 parse_bam --self-test）")
+def _short_scan_self_test() -> None:
+    import contextlib
+    import io
+
+    from ..shortread import scan
+
+    buffer = io.StringIO()
+    with contextlib.redirect_stdout(buffer):
+        scan.run_self_test()
+    assert "self-test 通过" in buffer.getvalue()
+
+
+def run(args: argparse.Namespace) -> int:
+    del args
+    failures: list[str] = []
+    total = len(_CHECKS)
+    for name, func in _CHECKS:
+        try:
+            func()
+        except Exception as exc:  # noqa: BLE001 - 自检要汇总所有失败
+            failures.append(name)
+            print(f"FAIL  {name}\n        {type(exc).__name__}: {exc}")
+        else:
+            print(f"PASS  {name}")
+    print(f"\n{total - len(failures)}/{total} 通过")
+    return 1 if failures else 0

alnkit/cli/short.py

@@ -0,0 +1,245 @@
+"""短读长子命令：``alnkit short scan``（B1）。
+
+参数名、默认值、帮助文本与旧脚本 ``parse_bam.py`` 一一对应；只把 ``--version`` 与
+``--self-test`` 换成了 alnkit 的全局选项。
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from ..shortread import scan
+from ._common import GLOBAL_OPTIONS
+
+
+def add_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    short = subparsers.add_parser(
+        "short",
+        help="短读长链路（二代插入断点证据）",
+        description="从 BAM 找外源序列插入参考基因组的断点证据（SR / PESR / DUP）。",
+    )
+    short_subparsers = short.add_subparsers(dest="short_command", metavar="<subcommand>")
+    short_subparsers.required = True
+    _add_scan(short_subparsers)
+
+
+def _add_scan(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "scan",
+        parents=[GLOBAL_OPTIONS],
+        help="BAM -> 断点证据三张表",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=(
+            "一条跨越“参考基因组 <-> 外源插入序列”的嵌合比对可定位断点；"
+            "本命令按断点聚合证据（SR / PESR / DUP）。"
+        ),
+        epilog=(
+            "上游 BAM 的比对要求（详见原脚本 README）:\n"
+            "  必须 -Y（补充比对用 soft clip，只从 CIGAR 的 S 取断点）；\n"
+            "  禁止 -M（会把补充比对标成 secondary，证据变少）；\n"
+            "  建议 -a -h 20；比对后不要用 samtools -F 2048 / -F 256 / -q 过滤。\n"
+            "\n示例:\n"
+            "  alnkit short scan --bam-dir ./bam --query-chr target_ref \\\n"
+            "      --insert-chrs decoy_ref,homolog_ref,target_ref \\\n"
+            "      --merge-window-bp 10 --out-dir out\n"
+            "  alnkit short scan --self-test"
+        ),
+    )
+    parser.add_argument(
+        "--bam",
+        action="append",
+        type=Path,
+        default=[],
+        metavar="PATH",
+        help="直接指定 BAM（可重复）。与 --bam-dir 二选一",
+    )
+    parser.add_argument(
+        "--bam-dir",
+        action="store",
+        type=Path,
+        default=Path.cwd(),
+        metavar="DIR",
+        help="扫描 BAM 的目录，默认当前目录",
+    )
+    parser.add_argument(
+        "--bam-glob",
+        action="store",
+        default="*.sorted.bam",
+        metavar="PATTERN",
+        help="在 --bam-dir 下匹配 BAM 的通配符，默认 *.sorted.bam",
+    )
+    parser.add_argument("--no-recursive", action="store_true", help="不递归子目录（默认递归）")
+    parser.add_argument(
+        "--out-dir",
+        action="store",
+        type=Path,
+        default=Path.cwd(),
+        metavar="DIR",
+        help="结果输出目录，默认当前目录",
+    )
+    parser.add_argument(
+        "--sample-name",
+        action="store",
+        default=None,
+        metavar="NAME",
+        help="样本名（输出文件名前缀），默认取 BAM 文件名首个 . 之前的部分",
+    )
+    parser.add_argument(
+        "--query-chr",
+        action="store",
+        default=None,
+        metavar="NAME",
+        help="本次要出结果的外源插入序列名（必填，除非 --self-test）",
+    )
+    parser.add_argument(
+        "--insert-chrs",
+        action="store",
+        default=None,
+        metavar="NAME1,NAME2,...",
+        help="参考序列里全部外源/同源序列名，逗号分隔；默认只含 --query-chr",
+    )
+    parser.add_argument(
+        "--insert-origin-policy",
+        action="store",
+        choices=("owned", "owned-strict", "lenient", "consensus", "legacy"),
+        default="owned",
+        help="共有 read 的区分策略：owned（默认）/owned-strict/lenient/consensus/legacy",
+    )
+    parser.add_argument(
+        "--merge-window-bp",
+        action="store",
+        type=int,
+        default=0,
+        metavar="INT",
+        help="位点窗口合并：相距 <= 该值的断点合并为一个位点，0=不合并（默认）；推荐 10",
+    )
+    parser.add_argument(
+        "--min-mapq",
+        action="store",
+        type=int,
+        default=20,
+        metavar="INT",
+        help="比对质量 <= 该值则丢弃，默认 20",
+    )
+    parser.add_argument(
+        "--max-mismatch",
+        action="store",
+        type=int,
+        default=3,
+        metavar="INT",
+        help="错配数 > 该值则丢弃，默认 3",
+    )
+    parser.add_argument(
+        "--max-softclip-blocks",
+        action="store",
+        type=int,
+        default=1,
+        metavar="INT",
+        help="soft clip 段数 > 该值则丢弃，默认 1",
+    )
+    parser.add_argument(
+        "--min-clip-length",
+        action="store",
+        type=int,
+        default=0,
+        metavar="INT",
+        help="作为断点证据时要求的最小 soft clip 长度，默认 0（不限制）",
+    )
+    parser.add_argument(
+        "--keep-secondary", action="store_true", help="保留 secondary 比对（默认丢弃）"
+    )
+    parser.add_argument(
+        "--mismatch-source",
+        action="store",
+        choices=("nm", "md"),
+        default="nm",
+        help="错配数来源：nm=NM 标签（默认）；md=由 MD 推导（历史行为）",
+    )
+    parser.add_argument(
+        "--on-missing-tag",
+        action="store",
+        choices=("skip", "error"),
+        default="skip",
+        help="缺少 NM/MD 标签时：skip=丢弃该比对（默认）；error=报错",
+    )
+    parser.add_argument(
+        "--no-split-match",
+        action="store_true",
+        help="关闭「目标序列上要求存在等长 split 比对」的校验（默认开启）",
+    )
+    parser.add_argument(
+        "--no-candidate-gate",
+        action="store_true",
+        help="关闭候选 read 闸门（等价 2.4.0 全量逐条处理）；legacy 策略下自动关闭",
+    )
+    parser.add_argument(
+        "--no-duplicate-filter",
+        action="store_true",
+        help="保留被 markdup 标记为重复的 read 作为证据（默认剔除，只写 dup 列）",
+    )
+    parser.add_argument(
+        "--require-dup-flags",
+        action="store_true",
+        help="BAM 里没有任何 FLAG 0x400（未做 markdup）时报错退出（退出码 2）",
+    )
+    parser.add_argument(
+        "--bam-threads",
+        action="store",
+        type=int,
+        default=1,
+        metavar="INT",
+        help="BAM 解压线程数，默认 1；大文件可调到 2-4",
+    )
+    parser.add_argument(
+        "--legacy-coordinates",
+        action="store_true",
+        help="使用历史的 M 块选取规则（取最后一个 M 块）",
+    )
+    parser.add_argument(
+        "--legacy-profile",
+        action="store_true",
+        help="一键复现历史结果（= legacy 坐标 + legacy 归属 + 由 MD 推导错配）",
+    )
+    parser.add_argument("--self-test", action="store_true", help="只跑内置自检（不读 BAM）")
+    parser.set_defaults(handler=run_scan)
+
+
+def run_scan(args: argparse.Namespace) -> int:
+    if args.self_test:
+        scan.run_self_test()
+        return 0
+    settings = scan.ScanSettings(
+        bam=tuple(args.bam),
+        bam_dir=args.bam_dir,
+        bam_glob=args.bam_glob,
+        no_recursive=args.no_recursive,
+        out_dir=args.out_dir,
+        sample_name=args.sample_name,
+        query_chr=args.query_chr,
+        insert_chrs=args.insert_chrs,
+        insert_origin_policy=args.insert_origin_policy,
+        merge_window_bp=args.merge_window_bp,
+        min_mapq=args.min_mapq,
+        max_mismatch=args.max_mismatch,
+        max_softclip_blocks=args.max_softclip_blocks,
+        min_clip_length=args.min_clip_length,
+        keep_secondary=args.keep_secondary,
+        mismatch_source=args.mismatch_source,
+        on_missing_tag=args.on_missing_tag,
+        no_split_match=args.no_split_match,
+        no_candidate_gate=args.no_candidate_gate,
+        no_duplicate_filter=args.no_duplicate_filter,
+        require_dup_flags=args.require_dup_flags,
+        bam_threads=args.bam_threads,
+        legacy_coordinates=args.legacy_coordinates,
+        legacy_profile=args.legacy_profile,
+        log_level=args.log_level,
+        quiet=args.quiet,
+    )
+    result = scan.run(settings)
+    print(
+        f"完成：{len(result['bams'])} 个 BAM，"
+        f"query={result['query_chr']}，输出目录 {result['out_dir']}"
+    )
+    return 0

alnkit/core/__init__.py

@@ -0,0 +1,9 @@
+"""核心层：坐标换算、表契约、比对段模型、外部命令与错误类型。
+
+依赖方向固定为 ``core <- longread/shortread/plot <- cli``；核心层不反向依赖。
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+__version__ = "0.1.0.dev0"