From 08229524e0a69a918b2194d8969bf5774567a053 Mon Sep 17 00:00:00 2001 From: Benjamin Nemoz Date: Tue, 17 Nov 2026 16:26:01 +0000 Subject: [PATCH] fix(parser): strip only the TSO's G-run, not every leading G parse_barcodes did s[36:].lstrip("G"), which also removed genuine 5' Gs of the insert after the TSO's rGrGrG. Strip at most tso_g_max Gs (default 3). New run() options tso_g_max (CLI --tso_g_max) and legacy (CLI --legacy); legacy=True restores lstrip("G") exactly. Co-Authored-By: Claude Opus 5.5 --- pairplex/cli/pairplex.py | 15 ++++++ pairplex/pairplex.py | 21 +++++++- pairplex/tests/test_tso_g_strip.py | 87 ++++++++++++++++++++++++++++++ pairplex/utils.py | 26 ++++++++- 4 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 pairplex/tests/test_tso_g_strip.py diff --git a/pairplex/cli/pairplex.py b/pairplex/cli/pairplex.py index 8a39506..4eee0bf 100644 --- a/pairplex/cli/pairplex.py +++ b/pairplex/cli/pairplex.py @@ -98,6 +98,17 @@ def version(): default="human", help="Germline database for V(D)J assignment", ) +@click.option( + "--tso_g_max", + type=click.IntRange(min=0), + default=3, + help="Maximum number of Gs stripped after the TSO prefix (the TSO's rGrGrG run); genuine 5' Gs are kept", +) +@click.option( + "--legacy", + is_flag=True, + help="Reproduce v2-base behaviour exactly (overrides the options of newer fixes)", +) @click.option("--quiet", is_flag=True, help="Whether to suppress output") @click.option( "--debug", @@ -118,6 +129,8 @@ def run( merge_paired_reads: bool, receptor: str, germline_database: str, + tso_g_max: int, + legacy: bool, quiet: bool, debug: bool, ): @@ -135,6 +148,8 @@ def run( merge_paired_reads=merge_paired_reads, receptor=receptor, germline_database=germline_database, + tso_g_max=tso_g_max, + legacy=legacy, quiet=quiet, debug=debug, ) diff --git a/pairplex/pairplex.py b/pairplex/pairplex.py index 85c4ed5..9bdcf48 100644 --- a/pairplex/pairplex.py +++ b/pairplex/pairplex.py @@ -49,6 +49,8 @@ def run( merge_paired_reads: bool = False, receptor: str = "bcr", germline_database: str = "human", + tso_g_max: int = 3, + legacy: bool = False, quiet: bool = False, debug: bool = False, ) -> list: @@ -105,6 +107,15 @@ def run( The germline database to use. Options are anything accepted by `abstar.run`, including custom databases if available. + tso_g_max : int + Maximum number of Gs removed from the start of the insert, after the fixed TSO prefix + ``TTTCTTATAT`` (read positions 26-35). The 10x TSO ends in rGrGrG, so the default is ``3``; + genuine 5' Gs of the transcript beyond the TSO's run are kept. v2-base removed every leading + G (``lstrip("G")``). + + legacy : bool + If ``True``, reproduce v2-base exactly: forces ``tso_g_max`` to strip every leading G. + quiet : bool Whether to suppress the progress bar and other update messages. @@ -119,6 +130,10 @@ def run( """ parameters = dict(locals()) # captured first: exactly the arguments of this call + if legacy: + tso_g_max = None # v2-base: lstrip("G") + elif not isinstance(tso_g_max, int) or tso_g_max < 0: + raise ValueError(f"tso_g_max must be a non-negative integer, got {tso_g_max!r}") # print splash screen if not quiet: @@ -275,7 +290,11 @@ def run( parquet_chunks = [] futures = [ executor.submit( - parse_barcodes, chunk, temp_directory, whitelist_path=whitelist_path + parse_barcodes, + chunk, + temp_directory, + whitelist_path=whitelist_path, + tso_g_max=tso_g_max, ) for chunk in fastq_chunks ] diff --git a/pairplex/tests/test_tso_g_strip.py b/pairplex/tests/test_tso_g_strip.py new file mode 100644 index 0000000..9feb76f --- /dev/null +++ b/pairplex/tests/test_tso_g_strip.py @@ -0,0 +1,87 @@ +"""Only the TSO's rGrGrG run is stripped after the TSO prefix; genuine 5' Gs are kept.""" + +from unittest import mock + +import polars as pl +import pytest + +from pairplex import pairplex as pp +from pairplex.utils import DEFAULT_WHITELIST, parse_barcodes, strip_tso_g + +TSO = "TTTCTTATATGGG" +UMI = "ACGTACGTAC" + + +def _barcodes(n): + with open(DEFAULT_WHITELIST) as f: + return [next(f).strip() for _ in range(n)] + + +@pytest.mark.parametrize( + "insert, k, expected", + [ + ("GGGACT", 3, "ACT"), # TSO run only + ("GGGGACT", 3, "GACT"), # one genuine 5' G kept + ("GGGGGACT", 3, "GGACT"), + ("GGACT", 3, "ACT"), # shorter run (e.g. a miscalled G): strip what is there + ("ACT", 3, "ACT"), + ("GGGGACT", 4, "ACT"), + ("GGGGACT", 0, "GGGGACT"), + ("GGGGACT", None, "ACT"), # legacy lstrip("G") + ("GGGGG", 3, "GG"), + ("GG", 3, ""), + ("", 3, ""), + ], +) +def test_strip_tso_g(insert, k, expected): + assert strip_tso_g(insert, k) == expected + + +def _fastq(path, records): + with open(path, "w") as f: + for i, seq in enumerate(records): + f.write(f"@r{i}\n{seq}\n+\n{'I' * len(seq)}\n") + + +@pytest.mark.parametrize("k, expected", [(3, "GGACAGTC"), (None, "ACAGTC"), (4, "GACAGTC")]) +def test_parse_barcodes_keeps_genuine_g(tmp_path, k, expected): + bc = _barcodes(1)[0] + _fastq(tmp_path / "chunk.fastq", [bc + UMI + TSO + "GGACAGTC"]) + out = parse_barcodes(tmp_path / "chunk.fastq", tmp_path / "out", tso_g_max=k) + df = pl.read_parquet(out) + assert df["sequence"].to_list() == [expected] + assert df["barcode"].to_list() == [bc] + + +def test_parse_barcodes_default_is_three(): + import inspect + + assert inspect.signature(parse_barcodes).parameters["tso_g_max"].default == 3 + assert inspect.signature(pp.run).parameters["tso_g_max"].default == 3 + assert inspect.signature(pp.run).parameters["legacy"].default is False + + +def _run_parsed(tmp_path, monkeypatch, **kwargs): + monkeypatch.setenv("PAIRPLEX_MAX_WORKERS", "2") + reads = tmp_path / "well001.fastq" + _fastq(reads, [bc + UMI + TSO + "GACAGTCAGT" * 10 for bc in _barcodes(2) for _ in range(3)]) + out = tmp_path / "out" + with mock.patch.object(pp.abstar, "run", return_value=[]): + pp.run(str(reads), out, quiet=True, debug=True, **kwargs) + return pl.read_parquet(out / "parsed" / "well001.parquet")["sequence"].to_list() + + +def test_run_default_keeps_genuine_g(tmp_path, monkeypatch): + seqs = _run_parsed(tmp_path, monkeypatch) + assert seqs and all(s.startswith("GACAGT") for s in seqs) + + +def test_run_legacy_restores_lstrip(tmp_path, monkeypatch): + seqs = _run_parsed(tmp_path, monkeypatch, legacy=True, tso_g_max=5) + assert seqs and all(s.startswith("ACAGT") for s in seqs) + + +@pytest.mark.parametrize("bad", [-1, None, 2.5]) +def test_run_rejects_bad_tso_g_max(tmp_path, bad): + with pytest.raises(ValueError): + pp.run(str(tmp_path), tmp_path / "out", quiet=True, tso_g_max=bad) diff --git a/pairplex/utils.py b/pairplex/utils.py index 0c599a3..04eb729 100644 --- a/pairplex/utils.py +++ b/pairplex/utils.py @@ -187,11 +187,30 @@ def correct_barcode( return None # Explicitly return None if no single correction is found +TSO_G_MAX = 3 # the 10x 5' TSO ends in rGrGrG + + +def strip_tso_g(sequence: str, tso_g_max: int | None = TSO_G_MAX) -> str: + """ + Remove the TSO's G-run from the 5' end of ``sequence`` (the read after the fixed TSO prefix). + + At most ``tso_g_max`` leading Gs are removed, so genuine 5' Gs of the transcript are kept. + ``tso_g_max=None`` removes every leading G (``lstrip("G")``, the v2-base behaviour). + """ + if tso_g_max is None: + return sequence.lstrip("G") + n = 0 + while n < tso_g_max and n < len(sequence) and sequence[n] == "G": + n += 1 + return sequence[n:] + + def parse_barcodes( input_file: str | Path, output_directory: str | Path, whitelist_path: str | Path | None = None, check_rc: bool = True, + tso_g_max: int | None = TSO_G_MAX, ) -> str | None: """ Process a chunk of fastq file to extract barcodes, UMIs and TSO sequences. @@ -216,6 +235,11 @@ def parse_barcodes( check_rc : bool = True Whether to check the reverse complement of the sequences. + tso_g_max : int | None = 3 + Maximum number of Gs removed after the fixed TSO prefix (read positions 26-35, ``TTTCTTATAT``): + the TSO's own rGrGrG run. Genuine 5' Gs beyond it are kept. ``None`` removes every leading G + (``lstrip("G")``, the v2-base behaviour). + enforce_bc_whitelist : bool = True Whether to enforce the barcode whitelist. @@ -246,7 +270,7 @@ def parse_barcodes( # before the barcode will silently shift these offsets and corrupt extraction. # This is a known yield fragility that should be revisited (e.g. by locating the # TSO/barcode via pattern matching rather than assuming a fixed position). - sequence = s[36:].lstrip("G") # remove any remaining Gs from the TSO + sequence = strip_tso_g(s[36:], tso_g_max) # remove the TSO's G-run barcode = s[:16] umi = s[16:26] corrected = correct_barcode(barcode, whitelist)