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.
@@ -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",
@@ -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, and Element AVITI) -
10
- each base has its own dye, so any base produces signal. Illumina images
11
- four colours per cycle; Element's avidity chemistry likewise captures
12
- four images per cycle, one per avidite dye (Arslan et al., *Nat.
13
- Biotechnol.* 2023), so the AVITI is a four-channel platform with no dark
14
- base. The only real risk is *low diversity*: if every sample reads the
15
- same base at a cycle, the instrument struggles to focus and phase,
16
- degrading base-call quality.
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 mirrors Illumina low-plex pooling guidance (each channel
56
- # should carry meaningful signal, not a single stray sample).
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 captures four images per
103
- # cycle (one per avidite dye), so it is a four-channel platform with no
104
- # dark base. Ref: Arslan et al., Nat. Biotechnol. 2023.
105
- "aviti": Chemistry.FOUR_CHANNEL,
106
- "elementaviti": Chemistry.FOUR_CHANNEL,
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 or weak cycles were found."""
228
- return not self.dark_cycles and not self.weak_cycles
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
- The pool is analysed cycle-by-cycle. For 2-channel and 1-channel
251
- chemistries each cycle is checked for red and green signal: a channel
252
- with no contributing sample is a *dark cycle* (the run will fail to
253
- register), and a channel below *min_signal_fraction* is a *weak cycle*.
254
- For 4-channel chemistry, a cycle where the whole pool reads a single
255
- base is flagged as weak (low diversity degrades focusing and phasing).
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 index sequences, one per sample (empty strings are ignored).
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
- Minimum fraction of the pool that must light each channel at every
267
- cycle before the cycle is flagged weak. Defaults to
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 plus collected dark and weak cycles.
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
- # Any base produces signal; only flag total lack of diversity.
304
- if cb.distinct_bases <= 1 and pool >= 2:
305
- report.weak_cycles.append(cb)
306
- else:
307
- red = green = 0
308
- for base, n in counts.items():
309
- sig = _TWO_CHANNEL_SIGNAL.get(base)
310
- if sig is None:
311
- continue # N or unexpected char: no guaranteed signal
312
- if sig[0]:
313
- red += n
314
- if sig[1]:
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
@@ -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 (4-/2-/1-channel) and scores
558
- the index pool per cycle. On 2-/1-channel chemistry a cycle where the
559
- whole pool is dark (all ``G``) in a channel produces no signal and is
560
- reported as ``COLOR_BALANCE_NO_SIGNAL`` (error); a cycle with signal
561
- below *min_signal_fraction* in some channel is ``COLOR_BALANCE_LOW``
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
- f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
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
- if chemistry is Chemistry.FOUR_CHANNEL:
618
- base = next(iter(cb.base_counts))
619
- result.add_warning(
620
- "COLOR_BALANCE_LOW",
621
- f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
622
- f"{cb.cycle} has no base diversity (every sample reads "
623
- f"'{base}'), which degrades focusing and phasing.",
624
- instrument=name,
625
- chemistry=chemistry.value,
626
- read=cb.read,
627
- cycle=cb.cycle,
628
- base_counts=cb.base_counts,
629
- )
630
- else:
631
- pct = round(min(cb.red_fraction or 0.0, cb.green_fraction or 0.0) * 100, 1)
632
- result.add_warning(
633
- "COLOR_BALANCE_LOW",
634
- f"On {chemistry.value} chemistry ({name}), {cb.read} cycle "
635
- f"{cb.cycle} carries weak signal in one channel "
636
- f"(as low as {pct}% of the pool; recommended "
637
- f"≥ {round(min_signal_fraction * 100)}%), risking poor "
638
- f"base calls for this cycle.",
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
- )
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.0
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://illumina-samplesheet.readthedocs.io
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
- **Format-agnostic parser for Illumina SampleSheet.csv files.**
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
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
69
69
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
70
- [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
70
+ [![Docs](https://readthedocs.org/projects/samplesheet-parser/badge/)](https://samplesheet-parser.readthedocs.io)
71
71
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
72
72
 
73
- **Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
73
+ **Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
74
74
 
75
- ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
75
+ ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v2.3.png)
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 uses a three-step detection strategy — no format hints required from the caller:
348
+ The factory detects the format across vendors — no format hints required from the caller:
349
349
 
350
- 1. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
351
- 2. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
352
- 3. **Default** — fall back to V1 (broadest compatibility with legacy files)
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
- The detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
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: it transposes the indexes into columns and checks that
414
- each column produces signal in both channels.
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
- | Chemistry | Instruments | What is flagged |
453
- |---|---|---|
454
- | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000, Element AVITI | Zero-diversity cycles (warning) |
455
- | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | Dark cycles / weak channels |
456
- | 1-channel | iSeq 100 | Dark cycles / weak channels |
457
-
458
- Element AVITI uses four-channel avidity chemistry (four images per cycle, one
459
- per avidite dye — [Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7)),
460
- so it has no dark base; color-balance checking flags low-diversity index
461
- cycles rather than dark cycles.
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: Format-agnostic parser for Illumina SampleSheet.csv},
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
- version = {1.1.0}
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=nfBobOHN_aX9thGcCtyJoduIlL4DUeViqjBtadmLQ58,2844
2
- samplesheet_parser/chemistry.py,sha256=EoT4q-d9PYwLiZ20T4B3-Pb5keGNRsw_BIvboZ8ryN0,12369
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=pRHddhJJyCuN21zEIFkHMuBHMMxzCRyLOo2QsZcjFtA,27334
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.3.0.dist-info/METADATA,sha256=jX2nAR33oGB7r_Ng1mfKVQG_bPBi5HtxKzb3f5RAAKA,31370
22
- samplesheet_parser-2.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
23
- samplesheet_parser-2.3.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
24
- samplesheet_parser-2.3.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
25
- samplesheet_parser-2.3.0.dist-info/RECORD,,
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,,