samplesheet-parser 2.2.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.
@@ -2,11 +2,12 @@
2
2
  samplesheet-parser
3
3
  ====================
4
4
 
5
- Format-agnostic parser for Illumina SampleSheet.csv files.
5
+ Multi-vendor, format-agnostic parser for sequencing sample sheets.
6
6
 
7
7
  Supports:
8
8
  - Illumina Experiment Manager (IEM) V1 format - bcl2fastq era
9
9
  - BCLConvert V2 format - NovaSeq X / modern era
10
+ - Element Biosciences AVITI RunManifest.csv - non-Illumina, avidity chemistry
10
11
 
11
12
  Quickstart
12
13
  ----------
@@ -32,6 +33,13 @@ __author__ = "Chaitanya Kasaraneni"
32
33
  __email__ = "kc.kasaraneni@gmail.com"
33
34
  __license__ = "Apache 2.0"
34
35
 
36
+ from samplesheet_parser.chemistry import (
37
+ Chemistry,
38
+ ColorBalanceMode,
39
+ ColorBalanceReport,
40
+ analyze_color_balance,
41
+ chemistry_for_instrument,
42
+ )
35
43
  from samplesheet_parser.converter import SampleSheetConverter
36
44
  from samplesheet_parser.diff import DiffResult, SampleSheetDiff
37
45
  from samplesheet_parser.enums import IndexType, InstrumentPlatform, SampleSheetVersion, UMILocation
@@ -39,6 +47,7 @@ from samplesheet_parser.factory import SampleSheetFactory
39
47
  from samplesheet_parser.filter import FilterResult, SampleSheetFilter
40
48
  from samplesheet_parser.index_utils import normalize_index_lengths
41
49
  from samplesheet_parser.merger import MergeResult, SampleSheetMerger
50
+ from samplesheet_parser.parsers.element import ElementRunManifest
42
51
  from samplesheet_parser.parsers.v1 import SampleSheetV1
43
52
  from samplesheet_parser.parsers.v2 import SampleSheetV2
44
53
  from samplesheet_parser.protocol import SampleSheetParser
