split3c 0.0.1__py3-none-any.whl

split3c/cli.py

@@ -0,0 +1,336 @@
+"""
+This script is a the split3c project, designed to process paired-end FASTQ files by fragmenting DNA sequences at specified restriction enzyme sites.
+
+Copyright © 2024 Samir Bertache
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+===============================================================================
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the
+Free Software Foundation, either version 3 of the License, or (at your option)
+any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+
+split3c root command-line interface.
+
+This module dispatches the three user-facing subcommands:
+
+- split3c re-site
+- split3c ns-site
+- split3c resolve
+"""
+
+import difflib
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from typing import Any, Callable, Optional
+
+from .nssite.main import main_cli as nssite_main
+from .resite.main import main_cli as resite_main
+from .resolve.main import main_cli as resolve_main
+
+try:
+    __version__ = _pkg_version("split3c")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+DOC_URL = "https://gitbio.ens-lyon.fr/LBMC/physbio/split3c/-/blob/master/README.md?ref_type=heads"
+
+CommandRunner = Callable[[list[str] | None], int]
+
+COMMANDS: dict[str, dict[str, object]] = {
+    "re-site": {
+        "runner": resite_main,
+        "summary": (
+            "Restriction-based preprocessing for Hi-C / HiChIP / 3C-like libraries."
+        ),
+        "when": (
+            "Use when ligation junctions can be derived from known restriction enzymes."
+        ),
+        "inputs": "paired FASTQ",
+        "outputs": "split / multiplex FASTQ for remapping",
+    },
+    "ns-site": {
+        "runner": nssite_main,
+        "summary": ("Non-specific ligation preprocessing for Micro-C-like libraries."),
+        "when": (
+            "Use when ligation junctions must be inferred from mapped BAM structure."
+        ),
+        "inputs": "mapped BAM",
+        "outputs": "split FASTQ for remapping",
+    },
+    "resolve": {
+        "runner": resolve_main,
+        "summary": "Convert mapped or remapped BAM into standard .pairs.",
+        "when": (
+            "Use after mapping or remapping, in either simple or split-aware mode."
+        ),
+        "inputs": "mapped / remapped BAM",
+        "outputs": ".pairs",
+    },
+}
+
+ALIASES: dict[str, str] = {
+    "resite": "re-site",
+    "nssite": "ns-site",
+}
+
+
+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
+    except Exception:
+        return None
+
+    console = Console(
+        theme=Theme(
+            {
+                "info": "dim cyan",
+                "error": "bold red",
+                "warning": "magenta",
+                "ok": "bold green",
+                "title": "bold green",
+                "cmd": "bold cyan",
+            }
+        ),
+        width=110,
+    )
+    install(console=console)
+    return {
+        "console": console,
+        "Panel": Panel,
+        "Table": Table,
+        "box": box,
+    }
+
+
+_R = _try_rich()
+
+
+def _resolve_command_name(name: str) -> str | None:
+    if name in COMMANDS:
+        return name
+    return ALIASES.get(name)
+
+
+def _print_banner() -> None:
+    if _R is None:
+        print(f"split3c {__version__}")
+        print("Preprocess 3C-derived libraries and convert BAM to .pairs.")
+        print("")
+        return
+
+    console = _R["console"]
+    Panel = _R["Panel"]
+    console.print(
+        Panel(
+            "[bold blue]split3c[/bold blue]\n"
+            "Preprocess 3C-derived sequencing libraries and convert mapped/remapped BAM into `.pairs` to retrive multiplexes events.\n\n"
+            "Subcommands:\n"
+            "  [cmd]re-site[/cmd]   restriction-enzyme workflow\n"
+            "  [cmd]ns-site[/cmd]   non-specific ligation workflow\n"
+            "  [cmd]resolve[/cmd]   BAM to `.pairs` conversion",
+            title="[title]split3c[/title]",
+            subtitle=f"Version: {__version__}",
+            expand=True,
+            width=110,
+        )
+    )
+    console.print("")
+
+
+def _print_command_table() -> None:
+    if _R is None:
+        print("Commands:")
+        for name, meta in COMMANDS.items():
+            print(f"  {name:<10} {meta['summary']}")
+        print("")
+        return
+
+    console = _R["console"]
+    Table = _R["Table"]
+    box = _R["box"]
+
+    table = Table(
+        show_edge=True,
+        title="[title]Commands[/title]",
+        box=box.HEAVY,
+        width=110,
+    )
+    table.add_column("Command", style="cyan", no_wrap=True)
+    table.add_column("Use case", style="magenta")
+    table.add_column("Input", style="green", no_wrap=True)
+    table.add_column("Output", style="yellow")
+
+    for name, meta in COMMANDS.items():
+        table.add_row(
+            name,
+            str(meta["summary"]),
+            str(meta["inputs"]),
+            str(meta["outputs"]),
+        )
+
+    console.print(table)
+    console.print("")
+
+
+def _print_workflows() -> None:
+    if _R is None:
+        print("Typical workflows: How to catch multiplexes ")
+        print("")
+        print("  Restriction-based libraries:")
+        print("    FASTQ -> split3c re-site -> MAPPING -> split3c resolve --split")
+        print("")
+        print("  Micro-C-like libraries:")
+        print(
+            "    first-pass MAPPING -> split3c ns-site -> REMAPPING -> split3c resolve --split"
+        )
+        print("")
+        print("  Classic BAM to .pairs: Only duplex informations")
+        print("    mapped BAM -> split3c resolve --simple")
+        print("")
+        return
+
+    console = _R["console"]
+    Panel = _R["Panel"]
+
+    console.print(
+        Panel(
+            "[bold]Restriction-based libraries[/bold]\n"
+            "  FASTQ -> split3c re-site -> MAPPING -> split3c resolve --split\n\n"
+            "[bold]Micro-C-like libraries[/bold]\n"
+            "  first-pass MAPPING -> split3c ns-site -> REMAPPING -> split3c resolve --split\n\n"
+            "[bold]Classic BAM to `.pairs`[/bold]\n"
+            "  mapped BAM -> split3c resolve --simple",
+            title="[title]Typical workflows[/title]",
+            expand=True,
+            width=110,
+        )
+    )
+    console.print("")
+
+
+def _print_footer() -> None:
+    if _R is None:
+        print("Examples:")
+        print("  split3c re-site --help")
+        print("  split3c ns-site --help")
+        print("  split3c resolve --help")
+        print("  split3c help resolve")
+        print("")
+        print(f"Documentation:\n  {DOC_URL}")
+        print("")
+        return
+
+    console = _R["console"]
+    Panel = _R["Panel"]
+
+    console.print(
+        Panel(
+            "[bold]Examples[/bold]\n"
+            "  split3c re-site --help\n"
+            "  split3c ns-site --help\n"
+            "  split3c resolve --help\n"
+            "  split3c help resolve\n\n"
+            "[bold]Documentation[/bold]\n"
+            f"  {DOC_URL}",
+            title="[title]Getting started[/title]",
+            expand=True,
+            width=110,
+        )
+    )
+    console.print("")
+
+
+def _print_root_help(return_code: int = 0) -> int:
+    _print_banner()
+    _print_command_table()
+    _print_workflows()
+    _print_footer()
+    return return_code
+
+
+def _print_error(message: str, title: str = "Error") -> None:
+    if _R is None:
+        print(f"{title}: {message}", file=sys.stderr)
+        return
+
+    console = _R["console"]
+    Panel = _R["Panel"]
+    console.print(
+        Panel(
+            f"[bold red]{message}[/bold red]",
+            title=title,
+            expand=True,
+            width=110,
+        )
+    )
+
+
+def _dispatch(command_name: str, argv: list[str]) -> int:
+    resolved = _resolve_command_name(command_name)
+    if resolved is None:
+        known = list(COMMANDS) + list(ALIASES)
+        suggestions = difflib.get_close_matches(command_name, known, n=1, cutoff=0.55)
+        msg = f"Unknown command: {command_name}"
+        if suggestions:
+            best = _resolve_command_name(suggestions[0]) or suggestions[0]
+            msg += f"\nDid you mean: {best} ?"
+        _print_error(msg, title="Unknown command")
+        _print_root_help(return_code=2)
+        return 2
+
+    runner = COMMANDS[resolved]["runner"]
+    assert callable(runner)
+
+    try:
+        return int(runner(argv) or 0)
+    except SystemExit as exc:
+        if isinstance(exc.code, int):
+            return exc.code
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if not argv:
+        return _print_root_help(return_code=1)
+
+    first = argv[0]
+
+    if first in {"-h", "--help"}:
+        return _print_root_help(return_code=0)
+
+    if first == "--version":
+        print(f"split3c {__version__}")
+        return 0
+
+    if first == "help":
+        if len(argv) == 1:
+            return _print_root_help(return_code=0)
+        return _dispatch(argv[1], ["--help", *argv[2:]])
+
+    return _dispatch(first, argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

split3c/nssite/auxiliary.py

@@ -0,0 +1,190 @@
+def signal_handler(sig, frame, out_f, out_r=None):
+    """
+    Handle termination signals to gracefully terminate processes.
+
+    Parameters:
+        sig (int): Signal number.
+        frame (frame object): Current stack frame.
+        out_f (subprocess.Popen): Process for the forward output.
+        out_r (subprocess.Popen | None): Process for the reverse output.
+
+    Examples
+    --------
+    >>> class _P:
+    ...     def __init__(self):
+    ...         self.terminated = False
+    ...     def terminate(self):
+    ...         self.terminated = True
+    ...
+    >>> pf, pr = _P(), _P()
+    >>> try:
+    ...     signal_handler(None, None, pf, pr)
+    ... except SystemExit:
+    ...     pass
+    >>> pf.terminated, pr.terminated
+    (True, True)
+
+    >>> pf = _P()
+    >>> try:
+    ...     signal_handler(None, None, pf, None)
+    ... except SystemExit:
+    ...     pass
+    >>> pf.terminated
+    True
+    """
+    import sys
+
+    if out_f is not None:
+        out_f.terminate()
+    if out_r is not None:
+        out_r.terminate()
+    sys.exit()
+
+
+def partitionning(num_threads: int, single_bam: bool = False) -> tuple[int, int, int]:
+    """
+    Heuristique empirique de partition des ressources pour microsplit.
+
+    Retourne:
+      pigz_threads_per_file : threads pigz par fichier (F et R)
+      compute_processes     : nb de workers process_items
+      bam_threads           : threads pysam/htslib par fichier (lecture ET écriture)
+
+    IMPORTANT
+    ---------
+    Cette fonction est volontairement empirique (surallocation CPU acceptée).
+    `num_threads` est un *hint* de cœurs disponibles, pas un budget strict.
+
+    Points de calibration (bench observés)
+    --------------------------------------
+    - 4  cœurs -> (1, 1, 1)
+    - 8  cœurs -> (2, 3, 1)
+    - 16 cœurs -> (3, 4, 3)
+
+    En mode single_bam=True :
+    - on double les threads BAM, car un seul flux BAM doit alimenter toute la pipeline
+    - pigz_per_file et compute_processes restent inchangés
+
+    Doctests
+    --------
+    >>> partitionning(3)
+    Traceback (most recent call last):
+    ...
+    ValueError: Run with --threads >= 4.
+    >>> partitionning(4)
+    (1, 1, 1)
+    >>> partitionning(8)
+    (2, 3, 1)
+    >>> partitionning(8, single_bam=True)
+    (2, 3, 2)
+    >>> partitionning(12)
+    (2, 3, 2)
+    >>> partitionning(12, single_bam=True)
+    (2, 3, 4)
+    >>> partitionning(16)
+    (3, 4, 3)
+    >>> partitionning(16, single_bam=True)
+    (3, 4, 6)
+    """
+    if num_threads < 4:
+        raise ValueError("Run with --threads >= 4.")
+
+    # 4c
+    if num_threads <= 5:
+        pigz_threads_per_file, compute_processes, bam_threads = (1, 1, 1)
+
+    # Transition vers 8c
+    elif num_threads <= 7:
+        pigz_threads_per_file, compute_processes, bam_threads = (1, 2, 1)
+
+    # 8c
+    elif num_threads <= 10:
+        pigz_threads_per_file, compute_processes, bam_threads = (2, 3, 1)
+
+    # Transition vers 16c
+    elif num_threads <= 12:
+        pigz_threads_per_file, compute_processes, bam_threads = (2, 3, 2)
+
+    elif num_threads <= 14:
+        pigz_threads_per_file, compute_processes, bam_threads = (3, 4, 2)
+
+    # 16c et plus
+    else:
+        pigz_threads_per_file, compute_processes, bam_threads = (3, 4, 3)
+
+    if single_bam:
+        bam_threads *= 2
+
+    return pigz_threads_per_file, compute_processes, bam_threads
+
+
+def check_data(els):
+    for element in els:
+        if element is None:
+            return False
+    return True
+
+
+def write_command_txt(args, resolved: dict):
+    """
+    Write a small execution report into ``command.txt``.
+
+    The report contains:
+    - UTC timestamp
+    - current working directory
+    - reconstructed command line
+    - raw CLI arguments
+    - resolved runtime values
+
+    Examples
+    --------
+    >>> import os, sys, tempfile
+    >>> from types import SimpleNamespace
+    >>> old_cwd = os.getcwd()
+    >>> old_argv = sys.argv[:]
+    >>> with tempfile.TemporaryDirectory() as td:
+    ...     os.chdir(td)
+    ...     sys.argv = ["prog", "--foo", "bar"]
+    ...     args = SimpleNamespace(alpha=1, beta="x")
+    ...     write_command_txt(args, {"gamma": 3})
+    ...     txt = open("command.txt", "r", encoding="utf-8").read()
+    ...     ok = all(x in txt for x in ["command:", "cli_args:", "resolved:", "alpha: 1", "beta: x", "gamma: 3"])
+    ...     os.chdir(old_cwd)
+    ...     sys.argv = old_argv
+    ...     ok
+    True
+    """
+    import os
+    import shlex
+    import sys
+    from datetime import datetime, timezone
+
+    cmd = " ".join(shlex.quote(x) for x in sys.argv)
+
+    p = os.path.join("./", "command.txt")
+    with open(p, "w") as f:
+        f.write(f"timestamp_utc: {datetime.now(timezone.utc).isoformat()}\n")
+        f.write(f"cwd: {os.getcwd()}\n\n")
+        f.write("command:\n")
+        f.write(cmd + "\n\n")
+        f.write("cli_args:\n")
+        for k, v in sorted(vars(args).items()):
+            f.write(f"  {k}: {v}\n")
+        f.write("\nresolved:\n")
+        for k, v in sorted(resolved.items()):
+            f.write(f"  {k}: {v}\n")
+
+
+def handle_write_cmd(
+    bam_1, bam_2, output_fq1, output_fq2, output_bam1, output_bam2, args
+):
+    resolved = {
+        "BAM_R1_or_single": bam_1,
+        "BAM_R2": bam_2,
+        "output_Fastq_R1": output_fq1,
+        "output_Fastq_R2": output_fq2,
+        "output_bam1_or_single_unsplit": output_bam1,
+        "output_bam2_unsplit": output_bam2,
+        "single_bam": getattr(args, "single_bam", False),
+    }
+    write_command_txt(args=args, resolved=resolved)