Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions pairplex/cli/pairplex.py
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,17 @@ def version():
default=1,
help="Threads for MMseqs2 during annotation (always explicit; None made MMseqs2 use every node CPU and crash)",
)
@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",
Expand All @@ -125,6 +136,8 @@ def run(
receptor: str,
germline_database: str,
mmseqs_threads: int,
tso_g_max: int,
legacy: bool,
quiet: bool,
debug: bool,
):
Expand All @@ -143,6 +156,8 @@ def run(
receptor=receptor,
germline_database=germline_database,
mmseqs_threads=mmseqs_threads,
tso_g_max=tso_g_max,
legacy=legacy,
quiet=quiet,
debug=debug,
)
Expand Down
21 changes: 20 additions & 1 deletion pairplex/pairplex.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@ def run(
receptor: str = "bcr",
germline_database: str = "human",
mmseqs_threads: int = 1,
tso_g_max: int = 3,
legacy: bool = False,
quiet: bool = False,
debug: bool = False,
) -> list:
Expand Down Expand Up @@ -112,6 +114,15 @@ def run(
crashes when its thread count exceeds the size of an abstar sub-query batch. Annotation is not the
bottleneck of a run, so ``1`` costs little. Does not change results.

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.

Expand All @@ -128,6 +139,10 @@ def run(
parameters = dict(locals()) # captured first: exactly the arguments of this call
if not isinstance(mmseqs_threads, int) or mmseqs_threads < 1:
raise ValueError(f"mmseqs_threads must be a positive integer, got {mmseqs_threads!r}")
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:
Expand Down Expand Up @@ -284,7 +299,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
]
Expand Down
87 changes: 87 additions & 0 deletions pairplex/tests/test_tso_g_strip.py
Original file line number Diff line number Diff line change
@@ -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)
26 changes: 25 additions & 1 deletion pairplex/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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)
Expand Down
Loading