@@ -54,6 +63,7 @@ from samplesheet_parser.writer import SampleSheetWriter
54
63
  __all__ = [
55
64
  "SampleSheetV1",
56
65
  "SampleSheetV2",
66
+ "ElementRunManifest",
57
67
  "SampleSheetFactory",
58
68
  "SampleSheetParser",
59
69
  "SampleSheetVersion",
@@ -64,6 +74,11 @@ __all__ = [
64
74
  "ValidationResult",
65
75
  "hamming_distance",
66
76
  "index_collision_distance",
77
+ "Chemistry",
78
+ "ColorBalanceMode",
79
+ "ColorBalanceReport",
80
+ "analyze_color_balance",
81
+ "chemistry_for_instrument",
67
82
  "SampleSheetConverter",
68
83
  "SampleSheetDiff",
69
84
  "DiffResult",
@@ -0,0 +1,467 @@
1
+ """
2
+ Sequencing chemistry channel models and index colour-balance analysis.
3
+
4
+ Illumina (and Element) instruments call bases by detecting fluorescent
5
+ signal in one, two, or four optical channels per cycle. The number of
6
+ channels determines how a base is encoded as *signal*, and that in turn
7
+ determines what makes a pool of indexes safe to sequence together:
8
+
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.
20
+
21
+ * **2-channel SBS** (NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq) - two
22
+ images (nominally "red" and "green") are captured and the base is
23
+ inferred from which channels light up::
24
+
25
+ A -> red + green C -> red only
26
+ T -> green only G -> dark (no signal in either channel)
27
+
28
+ Because **G is a dark base**, a cycle in which the whole pool reads G
29
+ produces no signal at all: the instrument cannot register the tile and
30
+ the cycle (often the whole index read) fails. Even a cycle that is only
31
+ *mostly* G - leaving little red or green signal - calls bases poorly.
32
+
33
+ * **1-channel SBS** (iSeq 100) - a single image with a two-step chemistry.
34
+ G is again a permanently dark base, so the same "no-signal" risk applies.
35
+
36
+ This module exposes the channel model for each chemistry, a mapping from
37
+ instrument name to chemistry, and :func:`analyze_color_balance`, which
38
+ scores an index pool cycle-by-cycle and reports dark cycles and weak
39
+ channels. :class:`~samplesheet_parser.validators.SampleSheetValidator`
40
+ consumes it to emit ``COLOR_BALANCE_NO_SIGNAL`` / ``COLOR_BALANCE_LOW``
41
+ findings.
42
+
43
+ Authors
44
+ -------
45
+ Chaitanya Kasaraneni
46
+ """
47
+
48
+ from __future__ import annotations
49
+
50
+ from dataclasses import dataclass, field
51
+ from enum import Enum
52
+
53
+ from samplesheet_parser.instruments import _normalize
54
+
55
+ # Default minimum fraction of the pool that must produce signal in each
56
+ # optical channel at every index cycle. Below this (but above zero) the
57
+ # cycle is flagged as weak; exactly zero is flagged as a dark/no-signal
58
+ # cycle. 0.10 is a heuristic (not a published vendor number); Illumina's
59
+ # stated rule is qualitative.
60
+ DEFAULT_MIN_SIGNAL_FRACTION = 0.10
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
+
68
+
69
+ class Chemistry(str, Enum):
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
+ """
83
+
84
+ ONE_CHANNEL = "1-channel"
85
+ TWO_CHANNEL = "2-channel"
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"
101
+
102
+
103
+ # ---------------------------------------------------------------------------
104
+ # Per-base signal model
105
+ # ---------------------------------------------------------------------------
106
+
107
+ # For 1- and 2-channel chemistries, each base is encoded as the pair
108
+ # (red_channel_on, green_channel_on). ``G`` is the dark base in both
109
+ # chemistries. ``N`` is unknown and treated as contributing no guaranteed
110
+ # signal (conservative - an N cycle cannot be relied on for balance).
111
+ _TWO_CHANNEL_SIGNAL: dict[str, tuple[bool, bool]] = {
112
+ "A": (True, True),
113
+ "C": (True, False),
114
+ "T": (False, True),
115
+ "G": (False, False),
116
+ }
117
+
118
+ # 1-channel (iSeq) uses two sequential exposures rather than two colours,
119
+ # but the balance-relevant behaviour is identical to 2-channel: A/C carry
120
+ # signal in the first exposure, A/T in the second, and G is dark in both.
121
+ _ONE_CHANNEL_SIGNAL = _TWO_CHANNEL_SIGNAL
122
+
123
+
124
+ # ---------------------------------------------------------------------------
125
+ # Instrument -> chemistry mapping
126
+ # ---------------------------------------------------------------------------
127
+
128
+ # Keys are normalised (lowercase, non-alphanumerics stripped) by
129
+ # ``instruments._normalize`` so "NovaSeq X Plus" and "novaseqxplus" match.
130
+ _INSTRUMENT_CHEMISTRY: dict[str, Chemistry] = {
131
+ # 4-channel
132
+ "miseq": Chemistry.FOUR_CHANNEL,
133
+ "hiseq2000": Chemistry.FOUR_CHANNEL,
134
+ "hiseq2500": Chemistry.FOUR_CHANNEL,
135
+ "hiseq3000": Chemistry.FOUR_CHANNEL,
136
+ "hiseq4000": 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,
144
+ # 2-channel
145
+ "nextseq500": Chemistry.TWO_CHANNEL,
146
+ "nextseq550": Chemistry.TWO_CHANNEL,
147
+ "nextseq1000": Chemistry.TWO_CHANNEL,
148
+ "nextseq2000": Chemistry.TWO_CHANNEL,
149
+ "nextseq10002000": Chemistry.TWO_CHANNEL,
150
+ "novaseq6000": Chemistry.TWO_CHANNEL,
151
+ "novaseq": Chemistry.TWO_CHANNEL,
152
+ "novaseqx": Chemistry.TWO_CHANNEL,
153
+ "novaseqxplus": Chemistry.TWO_CHANNEL,
154
+ "novaseqxseries": Chemistry.TWO_CHANNEL,
155
+ "miniseq": Chemistry.TWO_CHANNEL,
156
+ # 1-channel
157
+ "iseq": Chemistry.ONE_CHANNEL,
158
+ "iseq100": Chemistry.ONE_CHANNEL,
159
+ }
160
+
161
+
162
+ def chemistry_for_instrument(instrument: str | None) -> Chemistry | None:
163
+ """Return the optical :class:`Chemistry` for an instrument name.
164
+
165
+ Parameters
166
+ ----------
167
+ instrument:
168
+ Free-form instrument name from a sample sheet header
169
+ (``InstrumentPlatform`` in V2, ``Instrument Type`` in V1, or a
170
+ vendor-specific field). Matched case- and punctuation-insensitively.
171
+
172
+ Returns
173
+ -------
174
+ Chemistry | None
175
+ The chemistry, or ``None`` if *instrument* is empty or unrecognised
176
+ (in which case callers should skip colour-balance checking rather
177
+ than guess).
178
+
179
+ Examples
180
+ --------
181
+ >>> chemistry_for_instrument("NovaSeq X Plus")
182
+ <Chemistry.TWO_CHANNEL: '2-channel'>
183
+ >>> chemistry_for_instrument("MiSeq")
184
+ <Chemistry.FOUR_CHANNEL: '4-channel'>
185
+ >>> chemistry_for_instrument("Unknown") is None
186
+ True
187
+ """
188
+ if not instrument:
189
+ return None
190
+ return _INSTRUMENT_CHEMISTRY.get(_normalize(instrument))
191
+
192
+
193
+ # ---------------------------------------------------------------------------
194
+ # Colour-balance analysis
195
+ # ---------------------------------------------------------------------------
196
+
197
+
198
+ @dataclass
199
+ class CycleBalance:
200
+ """Per-cycle colour-balance diagnostics for one index read position.
201
+
202
+ Attributes
203
+ ----------
204
+ read:
205
+ ``"index1"`` or ``"index2"`` - which index read this cycle belongs to.
206
+ cycle:
207
+ 1-based cycle position within that index read.
208
+ base_counts:
209
+ Count of each base (``A``/``C``/``G``/``T``/``N``) across the pool at
210
+ this cycle.
211
+ red_fraction, green_fraction:
212
+ Fraction of the pool producing signal in each channel (2-/1-channel
213
+ only). ``None`` for 4-channel chemistry.
214
+ distinct_bases:
215
+ Number of distinct non-``N`` bases observed (used for 4-channel
216
+ low-diversity detection).
217
+ pool_size:
218
+ Number of samples contributing a base at this cycle.
219
+ """
220
+
221
+ read: str
222
+ cycle: int
223
+ base_counts: dict[str, int]
224
+ pool_size: int
225
+ red_fraction: float | None = None
226
+ green_fraction: float | None = None
227
+ distinct_bases: int = 0
228
+
229
+ @property
230
+ def is_dark(self) -> bool:
231
+ """True if a channel has zero signal (2-/1-channel) - a failed cycle."""
232
+ if self.red_fraction is None or self.green_fraction is None:
233
+ return False
234
+ return self.red_fraction == 0.0 or self.green_fraction == 0.0
235
+
236
+
237
+ @dataclass
238
+ class ColorBalanceReport:
239
+ """Result of :func:`analyze_color_balance`.
240
+
241
+ Attributes
242
+ ----------
243
+ chemistry:
244
+ The chemistry the pool was scored against.
245
+ cycles:
246
+ Per-cycle diagnostics across both index reads.
247
+ dark_cycles:
248
+ Cycles with no signal in at least one channel (guaranteed failure).
249
+ weak_cycles:
250
+ Cycles with signal below ``min_signal_fraction`` in some channel, or
251
+ single-base cycles for 4-channel chemistry (degraded quality).
252
+ pool_size:
253
+ Number of samples analysed.
254
+ """
255
+
256
+ chemistry: Chemistry
257
+ pool_size: int
258
+ mode: ColorBalanceMode = ColorBalanceMode.VENDOR_FAITHFUL
259
+ cycles: list[CycleBalance] = field(default_factory=list)
260
+ dark_cycles: list[CycleBalance] = field(default_factory=list)
261
+ weak_cycles: list[CycleBalance] = field(default_factory=list)
262
+ advisory_cycles: list[CycleBalance] = field(default_factory=list)
263
+
264
+ @property
265
+ def is_balanced(self) -> bool:
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
273
+
274
+
275
+ def _column_bases(indexes: list[str], cycle: int) -> dict[str, int]:
276
+ """Count bases at a 0-based ``cycle`` across indexes long enough to reach it."""
277
+ counts: dict[str, int] = {}
278
+ for seq in indexes:
279
+ if cycle < len(seq):
280
+ base = seq[cycle].upper()
281
+ counts[base] = counts.get(base, 0) + 1
282
+ return counts
283
+
284
+
285
+ def analyze_color_balance(
286
+ index1: list[str],
287
+ index2: list[str] | None = None,
288
+ *,
289
+ chemistry: Chemistry,
290
+ mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
291
+ min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
292
+ ) -> ColorBalanceReport:
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.
313
+
314
+ Parameters
315
+ ----------
316
+ index1, index2:
317
+ I7 (and optional I5) index sequences; empty strings are ignored.
318
+ chemistry:
319
+ Chemistry to score against - see :func:`chemistry_for_instrument`.
320
+ mode:
321
+ :class:`ColorBalanceMode` (or its string value). Defaults to
322
+ ``VENDOR_FAITHFUL``.
323
+ min_signal_fraction:
324
+ Soft threshold below which an otherwise-present channel is flagged weak
325
+ (heuristic; not a published vendor number).
326
+
327
+ Returns
328
+ -------
329
+ ColorBalanceReport
330
+ Per-cycle diagnostics with dark (failing), weak (warning), and advisory
331
+ cycles collected separately.
332
+ """
333
+ mode = ColorBalanceMode(mode)
334
+ conservative = mode is ColorBalanceMode.CONSERVATIVE
335
+
336
+ reads: list[tuple[str, list[str]]] = [("index1", [s for s in index1 if s])]
337
+ if index2 is not None:
338
+ reads.append(("index2", [s for s in index2 if s]))
339
+
340
+ report = ColorBalanceReport(
341
+ chemistry=chemistry,
342
+ pool_size=len([s for s in index1 if s]),
343
+ mode=mode,
344
+ )
345
+
346
+ for read_name, seqs in reads:
347
+ if not seqs:
348
+ continue
349
+ max_len = max(len(s) for s in seqs)
350
+ for c in range(max_len):
351
+ counts = _column_bases(seqs, c)
352
+ pool = sum(counts.values())
353
+ if pool == 0:
354
+ continue
355
+
356
+ cb = CycleBalance(
357
+ read=read_name,
358
+ cycle=c + 1,
359
+ base_counts=counts,
360
+ pool_size=pool,
361
+ distinct_bases=len([b for b in counts if b != "N"]),
362
+ )
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
+
370
+ if chemistry is Chemistry.FOUR_CHANNEL:
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
+ )
383
+
384
+ report.cycles.append(cb)
385
+
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
@@ -263,6 +263,28 @@ if _TYPER_AVAILABLE:
263
263
  metavar="N",
264
264
  ),
