split3c 0.0.1__py3-none-any.whl

split3c/resolve/parse.py

@@ -0,0 +1,1218 @@
+from collections import defaultdict
+from typing import Literal
+
+import pysam
+
+from .bam import (
+    chromsizes_from_header,
+    get_bam_header_single,
+    get_bam_headers,
+    iter_bam_pairs,
+    iter_bam_pairs_single,
+)
+from .io_utils import open_text_output
+from .pairs import make_pairs_header, write_pairs_header
+
+# Minimal mutable alignment layout:
+# [chrom, pos5, pos3, strand, mapq, anchor_tag, origin, merged_count, sam]
+CHROM = 0
+POS5 = 1
+POS3 = 2
+STRAND = 3
+MAPQ = 4
+ANCHOR = 5
+ORIGIN = 6
+MERGED = 7
+SAM = 8
+
+REF_CONSUMING_OPS = {0, 2, 3, 7, 8}  # M, D, N, =, X
+
+
+def parse_qname_any(qname: str) -> tuple[str, str, str, int, int]:
+    """
+    Supports:
+      - enriched: base:[F1,R2:FT3,RT2]
+      - classic : base           -> treated as FT1/RT1 with tags F1,R1
+
+    >>> parse_qname_any("READ")
+    ('READ', 'F1', 'R1', 1, 1)
+    >>> parse_qname_any("readA:[F1,R2:FT3,RT2]")
+    ('readA', 'F1', 'R2', 3, 2)
+    >>> parse_qname_any("READ:SP")
+    ('READ', 'F1', 'R1', 1, 1)
+    >>> parse_qname_any("READ:SP_4")
+    ('READ', 'F1', 'R1', 1, 1)
+    """
+    # fast path for classic
+    if ":[" not in qname:
+        if ":SP" in qname:
+            qname = qname.split(":SP", 1)[0]
+        return qname, "F1", "R1", 1, 1
+
+    # enriched path (your current logic, but without try/except in the normal case)
+    try:
+        base_name, rest = qname.rsplit(":[", 1)
+        rest = rest[:-1]  # drop trailing ']'
+        tags_part, counts_part = rest.split(":FT", 1)
+        tag1, tag2 = tags_part.split(",", 1)
+        ft_str, rt_str = counts_part.split(",RT", 1)
+        return base_name, tag1, tag2, int(ft_str), int(rt_str)
+    except Exception as exc:
+        raise ValueError(f"Invalid qname format: {qname!r}") from exc
+
+
+def parse_qname(qname: str) -> tuple[str, str, str, int, int]:
+    """
+    Parse a microsplit qname without regex.
+
+    Expected format:
+        <base_name>:[<tag1>,<tag2>:FT<ft>,RT<rt>]
+
+    Examples
+    --------
+    >>> parse_qname("readA:[F1,R2:FT3,RT2]")
+    ('readA', 'F1', 'R2', 3, 2)
+
+    >>> parse_qname("bad_qname")
+    Traceback (most recent call last):
+    ...
+    ValueError: Invalid microsplit qname: 'bad_qname'
+    """
+    try:
+        base_name, rest = qname.rsplit(":[", 1)
+        rest = rest[:-1]
+        tags_part, counts_part = rest.split(":FT", 1)
+        tag1, tag2 = tags_part.split(",", 1)
+        ft_str, rt_str = counts_part.split(",RT", 1)
+        return base_name, tag1, tag2, int(ft_str), int(rt_str)
+    except Exception as exc:
+        raise ValueError(f"Invalid microsplit qname: {qname!r}") from exc
+
+
+def cigar_ref_span(read: pysam.AlignedSegment) -> int:
+    """
+    Return the reference span consumed by the CIGAR.
+
+    Examples
+    --------
+    >>> class FakeRead:
+    ...     cigartuples = [(0, 10), (1, 3), (2, 2), (7, 5), (8, 1)]
+    >>> cigar_ref_span(FakeRead())
+    18
+    """
+    span = 0
+    for op, length in read.cigartuples or []:
+        if op in REF_CONSUMING_OPS:
+            span += length
+    return span
+
+
+def read_to_minimal_alignment(
+    read: pysam.AlignedSegment,
+    tag: str,
+    sam_output: bool = False,
+) -> list | None:
+    """
+    Convert one read into a minimal mutable alignment list.
+
+    Returns None for unmapped reads.
+
+    Notes
+    -----
+    The last field stores the raw SAM line only when `sam_output=True`.
+
+    Examples
+    --------
+    >>> class FakeRead:
+    ...     is_unmapped = False
+    ...     reference_name = "chr1"
+    ...     mapping_quality = 42
+    ...     cigartuples = [(0, 10)]
+    ...     is_reverse = False
+    ...     reference_start = 99
+    ...     def to_string(self):
+    ...         return "read1\\t0\\tchr1\\t100\\t42\\t10M\\t*\\t0\\t0\\tACGT\\tFFFF"
+    >>> read_to_minimal_alignment(FakeRead(), "F1", sam_output=False)
+    ['chr1', 100, 109, '+', 42, 'F1', 'F', 1, None]
+    >>> read_to_minimal_alignment(FakeRead(), "F1", sam_output=True)[-1].startswith("read1\\t0\\tchr1")
+    True
+    """
+    if read.is_unmapped or read.reference_name is None:
+        return None
+
+    strand = "-" if read.is_reverse else "+"
+    ref_start_1based = read.reference_start + 1
+    ref_span = cigar_ref_span(read)
+
+    if strand == "+":
+        pos5 = ref_start_1based
+        pos3 = ref_start_1based + ref_span - 1
+    else:
+        pos5 = ref_start_1based + ref_span - 1
+        pos3 = ref_start_1based
+
+    sam_line = read.to_string() if sam_output else None
+
+    return [
+        read.reference_name,
+        pos5,
+        pos3,
+        strand,
+        int(read.mapping_quality),
+        tag,
+        tag[0],
+        1,
+        sam_line,
+    ]
+
+
+def observed_tags_in_block(
+    block: list[
+        tuple[
+            tuple[str, str, str, int, int],
+            pysam.AlignedSegment,
+            pysam.AlignedSegment,
+        ]
+    ],
+) -> set[str]:
+    """
+    Return the set of fragment tags observed in one block.
+
+    Examples
+    --------
+    >>> block = [
+    ...     (("readA", "F1", "R1", 2, 1), None, None),
+    ...     (("readA", "F2", "R1", 2, 1), None, None),
+    ... ]
+    >>> observed_tags_in_block(block) == {"F1", "F2", "R1"}
+    True
+    """
+    seen: set[str] = set()
+    for info, _, _ in block:
+        _, tag1, tag2, _, _ = info
+        seen.add(tag1)
+        seen.add(tag2)
+    return seen
+
+
+def tag_index(tag: str) -> int:
+    """
+    Return the numeric part of a tag.
+
+    Examples
+    --------
+    >>> tag_index("F1")
+    1
+    >>> tag_index("R12")
+    12
+    """
+    return int(tag[1:])
+
+
+def valid_slot(slot: list | None, min_mapq: int) -> bool:
+    """
+    Return True for mapped slots with enough MAPQ.
+
+    Examples
+    --------
+    >>> valid_slot(['chr1', 10, 20, '+', 5, 'F1', 'F', 1, None], 10)
+    False
+    >>> valid_slot(['chr1', 10, 20, '+', 20, 'F1', 'F', 1, None], 10)
+    True
+    >>> valid_slot(None, 10)
+    False
+    """
+    return slot is not None and slot[MAPQ] >= min_mapq
+
+
+def slot_len(slot: list) -> int:
+    """
+    Return genomic span length of one slot.
+
+    Examples
+    --------
+    >>> slot_len(['chr1', 100, 109, '+', 30, 'F1', 'F', 1, None])
+    10
+    >>> slot_len(['chr1', 219, 200, '-', 30, 'R1', 'R', 1, None])
+    20
+    """
+    return abs(slot[POS3] - slot[POS5]) + 1
+
+
+def adjacent_gap(a: list | None, b: list | None) -> int | None:
+    """
+    Compute the oriented genomic gap between two adjacent same-origin slots.
+
+    For '+' strand:
+        gap = b.pos5 - a.pos3 - 1
+    For '-' strand:
+        gap = a.pos3 - b.pos5 - 1
+
+    Returns None when comparison is not meaningful.
+
+    Examples
+    --------
+    >>> a = ['chr1', 100, 120, '+', 30, 'F1', 'F', 1, None]
+    >>> b = ['chr1', 126, 140, '+', 30, 'F2', 'F', 1, None]
+    >>> adjacent_gap(a, b)
+    5
+    """
+    if a is None or b is None:
+        return None
+    if a[CHROM] != b[CHROM]:
+        return None
+    if a[STRAND] != b[STRAND]:
+        return None
+
+    if a[STRAND] == "+":
+        return b[POS5] - a[POS3] - 1
+    return a[POS3] - b[POS5] - 1
+
+
+def merge_two_same_origin(a: list, b: list) -> list:
+    """
+    Merge b into a and keep one single node.
+
+    Rules
+    -----
+    - keep earliest anchor tag
+    - extend geometry
+    - keep max MAPQ
+    - merged_count is summed
+    - keep SAM from the surviving anchor tag
+
+    Examples
+    --------
+    >>> a = ['chr1', 100, 120, '+', 20, 'F1', 'F', 1, 'SAM_F1']
+    >>> b = ['chr1', 126, 140, '+', 30, 'F2', 'F', 1, 'SAM_F2']
+    >>> merge_two_same_origin(a, b)
+    ['chr1', 100, 140, '+', 30, 'F1', 'F', 2, 'SAM_F1']
+    """
+    if a[STRAND] == "+":
+        pos5 = min(a[POS5], b[POS5])
+        pos3 = max(a[POS3], b[POS3])
+    else:
+        pos5 = max(a[POS5], b[POS5])
+        pos3 = min(a[POS3], b[POS3])
+
+    keep_a_anchor = tag_index(a[ANCHOR]) <= tag_index(b[ANCHOR])
+    anchor = a[ANCHOR] if keep_a_anchor else b[ANCHOR]
+    sam_line = a[SAM] if keep_a_anchor else b[SAM]
+
+    return [
+        a[CHROM],
+        pos5,
+        pos3,
+        a[STRAND],
+        max(a[MAPQ], b[MAPQ]),
+        anchor,
+        a[ORIGIN],
+        a[MERGED] + b[MERGED],
+        sam_line,
+    ]
+
+
+def collapse_adjacent_in_place(
+    slots: list[list | None], max_gap: int, min_mapq: int
+) -> int:
+    """
+    Collapse adjacent alive slots in place while gap is compatible.
+
+    Returns the number of merges.
+
+    Examples
+    --------
+    >>> slots = [
+    ...     ['chr1', 1, 10, '+', 20, 'F1', 'F', 1, None],
+    ...     ['chr1', 12, 21, '+', 20, 'F2', 'F', 1, None],
+    ... ]
+    >>> collapse_adjacent_in_place(slots, 5, 1)
+    1
+    >>> slots[0]
+    ['chr1', 1, 21, '+', 20, 'F1', 'F', 2, None]
+    >>> slots[1] is None
+    True
+    """
+    n = len(slots)
+    merges = 0
+
+    while True:
+        changed = False
+        i = 0
+        while i < n:
+            if not valid_slot(slots[i], min_mapq):
+                i += 1
+                continue
+
+            j = i + 1
+            while j < n and not valid_slot(slots[j], min_mapq):
+                j += 1
+            if j >= n:
+                break
+
+            gap = adjacent_gap(slots[i], slots[j])
+            if gap is not None and 0 <= gap <= max_gap:
+                slots[i] = merge_two_same_origin(slots[i], slots[j])
+                slots[j] = None
+                merges += 1
+                changed = True
+            else:
+                i = j
+
+        if not changed:
+            break
+
+    return merges
+
+
+def terminal_gap_center(f_slot: list | None, r_slot: list | None) -> int | None:
+    """
+    Compute central gap between terminal forward and reverse slots.
+
+    Examples
+    --------
+    >>> f = ['chr1', 100, 150, '+', 20, 'F2', 'F', 1, None]
+    >>> r = ['chr1', 200, 160, '-', 20, 'R1', 'R', 1, None]
+    >>> terminal_gap_center(f, r)
+    9
+    """
+    if f_slot is None or r_slot is None:
+        return None
+    if f_slot[CHROM] != r_slot[CHROM]:
+        return None
+    if f_slot[STRAND] == "+" and r_slot[STRAND] == "-":
+        return r_slot[POS3] - f_slot[POS3] - 1
+    if f_slot[STRAND] == "-" and r_slot[STRAND] == "+":
+        return f_slot[POS3] - r_slot[POS3] - 1
+    return None
+
+
+def last_alive_index(slots: list[list | None], min_mapq: int) -> int | None:
+    """
+    Return the index of the last alive slot.
+
+    Examples
+    --------
+    >>> last_alive_index([None, ['chr1', 1, 10, '+', 20, 'F2', 'F', 1, None]], 1)
+    1
+    """
+    for i in range(len(slots) - 1, -1, -1):
+        if valid_slot(slots[i], min_mapq):
+            return i
+    return None
+
+
+def collapse_terminal_fr_in_place(
+    forward: list[list | None],
+    reverse: list[list | None],
+    max_center_gap: int,
+    overlap_tolerance: int,
+    min_mapq: int,
+) -> tuple[bool, int | None]:
+    """
+    Collapse the terminal F/R pair in place if compatible.
+
+    Policy
+    ------
+    Keep the slot with the higher MAPQ.
+    On tie, keep forward.
+
+    Returns
+    -------
+    (collapsed, gap)
+
+    Examples
+    --------
+    >>> F = [['chr1', 100, 119, '+', 30, 'F1', 'F', 1, 'SAM_F1']]
+    >>> R = [['chr1', 140, 125, '-', 20, 'R1', 'R', 1, 'SAM_R1']]
+    >>> collapse_terminal_fr_in_place(F, R, 10, 0, 1)
+    (True, 5)
+    >>> F[0] is not None, R[0] is None
+    (True, True)
+    """
+    fi = last_alive_index(forward, min_mapq)
+    ri = last_alive_index(reverse, min_mapq)
+    if fi is None or ri is None:
+        return False, None
+
+    f_slot = forward[fi]
+    r_slot = reverse[ri]
+    gap = terminal_gap_center(f_slot, r_slot)
+    if gap is None:
+        return False, None
+    if not (-overlap_tolerance <= gap <= max_center_gap):
+        return False, gap
+
+    if f_slot[MAPQ] >= r_slot[MAPQ]:
+        reverse[ri] = None
+    else:
+        forward[fi] = None
+
+    return True, gap
+
+
+def alive_slots(slots: list[list | None], min_mapq: int) -> list[list]:
+    """
+    Return alive slots only.
+
+    Examples
+    --------
+    >>> alive_slots([None, ['chr1', 1, 10, '+', 20, 'F2', 'F', 1, None]], 1)
+    [['chr1', 1, 10, '+', 20, 'F2', 'F', 1, None]]
+    """
+    return [slot for slot in slots if valid_slot(slot, min_mapq)]
+
+
+def multiplicity_status(initial_count: int, final_count: int) -> str:
+    """
+    Compute final molecule status.
+
+    Examples
+    --------
+    >>> multiplicity_status(4, 3)
+    'true_multiplex'
+    >>> multiplicity_status(4, 2)
+    'resolved_from_multiplex'
+    """
+    if initial_count > 2 and final_count > 2:
+        return "true_multiplex"
+    if initial_count > 2 and final_count == 2:
+        return "resolved_from_multiplex"
+    if initial_count > 2 and final_count < 2:
+        return "dropped_from_multiplex"
+    if initial_count == 2 and final_count == 2:
+        return "simple"
+    return "dropped"
+
+
+def build_pairs_columns(
+    sam_output: bool = False,
+    qual_stats: bool = False,
+    filter_stats: bool = False,
+) -> list[str]:
+    """
+    Build dynamic output columns.
+
+    Examples
+    --------
+    >>> build_pairs_columns()
+    ['readID', 'chrom1', 'pos1', 'chrom2', 'pos2', 'strand1', 'strand2', 'pair_type', 'tag1', 'tag2', 'ft', 'rt', 'status']
+    >>> build_pairs_columns(sam_output=True)
+    ['readID', 'chrom1', 'pos1', 'chrom2', 'pos2', 'strand1', 'strand2', 'pair_type', 'tag1', 'tag2', 'ft', 'rt', 'status', 'sam1', 'sam2']
+    >>> build_pairs_columns(sam_output=True, qual_stats=True, filter_stats=True)
+    ['readID', 'chrom1', 'pos1', 'chrom2', 'pos2', 'strand1', 'strand2', 'pair_type', 'tag1', 'tag2', 'ft', 'rt', 'status', 'sam1', 'sam2', 'len1', 'len2', 'mapq1', 'mapq2', 'hard_merged', 'terminal_aliased']
+    """
+    cols = [
+        "readID",
+        "chrom1",
+        "pos1",
+        "chrom2",
+        "pos2",
+        "strand1",
+        "strand2",
+        "pair_type",
+        "tag1",
+        "tag2",
+        "ft",
+        "rt",
+        "status",
+    ]
+    if sam_output:
+        cols.extend(["sam1", "sam2"])
+    if qual_stats:
+        cols.extend(["len1", "len2", "mapq1", "mapq2"])
+    if filter_stats:
+        cols.extend(["hard_merged", "terminal_aliased"])
+    return cols
+
+
+def serialize_pair_line(
+    read_id: str,
+    a: list,
+    b: list,
+    ft: int,
+    rt: int,
+    status: str,
+    sam_output: bool = False,
+    qual_stats: bool = False,
+    filter_stats: bool = False,
+    terminal_aliased: bool = False,
+) -> str:
+    """
+    Serialize one pair line directly.
+
+    Examples
+    --------
+    >>> a = ['chr1', 10, 20, '+', 30, 'F1', 'F', 2, 'SAM_A']
+    >>> b = ['chr2', 40, 30, '-', 25, 'R1', 'R', 1, 'SAM_B']
+    >>> serialize_pair_line("read1", a, b, 2, 1, "resolved_from_multiplex")
+    'read1\\tchr1\\t10\\tchr2\\t40\\t+\\t-\\tUU\\tF1\\tR1\\t2\\t1\\tresolved_from_multiplex'
+    >>> serialize_pair_line("read1", a, b, 2, 1, "resolved_from_multiplex", sam_output=True)
+    'read1\\tchr1\\t10\\tchr2\\t40\\t+\\t-\\tUU\\tF1\\tR1\\t2\\t1\\tresolved_from_multiplex\\tSAM_A\\tSAM_B'
+    """
+    fields = [
+        read_id,
+        a[CHROM],
+        str(a[POS5]),
+        b[CHROM],
+        str(b[POS5]),
+        a[STRAND],
+        b[STRAND],
+        "UU",
+        a[ANCHOR],
+        b[ANCHOR],
+        str(ft),
+        str(rt),
+        status,
+    ]
+
+    if sam_output:
+        fields.extend(
+            [
+                a[SAM] if a[SAM] is not None else ".",
+                b[SAM] if b[SAM] is not None else ".",
+            ]
+        )
+
+    if qual_stats:
+        fields.extend(
+            [
+                str(slot_len(a)),
+                str(slot_len(b)),
+                str(a[MAPQ]),
+                str(b[MAPQ]),
+            ]
+        )
+
+    if filter_stats:
+        hard_merged = 1 if (a[MERGED] > 1 or b[MERGED] > 1) else 0
+        fields.extend(
+            [
+                str(hard_merged),
+                "1" if terminal_aliased else "0",
+            ]
+        )
+
+    return "\t".join(fields)
+
+
+def build_pair_lines(
+    base_name: str,
+    forward: list[list | None],
+    reverse: list[list | None],
+    ft: int,
+    rt: int,
+    min_mapq: int,
+    status: str,
+    chrom_order: dict[str, int],
+    flip: bool,
+    sam_output: bool = False,
+    qual_stats: bool = False,
+    filter_stats: bool = False,
+    terminal_aliased: bool = False,
+) -> list[str]:
+    """
+    Build all final pair lines from alive nodes.
+
+    Examples
+    --------
+    >>> F = [['chr1', 1, 10, '+', 20, 'F1', 'F', 1, 'SAM_F1']]
+    >>> R = [['chr2', 50, 41, '-', 20, 'R1', 'R', 1, 'SAM_R1']]
+    >>> lines = build_pair_lines("q", F, R, 1, 1, 1, "simple", {"chr1": 0, "chr2": 1}, True, sam_output=True)
+    >>> len(lines)
+    1
+    >>> lines[0].startswith('q\\tchr1\\t1\\tchr2\\t50')
+    True
+    >>> '\\tSAM_F1\\tSAM_R1' in lines[0]
+    True
+    """
+    nodes = alive_slots(forward, min_mapq) + alive_slots(reverse, min_mapq)
+    n = len(nodes)
+    lines: list[str] = []
+
+    for i in range(n):
+        a = nodes[i]
+        for j in range(i + 1, n):
+            b = nodes[j]
+
+            if flip:
+                key_a = (chrom_order.get(a[CHROM], 10**9), a[POS5])
+                key_b = (chrom_order.get(b[CHROM], 10**9), b[POS5])
+                if key_a <= key_b:
+                    lines.append(
+                        serialize_pair_line(
+                            base_name,
+                            a,
+                            b,
+                            ft,
+                            rt,
+                            status,
+                            sam_output=sam_output,
+                            qual_stats=qual_stats,
+                            filter_stats=filter_stats,
+                            terminal_aliased=terminal_aliased,
+                        )
+                    )
+                else:
+                    lines.append(
+                        serialize_pair_line(
+                            base_name,
+                            b,
+                            a,
+                            ft,
+                            rt,
+                            status,
+                            sam_output=sam_output,
+                            qual_stats=qual_stats,
+                            filter_stats=filter_stats,
+                            terminal_aliased=terminal_aliased,
+                        )
+                    )
+            else:
+                lines.append(
+                    serialize_pair_line(
+                        base_name,
+                        a,
+                        b,
+                        ft,
+                        rt,
+                        status,
+                        sam_output=sam_output,
+                        qual_stats=qual_stats,
+                        filter_stats=filter_stats,
+                        terminal_aliased=terminal_aliased,
+                    )
+                )
+
+    return lines
+
+
+def parse_block_to_lines(
+    block: list[
+        tuple[
+            tuple[str, str, str, int, int], pysam.AlignedSegment, pysam.AlignedSegment
+        ]
+    ],
+    min_mapq: int,
+    adjacent_gap_max: int,
+    terminal_center_gap_max: int,
+    terminal_overlap_tolerance: int,
+    chrom_order: dict[str, int],
+    flip: bool = True,
+    sam_output: bool = False,
+    qual_stats: bool = False,
+    filter_stats: bool = False,
+    strict_complete_cover: bool = False,
+) -> tuple[list[str], str, dict]:
+    """
+    Parse one molecule block and return serialized pair lines.
+
+    Notes
+    -----
+    This works both from:
+    - all-pairs BAM inputs
+    - cover-pairs BAM inputs
+
+    because tags are first reconstructed into per-fragment slots, then all
+    final alive combinations are emitted.
+
+    >>> class FakeRead:
+    ...     def __init__(self, qname, chrom, start0, span, mapq, is_rev):
+    ...         self.query_name = qname
+    ...         self.is_unmapped = False
+    ...         self.reference_name = chrom
+    ...         self.reference_start = start0
+    ...         self.mapping_quality = mapq
+    ...         self.is_reverse = is_rev
+    ...         self.cigartuples = [(0, span)]
+    ...     def to_string(self):
+    ...         return f"{self.query_name}\\t0\\t{self.reference_name}\\t{self.reference_start+1}\\t{self.mapping_quality}\\t{self.cigartuples[0][1]}M\\t*\\t0\\t0\\tACGT\\tFFFF"
+    ...
+    >>> rF = FakeRead("q", "chr1", 99, 20, 30, False)   # pos5=100 pos3=119
+    >>> rR = FakeRead("q", "chr1", 124, 15, 20, True)   # pos3=125 => gap center = 125-119-1 = 5
+    >>> block = [(("q","F1","R1",1,1), rF, rR)]
+    >>> lines, status, core = parse_block_to_lines(block, min_mapq=1, adjacent_gap_max=5, terminal_center_gap_max=10, terminal_overlap_tolerance=0, chrom_order={"chr1":0})
+    >>> status
+    'simple'
+    >>> core["terminal_aliased"]
+    False
+    >>> len(lines)
+    1
+    >>> rF1 = FakeRead("q", "chr1", 99, 10, 30, False)   # 100-109
+    >>> rF2 = FakeRead("q", "chr1", 111, 10, 30, False)  # 112-121 gap = 112-109-1=2
+    >>> rR1 = FakeRead("q", "chr2", 199, 10, 30, True)
+    >>> block = [
+    ...   (("q","F1","R1",2,1), rF1, rR1),
+    ...   (("q","F2","R1",2,1), rF2, rR1),
+    ... ]
+    >>> lines, status, core = parse_block_to_lines(block, min_mapq=1, adjacent_gap_max=5, terminal_center_gap_max=300, terminal_overlap_tolerance=1, chrom_order={"chr1":0,"chr2":1})
+    >>> status
+    'resolved_from_multiplex'
+    >>> core["n_forward_merges"] >= 1
+    True
+    >>> len(lines) >= 1
+    True
+    """
+    if not block:
+        return (
+            [],
+            "empty",
+            {
+                "base_name": None,
+                "ft": 0,
+                "rt": 0,
+                "initial_count": 0,
+                "observed_tag_count": 0,
+                "valid_tag_count": 0,
+                "final_count": 0,
+                "n_forward_merges": 0,
+                "n_reverse_merges": 0,
+                "terminal_aliased": False,
+                "terminal_gap": None,
+                "input_mode": "unknown",
+                "complete_cover": False,
+            },
+        )
+
+    base_name, _, _, ft, rt = block[0][0]
+    initial_count = ft + rt
+
+    observed_tags = observed_tags_in_block(block)
+    observed_tag_count = len(observed_tags)
+    complete_cover = observed_tag_count == initial_count
+
+    if strict_complete_cover and not complete_cover:
+        return (
+            [],
+            "incomplete_cover",
+            {
+                "base_name": base_name,
+                "ft": ft,
+                "rt": rt,
+                "initial_count": initial_count,
+                "observed_tag_count": observed_tag_count,
+                "valid_tag_count": 0,
+                "final_count": 0,
+                "n_forward_merges": 0,
+                "n_reverse_merges": 0,
+                "terminal_aliased": False,
+                "terminal_gap": None,
+                "input_mode": "cover_or_partial",
+                "complete_cover": False,
+            },
+        )
+
+    forward: list[list | None] = [None] * ft
+    reverse: list[list | None] = [None] * rt
+
+    for info, read1, read2 in block:
+        _, tag1, tag2, _, _ = info
+
+        idx1 = tag_index(tag1) - 1
+        idx2 = tag_index(tag2) - 1
+
+        if tag1[0] == "F":
+            if forward[idx1] is None:
+                forward[idx1] = read_to_minimal_alignment(
+                    read1, tag1, sam_output=sam_output
+                )
+        else:
+            if reverse[idx1] is None:
+                reverse[idx1] = read_to_minimal_alignment(
+                    read1, tag1, sam_output=sam_output
+                )
+
+        if tag2[0] == "F":
+            if forward[idx2] is None:
+                forward[idx2] = read_to_minimal_alignment(
+                    read2, tag2, sam_output=sam_output
+                )
+        else:
+            if reverse[idx2] is None:
+                reverse[idx2] = read_to_minimal_alignment(
+                    read2, tag2, sam_output=sam_output
+                )
+
+    valid_tag_count = sum(1 for slot in forward if valid_slot(slot, min_mapq)) + sum(
+        1 for slot in reverse if valid_slot(slot, min_mapq)
+    )
+
+    do_multiplex_ops = initial_count > 2  # initial_count = ft + rt
+
+    if do_multiplex_ops:
+        n_forward_merges = collapse_adjacent_in_place(
+            forward, adjacent_gap_max, min_mapq
+        )
+        n_reverse_merges = collapse_adjacent_in_place(
+            reverse, adjacent_gap_max, min_mapq
+        )
+        terminal_aliased, terminal_gap = collapse_terminal_fr_in_place(
+            forward,
+            reverse,
+            terminal_center_gap_max,
+            terminal_overlap_tolerance,
+            min_mapq,
+        )
+    else:
+        n_forward_merges = 0
+        n_reverse_merges = 0
+        terminal_aliased = False
+        terminal_gap = None
+
+    final_nodes = alive_slots(forward, min_mapq) + alive_slots(reverse, min_mapq)
+    final_count = len(final_nodes)
+    status = multiplicity_status(initial_count, final_count)
+
+    if final_count < 2:
+        return (
+            [],
+            status,
+            {
+                "base_name": base_name,
+                "ft": ft,
+                "rt": rt,
+                "initial_count": initial_count,
+                "observed_tag_count": observed_tag_count,
+                "valid_tag_count": valid_tag_count,
+                "final_count": final_count,
+                "n_forward_merges": n_forward_merges,
+                "n_reverse_merges": n_reverse_merges,
+                "terminal_aliased": terminal_aliased,
+                "terminal_gap": terminal_gap,
+                "input_mode": (
+                    "all_or_complete_cover" if complete_cover else "cover_or_partial"
+                ),
+                "complete_cover": complete_cover,
+            },
+        )
+
+    lines = build_pair_lines(
+        base_name=base_name,
+        forward=forward,
+        reverse=reverse,
+        ft=ft,
+        rt=rt,
+        min_mapq=min_mapq,
+        status=status,
+        chrom_order=chrom_order,
+        flip=flip,
+        sam_output=sam_output,
+        qual_stats=qual_stats,
+        filter_stats=filter_stats,
+        terminal_aliased=terminal_aliased,
+    )
+
+    return (
+        lines,
+        status,
+        {
+            "base_name": base_name,
+            "ft": ft,
+            "rt": rt,
+            "initial_count": initial_count,
+            "observed_tag_count": observed_tag_count,
+            "valid_tag_count": valid_tag_count,
+            "final_count": final_count,
+            "n_forward_merges": n_forward_merges,
+            "n_reverse_merges": n_reverse_merges,
+            "terminal_aliased": terminal_aliased,
+            "terminal_gap": terminal_gap,
+            "input_mode": (
+                "all_or_complete_cover" if complete_cover else "cover_or_partial"
+            ),
+            "complete_cover": complete_cover,
+        },
+    )
+
+
+def _simple_pair_to_line(
+    read1: pysam.AlignedSegment,
+    read2: pysam.AlignedSegment,
+    *,
+    min_mapq: int,
+    chrom_order: dict[str, int],
+    flip: bool,
+    sam_output: bool,
+    qual_stats: bool,
+    filter_stats: bool,
+) -> str | None:
+    """
+    >>> class FakeRead:
+    ...     def __init__(self, qname, chrom, start0, span, mapq, is_rev):
+    ...         self.query_name = qname
+    ...         self.is_unmapped = False
+    ...         self.reference_name = chrom
+    ...         self.reference_start = start0
+    ...         self.mapping_quality = mapq
+    ...         self.is_reverse = is_rev
+    ...         self.cigartuples = [(0, span)]
+    ...     def to_string(self):
+    ...         return "x"
+    >>> r1 = FakeRead("q", "chr2", 10, 10, 30, False)
+    >>> r2 = FakeRead("q", "chr1", 10, 10, 30, False)
+    >>> line = _simple_pair_to_line(r1, r2, min_mapq=1, chrom_order={"chr1":0,"chr2":1}, flip=True, sam_output=False, qual_stats=False, filter_stats=False)
+    >>> line.split("\\t")[1]  # chrom1 après flip
+    'chr1'
+    """
+    a = read_to_minimal_alignment(read1, "F1", sam_output=sam_output)
+    b = read_to_minimal_alignment(read2, "R1", sam_output=sam_output)
+    if not valid_slot(a, min_mapq) or not valid_slot(b, min_mapq):
+        return None
+
+    # pas de merges, pas de terminal collapse, status simple
+    if flip:
+        key_a = (chrom_order.get(a[CHROM], 10**9), a[POS5])
+        key_b = (chrom_order.get(b[CHROM], 10**9), b[POS5])
+        if key_a > key_b:
+            a, b = b, a
+
+    return serialize_pair_line(
+        read_id=read1.query_name,  # ou base_name si tu préfères
+        a=a,
+        b=b,
+        ft=1,
+        rt=1,
+        status="simple",
+        sam_output=sam_output,
+        qual_stats=qual_stats,
+        filter_stats=filter_stats,
+        terminal_aliased=False,
+    )
+
+
+def parse_to_pairs(
+    bam_for_path: str,
+    bam_rev_path: str | None = None,
+    mode: Literal["simple", "split"] = "split",
+    out_pairs: str | None = None,
+    out_duplex: str | None = None,
+    out_true_multiplex_pairs: str | None = None,
+    min_mapq: int = 1,
+    adjacent_gap_max: int = 5,
+    terminal_center_gap_max: int = 300,
+    terminal_overlap_tolerance: int = 1,
+    assembly: str | None = None,
+    bam_threads: int = 1,
+    out_threads: int = 1,
+    flip: bool = True,
+    write_batch_size: int = 50000,
+    sam_output: bool = False,
+    qual_stats: bool = False,
+    filter_stats: bool = False,
+    strict_complete_cover: bool = False,
+    single_bam: bool = False,
+    version: str = "0.0.0",
+) -> dict[str, int]:
+    """
+    Parse remapped split BAM input into `.pairs` outputs.
+
+    Supports:
+    - two synchronized BAM files (`bam_for_path`, `bam_rev_path`)
+    - one interleaved BAM file (`single_bam=True`)
+
+    Notes
+    -----
+    - first-seen policy per tag
+    - no heavy stats
+    - direct line serialization
+    - buffered writes
+    """
+    if out_pairs is None and out_duplex is None and out_true_multiplex_pairs is None:
+        raise ValueError(
+            "Provide at least one output: out_pairs or out_duplex or out_true_multiplex_pairs"
+        )
+
+    if single_bam:
+        header_for_dict = get_bam_header_single(bam_for_path)
+    else:
+        if bam_rev_path is None:
+            raise ValueError("BAM Reverse File is required unless single_bam=True")
+        header_for_dict, _ = get_bam_headers(bam_for_path, bam_rev_path)
+
+    chromsizes = chromsizes_from_header(header_for_dict)
+    chrom_order = {chrom: i for i, (chrom, _) in enumerate(chromsizes)}
+
+    columns = build_pairs_columns(
+        sam_output=sam_output,
+        qual_stats=qual_stats,
+        filter_stats=filter_stats,
+    )
+
+    header_lines = make_pairs_header(
+        chromsizes=chromsizes,
+        columns=columns,
+        assembly=assembly,
+        shape="upper triangle" if flip else "whole matrix",
+        sorted_by="none",
+        program_id="splitparse",  # optionnel mais conseillé
+        program_version=version,
+    )
+
+    all_handle = open_text_output(out_pairs, nproc=out_threads) if out_pairs else None
+    resolved_handle = (
+        open_text_output(out_duplex, nproc=out_threads) if out_duplex else None
+    )
+    multiplex_handle = (
+        open_text_output(out_true_multiplex_pairs, nproc=out_threads)
+        if out_true_multiplex_pairs
+        else None
+    )
+
+    counts: dict[str, int] = defaultdict(int)
+    all_buffer: list[str] = []
+    resolved_buffer: list[str] = []
+    multiplex_buffer: list[str] = []
+
+    def flush_buffers() -> None:
+        if all_handle is not None and all_buffer:
+            all_handle.write("".join(all_buffer))
+            all_buffer.clear()
+        if resolved_handle is not None and resolved_buffer:
+            resolved_handle.write("".join(resolved_buffer))
+            resolved_buffer.clear()
+        if multiplex_handle is not None and multiplex_buffer:
+            multiplex_handle.write("".join(multiplex_buffer))
+            multiplex_buffer.clear()
+
+    try:
+        if all_handle is not None:
+            write_pairs_header(all_handle, header_lines)
+        if resolved_handle is not None:
+            write_pairs_header(resolved_handle, header_lines)
+        if multiplex_handle is not None:
+            write_pairs_header(multiplex_handle, header_lines)
+
+        current_base: str | None = None
+        current_block: list[
+            tuple[
+                tuple[str, str, str, int, int],
+                pysam.AlignedSegment,
+                pysam.AlignedSegment,
+            ]
+        ] = []
+
+        def flush_block() -> None:
+            nonlocal current_block
+            if not current_block:
+                return
+
+            lines, status, core = parse_block_to_lines(
+                block=current_block,
+                min_mapq=min_mapq,
+                adjacent_gap_max=adjacent_gap_max,
+                terminal_center_gap_max=terminal_center_gap_max,
+                terminal_overlap_tolerance=terminal_overlap_tolerance,
+                chrom_order=chrom_order,
+                flip=flip,
+                sam_output=sam_output,
+                qual_stats=qual_stats,
+                filter_stats=filter_stats,
+                strict_complete_cover=strict_complete_cover,
+            )
+
+            counts["molecules"] += 1
+            counts[f"status_{status}"] += 1
+            counts["pairs_total"] += len(lines)
+
+            if core["complete_cover"]:
+                counts["complete_cover_blocks"] += 1
+            else:
+                counts["incomplete_cover_blocks"] += 1
+
+            counts["observed_tags_total"] += core["observed_tag_count"]
+            counts["valid_tags_total"] += core["valid_tag_count"]
+            counts["final_nodes_total"] += core["final_count"]
+
+            if all_handle is not None:
+                for line in lines:
+                    all_buffer.append(line + "\n")
+
+            if status == "resolved_from_multiplex" and resolved_handle is not None:
+                for line in lines:
+                    resolved_buffer.append(line + "\n")
+
+            if status == "true_multiplex" and multiplex_handle is not None:
+                for line in lines:
+                    multiplex_buffer.append(line + "\n")
+
+            if (
+                len(all_buffer) >= write_batch_size
+                or len(resolved_buffer) >= write_batch_size
+                or len(multiplex_buffer) >= write_batch_size
+            ):
+                flush_buffers()
+
+        pair_iter = (
+            iter_bam_pairs_single(
+                bam_for_path,
+                bam_threads=bam_threads,
+            )
+            if single_bam
+            else iter_bam_pairs(
+                bam_for_path,
+                bam_rev_path,
+                bam_threads=bam_threads,
+            )
+        )
+
+        if mode == "simple":
+            if out_pairs is None:
+                raise ValueError("--simple requires out_pairs")
+
+            # boucle simple: 1 paire -> 0/1 ligne
+            for read1, read2 in pair_iter:
+                if read2.query_name != read1.query_name:
+                    raise ValueError("Unsynchronized pair: query_name mismatch")
+
+                line = _simple_pair_to_line(
+                    read1,
+                    read2,
+                    min_mapq=min_mapq,
+                    chrom_order=chrom_order,
+                    flip=flip,
+                    sam_output=sam_output,
+                    qual_stats=qual_stats,
+                    filter_stats=filter_stats,
+                )
+                counts["pairs_seen"] += 1
+                if line is None:
+                    counts["pairs_dropped"] += 1
+                    continue
+
+                all_buffer.append(line + "\n")
+                counts["pairs_written"] += 1
+                if len(all_buffer) >= write_batch_size:
+                    flush_buffers()
+
+            flush_buffers()
+            return dict(counts)
+
+        else:
+            for read1, read2 in pair_iter:
+                if read2.query_name != read1.query_name:
+                    raise ValueError("Unsynchronized pair: query_name mismatch")
+
+                info = parse_qname_any(read1.query_name)
+                base_name = info[0]
+
+                if current_base is None:
+                    current_base = base_name
+                elif base_name != current_base:
+                    flush_block()
+                    current_block = []
+                    current_base = base_name
+
+                current_block.append((info, read1, read2))
+
+            flush_block()
+            flush_buffers()
+
+    finally:
+        if all_handle is not None:
+            all_handle.close()
+        if resolved_handle is not None:
+            resolved_handle.close()
+        if multiplex_handle is not None:
+            multiplex_handle.close()
+
+    return dict(counts)