samplesheet-parser 2.3.0__py3-none-any.whl → 2.5.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/cli.py +25 -0
- samplesheet_parser/validators.py +139 -57
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.5.0.dist-info}/METADATA +66 -28
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.5.0.dist-info}/RECORD +9 -9
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.5.0.dist-info}/WHEEL +1 -1
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.5.0.dist-info}/entry_points.txt +0 -0
- {samplesheet_parser-2.3.0.dist-info → samplesheet_parser-2.5.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/cli.py
CHANGED
|
@@ -29,6 +29,7 @@ Usage
|
|
|
29
29
|
samplesheet validate SampleSheet.csv
|
|
30
30
|
samplesheet validate SampleSheet.csv --format json
|
|
31
31
|
samplesheet validate SampleSheet.csv --min-hamming 4
|
|
32
|
+
samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
|
|
32
33
|
|
|
33
34
|
samplesheet convert SampleSheet_v1.csv --to v2 --output SampleSheet_v2.csv
|
|
34
35
|
samplesheet convert SampleSheet_v2.csv --to v1 --output SampleSheet_v1.csv
|
|
@@ -66,6 +67,7 @@ try:
|
|
|
66
67
|
except ImportError: # pragma: no cover
|
|
67
68
|
_TYPER_AVAILABLE = False
|
|
68
69
|
|
|
70
|
+
from samplesheet_parser.chemistry import ColorBalanceMode
|
|
69
71
|
from samplesheet_parser.enums import SampleSheetVersion
|
|
70
72
|
from samplesheet_parser.validators import MIN_HAMMING_DISTANCE as _MIN_HAMMING_DEFAULT
|
|
71
73
|
|
|
@@ -274,6 +276,18 @@ if _TYPER_AVAILABLE:
|
|
|
274
276
|
),
|
|
275
277
|
),
|
|
276
278
|
] = False,
|
|
279
|
+
color_balance_mode: Annotated[
|
|
280
|
+
ColorBalanceMode,
|
|
281
|
+
typer.Option(
|
|
282
|
+
"--color-balance-mode",
|
|
283
|
+
help=(
|
|
284
|
+
"Strictness of the colour-balance check (only with "
|
|
285
|
+
"--color-balance). 'vendor_faithful' encodes each platform's "
|
|
286
|
+
"published rule; 'conservative' also fails single-channel and "
|
|
287
|
+
"low-diversity cycles the vendor minimum permits."
|
|
288
|
+
),
|
|
289
|
+
),
|
|
290
|
+
] = ColorBalanceMode.VENDOR_FAITHFUL,
|
|
277
291
|
instrument: Annotated[
|
|
278
292
|
str | None,
|
|
279
293
|
typer.Option(
|
|
@@ -318,6 +332,7 @@ if _TYPER_AVAILABLE:
|
|
|
318
332
|
sheet,
|
|
319
333
|
min_hamming_distance=min_hamming,
|
|
320
334
|
check_color_balance=color_balance,
|
|
335
|
+
color_balance_mode=color_balance_mode,
|
|
321
336
|
instrument=instrument,
|
|
322
337
|
)
|
|
323
338
|
|
|
@@ -329,6 +344,7 @@ if _TYPER_AVAILABLE:
|
|
|
329
344
|
"is_valid": result.is_valid,
|
|
330
345
|
"min_hamming_distance": min_hamming,
|
|
331
346
|
"color_balance_checked": color_balance,
|
|
347
|
+
"color_balance_mode": color_balance_mode.value if color_balance else None,
|
|
332
348
|
"errors": [
|
|
333
349
|
{"code": e.code, "message": e.message, "context": e.context}
|
|
334
350
|
for e in result.errors
|
|
@@ -337,6 +353,10 @@ if _TYPER_AVAILABLE:
|
|
|
337
353
|
{"code": w.code, "message": w.message, "context": w.context}
|
|
338
354
|
for w in result.warnings
|
|
339
355
|
],
|
|
356
|
+
"notes": [
|
|
357
|
+
{"code": n.code, "message": n.message, "context": n.context}
|
|
358
|
+
for n in result.notes
|
|
359
|
+
],
|
|
340
360
|
"summary": result.summary(),
|
|
341
361
|
}
|
|
342
362
|
)
|
|
@@ -345,6 +365,11 @@ if _TYPER_AVAILABLE:
|
|
|
345
365
|
typer.echo(f"Format: {version.value}")
|
|
346
366
|
typer.echo(f"Result: {result.summary()}")
|
|
347
367
|
|
|
368
|
+
if result.notes:
|
|
369
|
+
typer.echo("\nNotes:")
|
|
370
|
+
for n in result.notes:
|
|
371
|
+
typer.echo(f" {n}")
|
|
372
|
+
|
|
348
373
|
if result.warnings:
|
|
349
374
|
typer.echo("\nWarnings:")
|
|
350
375
|
for w in result.warnings:
|
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
|
)
|
|
@@ -77,7 +79,7 @@ class ValidationIssue:
|
|
|
77
79
|
Attributes
|
|
78
80
|
----------
|
|
79
81
|
level:
|
|
80
|
-
``"error"`` or ``"
|
|
82
|
+
``"error"``, ``"warning"``, or ``"note"``.
|
|
81
83
|
code:
|
|
82
84
|
Short machine-readable code (e.g. ``"DUPLICATE_INDEX"``).
|
|
83
85
|
message:
|
|
@@ -103,17 +105,23 @@ class ValidationResult:
|
|
|
103
105
|
Attributes
|
|
104
106
|
----------
|
|
105
107
|
is_valid:
|
|
106
|
-
``True`` if no *errors* were raised (warnings do not affect
|
|
108
|
+
``True`` if no *errors* were raised (warnings and notes do not affect
|
|
107
109
|
this flag).
|
|
108
110
|
errors:
|
|
109
111
|
List of error-level :class:`ValidationIssue` objects.
|
|
110
112
|
warnings:
|
|
111
113
|
List of warning-level :class:`ValidationIssue` objects.
|
|
114
|
+
notes:
|
|
115
|
+
List of informational :class:`ValidationIssue` objects. Notes record
|
|
116
|
+
checks that were requested but not performed (e.g. a colour-balance
|
|
117
|
+
check skipped because the instrument was unknown), so a clean result
|
|
118
|
+
is not mistaken for a check that silently did nothing.
|
|
112
119
|
"""
|
|
113
120
|
|
|
114
121
|
is_valid: bool = True
|
|
115
122
|
errors: list[ValidationIssue] = field(default_factory=list)
|
|
116
123
|
warnings: list[ValidationIssue] = field(default_factory=list)
|
|
124
|
+
notes: list[ValidationIssue] = field(default_factory=list)
|
|
117
125
|
|
|
118
126
|
def add_error(self, code: str, message: str, **context: Any) -> None:
|
|
119
127
|
self.is_valid = False
|
|
@@ -124,6 +132,11 @@ class ValidationResult:
|
|
|
124
132
|
self.warnings.append(ValidationIssue("warning", code, message, dict(context)))
|
|
125
133
|
logger.warning(f"{code}: {message}")
|
|
126
134
|
|
|
135
|
+
def add_note(self, code: str, message: str, **context: Any) -> None:
|
|
136
|
+
"""Record an informational note (does not affect ``is_valid``)."""
|
|
137
|
+
self.notes.append(ValidationIssue("note", code, message, dict(context)))
|
|
138
|
+
logger.info(f"{code}: {message}")
|
|
139
|
+
|
|
127
140
|
def to_dict(self) -> dict[str, Any]:
|
|
128
141
|
return {
|
|
129
142
|
"is_valid": self.is_valid,
|
|
@@ -133,6 +146,9 @@ class ValidationResult:
|
|
|
133
146
|
"warnings": [
|
|
134
147
|
{"code": w.code, "message": w.message, "context": w.context} for w in self.warnings
|
|
135
148
|
],
|
|
149
|
+
"notes": [
|
|
150
|
+
{"code": n.code, "message": n.message, "context": n.context} for n in self.notes
|
|
151
|
+
],
|
|
136
152
|
}
|
|
137
153
|
|
|
138
154
|
def summary(self) -> str:
|
|
@@ -245,6 +261,10 @@ class SampleSheetValidator:
|
|
|
245
261
|
in one channel (2-/1-channel) or no base
|
|
246
262
|
diversity (4-channel), degrading base-call
|
|
247
263
|
quality (warning only).
|
|
264
|
+
* **COLOR_BALANCE_SKIPPED** - Colour balance was requested but the
|
|
265
|
+
instrument chemistry could not be resolved, so
|
|
266
|
+
the check was not run (note only, so a clean
|
|
267
|
+
result is not mistaken for a passed check).
|
|
248
268
|
|
|
249
269
|
Examples
|
|
250
270
|
--------
|
|
@@ -260,6 +280,7 @@ class SampleSheetValidator:
|
|
|
260
280
|
min_hamming_distance: int = MIN_HAMMING_DISTANCE,
|
|
261
281
|
check_color_balance: bool = False,
|
|
262
282
|
instrument: str | None = None,
|
|
283
|
+
color_balance_mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
|
|
263
284
|
min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
|
|
264
285
|
) -> ValidationResult:
|
|
265
286
|
"""Run all validation checks on a parsed sample sheet.
|
|
@@ -314,6 +335,7 @@ class SampleSheetValidator:
|
|
|
314
335
|
samples,
|
|
315
336
|
result,
|
|
316
337
|
instrument=instrument,
|
|
338
|
+
mode=color_balance_mode,
|
|
317
339
|
min_signal_fraction=min_signal_fraction,
|
|
318
340
|
)
|
|
319
341
|
|
|
@@ -550,17 +572,16 @@ class SampleSheetValidator:
|
|
|
550
572
|
result: ValidationResult,
|
|
551
573
|
*,
|
|
552
574
|
instrument: str | None = None,
|
|
575
|
+
mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
|
|
553
576
|
min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
|
|
554
577
|
) -> None:
|
|
555
578
|
"""Flag index cycles that will fail or degrade on the instrument's chemistry.
|
|
556
579
|
|
|
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``.
|
|
580
|
+
Resolves the instrument's optical chemistry and scores the index pool
|
|
581
|
+
per cycle under *mode* (see :class:`ColorBalanceMode`). Failing cycles
|
|
582
|
+
are reported as ``COLOR_BALANCE_NO_SIGNAL`` (error), risky-but-permitted
|
|
583
|
+
cycles as ``COLOR_BALANCE_LOW`` (warning), and AVITI low-diversity in
|
|
584
|
+
``vendor_faithful`` mode as ``COLOR_BALANCE_ADVISORY`` (warning).
|
|
564
585
|
|
|
565
586
|
The check is skipped (no findings) when the instrument is unknown, since
|
|
566
587
|
guessing the chemistry could produce misleading errors. Pass *instrument*
|
|
@@ -572,7 +593,19 @@ class SampleSheetValidator:
|
|
|
572
593
|
name = instrument or self._resolve_instrument(sheet)
|
|
573
594
|
chemistry = chemistry_for_instrument(name)
|
|
574
595
|
if chemistry is None:
|
|
575
|
-
|
|
596
|
+
detail = (
|
|
597
|
+
f"instrument {name!r} is not recognised"
|
|
598
|
+
if name
|
|
599
|
+
else "no instrument is declared in the sheet or passed via --instrument"
|
|
600
|
+
)
|
|
601
|
+
result.add_note(
|
|
602
|
+
"COLOR_BALANCE_SKIPPED",
|
|
603
|
+
f"Colour balance was requested but not evaluated: {detail}, so the "
|
|
604
|
+
f"optical chemistry is unknown. A clean result here does not mean the "
|
|
605
|
+
f"index pool is colour balanced. Pass a known instrument to enable the "
|
|
606
|
+
f"check.",
|
|
607
|
+
instrument=name,
|
|
608
|
+
)
|
|
576
609
|
return
|
|
577
610
|
|
|
578
611
|
index1 = [(s.get("index") or s.get("Index") or "").upper() for s in samples]
|
|
@@ -583,67 +616,116 @@ class SampleSheetValidator:
|
|
|
583
616
|
index1,
|
|
584
617
|
index2 if has_index2 else None,
|
|
585
618
|
chemistry=chemistry,
|
|
619
|
+
mode=mode,
|
|
586
620
|
min_signal_fraction=min_signal_fraction,
|
|
587
621
|
)
|
|
588
622
|
|
|
589
623
|
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
624
|
result.add_error(
|
|
602
625
|
"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.",
|
|
626
|
+
self._dark_message(chemistry, name, cb, report.mode),
|
|
608
627
|
instrument=name,
|
|
609
628
|
chemistry=chemistry.value,
|
|
629
|
+
mode=report.mode.value,
|
|
610
630
|
read=cb.read,
|
|
611
631
|
cycle=cb.cycle,
|
|
612
|
-
channel=channel,
|
|
613
632
|
base_counts=cb.base_counts,
|
|
614
633
|
)
|
|
615
634
|
|
|
616
635
|
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
|
-
|
|
636
|
+
result.add_warning(
|
|
637
|
+
"COLOR_BALANCE_LOW",
|
|
638
|
+
self._weak_message(chemistry, name, cb, min_signal_fraction),
|
|
639
|
+
instrument=name,
|
|
640
|
+
chemistry=chemistry.value,
|
|
641
|
+
read=cb.read,
|
|
642
|
+
cycle=cb.cycle,
|
|
643
|
+
red_fraction=cb.red_fraction,
|
|
644
|
+
green_fraction=cb.green_fraction,
|
|
645
|
+
base_counts=cb.base_counts,
|
|
646
|
+
)
|
|
647
|
+
|
|
648
|
+
for cb in report.advisory_cycles:
|
|
649
|
+
base = next(iter(cb.base_counts))
|
|
650
|
+
result.add_warning(
|
|
651
|
+
"COLOR_BALANCE_ADVISORY",
|
|
652
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
653
|
+
f"{cb.cycle} has low base diversity (every sample reads '{base}') "
|
|
654
|
+
f"within the first {AVIDITY_ADVISORY_FIRST_CYCLES} cycles. AVITI "
|
|
655
|
+
f"tolerates low-diversity sequencing, so this is an advisory only, "
|
|
656
|
+
f"not a failure.",
|
|
657
|
+
instrument=name,
|
|
658
|
+
chemistry=chemistry.value,
|
|
659
|
+
read=cb.read,
|
|
660
|
+
cycle=cb.cycle,
|
|
661
|
+
base_counts=cb.base_counts,
|
|
662
|
+
)
|
|
663
|
+
|
|
664
|
+
@staticmethod
|
|
665
|
+
def _dark_message(
|
|
666
|
+
chemistry: Chemistry,
|
|
667
|
+
name: str | None,
|
|
668
|
+
cb: Any,
|
|
669
|
+
mode: ColorBalanceMode,
|
|
670
|
+
) -> str:
|
|
671
|
+
"""Human-readable message for a failing (dark) cycle, by chemistry."""
|
|
672
|
+
if chemistry is Chemistry.FOUR_CHANNEL:
|
|
673
|
+
missing = "red ({A,C})" if (cb.red_fraction or 0.0) == 0.0 else "green ({G,T})"
|
|
674
|
+
return (
|
|
675
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
676
|
+
f"{cb.cycle}: the {missing} laser is unrepresented across the pool "
|
|
677
|
+
f"(base counts {cb.base_counts}); both lasers are required for "
|
|
678
|
+
f"cluster registration, so the index read will fail."
|
|
679
|
+
)
|
|
680
|
+
if chemistry is Chemistry.AVIDITY:
|
|
681
|
+
base = next(iter(cb.base_counts))
|
|
682
|
+
return (
|
|
683
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
684
|
+
f"{cb.cycle} has low base diversity (every sample reads '{base}'); "
|
|
685
|
+
f"flagged as a failure in conservative mode."
|
|
686
|
+
)
|
|
687
|
+
no_red = (cb.red_fraction or 0.0) == 0.0
|
|
688
|
+
no_green = (cb.green_fraction or 0.0) == 0.0
|
|
689
|
+
if no_red and no_green:
|
|
690
|
+
channel, signal_bases = "red or green", "A/C/T"
|
|
691
|
+
elif no_red:
|
|
692
|
+
channel, signal_bases = "red", "A or C"
|
|
693
|
+
else:
|
|
694
|
+
channel, signal_bases = "green", "A or T"
|
|
695
|
+
return (
|
|
696
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
697
|
+
f"{cb.cycle} has no {channel} signal across the pool: no sample "
|
|
698
|
+
f"carries a {channel} base ({signal_bases}) at this cycle "
|
|
699
|
+
f"(base counts {cb.base_counts}). The instrument cannot register "
|
|
700
|
+
f"this cycle and the index read will fail."
|
|
701
|
+
)
|
|
702
|
+
|
|
703
|
+
@staticmethod
|
|
704
|
+
def _weak_message(
|
|
705
|
+
chemistry: Chemistry,
|
|
706
|
+
name: str | None,
|
|
707
|
+
cb: Any,
|
|
708
|
+
min_signal_fraction: float,
|
|
709
|
+
) -> str:
|
|
710
|
+
"""Human-readable message for a weak (warning) cycle on 2-/1-channel."""
|
|
711
|
+
no_red = (cb.red_fraction or 0.0) == 0.0
|
|
712
|
+
no_green = (cb.green_fraction or 0.0) == 0.0
|
|
713
|
+
if no_red or no_green:
|
|
714
|
+
present = "green" if no_red else "red"
|
|
715
|
+
return (
|
|
716
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
717
|
+
f"{cb.cycle} carries signal in only the {present} channel "
|
|
718
|
+
f"(base counts {cb.base_counts}). This meets Illumina's "
|
|
719
|
+
f"'at least one channel' minimum but is colour-imbalanced; "
|
|
720
|
+
f"enable conservative mode to treat it as a failure."
|
|
721
|
+
)
|
|
722
|
+
pct = round(min(cb.red_fraction or 0.0, cb.green_fraction or 0.0) * 100, 1)
|
|
723
|
+
return (
|
|
724
|
+
f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
|
|
725
|
+
f"{cb.cycle} carries weak signal in one channel (as low as {pct}% "
|
|
726
|
+
f"of the pool; recommended >= {round(min_signal_fraction * 100)}%), "
|
|
727
|
+
f"risking poor base calls for this cycle."
|
|
728
|
+
)
|
|
647
729
|
|
|
648
730
|
def _check_adapters(
|
|
649
731
|
self,
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: samplesheet-parser
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.5.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
|
|
@@ -429,8 +430,9 @@ for err in result.errors:
|
|
|
429
430
|
```
|
|
430
431
|
|
|
431
432
|
The chemistry is resolved from the instrument name; the check is **off by
|
|
432
|
-
default** (it can legitimately fail a low-plex pool) and
|
|
433
|
-
|
|
433
|
+
default** (it can legitimately fail a low-plex pool) and, for an unknown
|
|
434
|
+
instrument, is not run but reported as a `COLOR_BALANCE_SKIPPED` note rather than
|
|
435
|
+
passing silently. The same analysis is available standalone:
|
|
434
436
|
|
|
435
437
|
```python
|
|
436
438
|
from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
|
|
@@ -447,18 +449,42 @@ From the CLI:
|
|
|
447
449
|
```bash
|
|
448
450
|
samplesheet validate SampleSheet.csv --color-balance
|
|
449
451
|
samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
|
|
452
|
+
samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
|
|
450
453
|
```
|
|
451
454
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
455
|
+
When `--color-balance` is requested but the instrument cannot be resolved, the
|
|
456
|
+
check is not run (guessing the chemistry would be misleading). This is surfaced
|
|
457
|
+
as a `COLOR_BALANCE_SKIPPED` note (in text and JSON output) rather than a silent
|
|
458
|
+
pass, so a clean result is never mistaken for a passed color-balance check. Pass
|
|
459
|
+
`--instrument` to enable the check.
|
|
460
|
+
|
|
461
|
+
#### Modes: `vendor_faithful` (default) and `conservative`
|
|
462
|
+
|
|
463
|
+
Color balance has two modes, selectable on the CLI via
|
|
464
|
+
`--color-balance-mode {vendor_faithful,conservative}` or in the library via
|
|
465
|
+
`validate(..., color_balance_mode=...)` / `analyze_color_balance(..., mode=...)`:
|
|
466
|
+
|
|
467
|
+
- **`vendor_faithful`** (default) encodes each platform's *published* rule
|
|
468
|
+
exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
|
|
469
|
+
the both-lasers rule for 4-channel, and Element's permissive low-diversity
|
|
470
|
+
stance for AVITI.
|
|
471
|
+
- **`conservative`** is stricter than the published minimum: it also fails
|
|
472
|
+
single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
|
|
473
|
+
behavior before modes existed — pass `color_balance_mode="conservative"` to
|
|
474
|
+
keep it.)
|
|
475
|
+
|
|
476
|
+
| Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
|
|
477
|
+
|---|---|---|---|
|
|
478
|
+
| 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
|
|
479
|
+
| 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
|
|
480
|
+
| 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
|
|
481
|
+
| avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
|
|
482
|
+
|
|
483
|
+
Element AVITI uses avidity chemistry — each base has its own avidite dye
|
|
484
|
+
([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
|
|
485
|
+
— so it has no dark base and no laser-pair constraint. In `vendor_faithful`
|
|
486
|
+
mode, AVITI low diversity in the first cycles is an advisory
|
|
487
|
+
(`COLOR_BALANCE_ADVISORY`), never a failure.
|
|
462
488
|
|
|
463
489
|
---
|
|
464
490
|
|
|
@@ -785,14 +811,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
|
|
|
785
811
|
|
|
786
812
|
```bibtex
|
|
787
813
|
@software{kasaraneni2026samplesheetparser,
|
|
788
|
-
author = {Kasaraneni, Chaitanya},
|
|
789
|
-
title = {samplesheet-parser:
|
|
814
|
+
author = {Kasaraneni, Chaitanya Krishna},
|
|
815
|
+
title = {samplesheet-parser: A multi-vendor parser, validator, and converter for sequencing sample sheets},
|
|
790
816
|
year = {2026},
|
|
791
817
|
url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
|
|
792
|
-
|
|
818
|
+
doi = {10.5281/zenodo.18989694},
|
|
819
|
+
version = {2.4.0}
|
|
793
820
|
}
|
|
794
821
|
```
|
|
795
822
|
|
|
823
|
+
See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
|
|
824
|
+
|
|
796
825
|
---
|
|
797
826
|
|
|
798
827
|
## License
|
|
@@ -801,6 +830,15 @@ Apache 2.0 — see [LICENSE](LICENSE).
|
|
|
801
830
|
|
|
802
831
|
---
|
|
803
832
|
|
|
833
|
+
## AI-assisted development
|
|
834
|
+
|
|
835
|
+
Parts of this project's code, tests, and documentation were developed with the
|
|
836
|
+
assistance of generative AI tools (including GitHub Copilot). All AI-generated
|
|
837
|
+
output was reviewed, edited, and verified by the author, who is responsible for
|
|
838
|
+
the correctness of the final software.
|
|
839
|
+
|
|
840
|
+
---
|
|
841
|
+
|
|
804
842
|
## Related resources
|
|
805
843
|
|
|
806
844
|
- [Illumina IEM V1 SampleSheet reference (Knowledge Article #2204)](https://knowledge.illumina.com/software/on-premises-software/software-on-premises-software-reference_material-list/000002204)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
samplesheet_parser/__init__.py,sha256=
|
|
2
|
-
samplesheet_parser/chemistry.py,sha256=
|
|
3
|
-
samplesheet_parser/cli.py,sha256=
|
|
1
|
+
samplesheet_parser/__init__.py,sha256=eSlshig-sXWyxW70vbd__lu9u6nfqVTyv-48MUsmiZg,2890
|
|
2
|
+
samplesheet_parser/chemistry.py,sha256=1I6jxzCmZqNqHitUzWQWo3JnuVHdASTVNUu-6jU4eoE,17631
|
|
3
|
+
samplesheet_parser/cli.py,sha256=GbYL0tTHP5ofGXLPVPzR5CNWVarUolzdoyOqsDl2WPg,31993
|
|
4
4
|
samplesheet_parser/converter.py,sha256=g4s5R6iB5mPDF-e8JD4Iezt2dMBBxgQ-OPL9vxJ2zM0,20236
|
|
5
5
|
samplesheet_parser/diff.py,sha256=RruQhKRi0Ja6x5pq8CA-yafJ4JQJ3p0JXDp68RS53GE,15369
|
|
6
6
|
samplesheet_parser/enums.py,sha256=SqxE5sRjBGRGk2J6lxpkgxb6luEqBTcdalok5lDFUS0,1790
|
|
@@ -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=hiMI8mFpmSmba2stIWBXwFFXL_Ldjn2QAT1lwdCAJxI,31124
|
|
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.5.0.dist-info/METADATA,sha256=gxmeIQzX8iqquCjsX1G45_5urIVd6l00z0G4Nd_zTzs,33619
|
|
22
|
+
samplesheet_parser-2.5.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
|
|
23
|
+
samplesheet_parser-2.5.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
|
|
24
|
+
samplesheet_parser-2.5.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
|
|
25
|
+
samplesheet_parser-2.5.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|