gffkit 0.2__tar.gz → 0.3.1__tar.gz

{gffkit-0.2/src/gffkit.egg-info → gffkit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gffkit
-Version: 0.2
+Version: 0.3.1
 Summary: Region-aware GFF annotation integration toolkit
 Author: Qunjie Zhang
 License: MIT
@@ -48,7 +48,8 @@ gffkit integrate \
   --annotation-a EviAnn.gff3 \
   --annotation-b ANNEVO.gff3 \
   --outdir gffkit_out \
-  --prefix sample
+  --prefix sample \
+  -t 8
 ```
 
 Outputs:
@@ -61,7 +62,7 @@ Outputs:
 
 ```bash
 # 1. Detect suspicious merged genes in Annotation A
-gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv
+gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv -t 8
 
 # 2. Use A as the global reference, but switch to B in suspicious regions
 gffkit complement \
@@ -69,12 +70,27 @@ gffkit complement \
   --add ANNEVO.gff3 \
   --swap_region_tsv suspicious.tsv \
   --swap_region_flank 100 \
-  --output merged.gff3
+  --output merged.gff3 \
+  -t 8
 
 # 3. Add UTR features
 gffkit add-utr -i merged.gff3 -o final.annotation.withUTR.gff3
 ```
 
+### Merge three or more annotations
+
+Use repeated `--add` arguments. Files are merged in the order provided.
+
+```bash
+gffkit complement \
+  --ref EviAnn.gff3 \
+  --add ANNEVO.gff3 \
+  --add Helixer.gff3 \
+  --add PASA.gff3 \
+  --output merged.multi.gff3 \
+  -t 8
+```
+
 ## Command overview
 
 ```bash
@@ -85,11 +101,30 @@ gffkit add-utr --help
 gffkit integrate --help
 ```
 
+## Threads
+
+Version 0.3 and later add `-t/--threads`.
+
+- `detect-bridge` analyzes genes in parallel.
+- `complement` pre-parses multiple `--add` files in parallel, then merges them in the original command-line order.
+- `integrate` passes the thread count to the detect and complement steps.
+
+Example:
+
+```bash
+gffkit integrate --annotation-a EviAnn.gff3 --annotation-b ANNEVO.gff3 -t 16
+```
+
 ## Annotation integration strategy
 
 - Annotation A, for example EviAnn/RNA-seq-supported GFF, is used as the global primary reference.
 - Annotation B, for example ANNEVO/deep-learning GFF, is used as the local primary reference only in suspicious merged-gene regions.
 - UTR features are reconstructed after merging using an exon-minus-CDS strategy.
+- When multiple tools annotate the same gene locus, the GFF source column is combined with `|`, for example `EviAnn|ANNEVO`.
+
+## Maintainer notes
+
+When command-line options or behavior changes, update this `README.md` in the versioned package directory before building and uploading to PyPI.
 
 ## License
 

{gffkit-0.2 → gffkit-0.3.1}/README.md

@@ -23,7 +23,8 @@ gffkit integrate \
   --annotation-a EviAnn.gff3 \
   --annotation-b ANNEVO.gff3 \
   --outdir gffkit_out \
-  --prefix sample
+  --prefix sample \
+  -t 8
 ```
 
 Outputs:
@@ -36,7 +37,7 @@ Outputs:
 
 ```bash
 # 1. Detect suspicious merged genes in Annotation A
-gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv
+gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv -t 8
 
 # 2. Use A as the global reference, but switch to B in suspicious regions
 gffkit complement \
@@ -44,12 +45,27 @@ gffkit complement \
   --add ANNEVO.gff3 \
   --swap_region_tsv suspicious.tsv \
   --swap_region_flank 100 \
-  --output merged.gff3
+  --output merged.gff3 \
+  -t 8
 
 # 3. Add UTR features
 gffkit add-utr -i merged.gff3 -o final.annotation.withUTR.gff3
 ```
 
+### Merge three or more annotations
+
+Use repeated `--add` arguments. Files are merged in the order provided.
+
+```bash
+gffkit complement \
+  --ref EviAnn.gff3 \
+  --add ANNEVO.gff3 \
+  --add Helixer.gff3 \
+  --add PASA.gff3 \
+  --output merged.multi.gff3 \
+  -t 8
+```
+
 ## Command overview
 
 ```bash
@@ -60,11 +76,30 @@ gffkit add-utr --help
 gffkit integrate --help
 ```
 
+## Threads
+
+Version 0.3 and later add `-t/--threads`.
+
+- `detect-bridge` analyzes genes in parallel.
+- `complement` pre-parses multiple `--add` files in parallel, then merges them in the original command-line order.
+- `integrate` passes the thread count to the detect and complement steps.
+
+Example:
+
+```bash
+gffkit integrate --annotation-a EviAnn.gff3 --annotation-b ANNEVO.gff3 -t 16
+```
+
 ## Annotation integration strategy
 
 - Annotation A, for example EviAnn/RNA-seq-supported GFF, is used as the global primary reference.
 - Annotation B, for example ANNEVO/deep-learning GFF, is used as the local primary reference only in suspicious merged-gene regions.
 - UTR features are reconstructed after merging using an exon-minus-CDS strategy.
+- When multiple tools annotate the same gene locus, the GFF source column is combined with `|`, for example `EviAnn|ANNEVO`.
+
+## Maintainer notes
+
+When command-line options or behavior changes, update this `README.md` in the versioned package directory before building and uploading to PyPI.
 
 ## License
 

{gffkit-0.2 → gffkit-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gffkit"
-version = "0.2"
+version = "0.3.1"
 description = "Region-aware GFF annotation integration toolkit"
 readme = "README.md"
 requires-python = ">=3.8"

{gffkit-0.2 → gffkit-0.3.1}/src/gffkit/__init__.py

@@ -1,3 +1,3 @@
 """gffkit: region-aware GFF annotation integration utilities."""
 
-__version__ = "0.2"
+__version__ = "0.3.1"

{gffkit-0.2 → gffkit-0.3.1}/src/gffkit/complement_annotations.py

@@ -20,13 +20,14 @@ agat_sp_complement_annotations.pl 的 Python 改写版（纯 Python，不调用
 
 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
+import argparse
+import copy
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, Iterable, List, Optional, Tuple
 
 
 GENE_LIKE_TYPES = {
@@ -607,7 +608,7 @@ def merge_source_names(*source_groups: Iterable[str]) -> str:
             for name in split_source_names(source):
                 if name not in merged:
                     merged.append(name)
-    return ",".join(merged) if merged else "."
+    return "|".join(merged) if merged else "."
 
 
 def set_tree_source(root: Feature, source: str) -> None:
@@ -843,7 +844,7 @@ def print_complement_resume(before_counts: Dict[str, Dict[str, int]],
         eprint("\nNow the data contains:")
 
 
-def build_arg_parser() -> argparse.ArgumentParser:
+def build_arg_parser() -> argparse.ArgumentParser:
     """构建命令行参数解析器。"""
     parser = argparse.ArgumentParser(
         description="用一个或多个注释文件去补充参考注释（Python 版，纯 Python，不调用 Perl）。"
@@ -880,12 +881,16 @@ def build_arg_parser() -> argparse.ArgumentParser:
         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
+    parser.add_argument("--output", "--out", "-o", default=None, help="输出文件路径；默认输出到 STDOUT")
+    parser.add_argument(
+        "-t", "--threads", type=int, default=1,
+        help="并行线程数；多个 --add 文件会并行预解析，但仍按输入顺序合并，默认 1"
+    )
+    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]:
@@ -918,7 +923,7 @@ def parse_swap_regions(raw_regions: Optional[List[List[str]]]) -> List[SwapRegio
     return parsed
 
 
-def parse_swap_regions_from_tsv(tsv_path: str, flank_bp: int = 100) -> List[SwapRegion]:
+def parse_swap_regions_from_tsv(tsv_path: str, flank_bp: int = 100) -> List[SwapRegion]:
     """
     从 detect_bridge_merged_genes.py 产生的 suspicious.tsv 读取区间。
 
@@ -994,12 +999,26 @@ def parse_swap_regions_from_tsv(tsv_path: str, flank_bp: int = 100) -> List[Swap
                     f" 当前行内容为：{line}"
                 ) from exc
 
-    return regions
+    return regions
+
+
+def parse_add_files(add_files: List[str], threads: int) -> List[Tuple[str, AnnotationSet]]:
+    """并行预解析补充注释文件，返回顺序与命令行 --add 顺序一致。"""
+    threads = max(1, threads)
+    if threads == 1 or len(add_files) <= 1:
+        return [(path, parse_annotation_file(path)) for path in add_files]
+
+    with ThreadPoolExecutor(max_workers=min(threads, len(add_files))) as executor:
+        parsed_sets = list(executor.map(parse_annotation_file, add_files))
+    return list(zip(add_files, parsed_sets))
 
 
 def main() -> int:
     parser = build_arg_parser()
-    args = parser.parse_args()
+    args = parser.parse_args()
+
+    if args.threads < 1:
+        parser.error("--threads/-t 必须是正整数")
 
     try:
         swap_regions = parse_swap_regions(args.swap_region)
@@ -1025,11 +1044,11 @@ def main() -> int:
         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()
+    # 2) 按用户给定顺序，逐个补充；多个输入文件可并行预解析
+    parsed_add_sets = parse_add_files(args.add, args.threads)
+    for next_file, add_set in parsed_add_sets:
+        eprint(f"{next_file} parsed")
+        add_set.info()
 
         before_counts = ref_set.level_counts()
 

{gffkit-0.2 → gffkit-0.3.1}/src/gffkit/detect_bridge_merged_genes.py

@@ -43,9 +43,10 @@ detect_bridge_merged_genes.py
     bridge_members
 """
 
-import argparse
-import sys
-from collections import defaultdict
+import argparse
+import sys
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
 
 
 # ----------------------------
@@ -343,7 +344,7 @@ def read_gff3(gff_file):
 # 核心检测逻辑
 # ----------------------------
 
-def analyze_gene(
+def analyze_gene(
     gene,
     min_gap=10000,
     cluster_gap=2000,
@@ -432,7 +433,13 @@ def analyze_gene(
         "cluster_members": ";".join(cluster_member_strs),
         "bridge_members": ";".join(bridge_member_strs)
     }
-    return result
+    return result
+
+
+def analyze_gene_task(task):
+    """ThreadPoolExecutor 需要顶层函数；返回 (gene_id, result)。"""
+    gid, gene, params = task
+    return gid, analyze_gene(gene, **params)
 
 
 # ----------------------------
@@ -469,15 +476,24 @@ def main():
         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
+    parser.add_argument(
+        "--no-use-cds-if-no-exon",
+        action="store_true",
+        help="若 transcript 没有 exon，则不要回退使用 CDS"
+    )
+    parser.add_argument(
+        "-t", "--threads",
+        type=int,
+        default=1,
+        help="并行分析 gene 的线程数，默认 1"
+    )
+
+    args = parser.parse_args()
+
+    if args.threads < 1:
+        parser.error("--threads/-t 必须是正整数")
+
+    use_cds_if_no_exon = not args.no_use_cds_if_no_exon
 
     genes = read_gff3(args.input)
 
@@ -499,25 +515,30 @@ def main():
     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")
+    analyze_params = {
+        "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,
+    }
+    sorted_genes = [(gid, genes[gid], analyze_params) for gid in sorted(genes.keys())]
+
+    if args.threads == 1:
+        analyzed = [analyze_gene_task(task) for task in sorted_genes]
+    else:
+        with ThreadPoolExecutor(max_workers=args.threads) as executor:
+            analyzed = list(executor.map(analyze_gene_task, sorted_genes))
+
+    with open(args.output, "w", encoding="utf-8") as out:
+        out.write("\t".join(out_fields) + "\n")
+
+        for gid, result in analyzed:
+            n_total += 1
+
+            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"
@@ -527,4 +548,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

{gffkit-0.2 → gffkit-0.3.1}/src/gffkit/main.py

@@ -25,7 +25,7 @@ def _run_legacy_main(func: Callable[[], object], prog: str, args: List[str]) ->
 
 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 = ["-i", args.input, "-o", args.output, "-t", str(args.threads)]
     cli += extra
     return _run_legacy_main(mod.main, "gffkit detect-bridge", cli)
 
@@ -37,6 +37,7 @@ def cmd_complement(args: argparse.Namespace, extra: List[str]) -> int:
         cli += ["--add", add_file]
     if args.output:
         cli += ["--output", args.output]
+    cli += ["-t", str(args.threads)]
     cli += extra
     return _run_legacy_main(mod.main, "gffkit complement", cli)
 
@@ -69,6 +70,7 @@ def cmd_integrate(args: argparse.Namespace, extra: List[str]) -> int:
         "--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),
+        "-t", str(args.threads),
     ]
     if args.no_use_cds_if_no_exon:
         detect_cli.append("--no-use-cds-if-no-exon")
@@ -84,6 +86,7 @@ def cmd_integrate(args: argparse.Namespace, extra: List[str]) -> int:
         "--swap_region_flank", str(args.swap_region_flank),
         "--size_min", str(args.size_min),
         "--output", str(merged_gff),
+        "-t", str(args.threads),
     ]
     ret = _run_legacy_main(complement_mod.main, "gffkit complement", complement_cli)
     if ret != 0:
@@ -120,6 +123,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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.add_argument("-t", "--threads", type=int, default=1, help="Number of worker threads.")
     p.set_defaults(handler=cmd_detect_bridge)
 
     p = subparsers.add_parser(
@@ -130,6 +134,7 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument("-t", "--threads", type=int, default=1, help="Number of worker threads.")
     p.set_defaults(handler=cmd_complement)
 
     p = subparsers.add_parser(
@@ -162,6 +167,7 @@ def build_parser() -> argparse.ArgumentParser:
     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("-t", "--threads", type=int, default=1, help="Number of worker threads used by detect and complement steps.")
 
     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.")

{gffkit-0.2 → gffkit-0.3.1/src/gffkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gffkit
-Version: 0.2
+Version: 0.3.1
 Summary: Region-aware GFF annotation integration toolkit
 Author: Qunjie Zhang
 License: MIT
@@ -48,7 +48,8 @@ gffkit integrate \
   --annotation-a EviAnn.gff3 \
   --annotation-b ANNEVO.gff3 \
   --outdir gffkit_out \
-  --prefix sample
+  --prefix sample \
+  -t 8
 ```
 
 Outputs:
@@ -61,7 +62,7 @@ Outputs:
 
 ```bash
 # 1. Detect suspicious merged genes in Annotation A
-gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv
+gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv -t 8
 
 # 2. Use A as the global reference, but switch to B in suspicious regions
 gffkit complement \
@@ -69,12 +70,27 @@ gffkit complement \
   --add ANNEVO.gff3 \
   --swap_region_tsv suspicious.tsv \
   --swap_region_flank 100 \
-  --output merged.gff3
+  --output merged.gff3 \
+  -t 8
 
 # 3. Add UTR features
 gffkit add-utr -i merged.gff3 -o final.annotation.withUTR.gff3
 ```
 
+### Merge three or more annotations
+
+Use repeated `--add` arguments. Files are merged in the order provided.
+
+```bash
+gffkit complement \
+  --ref EviAnn.gff3 \
+  --add ANNEVO.gff3 \
+  --add Helixer.gff3 \
+  --add PASA.gff3 \
+  --output merged.multi.gff3 \
+  -t 8
+```
+
 ## Command overview
 
 ```bash
@@ -85,11 +101,30 @@ gffkit add-utr --help
 gffkit integrate --help
 ```
 
+## Threads
+
+Version 0.3 and later add `-t/--threads`.
+
+- `detect-bridge` analyzes genes in parallel.
+- `complement` pre-parses multiple `--add` files in parallel, then merges them in the original command-line order.
+- `integrate` passes the thread count to the detect and complement steps.
+
+Example:
+
+```bash
+gffkit integrate --annotation-a EviAnn.gff3 --annotation-b ANNEVO.gff3 -t 16
+```
+
 ## Annotation integration strategy
 
 - Annotation A, for example EviAnn/RNA-seq-supported GFF, is used as the global primary reference.
 - Annotation B, for example ANNEVO/deep-learning GFF, is used as the local primary reference only in suspicious merged-gene regions.
 - UTR features are reconstructed after merging using an exon-minus-CDS strategy.
+- When multiple tools annotate the same gene locus, the GFF source column is combined with `|`, for example `EviAnn|ANNEVO`.
+
+## Maintainer notes
+
+When command-line options or behavior changes, update this `README.md` in the versioned package directory before building and uploading to PyPI.
 
 ## License
 

{gffkit-0.2 → gffkit-0.3.1}/tests/test_complement_sources.py

@@ -37,7 +37,7 @@ def test_overlapping_gene_sources_are_merged(tmp_path):
 
     assert added == 0
     assert len(ref_set.roots) == 1
-    assert {feature.source for feature in ref_set.roots[0].iter_all()} == {"EviAnn,ANNEVO"}
+    assert {feature.source for feature in ref_set.roots[0].iter_all()} == {"EviAnn|ANNEVO"}
 
 
 def test_non_overlapping_gene_keeps_single_source(tmp_path):