265
265
  ] = _MIN_HAMMING_DEFAULT,
266
+ color_balance: Annotated[
267
+ bool,
268
+ typer.Option(
269
+ "--color-balance/--no-color-balance",
270
+ help=(
271
+ "Also check per-cycle index colour balance against the "
272
+ "instrument's optical chemistry (flags dark/no-signal "
273
+ "cycles on 2-/1-channel instruments). Off by default."
274
+ ),
275
+ ),
276
+ ] = False,
277
+ instrument: Annotated[
278
+ str | None,
279
+ typer.Option(
280
+ "--instrument",
281
+ help=(
282
+ "Instrument name for the colour-balance check, overriding "
283
+ "the sheet header (e.g. 'NovaSeqXSeries', 'MiSeq')."
284
+ ),
285
+ metavar="NAME",
286
+ ),
287
+ ] = None,
266
288
  ) -> None:
267
289
  """Validate a sample sheet for index, adapter, and structural issues.
268
290
 
@@ -292,7 +314,12 @@ if _TYPER_AVAILABLE:
292
314
  raise RuntimeError("SampleSheetFactory.version must be set after create_parser")
293
315
  version = factory.version
294
316
 
295
- result = SampleSheetValidator().validate(sheet, min_hamming_distance=min_hamming)
317
+ result = SampleSheetValidator().validate(
318
+ sheet,
319
+ min_hamming_distance=min_hamming,
320
+ check_color_balance=color_balance,
321
+ instrument=instrument,
322
+ )
296
323
 
297
324
  if fmt == "json":
298
325
  _print_json(
@@ -301,6 +328,7 @@ if _TYPER_AVAILABLE:
301
328
  "version": version.value,
302
329
  "is_valid": result.is_valid,
303
330
  "min_hamming_distance": min_hamming,
331
+ "color_balance_checked": color_balance,
304
332
  "errors": [
305
333
  {"code": e.code, "message": e.message, "context": e.context}
306
334
  for e in result.errors
@@ -408,8 +436,7 @@ if _TYPER_AVAILABLE:
408
436
  )
409
437
  else:
410
438
  typer.echo(
411
- f"Converted {path.name} ({converter.source_version.value})"
412
- f" → {out} ({target.value})"
439
+ f"Converted {path.name} ({converter.source_version.value}) → {out} ({target.value})"
413
440
  )
414
441
 
415
442
  # ---------------------------------------------------------------------------
@@ -20,6 +20,13 @@ class SampleSheetVersion(str, Enum):
20
20
 
21
21
  V1 = "V1"
22
22
  V2 = "V2"
23
+ ELEMENT_AVITI = "ElementAVITI"
24
+ """Element Biosciences AVITI ``RunManifest.csv`` (non-Illumina vendor).
25
+
26
+ Detected by the presence of a ``[SAMPLES]`` section together with a
27
+ ``[RUNVALUES]`` section or a ``SampleName``/``Index1`` column layout.
28
+ Parsed by :class:`~samplesheet_parser.parsers.element.ElementRunManifest`.
29
+ """
23
30
 
24
31
 
25
32
  class IndexType(str, Enum):
@@ -48,6 +48,7 @@ from pathlib import Path
48
48
  from typing import Any
49
49
 
50
50
  from samplesheet_parser.enums import SampleSheetVersion
51
+ from samplesheet_parser.parsers.element import ElementRunManifest
51
52
  from samplesheet_parser.parsers.v1 import SampleSheetV1
52
53
  from samplesheet_parser.parsers.v2 import SampleSheetV2
53
54
  from samplesheet_parser.protocol import SampleSheetParser
@@ -116,7 +117,7 @@ class SampleSheetFactory:
116
117
  """
117
118
  cls._registry.insert(0, (detector, parser_class, version))
118
119
  logger.debug(
119
- f"Registered custom parser {parser_class.__name__!r} " f"for version {version.value!r}."
120
+ f"Registered custom parser {parser_class.__name__!r} for version {version.value!r}."
120
121
  )
121
122
 
122
123
  @classmethod
@@ -190,6 +191,15 @@ class SampleSheetFactory:
190
191
  except Exception as exc:
191
192
  logger.debug(f"Custom detector {detector!r} raised {exc!r} for {path} - skipping.")
192
193
 
194
+ # Built-in non-Illumina vendor detection. Run as a first-class step
195
+ # (not via the clearable registry) so it survives clear_registry().
196
+ if ElementRunManifest.is_manifest(path):
197
+ logger.info("Detected Element AVITI RunManifest - using ElementRunManifest")
198
+ self.version = SampleSheetVersion.ELEMENT_AVITI
199
+ element_parser: SampleSheetParser = ElementRunManifest(path, **kwargs)
200
+ self.parser = element_parser
201
+ return element_parser
202
+
193
203
  # Built-in V1/V2 detection.
194
204
  detected = self._detect_version(path)
195
205
  self.version = detected