samplesheet-parser 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- samplesheet_parser/__init__.py +2 -0
- samplesheet_parser/chemistry.py +195 -63
- samplesheet_parser/validators.py +106 -54
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.4.0.dist-info}/METADATA +46 -26
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.4.0.dist-info}/RECORD +8 -8
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.4.0.dist-info}/WHEEL +0 -0
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.4.0.dist-info}/entry_points.txt +0 -0
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.4.0.dist-info}/licenses/LICENSE +0 -0
samplesheet_parser/__init__.py
CHANGED
|
@@ -35,6 +35,7 @@ __license__ = "Apache 2.0"
|
|
|
35
35
|
|
|
36
36
|
from samplesheet_parser.chemistry import (
|
|
37
37
|
Chemistry,
|
|
38
|
+
ColorBalanceMode,
|
|
38
39
|
ColorBalanceReport,
|
|
39
40
|
analyze_color_balance,
|
|
40
41
|
chemistry_for_instrument,
|
|
@@ -74,6 +75,7 @@ __all__ = [
|
|
|
74
75
|
"hamming_distance",
|
|
75
76
|
"index_collision_distance",
|
|
76
77
|
"Chemistry",
|
|
78
|
+
"ColorBalanceMode",
|
|
77
79
|
"ColorBalanceReport",
|
|
78
80
|
"analyze_color_balance",
|
|
79
81
|
"chemistry_for_instrument",
|
samplesheet_parser/chemistry.py
CHANGED
|
@@ -6,14 +6,17 @@ signal in one, two, or four optical channels per cycle. The number of
|
|
|
6
6
|
channels determines how a base is encoded as *signal*, and that in turn
|
|
7
7
|
determines what makes a pool of indexes safe to sequence together:
|
|
8
8
|
|
|
9
|
-
* **4-channel** (MiSeq, HiSeq 2000/2500/3000/4000
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
9
|
+
* **4-channel** (Illumina MiSeq, HiSeq 2000/2500/3000/4000) - four colours
|
|
10
|
+
imaged with two lasers: a green laser reads ``{G,T}`` and a red laser
|
|
11
|
+
reads ``{A,C}``. Every base produces signal, but each cycle still needs at
|
|
12
|
+
least one base from *each* laser group across the pool, or one laser is
|
|
13
|
+
dark and clusters cannot be registered.
|
|
14
|
+
|
|
15
|
+
* **avidity** (Element AVITI) - each base is labelled with its own avidite
|
|
16
|
+
dye (four images per cycle, no dark base; Arslan et al., *Nat. Biotechnol.*
|
|
17
|
+
2023). Unlike Illumina's two-laser SBS there is no laser-pair constraint,
|
|
18
|
+
so the platform tolerates low-diversity pools; low diversity is at most an
|
|
19
|
+
advisory, never a failure.
|
|
17
20
|
|
|
18
21
|
* **2-channel SBS** (NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq) - two
|
|
19
22
|
images (nominally "red" and "green") are captured and the base is
|
|
@@ -52,17 +55,49 @@ from samplesheet_parser.instruments import _normalize
|
|
|
52
55
|
# Default minimum fraction of the pool that must produce signal in each
|
|
53
56
|
# optical channel at every index cycle. Below this (but above zero) the
|
|
54
57
|
# cycle is flagged as weak; exactly zero is flagged as a dark/no-signal
|
|
55
|
-
# cycle. 0.10
|
|
56
|
-
#
|
|
58
|
+
# cycle. 0.10 is a heuristic (not a published vendor number); Illumina's
|
|
59
|
+
# stated rule is qualitative.
|
|
57
60
|
DEFAULT_MIN_SIGNAL_FRACTION = 0.10
|
|
58
61
|
|
|
62
|
+
# AVITI (avidity) advisory window: Element's metrics flag low base diversity in
|
|
63
|
+
# the first few cycles of an index/read for attention, but never as a failure.
|
|
64
|
+
# Ref: Element "ElemBio Cloud / AVITI OS - Metrics and Charts"; Element "AVITI
|
|
65
|
+
# System: The Ideal Platform for Low-Diversity Sequencing."
|
|
66
|
+
AVIDITY_ADVISORY_FIRST_CYCLES = 5
|
|
67
|
+
|
|
59
68
|
|
|
60
69
|
class Chemistry(str, Enum):
|
|
61
|
-
"""Optical detection chemistry of a sequencing instrument.
|
|
70
|
+
"""Optical detection chemistry of a sequencing instrument.
|
|
71
|
+
|
|
72
|
+
``FOUR_CHANNEL`` and ``AVIDITY`` are both "four-colour" in that every base
|
|
73
|
+
produces signal (no single dark base), but they differ in registration
|
|
74
|
+
structure and therefore in color-balance rules:
|
|
75
|
+
|
|
76
|
+
* ``FOUR_CHANNEL`` (Illumina MiSeq/HiSeq) images two lasers - a green laser
|
|
77
|
+
reads ``{G,T}`` and a red laser reads ``{A,C}`` - so each cycle needs at
|
|
78
|
+
least one base from *each* laser group across the pool.
|
|
79
|
+
* ``AVIDITY`` (Element AVITI) labels each base with its own avidite dye, so
|
|
80
|
+
there is no laser-pair constraint and the platform tolerates low-diversity
|
|
81
|
+
pools (Arslan et al., Nat. Biotechnol. 2023).
|
|
82
|
+
"""
|
|
62
83
|
|
|
63
84
|
ONE_CHANNEL = "1-channel"
|
|
64
85
|
TWO_CHANNEL = "2-channel"
|
|
65
86
|
FOUR_CHANNEL = "4-channel"
|
|
87
|
+
AVIDITY = "avidity"
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class ColorBalanceMode(str, Enum):
|
|
91
|
+
"""How strictly to score color balance.
|
|
92
|
+
|
|
93
|
+
``VENDOR_FAITHFUL`` (default) encodes each platform's *published* rule
|
|
94
|
+
exactly. ``CONSERVATIVE`` is stricter than the published hard minimum,
|
|
95
|
+
flagging risks the vendor's minimum permits (e.g. single-channel 2-channel
|
|
96
|
+
cycles, or AVITI low diversity).
|
|
97
|
+
"""
|
|
98
|
+
|
|
99
|
+
VENDOR_FAITHFUL = "vendor_faithful"
|
|
100
|
+
CONSERVATIVE = "conservative"
|
|
66
101
|
|
|
67
102
|
|
|
68
103
|
# ---------------------------------------------------------------------------
|
|
@@ -99,11 +134,13 @@ _INSTRUMENT_CHEMISTRY: dict[str, Chemistry] = {
|
|
|
99
134
|
"hiseq2500": Chemistry.FOUR_CHANNEL,
|
|
100
135
|
"hiseq3000": Chemistry.FOUR_CHANNEL,
|
|
101
136
|
"hiseq4000": Chemistry.FOUR_CHANNEL,
|
|
102
|
-
# Element Biosciences AVITI - avidity chemistry
|
|
103
|
-
#
|
|
104
|
-
#
|
|
105
|
-
|
|
106
|
-
|
|
137
|
+
# Element Biosciences AVITI - avidity chemistry labels each base with its
|
|
138
|
+
# own avidite dye (four images per cycle, no dark base) and, unlike
|
|
139
|
+
# Illumina's two-laser four-colour SBS, has no laser-pair constraint, so it
|
|
140
|
+
# tolerates low-diversity pools. Modelled as its own chemistry.
|
|
141
|
+
# Ref: Arslan et al., Nat. Biotechnol. 2023.
|
|
142
|
+
"aviti": Chemistry.AVIDITY,
|
|
143
|
+
"elementaviti": Chemistry.AVIDITY,
|
|
107
144
|
# 2-channel
|
|
108
145
|
"nextseq500": Chemistry.TWO_CHANNEL,
|
|
109
146
|
"nextseq550": Chemistry.TWO_CHANNEL,
|
|
@@ -218,14 +255,21 @@ class ColorBalanceReport:
|
|
|
218
255
|
|
|
219
256
|
chemistry: Chemistry
|
|
220
257
|
pool_size: int
|
|
258
|
+
mode: ColorBalanceMode = ColorBalanceMode.VENDOR_FAITHFUL
|
|
221
259
|
cycles: list[CycleBalance] = field(default_factory=list)
|
|
222
260
|
dark_cycles: list[CycleBalance] = field(default_factory=list)
|
|
223
261
|
weak_cycles: list[CycleBalance] = field(default_factory=list)
|
|
262
|
+
advisory_cycles: list[CycleBalance] = field(default_factory=list)
|
|
224
263
|
|
|
225
264
|
@property
|
|
226
265
|
def is_balanced(self) -> bool:
|
|
227
|
-
"""True if no dark
|
|
228
|
-
|
|
266
|
+
"""True if no *failing* (dark) cycles were found.
|
|
267
|
+
|
|
268
|
+
Weak cycles (single-channel-but-present, or below the soft signal
|
|
269
|
+
threshold) and advisory cycles (AVITI low diversity) are quality flags
|
|
270
|
+
that do not fail the pool.
|
|
271
|
+
"""
|
|
272
|
+
return not self.dark_cycles
|
|
229
273
|
|
|
230
274
|
|
|
231
275
|
def _column_bases(indexes: list[str], cycle: int) -> dict[str, int]:
|
|
@@ -243,35 +287,52 @@ def analyze_color_balance(
|
|
|
243
287
|
index2: list[str] | None = None,
|
|
244
288
|
*,
|
|
245
289
|
chemistry: Chemistry,
|
|
290
|
+
mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
|
|
246
291
|
min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
|
|
247
292
|
) -> ColorBalanceReport:
|
|
248
|
-
"""Score an index pool for colour balance against a chemistry.
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
293
|
+
"""Score an index pool for colour balance against a chemistry and mode.
|
|
294
|
+
|
|
295
|
+
Rules per chemistry (sources cited inline below):
|
|
296
|
+
|
|
297
|
+
* **2-/1-channel** (NextSeq/MiniSeq/NovaSeq, iSeq). ``G`` is the dark base.
|
|
298
|
+
An all-``G`` cycle (no signal in either channel) is a *dark* failure in
|
|
299
|
+
both modes. A single-channel cycle (one channel present, the other dark)
|
|
300
|
+
is a *failure* in ``CONSERVATIVE`` mode but only a *weak* warning in
|
|
301
|
+
``VENDOR_FAITHFUL`` mode, matching Illumina's hard minimum of "signal in
|
|
302
|
+
at least one channel" (Index Adapters Pooling Guide #1000000041074).
|
|
303
|
+
* **4-channel** (Illumina MiSeq/HiSeq). A green laser reads ``{G,T}`` and a
|
|
304
|
+
red laser reads ``{A,C}``; each cycle must include at least one base from
|
|
305
|
+
each laser group across the pool, else a laser is dark. A cycle missing
|
|
306
|
+
either laser is a *dark* failure in **both** modes (correctness, not a
|
|
307
|
+
strictness choice).
|
|
308
|
+
* **avidity** (Element AVITI). No dark base and no laser-pair constraint, so
|
|
309
|
+
low diversity never fails. In ``VENDOR_FAITHFUL`` mode low diversity in
|
|
310
|
+
the first :data:`AVIDITY_ADVISORY_FIRST_CYCLES` cycles is an *advisory*
|
|
311
|
+
(never a failure); in ``CONSERVATIVE`` mode any low-diversity cycle is
|
|
312
|
+
escalated to a *dark* failure.
|
|
256
313
|
|
|
257
314
|
Parameters
|
|
258
315
|
----------
|
|
259
|
-
index1:
|
|
260
|
-
I7
|
|
261
|
-
index2:
|
|
262
|
-
Optional I5 index sequences, one per sample.
|
|
316
|
+
index1, index2:
|
|
317
|
+
I7 (and optional I5) index sequences; empty strings are ignored.
|
|
263
318
|
chemistry:
|
|
264
319
|
Chemistry to score against - see :func:`chemistry_for_instrument`.
|
|
320
|
+
mode:
|
|
321
|
+
:class:`ColorBalanceMode` (or its string value). Defaults to
|
|
322
|
+
``VENDOR_FAITHFUL``.
|
|
265
323
|
min_signal_fraction:
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
:data:`DEFAULT_MIN_SIGNAL_FRACTION`.
|
|
324
|
+
Soft threshold below which an otherwise-present channel is flagged weak
|
|
325
|
+
(heuristic; not a published vendor number).
|
|
269
326
|
|
|
270
327
|
Returns
|
|
271
328
|
-------
|
|
272
329
|
ColorBalanceReport
|
|
273
|
-
Per-cycle diagnostics
|
|
330
|
+
Per-cycle diagnostics with dark (failing), weak (warning), and advisory
|
|
331
|
+
cycles collected separately.
|
|
274
332
|
"""
|
|
333
|
+
mode = ColorBalanceMode(mode)
|
|
334
|
+
conservative = mode is ColorBalanceMode.CONSERVATIVE
|
|
335
|
+
|
|
275
336
|
reads: list[tuple[str, list[str]]] = [("index1", [s for s in index1 if s])]
|
|
276
337
|
if index2 is not None:
|
|
277
338
|
reads.append(("index2", [s for s in index2 if s]))
|
|
@@ -279,6 +340,7 @@ def analyze_color_balance(
|
|
|
279
340
|
report = ColorBalanceReport(
|
|
280
341
|
chemistry=chemistry,
|
|
281
342
|
pool_size=len([s for s in index1 if s]),
|
|
343
|
+
mode=mode,
|
|
282
344
|
)
|
|
283
345
|
|
|
284
346
|
for read_name, seqs in reads:
|
|
@@ -299,37 +361,107 @@ def analyze_color_balance(
|
|
|
299
361
|
distinct_bases=len([b for b in counts if b != "N"]),
|
|
300
362
|
)
|
|
301
363
|
|
|
364
|
+
# A single sample lights whatever its own bases dictate; not
|
|
365
|
+
# assessable as a pool. Record but never flag.
|
|
366
|
+
if pool < 2:
|
|
367
|
+
report.cycles.append(cb)
|
|
368
|
+
continue
|
|
369
|
+
|
|
302
370
|
if chemistry is Chemistry.FOUR_CHANNEL:
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
else:
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
green += n
|
|
316
|
-
cb.red_fraction = red / pool
|
|
317
|
-
cb.green_fraction = green / pool
|
|
318
|
-
|
|
319
|
-
# Pool size 1 cannot be "balanced" - a single sample lights
|
|
320
|
-
# whatever channels its own bases dictate. Skip it rather than
|
|
321
|
-
# flag every cycle of a single-sample sheet.
|
|
322
|
-
if pool < 2:
|
|
323
|
-
report.cycles.append(cb)
|
|
324
|
-
continue
|
|
325
|
-
|
|
326
|
-
if cb.is_dark:
|
|
327
|
-
report.dark_cycles.append(cb)
|
|
328
|
-
elif (
|
|
329
|
-
cb.red_fraction < min_signal_fraction or cb.green_fraction < min_signal_fraction
|
|
330
|
-
):
|
|
331
|
-
report.weak_cycles.append(cb)
|
|
371
|
+
_score_four_channel(cb, counts, pool, report)
|
|
372
|
+
elif chemistry is Chemistry.AVIDITY:
|
|
373
|
+
_score_avidity(cb, report, conservative=conservative)
|
|
374
|
+
else: # TWO_CHANNEL / ONE_CHANNEL
|
|
375
|
+
_score_two_channel(
|
|
376
|
+
cb,
|
|
377
|
+
counts,
|
|
378
|
+
pool,
|
|
379
|
+
report,
|
|
380
|
+
conservative=conservative,
|
|
381
|
+
min_signal_fraction=min_signal_fraction,
|
|
382
|
+
)
|
|
332
383
|
|
|
333
384
|
report.cycles.append(cb)
|
|
334
385
|
|
|
335
386
|
return report
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
def _score_two_channel(
|
|
390
|
+
cb: CycleBalance,
|
|
391
|
+
counts: dict[str, int],
|
|
392
|
+
pool: int,
|
|
393
|
+
report: ColorBalanceReport,
|
|
394
|
+
*,
|
|
395
|
+
conservative: bool,
|
|
396
|
+
min_signal_fraction: float,
|
|
397
|
+
) -> None:
|
|
398
|
+
"""2-/1-channel rule. Red = {A,C}, green = {A,T}; G is dark.
|
|
399
|
+
|
|
400
|
+
Illumina hard minimum: signal in at least one channel (Index Adapters
|
|
401
|
+
Pooling Guide #1000000041074; NextSeq/MiniSeq and NovaSeq 6000
|
|
402
|
+
color-balancing knowledge articles).
|
|
403
|
+
"""
|
|
404
|
+
red = green = 0
|
|
405
|
+
for base, n in counts.items():
|
|
406
|
+
sig = _TWO_CHANNEL_SIGNAL.get(base)
|
|
407
|
+
if sig is None:
|
|
408
|
+
continue # N or unexpected char: no guaranteed signal
|
|
409
|
+
if sig[0]:
|
|
410
|
+
red += n
|
|
411
|
+
if sig[1]:
|
|
412
|
+
green += n
|
|
413
|
+
cb.red_fraction = red / pool
|
|
414
|
+
cb.green_fraction = green / pool
|
|
415
|
+
|
|
416
|
+
red_present = red > 0
|
|
417
|
+
green_present = green > 0
|
|
418
|
+
if not red_present and not green_present:
|
|
419
|
+
report.dark_cycles.append(cb) # all-G: no signal either channel (both modes)
|
|
420
|
+
elif not red_present or not green_present:
|
|
421
|
+
# Single channel: vendor minimum met (>=1 channel), but imbalanced.
|
|
422
|
+
if conservative:
|
|
423
|
+
report.dark_cycles.append(cb)
|
|
424
|
+
else:
|
|
425
|
+
report.weak_cycles.append(cb)
|
|
426
|
+
elif cb.red_fraction < min_signal_fraction or cb.green_fraction < min_signal_fraction:
|
|
427
|
+
report.weak_cycles.append(cb) # both present but one is faint (both modes)
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
def _score_four_channel(
|
|
431
|
+
cb: CycleBalance,
|
|
432
|
+
counts: dict[str, int],
|
|
433
|
+
pool: int,
|
|
434
|
+
report: ColorBalanceReport,
|
|
435
|
+
) -> None:
|
|
436
|
+
"""Illumina 4-colour rule (both modes). Green laser = {G,T}, red laser = {A,C}.
|
|
437
|
+
|
|
438
|
+
Each cycle must include at least one base from each laser group across the
|
|
439
|
+
pool, or a laser is dark and clusters cannot be registered. Ref: Index
|
|
440
|
+
Adapters Pooling Guide #1000000041074, four-channel section.
|
|
441
|
+
"""
|
|
442
|
+
red_laser = counts.get("A", 0) + counts.get("C", 0) # {A,C}
|
|
443
|
+
green_laser = counts.get("G", 0) + counts.get("T", 0) # {G,T}
|
|
444
|
+
cb.red_fraction = red_laser / pool
|
|
445
|
+
cb.green_fraction = green_laser / pool
|
|
446
|
+
if red_laser == 0 or green_laser == 0:
|
|
447
|
+
report.dark_cycles.append(cb)
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
def _score_avidity(
|
|
451
|
+
cb: CycleBalance,
|
|
452
|
+
report: ColorBalanceReport,
|
|
453
|
+
*,
|
|
454
|
+
conservative: bool,
|
|
455
|
+
) -> None:
|
|
456
|
+
"""Element AVITI (avidity) rule. No dark base; low diversity is tolerated.
|
|
457
|
+
|
|
458
|
+
Ref: Element "ElemBio Cloud / AVITI OS - Metrics and Charts"; Element
|
|
459
|
+
"AVITI System: The Ideal Platform for Low-Diversity Sequencing."
|
|
460
|
+
"""
|
|
461
|
+
low_diversity = cb.distinct_bases <= 1
|
|
462
|
+
if not low_diversity:
|
|
463
|
+
return
|
|
464
|
+
if conservative:
|
|
465
|
+
report.dark_cycles.append(cb) # escalate low diversity to a failure
|
|
466
|
+
elif cb.cycle <= AVIDITY_ADVISORY_FIRST_CYCLES:
|
|
467
|
+
report.advisory_cycles.append(cb) # first-cycles low diversity: advisory only
|
samplesheet_parser/validators.py
CHANGED
|
@@ -23,8 +23,10 @@ from dataclasses import dataclass, field
|
|
|
23
23
|
from typing import Any
|
|
24
24
|
|
|
25
25
|
from samplesheet_parser.chemistry import (
|
|
26
|
+
AVIDITY_ADVISORY_FIRST_CYCLES,
|
|
26
27
|
DEFAULT_MIN_SIGNAL_FRACTION,
|
|
27
28
|
Chemistry,
|
|
29
|
+
ColorBalanceMode,
|
|
28
30
|
analyze_color_balance,
|
|
29
31
|
chemistry_for_instrument,
|
|
30
32
|
)
|
|
@@ -260,6 +262,7 @@ class SampleSheetValidator:
|
|
|
260
262
|
min_hamming_distance: int = MIN_HAMMING_DISTANCE,
|
|
261
263
|
check_color_balance: bool = False,
|
|
262
264
|
instrument: str | None = None,
|
|
265
|
+
color_balance_mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
|
|
263
266
|
min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
|
|
264
267
|
) -> ValidationResult:
|
|
265
268
|
"""Run all validation checks on a parsed sample sheet.
|
|
@@ -314,6 +317,7 @@ class SampleSheetValidator:
|
|
|
314
317
|
samples,
|
|
315
318
|
result,
|
|
316
319
|
instrument=instrument,
|
|
320
|
+
mode=color_balance_mode,
|
|
317
321
|
min_signal_fraction=min_signal_fraction,
|
|
318
322
|
)
|
|
319
323
|
|
|
@@ -550,17 +554,16 @@ class SampleSheetValidator:
|
|
|
550
554
|
result: ValidationResult,
|
|
551
555
|
*,
|
|
552
556
|
instrument: str | None = None,
|
|
557
|
+
mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
|
|
553
558
|
min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
|
|
554
559
|
) -> None:
|
|
555
560
|
"""Flag index cycles that will fail or degrade on the instrument's chemistry.
|
|
556
561
|
|
|
557
|
-
Resolves the instrument's optical chemistry
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
(warning). On 4-channel chemistry only single-base (zero-diversity)
|
|
563
|
-
cycles are flagged as ``COLOR_BALANCE_LOW``.
|
|
562
|
+
Resolves the instrument's optical chemistry and scores the index pool
|
|
563
|
+
per cycle under *mode* (see :class:`ColorBalanceMode`). Failing cycles
|
|
564
|
+
are reported as ``COLOR_BALANCE_NO_SIGNAL`` (error), risky-but-permitted
|
|
565
|
+
cycles as ``COLOR_BALANCE_LOW`` (warning), and AVITI low-diversity in
|
|
566
|
+
``vendor_faithful`` mode as ``COLOR_BALANCE_ADVISORY`` (warning).
|
|
564
567
|
|
|
565
568
|
The check is skipped (no findings) when the instrument is unknown, since
|
|
566
569
|
guessing the chemistry could produce misleading errors. Pass *instrument*
|
|
@@ -583,67 +586,116 @@ class SampleSheetValidator:
|
|
|
583
586
|
index1,
|
|
584
587
|
index2 if has_index2 else None,
|
|
585
588
|
chemistry=chemistry,
|
|
589
|
+
mode=mode,
|
|
586
590
|
min_signal_fraction=min_signal_fraction,
|
|
587
591
|
)
|
|
588
592
|
|
|
589
593
|
for cb in report.dark_cycles:
|
|
590
|
-
no_red = cb.red_fraction == 0.0
|
|
591
|
-
no_green = cb.green_fraction == 0.0
|
|
592
|
-
if no_red and no_green:
|
|
593
|
-
channel = "red or green"
|
|
594
|
-
signal_bases = "A/C/T"
|
|
595
|
-
elif no_red:
|
|
596
|
-
channel = "red"
|
|
597
|
-
signal_bases = "A or C"
|
|
598
|
-
else:
|
|
599
|
-
channel = "green"
|
|
600
|
-
signal_bases = "A or T"
|
|
601
594
|
result.add_error(
|
|
602
595
|
"COLOR_BALANCE_NO_SIGNAL",
|
|
603
|
-
|
|
604
|
-
f"{cb.cycle} has no {channel} signal across the pool: no sample "
|
|
605
|
-
f"carries a {channel} base ({signal_bases}) at this cycle "
|
|
606
|
-
f"(base counts {cb.base_counts}). The instrument cannot register "
|
|
607
|
-
f"this cycle and the index read will fail.",
|
|
596
|
+
self._dark_message(chemistry, name, cb, report.mode),
|
|
608
597
|
instrument=name,
|
|
609
598
|
chemistry=chemistry.value,
|
|
599
|
+
mode=report.mode.value,
|
|
610
600
|
read=cb.read,
|
|
611
601
|
cycle=cb.cycle,
|
|
612
|
-
channel=channel,
|
|
613
602
|
base_counts=cb.base_counts,
|
|
614
603
|
)
|
|
615
604
|
|
|
616
605
|
for cb in report.weak_cycles:
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
606
|
+
result.add_warning(
|
|
607
|
+
"COLOR_BALANCE_LOW",
|
|
608
|
+
self._weak_message(chemistry, name, cb, min_signal_fraction),
|
|
609
|
+
instrument=name,
|
|
610
|
+
chemistry=chemistry.value,
|
|
611
|
+
read=cb.read,
|
|
612
|
+
cycle=cb.cycle,
|
|
613
|
+
red_fraction=cb.red_fraction,
|
|
614
|
+
green_fraction=cb.green_fraction,
|
|
615
|
+
base_counts=cb.base_counts,
|
|
616
|
+
)
|
|
617
|
+
|
|
618
|
+
for cb in report.advisory_cycles:
|
|
619
|
+
base = next(iter(cb.base_counts))
|
|
620
|
+
result.add_warning(
|
|
621
|
+
"COLOR_BALANCE_ADVISORY",
|
|
622
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
623
|
+
f"{cb.cycle} has low base diversity (every sample reads '{base}') "
|
|
624
|
+
f"within the first {AVIDITY_ADVISORY_FIRST_CYCLES} cycles. AVITI "
|
|
625
|
+
f"tolerates low-diversity sequencing, so this is an advisory only, "
|
|
626
|
+
f"not a failure.",
|
|
627
|
+
instrument=name,
|
|
628
|
+
chemistry=chemistry.value,
|
|
629
|
+
read=cb.read,
|
|
630
|
+
cycle=cb.cycle,
|
|
631
|
+
base_counts=cb.base_counts,
|
|
632
|
+
)
|
|
633
|
+
|
|
634
|
+
@staticmethod
|
|
635
|
+
def _dark_message(
|
|
636
|
+
chemistry: Chemistry,
|
|
637
|
+
name: str | None,
|
|
638
|
+
cb: Any,
|
|
639
|
+
mode: ColorBalanceMode,
|
|
640
|
+
) -> str:
|
|
641
|
+
"""Human-readable message for a failing (dark) cycle, by chemistry."""
|
|
642
|
+
if chemistry is Chemistry.FOUR_CHANNEL:
|
|
643
|
+
missing = "red ({A,C})" if (cb.red_fraction or 0.0) == 0.0 else "green ({G,T})"
|
|
644
|
+
return (
|
|
645
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
646
|
+
f"{cb.cycle}: the {missing} laser is unrepresented across the pool "
|
|
647
|
+
f"(base counts {cb.base_counts}); both lasers are required for "
|
|
648
|
+
f"cluster registration, so the index read will fail."
|
|
649
|
+
)
|
|
650
|
+
if chemistry is Chemistry.AVIDITY:
|
|
651
|
+
base = next(iter(cb.base_counts))
|
|
652
|
+
return (
|
|
653
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
654
|
+
f"{cb.cycle} has low base diversity (every sample reads '{base}'); "
|
|
655
|
+
f"flagged as a failure in conservative mode."
|
|
656
|
+
)
|
|
657
|
+
no_red = (cb.red_fraction or 0.0) == 0.0
|
|
658
|
+
no_green = (cb.green_fraction or 0.0) == 0.0
|
|
659
|
+
if no_red and no_green:
|
|
660
|
+
channel, signal_bases = "red or green", "A/C/T"
|
|
661
|
+
elif no_red:
|
|
662
|
+
channel, signal_bases = "red", "A or C"
|
|
663
|
+
else:
|
|
664
|
+
channel, signal_bases = "green", "A or T"
|
|
665
|
+
return (
|
|
666
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
667
|
+
f"{cb.cycle} has no {channel} signal across the pool: no sample "
|
|
668
|
+
f"carries a {channel} base ({signal_bases}) at this cycle "
|
|
669
|
+
f"(base counts {cb.base_counts}). The instrument cannot register "
|
|
670
|
+
f"this cycle and the index read will fail."
|
|
671
|
+
)
|
|
672
|
+
|
|
673
|
+
@staticmethod
|
|
674
|
+
def _weak_message(
|
|
675
|
+
chemistry: Chemistry,
|
|
676
|
+
name: str | None,
|
|
677
|
+
cb: Any,
|
|
678
|
+
min_signal_fraction: float,
|
|
679
|
+
) -> str:
|
|
680
|
+
"""Human-readable message for a weak (warning) cycle on 2-/1-channel."""
|
|
681
|
+
no_red = (cb.red_fraction or 0.0) == 0.0
|
|
682
|
+
no_green = (cb.green_fraction or 0.0) == 0.0
|
|
683
|
+
if no_red or no_green:
|
|
684
|
+
present = "green" if no_red else "red"
|
|
685
|
+
return (
|
|
686
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
687
|
+
f"{cb.cycle} carries signal in only the {present} channel "
|
|
688
|
+
f"(base counts {cb.base_counts}). This meets Illumina's "
|
|
689
|
+
f"'at least one channel' minimum but is colour-imbalanced; "
|
|
690
|
+
f"enable conservative mode to treat it as a failure."
|
|
691
|
+
)
|
|
692
|
+
pct = round(min(cb.red_fraction or 0.0, cb.green_fraction or 0.0) * 100, 1)
|
|
693
|
+
return (
|
|
694
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
695
|
+
f"{cb.cycle} carries weak signal in one channel (as low as {pct}% "
|
|
696
|
+
f"of the pool; recommended >= {round(min_signal_fraction * 100)}%), "
|
|
697
|
+
f"risking poor base calls for this cycle."
|
|
698
|
+
)
|
|
647
699
|
|
|
648
700
|
def _check_adapters(
|
|
649
701
|
self,
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: samplesheet-parser
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.4.0
|
|
4
4
|
Summary: Multi-vendor, format-agnostic parser for sequencing sample sheets — Illumina IEM V1 & BCLConvert V2 plus Element AVITI run manifests, with index validation and color-balance checking
|
|
5
5
|
Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
|
|
6
|
-
Project-URL: Documentation, https://
|
|
6
|
+
Project-URL: Documentation, https://samplesheet-parser.readthedocs.io
|
|
7
7
|
Project-URL: Repository, https://github.com/chaitanyakasaraneni/samplesheet-parser
|
|
8
8
|
Project-URL: Issues, https://github.com/chaitanyakasaraneni/samplesheet-parser/issues
|
|
9
9
|
Author-email: Chaitanya Kasaraneni <kc.kasaraneni@gmail.com>
|
|
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
|
|
|
56
56
|
|
|
57
57
|
# samplesheet-parser
|
|
58
58
|
|
|
59
|
-
**
|
|
59
|
+
**Multi-vendor, format-agnostic parser for sequencing sample sheets.**
|
|
60
60
|
|
|
61
61
|
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — plus non-Illumina **Element AVITI** run manifests — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
62
62
|
|
|
@@ -67,12 +67,12 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
|
|
|
67
67
|
|
|
68
68
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
69
69
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
70
|
-
[](https://samplesheet-parser.readthedocs.io)
|
|
71
71
|
[](https://doi.org/10.5281/zenodo.18989694)
|
|
72
72
|
|
|
73
|
-
**Docs:** https://
|
|
73
|
+
**Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
74
74
|
|
|
75
|
-

|
|
76
76
|
|
|
77
77
|
*`SampleSheetFactory` auto-detects the format — Illumina V1/V2 or an Element AVITI run manifest — and routes to the correct parser. All formats share a common interface — `SampleSheetConverter` handles bidirectional conversion between the Illumina formats, `SampleSheetValidator` catches index, adapter, and color-balance issues, `SampleSheetDiff` compares two sheets across any combination of formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
|
|
78
78
|
|
|
@@ -345,13 +345,14 @@ samplesheet merge ProjectA.csv ProjectB.csv --output combined.csv --format json
|
|
|
345
345
|
|
|
346
346
|
## Format detection logic
|
|
347
347
|
|
|
348
|
-
The factory
|
|
348
|
+
The factory detects the format across vendors — no format hints required from the caller:
|
|
349
349
|
|
|
350
|
-
1. **
|
|
351
|
-
2. **
|
|
352
|
-
3. **
|
|
350
|
+
1. **Vendor manifest check** — recognise a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
|
|
351
|
+
2. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
|
|
352
|
+
3. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
|
|
353
|
+
4. **Default** — fall back to V1 (broadest compatibility with legacy files)
|
|
353
354
|
|
|
354
|
-
|
|
355
|
+
For Illumina sheets the detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
|
|
355
356
|
|
|
356
357
|
---
|
|
357
358
|
|
|
@@ -410,8 +411,8 @@ a real, common cause of wrecked runs that a Hamming-distance check cannot see.
|
|
|
410
411
|
|
|
411
412
|
Because the sample sheet already contains every sample's index, this can be
|
|
412
413
|
predicted *before the run starts* with no sequencing data. The validator scores
|
|
413
|
-
the pool cycle-by-cycle
|
|
414
|
-
|
|
414
|
+
the pool cycle-by-cycle against the instrument's chemistry, with the exact rule
|
|
415
|
+
depending on the chemistry and the selected mode (see below).
|
|
415
416
|
|
|
416
417
|
```python
|
|
417
418
|
from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
|
|
@@ -449,16 +450,32 @@ samplesheet validate SampleSheet.csv --color-balance
|
|
|
449
450
|
samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
|
|
450
451
|
```
|
|
451
452
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
453
|
+
#### Modes: `vendor_faithful` (default) and `conservative`
|
|
454
|
+
|
|
455
|
+
Color balance has two modes, selectable via
|
|
456
|
+
`validate(..., color_balance_mode=...)` or `analyze_color_balance(..., mode=...)`:
|
|
457
|
+
|
|
458
|
+
- **`vendor_faithful`** (default) encodes each platform's *published* rule
|
|
459
|
+
exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
|
|
460
|
+
the both-lasers rule for 4-channel, and Element's permissive low-diversity
|
|
461
|
+
stance for AVITI.
|
|
462
|
+
- **`conservative`** is stricter than the published minimum: it also fails
|
|
463
|
+
single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
|
|
464
|
+
behavior before modes existed — pass `color_balance_mode="conservative"` to
|
|
465
|
+
keep it.)
|
|
466
|
+
|
|
467
|
+
| Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
|
|
468
|
+
|---|---|---|---|
|
|
469
|
+
| 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
|
|
470
|
+
| 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
|
|
471
|
+
| 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
|
|
472
|
+
| avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
|
|
473
|
+
|
|
474
|
+
Element AVITI uses avidity chemistry — each base has its own avidite dye
|
|
475
|
+
([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
|
|
476
|
+
— so it has no dark base and no laser-pair constraint. In `vendor_faithful`
|
|
477
|
+
mode, AVITI low diversity in the first cycles is an advisory
|
|
478
|
+
(`COLOR_BALANCE_ADVISORY`), never a failure.
|
|
462
479
|
|
|
463
480
|
---
|
|
464
481
|
|
|
@@ -785,14 +802,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
|
|
|
785
802
|
|
|
786
803
|
```bibtex
|
|
787
804
|
@software{kasaraneni2026samplesheetparser,
|
|
788
|
-
author = {Kasaraneni, Chaitanya},
|
|
789
|
-
title = {samplesheet-parser:
|
|
805
|
+
author = {Kasaraneni, Chaitanya Krishna},
|
|
806
|
+
title = {samplesheet-parser: A multi-vendor parser, validator, and converter for sequencing sample sheets},
|
|
790
807
|
year = {2026},
|
|
791
808
|
url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
|
|
792
|
-
|
|
809
|
+
doi = {10.5281/zenodo.18989694},
|
|
810
|
+
version = {2.4.0}
|
|
793
811
|
}
|
|
794
812
|
```
|
|
795
813
|
|
|
814
|
+
See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
|
|
815
|
+
|
|
796
816
|
---
|
|
797
817
|
|
|
798
818
|
## License
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
samplesheet_parser/__init__.py,sha256=
|
|
2
|
-
samplesheet_parser/chemistry.py,sha256=
|
|
1
|
+
samplesheet_parser/__init__.py,sha256=eSlshig-sXWyxW70vbd__lu9u6nfqVTyv-48MUsmiZg,2890
|
|
2
|
+
samplesheet_parser/chemistry.py,sha256=1I6jxzCmZqNqHitUzWQWo3JnuVHdASTVNUu-6jU4eoE,17631
|
|
3
3
|
samplesheet_parser/cli.py,sha256=zL_JPj7wNj24ozB4CjQsXwskefAfxqq01osGqJ0S_QA,30815
|
|
4
4
|
samplesheet_parser/converter.py,sha256=g4s5R6iB5mPDF-e8JD4Iezt2dMBBxgQ-OPL9vxJ2zM0,20236
|
|
5
5
|
samplesheet_parser/diff.py,sha256=RruQhKRi0Ja6x5pq8CA-yafJ4JQJ3p0JXDp68RS53GE,15369
|
|
@@ -12,14 +12,14 @@ samplesheet_parser/merger.py,sha256=UxQ8bmX7632S70Lko3GFQTjHqTZUt7aRch_UCSxVjsw,
|
|
|
12
12
|
samplesheet_parser/protocol.py,sha256=YOT1iZ-727nDKDGvZXNTjVG-OAgGdq0F0y3Tzbk7bwM,3104
|
|
13
13
|
samplesheet_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
14
14
|
samplesheet_parser/splitter.py,sha256=QMmTTXg4HwZl3oUvA-4KKUVF62oIn4k2D1ko_dT1wS4,11314
|
|
15
|
-
samplesheet_parser/validators.py,sha256=
|
|
15
|
+
samplesheet_parser/validators.py,sha256=60VSOIUuSijON0G9WuZCijAV_idRmc8ZIbKBQok526s,29496
|
|
16
16
|
samplesheet_parser/writer.py,sha256=NQY0x28rKF-694w11FZTCqCXxlNiHnMspB5M33GoD0k,33541
|
|
17
17
|
samplesheet_parser/parsers/__init__.py,sha256=N5ICN_46x-ARbG8kyrck6g1V_gOU0XacqzUJI-D6KX8,213
|
|
18
18
|
samplesheet_parser/parsers/element.py,sha256=7DrketMyQzPnEvAaaj6pstAiuvAJ6ljcFltsU-uymxs,11358
|
|
19
19
|
samplesheet_parser/parsers/v1.py,sha256=MRt_BUJTmj763N2kByELNwQPY-_jcLKcwahG4jPBH98,23956
|
|
20
20
|
samplesheet_parser/parsers/v2.py,sha256=pCd18DNcpIIh7vJNEB8asRleIriH2NSx7h7NAtsomug,27982
|
|
21
|
-
samplesheet_parser-2.
|
|
22
|
-
samplesheet_parser-2.
|
|
23
|
-
samplesheet_parser-2.
|
|
24
|
-
samplesheet_parser-2.
|
|
25
|
-
samplesheet_parser-2.
|
|
21
|
+
samplesheet_parser-2.4.0.dist-info/METADATA,sha256=f2P2WVRRDGIM3qAPVFTl61VoQnU-bhEWfhqX_LzPdIk,32706
|
|
22
|
+
samplesheet_parser-2.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
|
|
23
|
+
samplesheet_parser-2.4.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
|
|
24
|
+
samplesheet_parser-2.4.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
|
|
25
|
+
samplesheet_parser-2.4.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|