split3c 0.0.1__py3-none-any.whl

split3c/resolve/main.py

@@ -0,0 +1,506 @@
+"""
+Parse and filter remapped multiplexes from Microsplit / Parasplit outputs.
+
+Build `.pairs` files from remapped split BAM pairs.
+Also build `.pairs` files from from classic bam.
+
+Copyright © 2026 Samir Bertache
+SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+from typing import Any, Optional
+
+from .parse import parse_to_pairs
+
+__version__ = "0.0.4"
+
+
+def _try_rich() -> Optional[dict[str, Any]]:
+    try:
+        from rich import box
+        from rich.console import Console
+        from rich.panel import Panel
+        from rich.table import Table
+        from rich.theme import Theme
+        from rich.traceback import install
+        from rich_argparse import RichHelpFormatter
+    except Exception:
+        return None
+
+    console = Console(
+        theme=Theme(
+            {
+                "info": "dim cyan",
+                "error": "bold red",
+                "warning": "magenta",
+                "ok": "bold green",
+            }
+        ),
+        width=110,
+    )
+    install(console=console)
+    return {
+        "console": console,
+        "Panel": Panel,
+        "Table": Table,
+        "box": box,
+        "RichHelpFormatter": RichHelpFormatter,
+    }
+
+
+_R = _try_rich()
+
+
+class MyArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        if _R is not None:
+            console = _R["console"]
+            Panel = _R["Panel"]
+            console.print(
+                Panel(
+                    f"[bold red]Error:[/bold red] {message}",
+                    title="Incorrect arguments",
+                    expand=True,
+                    width=110,
+                )
+            )
+            self.print_help()
+            self.exit(2)
+
+        self.print_usage(sys.stderr)
+        self.exit(2, f"{self.prog}: error: {message}\n")
+
+
+def _formatter_class():
+    if _R is None:
+        return argparse.RawTextHelpFormatter
+
+    from rich_argparse import RawTextRichHelpFormatter
+
+    return lambda prog: RawTextRichHelpFormatter(
+        prog,
+        max_help_position=42,
+        width=110,
+    )
+
+
+def _print_banner() -> None:
+    if _R is None:
+        return
+
+    console = _R["console"]
+    Panel = _R["Panel"]
+    console.print(
+        Panel(
+            "[bold blue]splitparse[/bold blue]\n"
+            "Parse remapped split BAM input into `.pairs` files.\n"
+            "Supports either two synchronized BAM files or one interleaved BAM.\n\n"
+            "Use --help to see detailed options.",
+            title="[bold green]splitparse[/bold green]",
+            subtitle=f"Version: {__version__}",
+            expand=True,
+            width=110,
+        )
+    )
+    console.print("")
+
+
+def _print_summary(args: argparse.Namespace) -> None:
+    if _R is None:
+        return
+
+    console = _R["console"]
+    Table = _R["Table"]
+    box = _R["box"]
+
+    table = Table(
+        show_edge=True,
+        title="[bold green]Run summary[/bold green]",
+        box=box.HEAVY,
+        width=110,
+    )
+    table.add_column("Key", style="cyan", no_wrap=True)
+    table.add_column("Value", style="magenta")
+
+    table.add_row("--single-bam", str(args.single_bam))
+    table.add_row("--bam-forward", str(args.bam_forward))
+    table.add_row("--bam-reverse", str(args.bam_reverse))
+    table.add_row("--mode", "simple" if args.simple else "split")
+    table.add_row("--out-pairs", str(args.out_pairs))
+    table.add_row("-o/--out-true-multiplex", str(args.out_true_multiplex))
+    table.add_row("--out-duplex", str(args.out_duplex))
+    table.add_row("--min-mapq", str(args.min_mapq))
+    table.add_row("--adjacent-gap-max", str(args.adjacent_gap_max))
+    table.add_row("--terminal-center-gap-max", str(args.terminal_center_gap_max))
+    table.add_row("--strict-complete-cover", str(args.strict_complete_cover))
+    table.add_row("--terminal-overlap-tolerance", str(args.terminal_overlap_tolerance))
+    table.add_row("--assembly", str(args.assembly))
+    table.add_row("--bam-threads", str(args.bam_threads))
+    table.add_row("--out-threads", str(args.out_threads))
+    table.add_row("--write-batch-size", str(args.write_batch_size))
+    table.add_row("--qual-stats", str(args.qual_stats))
+    table.add_row("--sam", str(args.sam))
+    table.add_row("--filter-stats", str(args.filter_stats))
+    table.add_row("--no-flip", str(args.no_flip))
+    table.add_row("--force", str(args.force))
+    table.add_row("--verbose", str(args.verbose))
+
+    console.print(table)
+    console.print("")
+
+
+def validate_args(args: argparse.Namespace) -> None:
+    def _file_exists(path: str, what: str) -> None:
+        if not os.path.exists(path):
+            raise ValueError(f"{what}: file not found: {path}")
+        if not os.path.isfile(path):
+            raise ValueError(f"{what}: not a file: {path}")
+
+    def _parent_writable(path: str, what: str) -> None:
+        parent = os.path.dirname(os.path.abspath(path)) or os.getcwd()
+        if not os.path.exists(parent):
+            raise ValueError(f"{what}: parent directory does not exist: {parent}")
+        if not os.access(parent, os.W_OK):
+            raise ValueError(f"{what}: parent directory not writable: {parent}")
+
+    def _check_output(path: Optional[str], what: str) -> None:
+        if path is None:
+            return
+        _parent_writable(path, what)
+        if not args.force and os.path.exists(path):
+            raise ValueError(f"{what}: output already exists: {path} (use --force)")
+
+    _file_exists(args.bam_forward, "Input BAM")
+
+    if args.single_bam:
+        if args.bam_reverse is not None:
+            raise ValueError("--bam-reverse must not be provided with --single-bam")
+    else:
+        if args.bam_reverse is None:
+            raise ValueError("--bam-reverse is required unless --single-bam is used")
+        _file_exists(args.bam_reverse, "Reverse BAM")
+
+    # outputs distincts
+    paths = [p for p in [args.out_pairs, args.out_duplex, args.out_true_multiplex] if p]
+    if len(paths) != len(set(paths)):
+        raise ValueError("All output paths must be distinct")
+
+    if args.simple:
+        if args.out_pairs is None:
+            raise ValueError("--simple requires --out-pairs")
+        if args.out_duplex or args.out_true_multiplex:
+            raise ValueError("--simple forbids --out-resolved/--out-true-multiplex")
+
+    if args.split:
+        # strict spec :
+        has_out_pairs = args.out_pairs is not None
+        has_split_outputs = (args.out_duplex is not None) or (
+            args.out_true_multiplex is not None
+        )
+
+        # soit out_pairs, soit (resolved + true multiplex)
+        if has_out_pairs and has_split_outputs:
+            raise ValueError(
+                "--split: choose either --out-pairs OR (--out-resolved and --out-true-multiplex), not both"
+            )
+        if not has_out_pairs:
+            if args.out_duplex is None or args.out_true_multiplex is None:
+                raise ValueError(
+                    "--split without --out-pairs requires BOTH --out-resolved and --out-true-multiplex"
+                )
+
+    if args.out_pairs:
+        _check_output(args.out_pairs, "All pairs output")
+
+    if args.out_true_multiplex:
+        _check_output(args.out_true_multiplex, "True multiplex pairs output")
+        _check_output(args.out_duplex, "Duplex pairs output")
+
+    if args.min_mapq < 0:
+        raise ValueError("--min-mapq must be >= 0")
+    if args.adjacent_gap_max < 0:
+        raise ValueError("--adjacent-gap-max must be >= 0")
+    if args.terminal_center_gap_max < 0:
+        raise ValueError("--terminal-center-gap-max must be >= 0")
+    if args.terminal_overlap_tolerance < 0:
+        raise ValueError("--terminal-overlap-tolerance must be >= 0")
+    if args.bam_threads < 1:
+        raise ValueError("--bam-threads must be >= 1")
+    if args.out_threads < 1:
+        raise ValueError("--out-threads must be >= 1")
+    if args.write_batch_size < 1:
+        raise ValueError("--write-batch-size must be >= 1")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = MyArgumentParser(
+        description=(
+            "Parse remapped/mapped split BAM pairs into `.pairs` outputs.\n"
+            "The parser keeps the first alignment seen per tag, filters low-MAPQ slots,\n"
+            "merges adjacent same-origin fragments when their genomic gap is small,\n"
+            "optionally collapses the terminal forward/reverse pair when compatible,\n"
+            "and emits pairs for molecules that remain multiplex or become resolved."
+        ),
+        epilog=(
+            "Examples:\n"
+            "\n\tOne output (simple event : duplex) : \n\tsplitparse --simple -1 R1.bam -2 R2.bam --out-pairs out.pairs.gz\n"
+            "\n\tGlobal output (all pairs) :  \n\tsplitparse --split -1 R1_split.bam -2 R2_split.bam --out-pairs all.pairs.gz\n"
+            "\n\tSeparate outputs (resolved + true multiplex) : \n\tsplitparse --split -1 R1_split.bam -2 R2_split.bam -o true_multiplex.pairs.gz --out-resolved resolved.pairs.gz\n"
+            "\n\tSingle bam : \n\tsplitparse --simple -1 merged.bam --single- --out-pairs out.pairs.gz"
+        ),
+        formatter_class=_formatter_class(),
+    )
+
+    req = parser.add_argument_group("Required inputs")
+    out = parser.add_argument_group("Outputs")
+    flt = parser.add_argument_group("Filtering parameters")
+    extra = parser.add_argument_group("Optional pair columns")
+    perf = parser.add_argument_group("Performance")
+    misc = parser.add_argument_group("Misc")
+
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument(
+        "--simple",
+        action="store_true",
+        help="Classic .pairs from BAM input (ignore split tags). Use it to transform your unsplit bam to .pairs",
+    )
+    mode.add_argument(
+        "--split",
+        action="store_true",
+        help="Split-aware mode (parse tags if present; fallback simple).",
+    )
+
+    req.add_argument(
+        "-1",
+        "--bam-forward",
+        required=True,
+        help="Path to R1 split BAM, or to a single interleaved BAM if --single-bam is used.",
+    )
+    req.add_argument(
+        "-2",
+        "--bam-reverse",
+        default=None,
+        help="Path to R2 split BAM. Not required if --single-bam is used.",
+    )
+    req.add_argument(
+        "--single-bam",
+        action="store_true",
+        help="Use one interleaved BAM instead of two synchronized BAM files.",
+    )
+
+    out.add_argument(
+        "--out-pairs",
+        default=None,
+        help="Output pairs for --simple or global output for --split.",
+    )
+    out.add_argument(
+        "-o",
+        "--out-true-multiplex",
+        default=None,
+        help="Output true multiplex pairs (split mode).",
+    )
+    out.add_argument(
+        "--out-duplex",
+        default=None,
+        help="Output resolved pairs which become duplex (split mode).",
+    )
+
+    out.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing output files.",
+    )
+    out.add_argument(
+        "--sam",
+        action="store_true",
+        help=(
+            "Append two extra columns, sam1 and sam2, containing the raw SAM lines "
+            "of the emitted pair sides."
+        ),
+    )
+
+    flt.add_argument(
+        "--strict-complete-cover",
+        action="store_true",
+        help=(
+            "Require each molecule block to expose all declared tags (FT+RT)."
+            "If not, the block is marked incomplete_cover and no pairs are emitted."
+        ),
+    )
+    flt.add_argument(
+        "--min-mapq",
+        type=int,
+        default=1,
+        help="Minimum MAPQ required for one alignment to be considered valid.",
+    )
+    flt.add_argument(
+        "--adjacent-gap-max",
+        type=int,
+        default=5,
+        help="Maximum strand-aware genomic gap allowed to merge two adjacent fragments from the same origin (origin means forward or reverse).",
+    )
+    flt.add_argument(
+        "--terminal-center-gap-max",
+        type=int,
+        default=300,
+        help="Maximum central gap allowed to collapse the terminal forward/reverse pair.",
+    )
+    flt.add_argument(
+        "--terminal-overlap-tolerance",
+        type=int,
+        default=1,
+        help="Allowed negative overlap when testing terminal forward/reverse collapse.",
+    )
+    flt.add_argument(
+        "--assembly",
+        default=None,
+        help="Optional assembly name to store in the `.pairs` header.",
+    )
+    flt.add_argument(
+        "--no-flip",
+        action="store_true",
+        help="Do not reorder pairs into genomic upper-triangle order.",
+    )
+
+    extra.add_argument(
+        "--qual-stats",
+        action="store_true",
+        help="Add len1 len2 mapq1 mapq2 columns to output pairs.",
+    )
+    extra.add_argument(
+        "--filter-stats",
+        action="store_true",
+        help="Add hard_merged terminal_aliased columns to output pairs.",
+    )
+
+    perf.add_argument(
+        "--bam-threads",
+        type=int,
+        default=3,
+        help="Number of threads used for BAM reading.",
+    )
+    perf.add_argument(
+        "--out-threads",
+        type=int,
+        default=3,
+        help="Number of threads used by the output compression backend.",
+    )
+    perf.add_argument(
+        "--write-batch-size",
+        type=int,
+        default=50000,
+        help="Number of pair lines buffered before flushing to disk.",
+    )
+
+    misc.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    misc.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v, -vv).",
+    )
+
+    return parser
+
+
+def main_cli(argv: list[str] | None = None) -> int:
+    _print_banner()
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    level = logging.WARNING
+    if args.verbose == 1:
+        level = logging.INFO
+    elif args.verbose >= 2:
+        level = logging.DEBUG
+    logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
+
+    try:
+        validate_args(args)
+    except ValueError as exc:
+        if _R is not None:
+            Panel = _R["Panel"]
+            _R["console"].print(
+                Panel(
+                    f"[bold red]{exc}[/bold red]",
+                    title="Validation",
+                    expand=True,
+                    width=110,
+                )
+            )
+            parser.print_help()
+        else:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            parser.print_help(sys.stderr)
+        return 2
+
+    _print_summary(args)
+    mode = "simple" if args.simple else "split"
+
+    try:
+        counts = parse_to_pairs(
+            bam_for_path=args.bam_forward,
+            bam_rev_path=args.bam_reverse,
+            mode=mode,
+            out_pairs=args.out_pairs,
+            out_duplex=args.out_duplex,
+            out_true_multiplex_pairs=args.out_true_multiplex,
+            min_mapq=args.min_mapq,
+            adjacent_gap_max=args.adjacent_gap_max,
+            terminal_center_gap_max=args.terminal_center_gap_max,
+            terminal_overlap_tolerance=args.terminal_overlap_tolerance,
+            assembly=args.assembly,
+            bam_threads=args.bam_threads,
+            out_threads=args.out_threads,
+            flip=not args.no_flip,
+            write_batch_size=args.write_batch_size,
+            sam_output=args.sam,
+            qual_stats=args.qual_stats,
+            filter_stats=args.filter_stats,
+            strict_complete_cover=args.strict_complete_cover,
+            single_bam=args.single_bam,
+            version=__version__,
+        )
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:
+        if _R is not None:
+            Panel = _R["Panel"]
+            _R["console"].print(
+                Panel(
+                    f"[bold red]{exc}[/bold red]",
+                    title="Runtime error",
+                    expand=True,
+                    width=110,
+                )
+            )
+        else:
+            print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    if _R is not None:
+        console = _R["console"]
+        Panel = _R["Panel"]
+        console.print(
+            Panel(
+                json.dumps(counts, indent=2, sort_keys=True),
+                title="[bold green]Run completed[/bold green]",
+                expand=True,
+                width=110,
+            )
+        )
+    else:
+        print(json.dumps(counts, indent=2, sort_keys=True))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main_cli())

split3c/resolve/pairs.py

@@ -0,0 +1,56 @@
+from typing import Iterable, TextIO
+
+DEFAULT_COLUMNS = [
+    "readID",
+    "chrom1",
+    "pos1",
+    "chrom2",
+    "pos2",
+    "strand1",
+    "strand2",
+    "pair_type",
+    "tag1",
+    "tag2",
+    "alias1",
+    "alias2",
+    "origin1",
+    "origin2",
+    "origin_class",
+    "FT",
+    "RT",
+    "status",
+    "hard_merged",
+    "terminal_aliased",
+]
+
+
+def make_pairs_header(
+    chromsizes: Iterable[tuple[str, int]],
+    columns: list[str] | None = None,
+    assembly: str | None = None,
+    shape: str = "whole matrix",
+    sorted_by: str = "none",
+    program_id: str = "parse2split",
+    program_version: str = "0.0.0",
+) -> list[str]:
+    if columns is None:
+        columns = DEFAULT_COLUMNS
+
+    header = [
+        "## pairs format v1.0",
+        f"#shape: {shape}",
+        f"#sorted: {sorted_by}",
+        f"#columns: {' '.join(columns)}",
+        f"#command: {program_id} {program_version}",
+    ]
+    if assembly:
+        header.append(f"#genome_assembly: {assembly}")
+    for chrom, length in chromsizes:
+        header.append(f"#chromsize: {chrom} {length}")
+    return header
+
+
+def write_pairs_header(out: TextIO, header_lines: list[str]) -> None:
+    for line in header_lines:
+        out.write(line)
+        out.write("\n")