gffkit 0.1.0__py3-none-any.whl

gffkit/detect_bridge_merged_genes.py

@@ -0,0 +1,530 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+detect_bridge_merged_genes.py
+
+用途：
+检测 GFF3 中这种异常情况：
+“一个 gene 下的转录本分成多个离散簇，且只有少数桥接转录本跨簇连接”，
+常见于自动注释把多个独立基因错误合并成一个 gene locus。
+
+作者思路：
+1. 解析 gene / mRNA(transcript) / exon / CDS
+2. 对每个 transcript 提取 exon blocks
+3. 优先识别“桥接型 transcript”：
+   - 含超长内含子
+   - exon 分布成多个远距离块
+4. 用非桥接 transcript 构建“核心簇”
+5. 若 gene 中存在 >=2 个核心簇，且桥接 transcript 能跨多个簇，则输出为可疑异常
+
+输入：
+    python detect_bridge_merged_genes.py -i input.gff3 -o suspicious.tsv
+
+可选参数：
+    --min-gap               认为两个 exon 块“相距很远”的最小 gap，默认 10000
+    --cluster-gap           构建核心簇时，两个 transcript span 允许合并的最大 gap，默认 2000
+    --min-core-tx-per-cluster   每个核心簇至少包含多少个非桥接 transcript，默认 1
+    --min-bridge-count      至少需要多少条桥接 transcript 才输出，默认 1
+    --use-cds-if-no-exon    若 transcript 无 exon，则使用 CDS，默认开启
+
+输出列：
+    gene_id
+    chrom
+    start
+    end
+    strand
+    total_tx
+    core_tx
+    bridge_tx
+    cluster_count
+    cluster_ranges
+    cluster_members
+    bridge_members
+"""
+
+import argparse
+import sys
+from collections import defaultdict
+
+
+# ----------------------------
+# 数据结构
+# ----------------------------
+
+class Gene:
+    def __init__(self, gid, chrom, start, end, strand):
+        self.id = gid
+        self.chrom = chrom
+        self.start = start
+        self.end = end
+        self.strand = strand
+        self.transcripts = []
+
+
+class Transcript:
+    def __init__(self, tid, parent_gene, chrom, start, end, strand):
+        self.id = tid
+        self.parent_gene = parent_gene
+        self.chrom = chrom
+        self.start = start
+        self.end = end
+        self.strand = strand
+        self.exons = []
+        self.cdss = []
+
+    def get_blocks(self, use_cds_if_no_exon=True):
+        """
+        优先使用 exon；若没有 exon 且允许，则用 CDS。
+        返回排序并合并后的 blocks: [(s1,e1), (s2,e2), ...]
+        """
+        blocks = self.exons[:]
+        if not blocks and use_cds_if_no_exon:
+            blocks = self.cdss[:]
+
+        if not blocks:
+            # 如果连 CDS 也没有，则退化成 transcript 自身 span
+            blocks = [(self.start, self.end)]
+
+        return merge_intervals(sorted(blocks))
+
+    def span(self, use_cds_if_no_exon=True):
+        blocks = self.get_blocks(use_cds_if_no_exon=use_cds_if_no_exon)
+        return (blocks[0][0], blocks[-1][1])
+
+    def introns(self, use_cds_if_no_exon=True):
+        """
+        根据 blocks 推导 intron 长度
+        """
+        blocks = self.get_blocks(use_cds_if_no_exon=use_cds_if_no_exon)
+        introns = []
+        for i in range(len(blocks) - 1):
+            intron_len = blocks[i + 1][0] - blocks[i][1] - 1
+            introns.append(max(0, intron_len))
+        return introns
+
+
+# ----------------------------
+# 工具函数
+# ----------------------------
+
+def parse_attributes(attr_str):
+    """
+    解析 GFF3 第9列属性
+    """
+    attrs = {}
+    for item in attr_str.strip().split(";"):
+        if not item:
+            continue
+        if "=" in item:
+            k, v = item.split("=", 1)
+            attrs[k] = v
+    return attrs
+
+
+def merge_intervals(intervals):
+    """
+    合并重叠/相邻区间
+    """
+    if not intervals:
+        return []
+    merged = [list(intervals[0])]
+    for s, e in intervals[1:]:
+        if s <= merged[-1][1] + 1:
+            merged[-1][1] = max(merged[-1][1], e)
+        else:
+            merged.append([s, e])
+    return [(x[0], x[1]) for x in merged]
+
+
+def interval_gap(a, b):
+    """
+    两区间间距；若重叠则返回 0
+    """
+    a1, a2 = a
+    b1, b2 = b
+    if a2 < b1:
+        return b1 - a2 - 1
+    elif b2 < a1:
+        return a1 - b2 - 1
+    else:
+        return 0
+
+
+def interval_overlap(a, b):
+    """
+    判断两区间是否重叠
+    """
+    a1, a2 = a
+    b1, b2 = b
+    return not (a2 < b1 or b2 < a1)
+
+
+def interval_overlap_or_close(a, b, max_gap=0):
+    """
+    重叠，或间距 <= max_gap
+    """
+    return interval_gap(a, b) <= max_gap
+
+
+def union_find_cluster(items, get_interval, max_gap):
+    """
+    按区间相互重叠/接近进行单链聚类
+    items: 任意对象列表
+    get_interval: 输入 item，返回 (start,end)
+    """
+    n = len(items)
+    parent = list(range(n))
+
+    def find(x):
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(x, y):
+        rx, ry = find(x), find(y)
+        if rx != ry:
+            parent[ry] = rx
+
+    for i in range(n):
+        a = get_interval(items[i])
+        for j in range(i + 1, n):
+            b = get_interval(items[j])
+            if interval_overlap_or_close(a, b, max_gap=max_gap):
+                union(i, j)
+
+    groups = defaultdict(list)
+    for i in range(n):
+        groups[find(i)].append(items[i])
+
+    return list(groups.values())
+
+
+def blocks_to_groups(blocks, min_gap):
+    """
+    把一个 transcript 的 exon blocks 按“远距离 gap”分成多个组。
+    例如：
+      [(100,200), (300,350), (20000,20100), (20200,20300)]
+    若 min_gap=10000，则前两块为一组，后两块为另一组。
+    """
+    if not blocks:
+        return []
+
+    groups = [[blocks[0]]]
+    for blk in blocks[1:]:
+        prev = groups[-1][-1]
+        gap = blk[0] - prev[1] - 1
+        if gap >= min_gap:
+            groups.append([blk])
+        else:
+            groups[-1].append(blk)
+
+    # 每组压缩成一个 span
+    spans = []
+    for g in groups:
+        spans.append((g[0][0], g[-1][1]))
+    return spans
+
+
+def transcript_is_bridge_candidate(tx, min_gap, use_cds_if_no_exon=True):
+    """
+    判断 transcript 是否像“桥接型 transcript”
+    条件之一满足即可：
+      1. 存在超长内含子（>= min_gap）
+      2. exon blocks 可分成 >=2 个远距离组
+    """
+    blocks = tx.get_blocks(use_cds_if_no_exon=use_cds_if_no_exon)
+    introns = tx.introns(use_cds_if_no_exon=use_cds_if_no_exon)
+    if any(x >= min_gap for x in introns):
+        return True
+
+    groups = blocks_to_groups(blocks, min_gap=min_gap)
+    if len(groups) >= 2:
+        return True
+
+    return False
+
+
+def cluster_range(transcripts, use_cds_if_no_exon=True):
+    """
+    求一个 transcript 簇的整体范围
+    """
+    spans = [tx.span(use_cds_if_no_exon=use_cds_if_no_exon) for tx in transcripts]
+    return (min(x[0] for x in spans), max(x[1] for x in spans))
+
+
+def transcript_hits_clusters(tx, cluster_ranges, use_cds_if_no_exon=True):
+    """
+    判断一个 transcript 是否横跨多个 cluster
+    这里用 transcript 自己的 exon-group span 去命中 cluster
+    """
+    blocks = tx.get_blocks(use_cds_if_no_exon=use_cds_if_no_exon)
+    groups = blocks_to_groups(blocks, min_gap=1)  # 这里只拿所有连续块组
+    # 实际上 exon merge 后本身已是连续块，这里直接用 blocks 即可；
+    # 但为了稳妥，我们仍按单块 span 来命中 cluster。
+    spans = blocks if blocks else [tx.span(use_cds_if_no_exon=use_cds_if_no_exon)]
+
+    hit = set()
+    for i, cr in enumerate(cluster_ranges):
+        for sp in spans:
+            if interval_overlap(sp, cr):
+                hit.add(i)
+                break
+    return sorted(hit)
+
+
+# ----------------------------
+# GFF3 解析
+# ----------------------------
+
+def read_gff3(gff_file):
+    genes = {}
+    transcripts = {}
+
+    # 有些 GFF3 exon 的 Parent 可能是多个 transcript，用逗号分隔
+    child_features = []
+
+    with open(gff_file, "r", encoding="utf-8") as fh:
+        for line in fh:
+            if not line.strip() or line.startswith("#"):
+                continue
+
+            parts = line.rstrip("\n").split("\t")
+            if len(parts) != 9:
+                continue
+
+            chrom, source, feature_type, start, end, score, strand, phase, attrs_str = parts
+            start = int(start)
+            end = int(end)
+            attrs = parse_attributes(attrs_str)
+
+            if feature_type == "gene":
+                gid = attrs.get("ID")
+                if not gid:
+                    continue
+                genes[gid] = Gene(gid, chrom, start, end, strand)
+
+            elif feature_type in ("mRNA", "transcript"):
+                tid = attrs.get("ID")
+                parent = attrs.get("Parent")
+                if not tid or not parent:
+                    continue
+                # Parent 理论上应指向 gene
+                parent_gene = parent.split(",")[0]
+                transcripts[tid] = Transcript(tid, parent_gene, chrom, start, end, strand)
+
+            elif feature_type in ("exon", "CDS"):
+                parents = attrs.get("Parent")
+                if not parents:
+                    continue
+                parent_list = parents.split(",")
+                child_features.append((feature_type, chrom, start, end, strand, parent_list))
+
+    # 挂接 transcript 到 gene
+    for tid, tx in transcripts.items():
+        if tx.parent_gene in genes:
+            genes[tx.parent_gene].transcripts.append(tx)
+
+    # 挂接 exon/CDS 到 transcript
+    for feature_type, chrom, start, end, strand, parent_list in child_features:
+        for pid in parent_list:
+            if pid in transcripts:
+                tx = transcripts[pid]
+                if feature_type == "exon":
+                    tx.exons.append((start, end))
+                elif feature_type == "CDS":
+                    tx.cdss.append((start, end))
+
+    return genes
+
+
+# ----------------------------
+# 核心检测逻辑
+# ----------------------------
+
+def analyze_gene(
+    gene,
+    min_gap=10000,
+    cluster_gap=2000,
+    min_core_tx_per_cluster=1,
+    min_bridge_count=1,
+    use_cds_if_no_exon=True
+):
+    """
+    返回：
+      None -> 不可疑
+      dict -> 可疑结果
+    """
+
+    if len(gene.transcripts) < 2:
+        return None
+
+    # 先识别桥接 transcript
+    bridge_candidates = []
+    core_candidates = []
+
+    for tx in gene.transcripts:
+        if transcript_is_bridge_candidate(tx, min_gap=min_gap, use_cds_if_no_exon=use_cds_if_no_exon):
+            bridge_candidates.append(tx)
+        else:
+            core_candidates.append(tx)
+
+    # 如果没有 core transcript，则无法稳定构建核心簇
+    if len(core_candidates) < 2:
+        return None
+
+    # 用非桥接 transcript 构建核心簇
+    core_clusters = union_find_cluster(
+        core_candidates,
+        get_interval=lambda x: x.span(use_cds_if_no_exon=use_cds_if_no_exon),
+        max_gap=cluster_gap
+    )
+
+    # 过滤过小簇
+    core_clusters = [c for c in core_clusters if len(c) >= min_core_tx_per_cluster]
+
+    if len(core_clusters) < 2:
+        return None
+
+    core_cluster_ranges = [
+        cluster_range(c, use_cds_if_no_exon=use_cds_if_no_exon)
+        for c in core_clusters
+    ]
+
+    # 检查桥接 transcript 是否真的命中多个簇
+    true_bridges = []
+    bridge_hit_info = {}
+
+    for tx in bridge_candidates:
+        hits = transcript_hits_clusters(tx, core_cluster_ranges, use_cds_if_no_exon=use_cds_if_no_exon)
+        if len(hits) >= 2:
+            true_bridges.append(tx)
+            bridge_hit_info[tx.id] = hits
+
+    if len(true_bridges) < min_bridge_count:
+        return None
+
+    # 输出结果
+    cluster_member_strs = []
+    cluster_range_strs = []
+    for i, c in enumerate(core_clusters, start=1):
+        cr = cluster_range(c, use_cds_if_no_exon=use_cds_if_no_exon)
+        cluster_range_strs.append(f"C{i}:{cr[0]}-{cr[1]}")
+        cluster_member_strs.append(f"C{i}:" + ",".join(sorted(tx.id for tx in c)))
+
+    bridge_member_strs = []
+    for tx in sorted(true_bridges, key=lambda x: x.id):
+        hit_clusters = ",".join(f"C{i+1}" for i in bridge_hit_info[tx.id])
+        bridge_member_strs.append(f"{tx.id}[{hit_clusters}]")
+
+    result = {
+        "gene_id": gene.id,
+        "chrom": gene.chrom,
+        "start": gene.start,
+        "end": gene.end,
+        "strand": gene.strand,
+        "total_tx": len(gene.transcripts),
+        "core_tx": len(core_candidates),
+        "bridge_tx": len(true_bridges),
+        "cluster_count": len(core_clusters),
+        "cluster_ranges": ";".join(cluster_range_strs),
+        "cluster_members": ";".join(cluster_member_strs),
+        "bridge_members": ";".join(bridge_member_strs)
+    }
+    return result
+
+
+# ----------------------------
+# 主程序
+# ----------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="检测 GFF3 中“一个 gene 下多个离散 transcript 簇被少数桥接 transcript 连接”的可疑错误合并基因。"
+    )
+    parser.add_argument("-i", "--input", required=True, help="输入 GFF3 文件")
+    parser.add_argument("-o", "--output", required=True, help="输出 TSV 文件")
+    parser.add_argument(
+        "--min-gap",
+        type=int,
+        default=10000,
+        help="判定桥接 transcript 的最小远距离 gap / 超长内含子阈值，默认 10000"
+    )
+    parser.add_argument(
+        "--cluster-gap",
+        type=int,
+        default=2000,
+        help="核心 transcript 聚类时允许的最大 gap，默认 2000"
+    )
+    parser.add_argument(
+        "--min-core-tx-per-cluster",
+        type=int,
+        default=1,
+        help="每个核心簇至少包含多少条非桥接 transcript，默认 1"
+    )
+    parser.add_argument(
+        "--min-bridge-count",
+        type=int,
+        default=1,
+        help="至少多少条真实桥接 transcript 才输出，默认 1"
+    )
+    parser.add_argument(
+        "--no-use-cds-if-no-exon",
+        action="store_true",
+        help="若 transcript 没有 exon，则不要回退使用 CDS"
+    )
+
+    args = parser.parse_args()
+
+    use_cds_if_no_exon = not args.no_use_cds_if_no_exon
+
+    genes = read_gff3(args.input)
+
+    out_fields = [
+        "gene_id",
+        "chrom",
+        "start",
+        "end",
+        "strand",
+        "total_tx",
+        "core_tx",
+        "bridge_tx",
+        "cluster_count",
+        "cluster_ranges",
+        "cluster_members",
+        "bridge_members"
+    ]
+
+    n_total = 0
+    n_flagged = 0
+
+    with open(args.output, "w", encoding="utf-8") as out:
+        out.write("\t".join(out_fields) + "\n")
+
+        for gid in sorted(genes.keys()):
+            gene = genes[gid]
+            n_total += 1
+
+            result = analyze_gene(
+                gene,
+                min_gap=args.min_gap,
+                cluster_gap=args.cluster_gap,
+                min_core_tx_per_cluster=args.min_core_tx_per_cluster,
+                min_bridge_count=args.min_bridge_count,
+                use_cds_if_no_exon=use_cds_if_no_exon
+            )
+
+            if result:
+                n_flagged += 1
+                out.write("\t".join(str(result[f]) for f in out_fields) + "\n")
+
+    sys.stderr.write(
+        f"[INFO] Total genes checked: {n_total}\n"
+        f"[INFO] Suspicious merged genes: {n_flagged}\n"
+        f"[INFO] Output written to: {args.output}\n"
+    )
+
+
+if __name__ == "__main__":
+    main()

gffkit/main.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Command line interface for gffkit."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from . import __version__
+
+
+def _run_legacy_main(func: Callable[[], object], prog: str, args: List[str]) -> int:
+    """Run an existing script-style main() by temporarily replacing sys.argv."""
+    old_argv = sys.argv[:]
+    sys.argv = [prog] + list(args)
+    try:
+        ret = func()
+        return 0 if ret is None else int(ret)
+    finally:
+        sys.argv = old_argv
+
+
+def cmd_detect_bridge(args: argparse.Namespace, extra: List[str]) -> int:
+    from . import detect_bridge_merged_genes as mod
+    cli = ["-i", args.input, "-o", args.output]
+    cli += extra
+    return _run_legacy_main(mod.main, "gffkit detect-bridge", cli)
+
+
+def cmd_complement(args: argparse.Namespace, extra: List[str]) -> int:
+    from . import complement_annotations as mod
+    cli = ["--ref", args.ref]
+    for add_file in args.add:
+        cli += ["--add", add_file]
+    if args.output:
+        cli += ["--output", args.output]
+    cli += extra
+    return _run_legacy_main(mod.main, "gffkit complement", cli)
+
+
+def cmd_add_utr(args: argparse.Namespace, extra: List[str]) -> int:
+    from . import add_utr as mod
+    cli = ["-i", args.input, "-o", args.output]
+    cli += extra
+    return _run_legacy_main(mod.main, "gffkit add-utr", cli)
+
+
+def cmd_integrate(args: argparse.Namespace, extra: List[str]) -> int:
+    """Run the full three-step annotation integration workflow."""
+    from . import detect_bridge_merged_genes as detect_mod
+    from . import complement_annotations as complement_mod
+    from . import add_utr as utr_mod
+
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    suspicious_tsv = Path(args.suspicious_tsv) if args.suspicious_tsv else outdir / f"{args.prefix}.suspicious.tsv"
+    merged_gff = Path(args.merged_gff) if args.merged_gff else outdir / f"{args.prefix}.merged.gff3"
+    final_gff = Path(args.output) if args.output else outdir / f"{args.prefix}.final.withUTR.gff3"
+
+    print("[gffkit] Step 1/3: detecting suspicious merged genes", file=sys.stderr)
+    detect_cli = [
+        "-i", args.annotation_a,
+        "-o", str(suspicious_tsv),
+        "--min-gap", str(args.min_gap),
+        "--cluster-gap", str(args.cluster_gap),
+        "--min-core-tx-per-cluster", str(args.min_core_tx_per_cluster),
+        "--min-bridge-count", str(args.min_bridge_count),
+    ]
+    if args.no_use_cds_if_no_exon:
+        detect_cli.append("--no-use-cds-if-no-exon")
+    ret = _run_legacy_main(detect_mod.main, "gffkit detect-bridge", detect_cli)
+    if ret != 0:
+        return ret
+
+    print("[gffkit] Step 2/3: region-aware annotation merging", file=sys.stderr)
+    complement_cli = [
+        "--ref", args.annotation_a,
+        "--add", args.annotation_b,
+        "--swap_region_tsv", str(suspicious_tsv),
+        "--swap_region_flank", str(args.swap_region_flank),
+        "--size_min", str(args.size_min),
+        "--output", str(merged_gff),
+    ]
+    ret = _run_legacy_main(complement_mod.main, "gffkit complement", complement_cli)
+    if ret != 0:
+        return ret
+
+    print("[gffkit] Step 3/3: adding UTR features", file=sys.stderr)
+    utr_cli = ["-i", str(merged_gff), "-o", str(final_gff), "--id-prefix", args.utr_id_prefix]
+    if args.replace_existing_utrs:
+        utr_cli.append("--replace-existing-utrs")
+    ret = _run_legacy_main(utr_mod.main, "gffkit add-utr", utr_cli)
+    if ret != 0:
+        return ret
+
+    print("[gffkit] Done", file=sys.stderr)
+    print(f"[gffkit] suspicious TSV: {suspicious_tsv}", file=sys.stderr)
+    print(f"[gffkit] merged GFF3:     {merged_gff}", file=sys.stderr)
+    print(f"[gffkit] final GFF3:      {final_gff}", file=sys.stderr)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gffkit",
+        description="Utilities for detecting merged-gene artifacts, region-aware GFF merging, and UTR reconstruction.",
+    )
+    parser.add_argument("--version", action="version", version=f"gffkit {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p = subparsers.add_parser(
+        "detect-bridge",
+        help="Detect suspicious merged genes caused by bridge transcripts.",
+        description="Wrapper around detect_bridge_merged_genes.py. Unknown options are forwarded.",
+    )
+    p.add_argument("-i", "--input", required=True, help="Input GFF3 file, usually Annotation A.")
+    p.add_argument("-o", "--output", required=True, help="Output suspicious.tsv file.")
+    p.set_defaults(handler=cmd_detect_bridge)
+
+    p = subparsers.add_parser(
+        "complement",
+        help="Complement/merge GFF annotations with optional region-swap mode.",
+        description="Wrapper around complement_annotations.py. Unknown options are forwarded.",
+    )
+    p.add_argument("--ref", "-r", "-i", required=True, help="Reference GFF/GTF file.")
+    p.add_argument("--add", "-a", action="append", required=True, help="Supplementary GFF/GTF file; can be repeated.")
+    p.add_argument("--output", "--out", "-o", default=None, help="Output GFF3 path. Default: stdout.")
+    p.set_defaults(handler=cmd_complement)
+
+    p = subparsers.add_parser(
+        "add-utr",
+        help="Add five_prime_UTR and three_prime_UTR features from exon/CDS coordinates.",
+        description="Wrapper around add_utr.py. Unknown options are forwarded.",
+    )
+    p.add_argument("-i", "--input", required=True, help="Input GFF3/GTF file.")
+    p.add_argument("-o", "--output", required=True, help="Output GFF3 file.")
+    p.set_defaults(handler=cmd_add_utr)
+
+    p = subparsers.add_parser(
+        "integrate",
+        help="Run the full A/B region-aware integration workflow.",
+        description=(
+            "Detect suspicious merged-gene regions in Annotation A, use Annotation B as the local "
+            "primary reference in those regions, then add UTR features."
+        ),
+    )
+    p.add_argument("--annotation-a", "--a", required=True, help="Annotation A: EviAnn/RNA-seq-supported GFF3.")
+    p.add_argument("--annotation-b", "--b", required=True, help="Annotation B: ANNEVO/deep-learning GFF3.")
+    p.add_argument("--outdir", default="gffkit_out", help="Output directory.")
+    p.add_argument("--prefix", default="gffkit", help="Output file prefix.")
+    p.add_argument("-o", "--output", default=None, help="Final GFF3 output path. Default: OUTDIR/PREFIX.final.withUTR.gff3")
+    p.add_argument("--suspicious-tsv", default=None, help="Optional path for intermediate suspicious.tsv.")
+    p.add_argument("--merged-gff", default=None, help="Optional path for intermediate merged.gff3.")
+
+    p.add_argument("--min-gap", type=int, default=10000, help="Bridge-candidate long gap threshold.")
+    p.add_argument("--cluster-gap", type=int, default=2000, help="Core cluster maximum gap.")
+    p.add_argument("--min-core-tx-per-cluster", type=int, default=1, help="Minimum core transcripts per cluster.")
+    p.add_argument("--min-bridge-count", type=int, default=1, help="Minimum true bridge transcripts required.")
+    p.add_argument("--no-use-cds-if-no-exon", action="store_true", help="Do not use CDS when transcript has no exon.")
+
+    p.add_argument("--swap-region-flank", type=int, default=100, help="Flanking bp added to suspicious regions.")
+    p.add_argument("--size-min", type=int, default=0, help="Minimum CDS size for non-overlapping supplementary roots.")
+    p.add_argument("--replace-existing-utrs", action="store_true", help="Remove existing UTRs and recreate them.")
+    p.add_argument("--utr-id-prefix", default="gffkit_utr_", help="Prefix for newly created UTR IDs.")
+    p.set_defaults(handler=cmd_integrate)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args, extra = parser.parse_known_args(argv)
+    return args.handler(args, extra)