gffkit 0.1.0__py3-none-any.whl

gffkit/complement_annotations.py

@@ -0,0 +1,1001 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+agat_sp_complement_annotations.pl 的 Python 改写版（纯 Python，不调用 Perl）。
+
+功能概要：
+1. 读取一个参考注释文件（--ref）；
+2. 依次读取一个或多个补充注释文件（--add）；
+3. 按原脚本说明的规则，把可补充的一级特征（通常是 gene）加入参考注释；
+4. 输出合并后的 GFF3 文件。
+5. 可选地对指定染色体区间启用“主参考/补充来源互换”模式。
+6. 支持从 detect_bridge_merged_genes.py 产生的 suspicious.tsv 自动读取交换区间，
+   并对区间边界自动扩展一定 bp（默认 100 bp）。
+
+说明：
+- 原 Perl 脚本依赖 AGAT::AGAT 中的内部函数；这里给出的是不依赖 Perl/AGAT 的 Python 实现。
+- 为了尽可能接近原始行为，脚本支持常见的 GFF3 / GTF 解析，并按描述中的规则做补充。
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional, Tuple
+
+
+GENE_LIKE_TYPES = {
+    "gene", "pseudogene", "nc_gene", "lnc_RNA_gene", "miRNA_gene",
+    "snRNA_gene", "snoRNA_gene", "tRNA_gene", "rRNA_gene",
+}
+
+TRANSCRIPT_LIKE_TYPES = {
+    "mRNA", "transcript", "lnc_RNA", "ncRNA", "miRNA", "snRNA",
+    "snoRNA", "tRNA", "rRNA", "pre_miRNA", "pseudogenic_transcript",
+}
+
+NON_L3_TYPES = GENE_LIKE_TYPES | TRANSCRIPT_LIKE_TYPES
+
+_SYNTHETIC_COUNTER = {
+    "gene": 0,
+    "transcript": 0,
+}
+
+
+@dataclass(frozen=True)
+class SwapRegion:
+    """
+    表示一个需要交换主次参考关系的区间。
+
+    规则：
+    - 在该区间内：-a 文件视为主参考，-r 文件视为补充来源；
+    - 在该区间外：仍保持原规则，即 -r 为主参考，-a 为补充来源。
+
+    说明：
+    - 这里以“一级特征（通常是 gene）是否与区间发生重叠”来判断该特征属于区间内还是区间外；
+    - 若某个一级特征横跨区间边界，只要与区间重叠，就按“区间内”处理。
+    """
+    seqid: str
+    start: int
+    end: int
+
+
+def eprint(*args, **kwargs):
+    """打印到标准错误，用于日志信息。"""
+    print(*args, file=sys.stderr, **kwargs)
+
+
+def overlaps_1d(a_start: int, a_end: int, b_start: int, b_end: int) -> bool:
+    """判断两个闭区间是否重叠。"""
+    return not (a_end < b_start or b_end < a_start)
+
+
+def strand_compatible(a: str, b: str) -> bool:
+    """
+    判断链方向是否可比较：
+    - 相同链：可比较
+    - 任一为 '.'：视为兼容
+    """
+    return a == b or a == "." or b == "."
+
+
+def merge_intervals(intervals: List[Tuple[int, int]]) -> List[Tuple[int, int]]:
+    """合并一组区间，避免 CDS 长度重复累计。"""
+    if not intervals:
+        return []
+    intervals = sorted(intervals)
+    merged = [list(intervals[0])]
+    for start, end in intervals[1:]:
+        if start <= merged[-1][1] + 1:
+            merged[-1][1] = max(merged[-1][1], end)
+        else:
+            merged.append([start, end])
+    return [(s, e) for s, e in merged]
+
+
+def parse_gff3_attributes(attr_text: str) -> Dict[str, str]:
+    """解析 GFF3 第 9 列属性。"""
+    attrs: Dict[str, str] = {}
+    if not attr_text.strip():
+        return attrs
+    for item in attr_text.strip().split(";"):
+        if not item:
+            continue
+        if "=" in item:
+            k, v = item.split("=", 1)
+            attrs[k.strip()] = v.strip()
+        else:
+            attrs[item.strip()] = ""
+    return attrs
+
+
+def parse_gtf_attributes(attr_text: str) -> Dict[str, str]:
+    """解析 GTF 第 9 列属性。"""
+    attrs: Dict[str, str] = {}
+    # 兼容 key "value"; 以及少数不规范写法
+    for part in re.finditer(r'(\S+)\s+"([^"]*)"|(\S+)\s+([^;]+)', attr_text):
+        if part.group(1) is not None:
+            attrs[part.group(1)] = part.group(2)
+        else:
+            attrs[part.group(3)] = part.group(4).strip().strip('"')
+    return attrs
+
+
+def detect_format(path: str) -> str:
+    """
+    根据文件内容粗略判断是 GFF3 还是 GTF。
+    返回值：'gff3' 或 'gtf'
+    """
+    with open(path, "r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split("\t")
+            if len(parts) != 9:
+                continue
+            attr_text = parts[8]
+            if "=" in attr_text:
+                return "gff3"
+            return "gtf"
+    return "gff3"
+
+
+@dataclass
+class Feature:
+    """
+    表示一个注释特征（gene / transcript / exon / CDS 等）。
+    """
+    seqid: str
+    source: str
+    feature_type: str
+    start: int
+    end: int
+    score: str
+    strand: str
+    phase: str
+    attrs: Dict[str, str] = field(default_factory=dict)
+    children: List["Feature"] = field(default_factory=list)
+    parent: Optional["Feature"] = None
+
+    @property
+    def id(self) -> Optional[str]:
+        return self.attrs.get("ID")
+
+    @id.setter
+    def id(self, value: str) -> None:
+        self.attrs["ID"] = value
+
+    @property
+    def name(self) -> Optional[str]:
+        return self.attrs.get("Name")
+
+    @name.setter
+    def name(self, value: str) -> None:
+        self.attrs["Name"] = value
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start + 1
+
+    def add_child(self, child: "Feature") -> None:
+        child.parent = self
+        self.children.append(child)
+
+    def iter_descendants(self) -> Iterable["Feature"]:
+        for child in self.children:
+            yield child
+            yield from child.iter_descendants()
+
+    def iter_all(self) -> Iterable["Feature"]:
+        yield self
+        yield from self.iter_descendants()
+
+    def deep_clone(self) -> "Feature":
+        cloned = copy.deepcopy(self)
+
+        def fix_parent(node: "Feature", parent: Optional["Feature"] = None) -> None:
+            node.parent = parent
+            for c in node.children:
+                fix_parent(c, node)
+
+        fix_parent(cloned, None)
+        return cloned
+
+    def overlaps(self, other: "Feature") -> bool:
+        return (
+            self.seqid == other.seqid
+            and strand_compatible(self.strand, other.strand)
+            and overlaps_1d(self.start, self.end, other.start, other.end)
+        )
+
+    def to_gff3_lines(self) -> List[str]:
+        """
+        递归导出为 GFF3 文本。
+        这里统一输出 GFF3，而不是原样保留 GTF。
+        """
+        lines = []
+        attrs = dict(self.attrs)
+
+        # Parent 关系由树结构决定，输出时重新写入，避免旧值不一致
+        if self.parent and self.parent.id:
+            attrs["Parent"] = self.parent.id
+        else:
+            attrs.pop("Parent", None)
+
+        attr_text = ";".join(
+            f"{k}={v}" if v != "" else k
+            for k, v in attrs.items()
+        )
+        row = [
+            self.seqid,
+            self.source,
+            self.feature_type,
+            str(self.start),
+            str(self.end),
+            self.score,
+            self.strand,
+            self.phase,
+            attr_text if attr_text else ".",
+        ]
+        lines.append("\t".join(row))
+
+        # 递归输出子节点；按坐标和类型稳定排序
+        for child in sorted(
+            self.children,
+            key=lambda x: (x.start, x.end, x.feature_type, x.id or "")
+        ):
+            lines.extend(child.to_gff3_lines())
+        return lines
+
+
+@dataclass
+class AnnotationSet:
+    """
+    保存整套注释数据，根节点一般是 gene（也允许是其他顶层特征）。
+    """
+    roots: List[Feature] = field(default_factory=list)
+
+    def all_ids(self) -> set:
+        ids = set()
+        for root in self.roots:
+            for feat in root.iter_all():
+                if feat.id:
+                    ids.add(feat.id)
+        return ids
+
+    def all_names(self) -> set:
+        names = set()
+        for root in self.roots:
+            for feat in root.iter_all():
+                if feat.name:
+                    names.add(feat.name)
+        return names
+
+    def level_counts(self) -> Dict[str, Dict[str, int]]:
+        """
+        统计 level1 / level2 的 feature_type 数量，模仿原脚本的 quick stat 逻辑。
+        """
+        counts = {
+            "level1": defaultdict(int),
+            "level2": defaultdict(int),
+        }
+        for root in self.roots:
+            counts["level1"][root.feature_type] += 1
+            for child in root.children:
+                counts["level2"][child.feature_type] += 1
+        return counts
+
+    def info(self) -> None:
+        counts = self.level_counts()
+        eprint("Current annotation summary:")
+        for level in ("level1", "level2"):
+            eprint(f"  {level}:")
+            for tag in sorted(counts[level]):
+                eprint(f"    {tag}: {counts[level][tag]}")
+
+    def write_gff3(self, output_path: Optional[str]) -> None:
+        out_fh = open(output_path, "w", encoding="utf-8") if output_path else sys.stdout
+        try:
+            print("##gff-version 3", file=out_fh)
+            for root in sorted(
+                self.roots,
+                key=lambda x: (x.seqid, x.start, x.end, x.feature_type, x.id or "")
+            ):
+                for line in root.to_gff3_lines():
+                    print(line, file=out_fh)
+        finally:
+            if output_path:
+                out_fh.close()
+
+
+def make_synthetic_id(prefix: str) -> str:
+    """为 GTF 中缺失的 gene/transcript 生成稳定的伪 ID。"""
+    _SYNTHETIC_COUNTER[prefix] += 1
+    return f"synthetic_{prefix}_{_SYNTHETIC_COUNTER[prefix]}"
+
+
+def parse_gff3(path: str) -> AnnotationSet:
+    """解析 GFF3 文件并构建树结构。"""
+    features_by_id: Dict[str, Feature] = {}
+    all_features: List[Tuple[Feature, List[str]]] = []
+
+    with open(path, "r", encoding="utf-8") as fh:
+        for line_num, line in enumerate(fh, start=1):
+            line = line.rstrip("\n")
+            if not line or line.startswith("#"):
+                continue
+
+            parts = line.split("\t")
+            if len(parts) != 9:
+                raise ValueError(f"{path}:{line_num} 不是合法的 9 列 GFF/GTF 记录")
+
+            seqid, source, ftype, start, end, score, strand, phase, attr_text = parts
+            attrs = parse_gff3_attributes(attr_text)
+            parent_ids = attrs.get("Parent", "")
+            parent_list = [x for x in parent_ids.split(",") if x] if parent_ids else []
+
+            feat = Feature(
+                seqid=seqid,
+                source=source,
+                feature_type=ftype,
+                start=int(start),
+                end=int(end),
+                score=score,
+                strand=strand,
+                phase=phase,
+                attrs=attrs,
+            )
+
+            if feat.id:
+                if feat.id in features_by_id:
+                    raise ValueError(f"{path}:{line_num} 出现重复 ID：{feat.id}")
+                features_by_id[feat.id] = feat
+
+            all_features.append((feat, parent_list))
+
+    roots: List[Feature] = []
+
+    # 第二轮：挂接父子关系
+    for feat, parent_ids in all_features:
+        if not parent_ids:
+            roots.append(feat)
+            continue
+
+        attached = False
+        for pid in parent_ids:
+            parent = features_by_id.get(pid)
+            if parent is None:
+                continue
+            parent.add_child(feat)
+            attached = True
+
+        # 若 Parent 指向不存在，则当作顶层特征保留，避免数据丢失
+        if not attached:
+            roots.append(feat)
+
+    return AnnotationSet(roots=roots)
+
+
+def parse_gtf(path: str) -> AnnotationSet:
+    """
+    解析 GTF，并补出缺失的 gene / transcript 层级。
+    最终仍构建成统一的树结构，方便后续处理。
+    """
+    genes: Dict[str, Feature] = {}
+    transcripts: Dict[str, Feature] = {}
+
+    with open(path, "r", encoding="utf-8") as fh:
+        for line_num, line in enumerate(fh, start=1):
+            line = line.rstrip("\n")
+            if not line or line.startswith("#"):
+                continue
+
+            parts = line.split("\t")
+            if len(parts) != 9:
+                raise ValueError(f"{path}:{line_num} 不是合法的 9 列 GFF/GTF 记录")
+
+            seqid, source, ftype, start, end, score, strand, phase, attr_text = parts
+            attrs = parse_gtf_attributes(attr_text)
+            start_i = int(start)
+            end_i = int(end)
+
+            gene_id = attrs.get("gene_id") or attrs.get("geneID") or attrs.get("ID")
+            transcript_id = attrs.get("transcript_id") or attrs.get("transcriptID")
+
+            # 处理 gene 记录
+            if ftype in GENE_LIKE_TYPES or (ftype == "gene"):
+                if not gene_id:
+                    gene_id = make_synthetic_id("gene")
+                if gene_id not in genes:
+                    gene_attrs = dict(attrs)
+                    gene_attrs["ID"] = gene_id
+                    gene_attrs.setdefault("Name", gene_id)
+                    genes[gene_id] = Feature(
+                        seqid=seqid,
+                        source=source,
+                        feature_type="gene",
+                        start=start_i,
+                        end=end_i,
+                        score=score,
+                        strand=strand,
+                        phase=".",
+                        attrs=gene_attrs,
+                    )
+                else:
+                    genes[gene_id].start = min(genes[gene_id].start, start_i)
+                    genes[gene_id].end = max(genes[gene_id].end, end_i)
+                continue
+
+            # 确保 gene 节点存在
+            if not gene_id:
+                gene_id = make_synthetic_id("gene")
+            if gene_id not in genes:
+                genes[gene_id] = Feature(
+                    seqid=seqid,
+                    source=source,
+                    feature_type="gene",
+                    start=start_i,
+                    end=end_i,
+                    score=".",
+                    strand=strand,
+                    phase=".",
+                    attrs={"ID": gene_id, "Name": gene_id},
+                )
+            else:
+                genes[gene_id].start = min(genes[gene_id].start, start_i)
+                genes[gene_id].end = max(genes[gene_id].end, end_i)
+
+            # transcript 记录
+            if ftype in TRANSCRIPT_LIKE_TYPES or ftype == "transcript":
+                if not transcript_id:
+                    transcript_id = make_synthetic_id("transcript")
+                if transcript_id not in transcripts:
+                    tx_attrs = dict(attrs)
+                    tx_attrs["ID"] = transcript_id
+                    tx_attrs.setdefault("Name", transcript_id)
+                    tx = Feature(
+                        seqid=seqid,
+                        source=source,
+                        feature_type="transcript",
+                        start=start_i,
+                        end=end_i,
+                        score=score,
+                        strand=strand,
+                        phase=".",
+                        attrs=tx_attrs,
+                    )
+                    genes[gene_id].add_child(tx)
+                    transcripts[transcript_id] = tx
+                else:
+                    transcripts[transcript_id].start = min(transcripts[transcript_id].start, start_i)
+                    transcripts[transcript_id].end = max(transcripts[transcript_id].end, end_i)
+                continue
+
+            # 其余子特征（exon / CDS / UTR 等）
+            parent_node: Feature
+            if transcript_id:
+                if transcript_id not in transcripts:
+                    tx = Feature(
+                        seqid=seqid,
+                        source=source,
+                        feature_type="transcript",
+                        start=start_i,
+                        end=end_i,
+                        score=".",
+                        strand=strand,
+                        phase=".",
+                        attrs={"ID": transcript_id, "Name": transcript_id},
+                    )
+                    genes[gene_id].add_child(tx)
+                    transcripts[transcript_id] = tx
+                else:
+                    transcripts[transcript_id].start = min(transcripts[transcript_id].start, start_i)
+                    transcripts[transcript_id].end = max(transcripts[transcript_id].end, end_i)
+                parent_node = transcripts[transcript_id]
+            else:
+                parent_node = genes[gene_id]
+
+            child_id = attrs.get("ID")
+            if not child_id:
+                # 子特征允许没有 ID，这里给一个不冲突的临时 ID，便于统一输出和后续重命名
+                child_id = f"{ftype}_{seqid}_{start_i}_{end_i}_{strand}_{line_num}"
+
+            child_attrs = dict(attrs)
+            child_attrs["ID"] = child_id
+            child = Feature(
+                seqid=seqid,
+                source=source,
+                feature_type=ftype,
+                start=start_i,
+                end=end_i,
+                score=score,
+                strand=strand,
+                phase=phase,
+                attrs=child_attrs,
+            )
+            parent_node.add_child(child)
+
+    return AnnotationSet(roots=list(genes.values()))
+
+
+def parse_annotation_file(path: str) -> AnnotationSet:
+    """自动判断输入格式并解析。"""
+    fmt = detect_format(path)
+    if fmt == "gtf":
+        return parse_gtf(path)
+    return parse_gff3(path)
+
+
+def get_cds_features(root: Feature) -> List[Feature]:
+    """提取某个一级特征下面所有 CDS 特征。"""
+    return [f for f in root.iter_all() if f.feature_type == "CDS"]
+
+
+def get_l3_features(root: Feature) -> List[Feature]:
+    """
+    取“三级及以下”的功能性子特征，用于“无 CDS vs 无 CDS”的重叠判断。
+    这里把所有非 gene / transcript 类的后代都视为可比较特征。
+    """
+    feats = []
+    for f in root.iter_descendants():
+        if f.feature_type not in NON_L3_TYPES:
+            feats.append(f)
+    return feats
+
+
+def gene_has_cds(root: Feature) -> bool:
+    """判断某个一级特征下是否存在 CDS。"""
+    return any(f.feature_type == "CDS" for f in root.iter_all())
+
+
+def cds_size_nt(root: Feature) -> int:
+    """
+    计算 CDS 总长度（核苷酸数）。
+    为避免同一基因不同转录本的重复区间被重复累计，这里按区间合并后求长度。
+    """
+    groups: Dict[Tuple[str, str], List[Tuple[int, int]]] = defaultdict(list)
+    for cds in get_cds_features(root):
+        groups[(cds.seqid, cds.strand)].append((cds.start, cds.end))
+
+    total = 0
+    for _, ivals in groups.items():
+        for s, e in merge_intervals(ivals):
+            total += (e - s + 1)
+    return total
+
+
+def any_feature_overlap(features_a: List[Feature], features_b: List[Feature]) -> bool:
+    """判断两组特征中是否存在任意一对重叠。"""
+    for fa in features_a:
+        for fb in features_b:
+            if fa.overlaps(fb):
+                return True
+    return False
+
+
+def should_add_root(add_root: Feature, ref_roots: List[Feature], size_min: int) -> bool:
+    """
+    按原脚本说明中的规则，判断 add_root 是否应该加入参考注释。
+
+    规则摘要：
+    1. add_root 与参考中任何一级特征都不重叠：
+       - 若 CDS 长度 >= size_min，则加入。
+    2. 若发生重叠：
+       - add 无 CDS、ref 有 CDS：加入
+       - add 有 CDS、ref 无 CDS：加入
+       - add 有 CDS、ref 有 CDS：仅在 CDS 不重叠时加入
+       - add 无 CDS、ref 无 CDS：仅在所有 l3 特征都不重叠时加入
+
+    注意：
+    - 只要有一个重叠关系不满足条件，就不加入整个一级特征。
+      这与原说明中“只要有一个 isoform 重叠，就阻止整个 gene 加入”的精神一致。
+    """
+    overlapping_refs = [r for r in ref_roots if add_root.overlaps(r)]
+
+    # 情况 1：完全不与参考一级特征重叠
+    if not overlapping_refs:
+        return cds_size_nt(add_root) >= size_min
+
+    add_has_cds = gene_has_cds(add_root)
+    add_cds = get_cds_features(add_root)
+    add_l3 = get_l3_features(add_root)
+
+    for ref_root in overlapping_refs:
+        ref_has_cds = gene_has_cds(ref_root)
+
+        # add 无 CDS；ref 有 CDS -> 允许
+        if (not add_has_cds) and ref_has_cds:
+            continue
+
+        # add 有 CDS；ref 无 CDS -> 允许
+        if add_has_cds and (not ref_has_cds):
+            continue
+
+        # 双方都有 CDS -> CDS 不能重叠
+        if add_has_cds and ref_has_cds:
+            ref_cds = get_cds_features(ref_root)
+            if any_feature_overlap(add_cds, ref_cds):
+                return False
+            continue
+
+        # 双方都没有 CDS -> 所有非 gene/transcript 子特征都不能重叠
+        ref_l3 = get_l3_features(ref_root)
+        if any_feature_overlap(add_l3, ref_l3):
+            return False
+
+    return True
+
+
+def feature_overlaps_region(feature: Feature, region: SwapRegion) -> bool:
+    """判断某个一级特征是否与指定交换区间重叠。"""
+    return (
+        feature.seqid == region.seqid
+        and overlaps_1d(feature.start, feature.end, region.start, region.end)
+    )
+
+
+def feature_in_swap_regions(feature: Feature, swap_regions: List[SwapRegion]) -> bool:
+    """判断一级特征是否落入任一交换区间。"""
+    return any(feature_overlaps_region(feature, region) for region in swap_regions)
+
+
+def build_priority_sets_for_region_swap(
+    ref_set: AnnotationSet,
+    add_set: AnnotationSet,
+    swap_regions: List[SwapRegion],
+) -> Tuple[AnnotationSet, AnnotationSet, Dict[str, int]]:
+    """
+    根据交换区间，把当前 ref/add 两套注释拆成“主参考集合”和“补充集合”。
+
+    返回：
+    - primary_set: 当前这一步真正作为主参考的一级特征集合
+    - supplemental_set: 当前这一步真正作为补充来源的一级特征集合
+    - stats: 各来源在区间内/外被分到哪一侧的统计，便于日志输出
+
+    逻辑：
+    - ref 在区间外 -> 仍为主参考
+    - ref 在区间内 -> 改为补充来源
+    - add 在区间外 -> 仍为补充来源
+    - add 在区间内 -> 改为主参考
+
+    这样做有一个重要好处：
+    - 补充判断时，补充来源中的特征会与“全部主参考特征”比较，
+      因此即使某个一级特征横跨区间边界，也不会漏掉与另一侧主参考的冲突判断。
+    """
+    primary_roots: List[Feature] = []
+    supplemental_roots: List[Feature] = []
+
+    stats = {
+        "ref_inside": 0,
+        "ref_outside": 0,
+        "add_inside": 0,
+        "add_outside": 0,
+    }
+
+    for root in ref_set.roots:
+        if feature_in_swap_regions(root, swap_regions):
+            supplemental_roots.append(root)
+            stats["ref_inside"] += 1
+        else:
+            primary_roots.append(root)
+            stats["ref_outside"] += 1
+
+    for root in add_set.roots:
+        if feature_in_swap_regions(root, swap_regions):
+            primary_roots.append(root)
+            stats["add_inside"] += 1
+        else:
+            supplemental_roots.append(root)
+            stats["add_outside"] += 1
+
+    return AnnotationSet(roots=primary_roots), AnnotationSet(roots=supplemental_roots), stats
+
+
+def uniquify_feature_tree(root: Feature, existing_ids: set, existing_names: set) -> None:
+    """
+    为即将加入的整棵特征树消除 ID/Name 冲突。
+    原 Perl 代码中说明会处理重复名字；这里同时处理 ID 和 Name。
+    """
+    for feat in root.iter_all():
+        # 处理 ID 冲突
+        if feat.id:
+            base = feat.id
+            if base in existing_ids:
+                i = 1
+                while f"{base}_dup{i}" in existing_ids:
+                    i += 1
+                feat.id = f"{base}_dup{i}"
+            existing_ids.add(feat.id)
+
+        # 处理 Name 冲突（若存在）
+        if feat.name:
+            base_name = feat.name
+            if base_name in existing_names:
+                i = 1
+                while f"{base_name}_dup{i}" in existing_names:
+                    i += 1
+                feat.name = f"{base_name}_dup{i}"
+            existing_names.add(feat.name)
+
+
+def complement_annotations(ref_set: AnnotationSet, add_set: AnnotationSet, size_min: int) -> int:
+    """
+    把 add_set 中满足条件的一级特征补充到 ref_set 中。
+    返回值：实际添加的一级特征数量。
+    """
+    added_count = 0
+    existing_ids = ref_set.all_ids()
+    existing_names = ref_set.all_names()
+
+    for add_root in sorted(
+        add_set.roots,
+        key=lambda x: (x.seqid, x.start, x.end, x.feature_type, x.id or "")
+    ):
+        if should_add_root(add_root, ref_set.roots, size_min):
+            cloned = add_root.deep_clone()
+            uniquify_feature_tree(cloned, existing_ids, existing_names)
+            ref_set.roots.append(cloned)
+            added_count += 1
+
+    return added_count
+
+
+def print_complement_resume(before_counts: Dict[str, Dict[str, int]],
+                            after_counts: Dict[str, Dict[str, int]]) -> None:
+    """
+    输出合并结果摘要。
+
+    与最初版本不同，这里同时兼容“增加”和“减少”两种情况：
+    - 默认补充模式下通常只会增加；
+    - 开启交换区间后，某些区间内原 ref 的一级特征会被 add 作为主参考覆盖，
+      因此统计上可能出现减少。
+    """
+    changed = False
+
+    for level in ("level1", "level2"):
+        all_tags = set(before_counts[level]) | set(after_counts[level])
+        for tag in sorted(all_tags):
+            before_n = before_counts[level].get(tag, 0)
+            after_n = after_counts[level].get(tag, 0)
+            delta = after_n - before_n
+            if delta > 0:
+                eprint(f"We added {delta} {tag}(s)")
+                changed = True
+            elif delta < 0:
+                eprint(f"We removed {-delta} {tag}(s)")
+                changed = True
+
+    if not changed:
+        eprint("\nNothing has been changed")
+    else:
+        eprint("\nNow the data contains:")
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    """构建命令行参数解析器。"""
+    parser = argparse.ArgumentParser(
+        description="用一个或多个注释文件去补充参考注释（Python 版，纯 Python，不调用 Perl）。"
+    )
+    parser.add_argument("--ref", "-r", "-i", required=True, help="参考 GFF/GTF 文件")
+    parser.add_argument(
+        "--add", "-a", action="append", required=True,
+        help="用于补充参考注释的 GFF/GTF 文件；可重复指定多次"
+    )
+    parser.add_argument(
+        "--size_min", "-s", type=int, default=0,
+        help="仅对“完全不重叠”的一级特征生效：其 CDS 总长度必须 >= 该值，默认 0"
+    )
+    parser.add_argument(
+        "--swap_region", action="append", nargs=3, metavar=("SEQID", "START", "END"),
+        help=(
+            "手动指定一个需要交换主次参考关系的区间。\n"
+            "在该区间内：-a 文件视为主参考，-r 文件视为补充来源；\n"
+            "在该区间外：仍按原规则处理。\n"
+            "可重复指定多次，例如：--swap_region chr09 160889718 200000000"
+        )
+    )
+    parser.add_argument(
+        "--swap_region_tsv",
+        help=(
+            "从 detect_bridge_merged_genes.py 产生的 suspicious.tsv 读取交换区间。"
+            "会自动忽略第一行表头；优先按表头 chrom/start/end 读取；"
+            "若无标准表头，则兼容按第2/3/4列读取（即 gene_id, chrom, start, end, ...）。"
+        )
+    )
+    parser.add_argument(
+        "--swap_region_flank",
+        type=int,
+        default=100,
+        help="从 suspicious.tsv 读取区间时，start/end 两端各扩展的 bp 数，默认 100"
+    )
+    parser.add_argument("--output", "--out", "-o", default=None, help="输出文件路径；默认输出到 STDOUT")
+    parser.add_argument(
+        "-v", "--verbose", type=int, default=1,
+        help="日志详细程度（0~4），这里只简单保留该参数接口，默认 1"
+    )
+    return parser
+
+
+def parse_swap_regions(raw_regions: Optional[List[List[str]]]) -> List[SwapRegion]:
+    """
+    把命令行传入的 --swap_region 参数解析为结构化区间。
+    """
+    if not raw_regions:
+        return []
+
+    parsed: List[SwapRegion] = []
+    for seqid, start_text, end_text in raw_regions:
+        try:
+            start = int(start_text)
+            end = int(end_text)
+        except ValueError as exc:
+            raise ValueError(
+                f"--swap_region 的 START/END 必须是整数：{seqid} {start_text} {end_text}"
+            ) from exc
+
+        if start <= 0 or end <= 0:
+            raise ValueError(
+                f"--swap_region 的坐标必须为正整数：{seqid} {start} {end}"
+            )
+
+        if start > end:
+            start, end = end, start
+
+        parsed.append(SwapRegion(seqid=seqid, start=start, end=end))
+
+    return parsed
+
+
+def parse_swap_regions_from_tsv(tsv_path: str, flank_bp: int = 100) -> List[SwapRegion]:
+    """
+    从 detect_bridge_merged_genes.py 产生的 suspicious.tsv 读取区间。
+
+    兼容两种情况：
+    1. 有表头，且包含 chrom/start/end 三列（推荐）
+    2. 无法识别表头时，回退为按第 2/3/4 列读取：
+       gene_id, chrom, start, end, ...
+
+    说明：
+    - 自动忽略第一行表头
+    - start 左扩 flank_bp
+    - end   右扩 flank_bp
+    - start 最小不小于 1
+    """
+    if flank_bp < 0:
+        raise ValueError("--swap_region_flank 不能小于 0")
+
+    regions: List[SwapRegion] = []
+
+    with open(tsv_path, "r", encoding="utf-8") as fh:
+        header = fh.readline().rstrip("\n")
+        if not header:
+            return regions
+
+        header_cols = header.split("\t")
+        lower_header = [x.strip().lower() for x in header_cols]
+
+        chrom_idx = None
+        start_idx = None
+        end_idx = None
+
+        # 优先按表头名识别
+        if "chrom" in lower_header and "start" in lower_header and "end" in lower_header:
+            chrom_idx = lower_header.index("chrom")
+            start_idx = lower_header.index("start")
+            end_idx = lower_header.index("end")
+
+        for line_num, line in enumerate(fh, start=2):
+            line = line.rstrip("\n")
+            if not line.strip():
+                continue
+
+            cols = line.split("\t")
+
+            try:
+                if chrom_idx is not None:
+                    seqid = cols[chrom_idx]
+                    start = int(cols[start_idx])
+                    end = int(cols[end_idx])
+                else:
+                    # 回退模式：按 suspicious.tsv 常见格式读取
+                    # gene_id, chrom, start, end, ...
+                    if len(cols) < 4:
+                        raise ValueError("列数不足，至少需要 4 列")
+                    seqid = cols[1]
+                    start = int(cols[2])
+                    end = int(cols[3])
+
+                if start <= 0 or end <= 0:
+                    raise ValueError("start/end 必须为正整数")
+
+                if start > end:
+                    start, end = end, start
+
+                start = max(1, start - flank_bp)
+                end = end + flank_bp
+
+                regions.append(SwapRegion(seqid=seqid, start=start, end=end))
+
+            except Exception as exc:
+                raise ValueError(
+                    f"{tsv_path}:{line_num} 解析失败，请确认文件格式正确。"
+                    f" 当前行内容为：{line}"
+                ) from exc
+
+    return regions
+
+
+def main() -> int:
+    parser = build_arg_parser()
+    args = parser.parse_args()
+
+    try:
+        swap_regions = parse_swap_regions(args.swap_region)
+
+        # 如果提供了 suspicious.tsv，则把其中区间也读入
+        if args.swap_region_tsv:
+            swap_regions_from_tsv = parse_swap_regions_from_tsv(
+                args.swap_region_tsv,
+                flank_bp=args.swap_region_flank
+            )
+            swap_regions.extend(swap_regions_from_tsv)
+
+    except ValueError as exc:
+        parser.error(str(exc))
+
+    # 1) 读取参考注释
+    ref_set = parse_annotation_file(args.ref)
+    eprint(f"{args.ref} parsed")
+    ref_set.info()
+
+    if swap_regions:
+        eprint("Configured swap regions:")
+        for region in swap_regions:
+            eprint(f"  - {region.seqid}:{region.start}-{region.end}")
+
+    # 2) 按用户给定顺序，逐个补充
+    for next_file in args.add:
+        add_set = parse_annotation_file(next_file)
+        eprint(f"{next_file} parsed")
+        add_set.info()
+
+        before_counts = ref_set.level_counts()
+
+        if swap_regions:
+            primary_set, supplemental_set, region_stats = build_priority_sets_for_region_swap(
+                ref_set, add_set, swap_regions
+            )
+            eprint(
+                "\nRegion swap summary: "
+                f"ref(outside->primary)={region_stats['ref_outside']}, "
+                f"ref(inside->supplement)={region_stats['ref_inside']}, "
+                f"add(inside->primary)={region_stats['add_inside']}, "
+                f"add(outside->supplement)={region_stats['add_outside']}"
+            )
+
+            added_count = complement_annotations(primary_set, supplemental_set, args.size_min)
+            ref_set = primary_set
+        else:
+            added_count = complement_annotations(ref_set, add_set, args.size_min)
+
+        eprint("\nComplement done !")
+
+        after_counts = ref_set.level_counts()
+        print_complement_resume(before_counts, after_counts)
+
+        if added_count > 0 or before_counts != after_counts:
+            ref_set.info()
+
+    # 3) 输出结果
+    ref_set.write_gff3(args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())