samplesheet-parser 2.1.0__py3-none-any.whl → 2.3.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,12 @@ __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
+ ColorBalanceReport,
39
+ analyze_color_balance,
40
+ chemistry_for_instrument,
41
+ )
35
42
  from samplesheet_parser.converter import SampleSheetConverter
36
43
  from samplesheet_parser.diff import DiffResult, SampleSheetDiff
37
44
  from samplesheet_parser.enums import IndexType, InstrumentPlatform, SampleSheetVersion, UMILocation
@@ -39,6 +46,7 @@ from samplesheet_parser.factory import SampleSheetFactory
39
46
  from samplesheet_parser.filter import FilterResult, SampleSheetFilter
40
47
  from samplesheet_parser.index_utils import normalize_index_lengths
41
48
  from samplesheet_parser.merger import MergeResult, SampleSheetMerger
49
+ from samplesheet_parser.parsers.element import ElementRunManifest
42
50
  from samplesheet_parser.parsers.v1 import SampleSheetV1
43
51
  from samplesheet_parser.parsers.v2 import SampleSheetV2
44
52
  from samplesheet_parser.protocol import SampleSheetParser
@@ -54,6 +62,7 @@ from samplesheet_parser.writer import SampleSheetWriter
54
62
  __all__ = [
55
63
  "SampleSheetV1",
56
64
  "SampleSheetV2",
65
+ "ElementRunManifest",
57
66
  "SampleSheetFactory",
58
67
  "SampleSheetParser",
59
68
  "SampleSheetVersion",
@@ -64,6 +73,10 @@ __all__ = [
64
73
  "ValidationResult",
65
74
  "hamming_distance",
66
75
  "index_collision_distance",
76
+ "Chemistry",
77
+ "ColorBalanceReport",
78
+ "analyze_color_balance",
79
+ "chemistry_for_instrument",
67
80
  "SampleSheetConverter",
68
81
  "SampleSheetDiff",
69
82
  "DiffResult",
@@ -0,0 +1,335 @@
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** (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.
17
+
18
+ * **2-channel SBS** (NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq) - two
19
+ images (nominally "red" and "green") are captured and the base is
20
+ inferred from which channels light up::
21
+
22
+ A -> red + green C -> red only
23
+ T -> green only G -> dark (no signal in either channel)
24
+
25
+ Because **G is a dark base**, a cycle in which the whole pool reads G
26
+ produces no signal at all: the instrument cannot register the tile and
27
+ the cycle (often the whole index read) fails. Even a cycle that is only
28
+ *mostly* G - leaving little red or green signal - calls bases poorly.
29
+
30
+ * **1-channel SBS** (iSeq 100) - a single image with a two-step chemistry.
31
+ G is again a permanently dark base, so the same "no-signal" risk applies.
32
+
33
+ This module exposes the channel model for each chemistry, a mapping from
34
+ instrument name to chemistry, and :func:`analyze_color_balance`, which
35
+ scores an index pool cycle-by-cycle and reports dark cycles and weak
36
+ channels. :class:`~samplesheet_parser.validators.SampleSheetValidator`
37
+ consumes it to emit ``COLOR_BALANCE_NO_SIGNAL`` / ``COLOR_BALANCE_LOW``
38
+ findings.
39
+
40
+ Authors
41
+ -------
42
+ Chaitanya Kasaraneni
43
+ """
44
+
45
+ from __future__ import annotations
46
+
47
+ from dataclasses import dataclass, field
48
+ from enum import Enum
49
+
50
+ from samplesheet_parser.instruments import _normalize
51
+
52
+ # Default minimum fraction of the pool that must produce signal in each
53
+ # optical channel at every index cycle. Below this (but above zero) the
54
+ # 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).
57
+ DEFAULT_MIN_SIGNAL_FRACTION = 0.10
58
+
59
+
60
+ class Chemistry(str, Enum):
61
+ """Optical detection chemistry of a sequencing instrument."""
62
+
63
+ ONE_CHANNEL = "1-channel"
64
+ TWO_CHANNEL = "2-channel"
65
+ FOUR_CHANNEL = "4-channel"
66
+
67
+
68
+ # ---------------------------------------------------------------------------
69
+ # Per-base signal model
70
+ # ---------------------------------------------------------------------------
71
+
72
+ # For 1- and 2-channel chemistries, each base is encoded as the pair
73
+ # (red_channel_on, green_channel_on). ``G`` is the dark base in both
74
+ # chemistries. ``N`` is unknown and treated as contributing no guaranteed
75
+ # signal (conservative - an N cycle cannot be relied on for balance).
76
+ _TWO_CHANNEL_SIGNAL: dict[str, tuple[bool, bool]] = {
77
+ "A": (True, True),
78
+ "C": (True, False),
79
+ "T": (False, True),
80
+ "G": (False, False),
81
+ }
82
+
83
+ # 1-channel (iSeq) uses two sequential exposures rather than two colours,
84
+ # but the balance-relevant behaviour is identical to 2-channel: A/C carry
85
+ # signal in the first exposure, A/T in the second, and G is dark in both.
86
+ _ONE_CHANNEL_SIGNAL = _TWO_CHANNEL_SIGNAL
87
+
88
+
89
+ # ---------------------------------------------------------------------------
90
+ # Instrument -> chemistry mapping
91
+ # ---------------------------------------------------------------------------
92
+
93
+ # Keys are normalised (lowercase, non-alphanumerics stripped) by
94
+ # ``instruments._normalize`` so "NovaSeq X Plus" and "novaseqxplus" match.
95
+ _INSTRUMENT_CHEMISTRY: dict[str, Chemistry] = {
96
+ # 4-channel
97
+ "miseq": Chemistry.FOUR_CHANNEL,
98
+ "hiseq2000": Chemistry.FOUR_CHANNEL,
99
+ "hiseq2500": Chemistry.FOUR_CHANNEL,
100
+ "hiseq3000": Chemistry.FOUR_CHANNEL,
101
+ "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,
107
+ # 2-channel
108
+ "nextseq500": Chemistry.TWO_CHANNEL,
109
+ "nextseq550": Chemistry.TWO_CHANNEL,
110
+ "nextseq1000": Chemistry.TWO_CHANNEL,
111
+ "nextseq2000": Chemistry.TWO_CHANNEL,
112
+ "nextseq10002000": Chemistry.TWO_CHANNEL,
113
+ "novaseq6000": Chemistry.TWO_CHANNEL,
114
+ "novaseq": Chemistry.TWO_CHANNEL,
115
+ "novaseqx": Chemistry.TWO_CHANNEL,
116
+ "novaseqxplus": Chemistry.TWO_CHANNEL,
117
+ "novaseqxseries": Chemistry.TWO_CHANNEL,
118
+ "miniseq": Chemistry.TWO_CHANNEL,
119
+ # 1-channel
120
+ "iseq": Chemistry.ONE_CHANNEL,
121
+ "iseq100": Chemistry.ONE_CHANNEL,
122
+ }
123
+
124
+
125
+ def chemistry_for_instrument(instrument: str | None) -> Chemistry | None:
126
+ """Return the optical :class:`Chemistry` for an instrument name.
127
+
128
+ Parameters
129
+ ----------
130
+ instrument:
131
+ Free-form instrument name from a sample sheet header
132
+ (``InstrumentPlatform`` in V2, ``Instrument Type`` in V1, or a
133
+ vendor-specific field). Matched case- and punctuation-insensitively.
134
+
135
+ Returns
136
+ -------
137
+ Chemistry | None
138
+ The chemistry, or ``None`` if *instrument* is empty or unrecognised
139
+ (in which case callers should skip colour-balance checking rather
140
+ than guess).
141
+
142
+ Examples
143
+ --------
144
+ >>> chemistry_for_instrument("NovaSeq X Plus")
145
+ <Chemistry.TWO_CHANNEL: '2-channel'>
146
+ >>> chemistry_for_instrument("MiSeq")
147
+ <Chemistry.FOUR_CHANNEL: '4-channel'>
148
+ >>> chemistry_for_instrument("Unknown") is None
149
+ True
150
+ """
151
+ if not instrument:
152
+ return None
153
+ return _INSTRUMENT_CHEMISTRY.get(_normalize(instrument))
154
+
155
+
156
+ # ---------------------------------------------------------------------------
157
+ # Colour-balance analysis
158
+ # ---------------------------------------------------------------------------
159
+
160
+
161
+ @dataclass
162
+ class CycleBalance:
163
+ """Per-cycle colour-balance diagnostics for one index read position.
164
+
165
+ Attributes
166
+ ----------
167
+ read:
168
+ ``"index1"`` or ``"index2"`` - which index read this cycle belongs to.
169
+ cycle:
170
+ 1-based cycle position within that index read.
171
+ base_counts:
172
+ Count of each base (``A``/``C``/``G``/``T``/``N``) across the pool at
173
+ this cycle.
174
+ red_fraction, green_fraction:
175
+ Fraction of the pool producing signal in each channel (2-/1-channel
176
+ only). ``None`` for 4-channel chemistry.
177
+ distinct_bases:
178
+ Number of distinct non-``N`` bases observed (used for 4-channel
179
+ low-diversity detection).
180
+ pool_size:
181
+ Number of samples contributing a base at this cycle.
182
+ """
183
+
184
+ read: str
185
+ cycle: int
186
+ base_counts: dict[str, int]
187
+ pool_size: int
188
+ red_fraction: float | None = None
189
+ green_fraction: float | None = None
190
+ distinct_bases: int = 0
191
+
192
+ @property
193
+ def is_dark(self) -> bool:
194
+ """True if a channel has zero signal (2-/1-channel) - a failed cycle."""
195
+ if self.red_fraction is None or self.green_fraction is None:
196
+ return False
197
+ return self.red_fraction == 0.0 or self.green_fraction == 0.0
198
+
199
+
200
+ @dataclass
201
+ class ColorBalanceReport:
202
+ """Result of :func:`analyze_color_balance`.
203
+
204
+ Attributes
205
+ ----------
206
+ chemistry:
207
+ The chemistry the pool was scored against.
208
+ cycles:
209
+ Per-cycle diagnostics across both index reads.
210
+ dark_cycles:
211
+ Cycles with no signal in at least one channel (guaranteed failure).
212
+ weak_cycles:
213
+ Cycles with signal below ``min_signal_fraction`` in some channel, or
214
+ single-base cycles for 4-channel chemistry (degraded quality).
215
+ pool_size:
216
+ Number of samples analysed.
217
+ """
218
+
219
+ chemistry: Chemistry
220
+ pool_size: int
221
+ cycles: list[CycleBalance] = field(default_factory=list)
222
+ dark_cycles: list[CycleBalance] = field(default_factory=list)
223
+ weak_cycles: list[CycleBalance] = field(default_factory=list)
224
+
225
+ @property
226
+ 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
229
+
230
+
231
+ def _column_bases(indexes: list[str], cycle: int) -> dict[str, int]:
232
+ """Count bases at a 0-based ``cycle`` across indexes long enough to reach it."""
233
+ counts: dict[str, int] = {}
234
+ for seq in indexes:
235
+ if cycle < len(seq):
236
+ base = seq[cycle].upper()
237
+ counts[base] = counts.get(base, 0) + 1
238
+ return counts
239
+
240
+
241
+ def analyze_color_balance(
242
+ index1: list[str],
243
+ index2: list[str] | None = None,
244
+ *,
245
+ chemistry: Chemistry,
246
+ min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
247
+ ) -> 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).
256
+
257
+ Parameters
258
+ ----------
259
+ index1:
260
+ I7 index sequences, one per sample (empty strings are ignored).
261
+ index2:
262
+ Optional I5 index sequences, one per sample.
263
+ chemistry:
264
+ Chemistry to score against - see :func:`chemistry_for_instrument`.
265
+ 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`.
269
+
270
+ Returns
271
+ -------
272
+ ColorBalanceReport
273
+ Per-cycle diagnostics plus collected dark and weak cycles.
274
+ """
275
+ reads: list[tuple[str, list[str]]] = [("index1", [s for s in index1 if s])]
276
+ if index2 is not None:
277
+ reads.append(("index2", [s for s in index2 if s]))
278
+
279
+ report = ColorBalanceReport(
280
+ chemistry=chemistry,
281
+ pool_size=len([s for s in index1 if s]),
282
+ )
283
+
284
+ for read_name, seqs in reads:
285
+ if not seqs:
286
+ continue
287
+ max_len = max(len(s) for s in seqs)
288
+ for c in range(max_len):
289
+ counts = _column_bases(seqs, c)
290
+ pool = sum(counts.values())
291
+ if pool == 0:
292
+ continue
293
+
294
+ cb = CycleBalance(
295
+ read=read_name,
296
+ cycle=c + 1,
297
+ base_counts=counts,
298
+ pool_size=pool,
299
+ distinct_bases=len([b for b in counts if b != "N"]),
300
+ )
301
+
302
+ 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)
332
+
333
+ report.cycles.append(cb)
334
+
335
+ return report
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
@@ -0,0 +1,329 @@
1
+ """
2
+ Parser for Element Biosciences AVITI ``RunManifest.csv`` files.
3
+
4
+ The AVITI platform (Element Biosciences) is not an Illumina instrument, but
5
+ its run manifest is a sectioned CSV very much in the spirit of an Illumina
6
+ sample sheet, so it slots into this library through the structural
7
+ :class:`~samplesheet_parser.protocol.SampleSheetParser` protocol - no
8
+ inheritance from the Illumina parsers required. Registering it lets the same
9
+ factory, validator, and colour-balance machinery work across vendors.
10
+
11
+ Manifest layout
12
+ ---------------
13
+ A RunManifest is made of named sections, each introduced by a
14
+ ``[SectionName]`` line::
15
+
16
+ [RUNVALUES]
17
+ KeyName, Value
18
+ run_name, MyRun
19
+
20
+ [SETTINGS]
21
+ SettingName, Value
22
+ R1Adapter, AGATCGGAAGAGC
23
+
24
+ [SAMPLES]
25
+ SampleName, Index1, Index2, Lane
26
+ Sample1, ACGTACGTAC, TGCATGCATG, 1
27
+ Sample2, GGTTCCAAGG, CCAAGGTTCC, 1
28
+
29
+ ``[RUNVALUES]`` and ``[SETTINGS]`` are key/value tables; ``[SAMPLES]`` is a
30
+ columnar table. Column and key names are matched case-insensitively because
31
+ Element manifests are not strict about casing.
32
+
33
+ Field mapping to the shared sample record
34
+ -----------------------------------------
35
+ ================== =========================
36
+ RunManifest column Shared ``samples()`` key
37
+ ================== =========================
38
+ ``SampleName`` ``sample_id``
39
+ ``Index1`` ``index``
40
+ ``Index2`` ``index2``
41
+ ``Lane`` ``lane``
42
+ ``Project`` ``sample_project``
43
+ ================== =========================
44
+
45
+ Authors
46
+ -------
47
+ Chaitanya Kasaraneni
48
+ """
49
+
50
+ from __future__ import annotations
51
+
52
+ import csv
53
+ import logging
54
+ from pathlib import Path
55
+ from typing import Any
56
+
57
+ logger = logging.getLogger(__name__)
58
+
59
+ # Section names, lowercased.
60
+ _RUNVALUES = "runvalues"
61
+ _SETTINGS = "settings"
62
+ _SAMPLES = "samples"
63
+
64
+ # Manifest sample-column name (lowercased) -> shared record key.
65
+ _SAMPLE_COLUMN_MAP = {
66
+ "samplename": "sample_id",
67
+ "index1": "index",
68
+ "index2": "index2",
69
+ "lane": "lane",
70
+ "project": "sample_project",
71
+ }
72
+
73
+ # Settings keys (lowercased) that hold adapter sequences.
74
+ _ADAPTER_SETTING_KEYS = {"r1adapter", "r2adapter", "adapterread1", "adapterread2"}
75
+
76
+
77
+ def _split_sections(path: Path) -> dict[str, list[str]]:
78
+ """Split a manifest into ``{lowercased_section_name: [raw_lines]}``."""
79
+ sections: dict[str, list[str]] = {}
80
+ current: str | None = None
81
+ with open(path, encoding="utf-8-sig", newline="") as fh:
82
+ for raw in fh:
83
+ line = raw.rstrip("\n").rstrip("\r")
84
+ stripped = line.strip()
85
+ if not stripped:
86
+ continue
87
+ if stripped.startswith("[") and stripped.endswith("]"):
88
+ current = stripped[1:-1].strip().lower()
89
+ sections.setdefault(current, [])
90
+ continue
91
+ if current is not None:
92
+ sections[current].append(line)
93
+ return sections
94
+
95
+
96
+ def _parse_kv(lines: list[str]) -> dict[str, str]:
97
+ """Parse a key/value section, skipping an optional header row.
98
+
99
+ A leading row whose first cell is a generic label (``KeyName`` /
100
+ ``SettingName``) is treated as a header and dropped.
101
+ """
102
+ out: dict[str, str] = {}
103
+ for row in csv.reader(lines):
104
+ if not row:
105
+ continue
106
+ key = row[0].strip()
107
+ if not key:
108
+ continue
109
+ if key.lower() in ("keyname", "settingname") and len(out) == 0:
110
+ continue # header row
111
+ value = row[1].strip() if len(row) > 1 else ""
112
+ out[key] = value
113
+ return out
114
+
115
+
116
+ class ElementRunManifest:
117
+ """Parser for an Element Biosciences AVITI ``RunManifest.csv``.
118
+
119
+ Implements the :class:`~samplesheet_parser.protocol.SampleSheetParser`
120
+ protocol so it works with :class:`~samplesheet_parser.factory.SampleSheetFactory`,
121
+ :class:`~samplesheet_parser.validators.SampleSheetValidator`, and the
122
+ colour-balance checks. AVITI uses four-channel avidity chemistry, so
123
+ colour-balance validation flags low-diversity index cycles once the
124
+ instrument is resolved (the parser reports ``instrument = "AVITI"``
125
+ unless the manifest overrides it).
126
+
127
+ Parameters
128
+ ----------
129
+ path:
130
+ Path to the ``RunManifest.csv`` file.
131
+ clean:
132
+ Accepted for signature compatibility with the Illumina parsers; the
133
+ manifest parser already trims whitespace, so this is a no-op.
134
+ experiment_id:
135
+ Optional override stored on the instance for callers that key on it.
136
+ parse:
137
+ If truthy, parse immediately on construction (matches the factory's
138
+ ``parse=`` contract).
139
+ """
140
+
141
+ AUTO_PARSE: bool = False
142
+
143
+ def __init__(
144
+ self,
145
+ path: str | Path,
146
+ *,
147
+ clean: bool = True,
148
+ experiment_id: str | None = None,
149
+ parse: bool | None = None,
150
+ ) -> None:
151
+ self.path: str = str(path)
152
+ self.experiment_id = experiment_id
153
+
154
+ # Populated by parse()
155
+ self.header: dict[str, str] | None = None
156
+ self.settings: dict[str, str] | None = None
157
+ self.columns: list[str] | None = None
158
+ self.records: list[dict[str, str]] = []
159
+ self.adapters: list[str] = []
160
+ self.sections: list[str] = []
161
+ self.instrument: str | None = None
162
+ self._section_dict: dict[str, list[str]] = {}
163
+
164
+ if parse or (parse is None and self.AUTO_PARSE):
165
+ self.parse(do_clean=clean)
166
+
167
+ # ------------------------------------------------------------------
168
+ # Parsing
169
+ # ------------------------------------------------------------------
170
+
171
+ def parse(
172
+ self,
173
+ do_clean: bool = True,
174
+ required_sections: list[str] | None = None,
175
+ ) -> None:
176
+ """Read and parse the manifest sections.
177
+
178
+ Parameters
179
+ ----------
180
+ do_clean:
181
+ No-op; accepted for protocol compatibility.
182
+ required_sections:
183
+ Section names that must be present (case-insensitive); a missing
184
+ one raises :class:`ValueError`. ``[SAMPLES]`` is always required.
185
+ """
186
+ path = Path(self.path)
187
+ if not path.exists():
188
+ raise FileNotFoundError(f"RunManifest not found: {path}")
189
+
190
+ section_dict = _split_sections(path)
191
+ self._section_dict = section_dict
192
+ self.sections = list(section_dict.keys())
193
+
194
+ required = {s.lower() for s in (required_sections or [])} | {_SAMPLES}
195
+ missing = [s for s in required if s not in section_dict]
196
+ if missing:
197
+ raise ValueError(
198
+ f"RunManifest {path} is missing required section(s): "
199
+ f"{', '.join('[' + m + ']' for m in sorted(missing))}"
200
+ )
201
+
202
+ self.header = _parse_kv(section_dict.get(_RUNVALUES, []))
203
+ self.settings = _parse_kv(section_dict.get(_SETTINGS, []))
204
+
205
+ # Instrument: honour an explicit manifest value, else default to AVITI.
206
+ self.instrument = next(
207
+ (
208
+ self.header[k]
209
+ for k in self.header
210
+ if k.lower() in ("instrument", "instrumentplatform", "platform")
211
+ ),
212
+ "AVITI",
213
+ )
214
+
215
+ self.adapters = [
216
+ v for k, v in self.settings.items() if k.lower() in _ADAPTER_SETTING_KEYS and v
217
+ ]
218
+
219
+ self._parse_samples(section_dict.get(_SAMPLES, []))
220
+
221
+ def _parse_samples(self, lines: list[str]) -> None:
222
+ rows = list(csv.reader(lines))
223
+ if not rows:
224
+ self.columns = []
225
+ self.records = []
226
+ return
227
+ self.columns = [c.strip() for c in rows[0]]
228
+ records: list[dict[str, str]] = []
229
+ for row in rows[1:]:
230
+ if not any(cell.strip() for cell in row):
231
+ continue
232
+ record = {
233
+ self.columns[i]: (row[i].strip() if i < len(row) else "")
234
+ for i in range(len(self.columns))
235
+ }
236
+ records.append(record)
237
+ self.records = records
238
+
239
+ # ------------------------------------------------------------------
240
+ # Shared interface
241
+ # ------------------------------------------------------------------
242
+
243
+ def samples(self) -> list[dict[str, Any]]:
244
+ """Return one record per sample, mapped to the shared schema.
245
+
246
+ Manifest columns are renamed to the shared keys (``sample_id``,
247
+ ``index``, ``index2``, ``lane``, ``sample_project``); any other
248
+ columns are preserved under their original names.
249
+ """
250
+ if self.columns is None:
251
+ raise RuntimeError("Call parse() before samples().")
252
+
253
+ result: list[dict[str, Any]] = []
254
+ for record in self.records:
255
+ sample: dict[str, Any] = {
256
+ "sample_id": None,
257
+ "index": None,
258
+ "index2": None,
259
+ "lane": None,
260
+ "sample_project": None,
261
+ "instrument_platform": self.instrument,
262
+ }
263
+ for col, value in record.items():
264
+ mapped = _SAMPLE_COLUMN_MAP.get(col.lower())
265
+ if mapped:
266
+ sample[mapped] = value or None
267
+ else:
268
+ sample[col] = value
269
+ result.append(sample)
270
+ return result
271
+
272
+ def index_type(self) -> str:
273
+ """Return ``"dual"``, ``"single"``, or ``"none"`` from the columns."""
274
+ if self.columns is None:
275
+ raise RuntimeError("Call parse() before index_type().")
276
+ lower = {c.lower() for c in self.columns}
277
+ if "index2" in lower:
278
+ return "dual"
279
+ if "index1" in lower:
280
+ return "single"
281
+ return "none"
282
+
283
+ def parse_custom_section(
284
+ self,
285
+ section_name: str,
286
+ *,
287
+ required: bool = False,
288
+ ) -> dict[str, str]:
289
+ """Parse any manifest section as a key/value dict (case-insensitive)."""
290
+ key = section_name.strip().lower()
291
+ lines = self._section_dict.get(key)
292
+ if lines is None:
293
+ if required:
294
+ raise ValueError(f"Required section [{section_name}] not found.")
295
+ return {}
296
+ return _parse_kv(lines)
297
+
298
+ # ------------------------------------------------------------------
299
+ # Detection
300
+ # ------------------------------------------------------------------
301
+
302
+ @staticmethod
303
+ def is_manifest(path: str | Path) -> bool:
304
+ """Return ``True`` if *path* looks like an AVITI RunManifest.
305
+
306
+ The discriminator is a ``[SAMPLES]`` section (Illumina sheets use
307
+ ``[Data]`` / ``[BCLConvert_Data]``) together with a ``[RUNVALUES]``
308
+ section or a ``SampleName`` column header - markers Illumina formats
309
+ never use. ``Index1`` is *not* required, since an AVITI manifest may
310
+ describe an index-free run.
311
+ """
312
+ try:
313
+ sections = _split_sections(Path(path))
314
+ except (OSError, UnicodeDecodeError):
315
+ return False
316
+ if _SAMPLES not in sections:
317
+ return False
318
+ if _RUNVALUES in sections:
319
+ return True
320
+ sample_lines = sections.get(_SAMPLES, [])
321
+ if sample_lines:
322
+ header = next(csv.reader(sample_lines[:1]), [])
323
+ cols = {c.strip().lower() for c in header}
324
+ return "samplename" in cols
325
+ return False
326
+
327
+ def __repr__(self) -> str:
328
+ n = len(self.records)
329
+ return f"ElementRunManifest(path={self.path!r}, samples={n})"
@@ -22,6 +22,12 @@ import re
22
22
  from dataclasses import dataclass, field
23
23
  from typing import Any
24
24
 
25
+ from samplesheet_parser.chemistry import (
26
+ DEFAULT_MIN_SIGNAL_FRACTION,
27
+ Chemistry,
28
+ analyze_color_balance,
29
+ chemistry_for_instrument,
30
+ )
25
31
  from samplesheet_parser.protocol import SampleSheetParser
26
32
 
27
33
  logger = logging.getLogger(__name__)
@@ -230,6 +236,15 @@ class SampleSheetValidator:
230
236
  no adapter sequences (warning only).
231
237
  * **ADAPTER_MISMATCH** - Adapter does not match any known Illumina
232
238
  adapter (warning only; custom adapters are valid).
239
+ * **COLOR_BALANCE_NO_SIGNAL** - On 2-/1-channel chemistry, an index cycle
240
+ where the whole pool is dark (all ``G``) in a
241
+ channel, so the instrument gets no signal and
242
+ the index read fails. See
243
+ :meth:`_check_color_balance`.
244
+ * **COLOR_BALANCE_LOW** - An index cycle with signal below the threshold
245
+ in one channel (2-/1-channel) or no base
246
+ diversity (4-channel), degrading base-call
247
+ quality (warning only).
233
248
 
234
249
  Examples
235
250
  --------
@@ -243,6 +258,9 @@ class SampleSheetValidator:
243
258
  sheet: SampleSheetParser,
244
259
  *,
245
260
  min_hamming_distance: int = MIN_HAMMING_DISTANCE,
261
+ check_color_balance: bool = False,
262
+ instrument: str | None = None,
263
+ min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
246
264
  ) -> ValidationResult:
247
265
  """Run all validation checks on a parsed sample sheet.
248
266
 
@@ -257,6 +275,21 @@ class SampleSheetValidator:
257
275
  ``INDEX_DISTANCE_TOO_LOW`` warning. Defaults to
258
276
  :data:`MIN_HAMMING_DISTANCE` (3). Set higher (e.g. ``4``) for
259
277
  stricter demultiplexing requirements with longer indexes.
278
+ check_color_balance:
279
+ Opt in to per-cycle index colour-balance checking against the
280
+ instrument's optical chemistry (see :meth:`_check_color_balance`).
281
+ Off by default because it can turn an otherwise-valid low-plex
282
+ pool into an error; enable it when the sheet declares (or you pass)
283
+ a known instrument.
284
+ instrument:
285
+ Instrument name used to resolve the optical chemistry for the
286
+ colour-balance check. Defaults to the instrument declared in the
287
+ sheet header (``InstrumentPlatform`` / ``Instrument Type``).
288
+ min_signal_fraction:
289
+ Minimum fraction of the pool that must light each optical channel
290
+ at every index cycle before a ``COLOR_BALANCE_LOW`` warning is
291
+ raised. Defaults to
292
+ :data:`~samplesheet_parser.chemistry.DEFAULT_MIN_SIGNAL_FRACTION`.
260
293
 
261
294
  Returns
262
295
  -------
@@ -275,6 +308,14 @@ class SampleSheetValidator:
275
308
  self._check_index_distances(samples, result, min_distance=min_hamming_distance)
276
309
  self._check_duplicate_sample_ids(samples, result)
277
310
  self._check_adapters(sheet, result)
311
+ if check_color_balance:
312
+ self._check_color_balance(
313
+ sheet,
314
+ samples,
315
+ result,
316
+ instrument=instrument,
317
+ min_signal_fraction=min_signal_fraction,
318
+ )
278
319
 
279
320
  return result
280
321
 
@@ -419,8 +460,12 @@ class SampleSheetValidator:
419
460
 
420
461
  for sample in samples:
421
462
  lane = sample.get("lane")
422
- idx1 = (sample.get("index") or "").upper()
423
- idx2 = (sample.get("index2") or "").upper()
463
+ # Accept both V1-style (``index``/``index2``) and V2-style
464
+ # (``Index``/``Index2``) keys so hand-built dicts and the output of
465
+ # ``normalize_index_lengths`` are checked the same way the duplicate
466
+ # and character checks already handle them.
467
+ idx1 = (sample.get("index") or sample.get("Index") or "").upper()
468
+ idx2 = (sample.get("index2") or sample.get("Index2") or "").upper()
424
469
  sid = sample.get("sample_id", "?")
425
470
 
426
471
  if not idx1:
@@ -479,6 +524,127 @@ class SampleSheetValidator:
479
524
  else:
480
525
  bucket.add(sid)
481
526
 
527
+ @staticmethod
528
+ def _resolve_instrument(sheet: SampleSheetParser) -> str | None:
529
+ """Best-effort read of the instrument name from a parsed sheet.
530
+
531
+ Looks at the parser attributes first (``instrument_platform`` for V2,
532
+ ``instrument_type`` for V1, ``instrument`` for vendor parsers) and
533
+ falls back to the equivalent ``[Header]`` keys.
534
+ """
535
+ for attr in ("instrument_platform", "instrument_type", "instrument"):
536
+ value = getattr(sheet, attr, None)
537
+ if value:
538
+ return str(value)
539
+ header = getattr(sheet, "header", None) or {}
540
+ for key in ("InstrumentPlatform", "Instrument Type", "InstrumentType", "Instrument"):
541
+ value = header.get(key)
542
+ if value:
543
+ return str(value)
544
+ return None
545
+
546
+ def _check_color_balance(
547
+ self,
548
+ sheet: SampleSheetParser,
549
+ samples: list[dict[str, Any]],
550
+ result: ValidationResult,
551
+ *,
552
+ instrument: str | None = None,
553
+ min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
554
+ ) -> None:
555
+ """Flag index cycles that will fail or degrade on the instrument's chemistry.
556
+
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``.
564
+
565
+ The check is skipped (no findings) when the instrument is unknown, since
566
+ guessing the chemistry could produce misleading errors. Pass *instrument*
567
+ to force a chemistry when the sheet header omits it.
568
+
569
+ Index sequences are read from each sample using the same ``index`` /
570
+ ``Index`` key fallback as :meth:`_check_index_distances`.
571
+ """
572
+ name = instrument or self._resolve_instrument(sheet)
573
+ chemistry = chemistry_for_instrument(name)
574
+ if chemistry is None:
575
+ logger.debug("Skipping colour-balance check: unknown instrument %r.", name)
576
+ return
577
+
578
+ index1 = [(s.get("index") or s.get("Index") or "").upper() for s in samples]
579
+ index2 = [(s.get("index2") or s.get("Index2") or "").upper() for s in samples]
580
+ has_index2 = any(index2)
581
+
582
+ report = analyze_color_balance(
583
+ index1,
584
+ index2 if has_index2 else None,
585
+ chemistry=chemistry,
586
+ min_signal_fraction=min_signal_fraction,
587
+ )
588
+
589
+ 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
+ result.add_error(
602
+ "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.",
608
+ instrument=name,
609
+ chemistry=chemistry.value,
610
+ read=cb.read,
611
+ cycle=cb.cycle,
612
+ channel=channel,
613
+ base_counts=cb.base_counts,
614
+ )
615
+
616
+ 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
+ )
647
+
482
648
  def _check_adapters(
483
649
  self,
484
650
  sheet: SampleSheetParser,
@@ -957,7 +957,16 @@ class SampleSheetWriter:
957
957
  }
958
958
  sid = std.get("Sample_ID", "")
959
959
  idx = std.get("index", "")
960
- if not sid or not idx:
960
+ if not sid:
961
+ continue
962
+ if not idx:
963
+ logger.warning(
964
+ "Sample %r has no index; the writer requires an index per "
965
+ "sample, so this index-free library is dropped from the "
966
+ "output. Add an index or write the sheet by another means "
967
+ "to preserve it.",
968
+ sid,
969
+ )
961
970
  continue
962
971
  self._samples.append(
963
972
  _SampleRecord(
@@ -1005,7 +1014,16 @@ class SampleSheetWriter:
1005
1014
  for record in sheet.records or []:
1006
1015
  sid = record.get("Sample_ID", "")
1007
1016
  idx = record.get("Index", "")
1008
- if not sid or not idx:
1017
+ if not sid:
1018
+ continue
1019
+ if not idx:
1020
+ logger.warning(
1021
+ "Sample %r has no index; the writer requires an index per "
1022
+ "sample, so this index-free library is dropped from the "
1023
+ "output. Add an index or write the sheet by another means "
1024
+ "to preserve it.",
1025
+ sid,
1026
+ )
1009
1027
  continue
1010
1028
  extra = {k: v for k, v in record.items() if k not in std_cols}
1011
1029
  self._samples.append(
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 2.1.0
4
- Summary: Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2
3
+ Version: 2.3.0
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
6
  Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
7
7
  Project-URL: Repository, https://github.com/chaitanyakasaraneni/samplesheet-parser
@@ -27,7 +27,7 @@ License: Apache License
27
27
  See the License for the specific language governing permissions and
28
28
  limitations under the License.
29
29
  License-File: LICENSE
30
- Keywords: bcl2fastq,bclconvert,bioinformatics,demultiplexing,genomics,illumina,ngs,samplesheet,sequencing
30
+ Keywords: aviti,bcl2fastq,bclconvert,bioinformatics,color-balance,demultiplexing,element,genomics,illumina,multi-vendor,ngs,run-manifest,samplesheet,sequencing
31
31
  Classifier: Development Status :: 5 - Production/Stable
32
32
  Classifier: Intended Audience :: Developers
33
33
  Classifier: Intended Audience :: Science/Research
@@ -58,7 +58,7 @@ Description-Content-Type: text/markdown
58
58
 
59
59
  **Format-agnostic parser for Illumina SampleSheet.csv files.**
60
60
 
61
- Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
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
 
63
63
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
64
64
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -74,15 +74,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
74
74
 
75
75
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
76
76
 
77
- *`SampleSheetFactory` auto-detects the format and routes to the correct parser. Both formats share a common interface — `SampleSheetConverter` handles bidirectional conversion, `SampleSheetValidator` catches index and adapter issues, `SampleSheetDiff` compares two sheets across any combination of V1/V2 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.*
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
 
79
79
  ---
80
80
 
81
81
  ## The problem this solves
82
82
 
83
- Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce two incompatible SampleSheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section.
83
+ Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
84
84
 
85
- Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for both, converts between formats, validates index integrity (including Hamming distance), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
85
+ Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
86
86
 
87
87
  ---
88
88
 
@@ -110,7 +110,7 @@ from samplesheet_parser import SampleSheetFactory
110
110
  factory = SampleSheetFactory()
111
111
  sheet = factory.create_parser("SampleSheet.csv", parse=True)
112
112
 
113
- print(factory.version) # SampleSheetVersion.V1 or .V2
113
+ print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
114
114
  print(sheet.index_type()) # "dual", "single", or "none"
115
115
 
116
116
  for sample in sheet.samples():
@@ -368,6 +368,8 @@ The detector reads only as much of the file as needed — stopping after `[Heade
368
368
  | `INDEX_DISTANCE_TOO_LOW` | warning | Two indexes in the same lane have Hamming distance < 3, risking demultiplexing bleed-through |
369
369
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
370
370
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
371
+ | `COLOR_BALANCE_NO_SIGNAL` | error | An index cycle has no signal in an optical channel (2-/1-channel chemistry) — the index read will fail. *Opt-in.* |
372
+ | `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) — degraded base calls. *Opt-in.* |
371
373
 
372
374
  ### Index distance checking
373
375
 
@@ -397,6 +399,95 @@ result = ValidationResult()
397
399
  SampleSheetValidator()._check_index_distances(samples, result, min_distance=4)
398
400
  ```
399
401
 
402
+ ### Color-balance checking (opt-in)
403
+
404
+ On 2-channel instruments (NextSeq, NovaSeq, NovaSeq X) and 1-channel
405
+ instruments (iSeq), bases are called from optical signal: `A` lights
406
+ both channels, `C` only red, `T` only green, and **`G` is a dark base with no
407
+ signal at all**. A cycle where the whole index pool reads `G` produces no
408
+ signal, so the instrument cannot register the tile and the index read fails —
409
+ a real, common cause of wrecked runs that a Hamming-distance check cannot see.
410
+
411
+ Because the sample sheet already contains every sample's index, this can be
412
+ 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.
415
+
416
+ ```python
417
+ from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
418
+
419
+ sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=True)
420
+
421
+ # Opt in; the instrument is read from the sheet header (or pass instrument=...)
422
+ result = SampleSheetValidator().validate(sheet, check_color_balance=True)
423
+
424
+ for err in result.errors:
425
+ print(err)
426
+ # [ERROR] COLOR_BALANCE_NO_SIGNAL: On 2-channel chemistry (NovaSeqXSeries),
427
+ # index1 cycle 4 has no red or green signal across the pool: no sample
428
+ # carries a red or green base (A/C/T) at this cycle ... the index read will fail.
429
+ ```
430
+
431
+ The chemistry is resolved from the instrument name; the check is **off by
432
+ default** (it can legitimately fail a low-plex pool) and is skipped silently
433
+ for unknown instruments. The same analysis is available standalone:
434
+
435
+ ```python
436
+ from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
437
+
438
+ chem = chemistry_for_instrument("NovaSeqXSeries") # Chemistry.TWO_CHANNEL
439
+ report = analyze_color_balance(["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"],
440
+ chemistry=chem)
441
+ for cb in report.dark_cycles:
442
+ print(cb.read, cb.cycle, cb.base_counts) # index1 4 {'G': 4}
443
+ ```
444
+
445
+ From the CLI:
446
+
447
+ ```bash
448
+ samplesheet validate SampleSheet.csv --color-balance
449
+ samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
450
+ ```
451
+
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.
462
+
463
+ ---
464
+
465
+ ## Multi-vendor support
466
+
467
+ The factory is not limited to Illumina. Any parser that implements the
468
+ `SampleSheetParser` protocol can be auto-detected, and **Element Biosciences
469
+ AVITI `RunManifest.csv`** files are supported out of the box — the same
470
+ `SampleSheetFactory` recognises them and returns a parser with the identical
471
+ interface:
472
+
473
+ ```python
474
+ from samplesheet_parser import SampleSheetFactory
475
+
476
+ factory = SampleSheetFactory()
477
+ sheet = factory.create_parser("RunManifest.csv", parse=True)
478
+
479
+ print(factory.version) # SampleSheetVersion.ELEMENT_AVITI
480
+ print(sheet.index_type()) # "dual"
481
+ for s in sheet.samples(): # same schema as Illumina: sample_id, index, index2, ...
482
+ print(s["sample_id"], s["index"], s["index2"])
483
+ ```
484
+
485
+ AVITI is a four-channel avidity platform, so color-balance validation applies
486
+ to it too (flagging low-diversity index cycles). Manifest columns
487
+ (`SampleName`, `Index1`, `Index2`, `Lane`, `Project`, `ExternalID`) are mapped
488
+ to the shared sample schema, so the validator, diff, and filter tooling work
489
+ across vendors without special-casing.
490
+
400
491
  ---
401
492
 
402
493
  ## Merger conflict and warning codes
@@ -1,9 +1,10 @@
1
- samplesheet_parser/__init__.py,sha256=X_hXNW-UHJK2-SOEVez06PXvkelf0Vz7rlSbj2rDqaY,2415
2
- samplesheet_parser/cli.py,sha256=J_aTvM-b-vn7mwouqGvs0IWOlQUQwy4oQie4R1vbQIc,29849
1
+ samplesheet_parser/__init__.py,sha256=nfBobOHN_aX9thGcCtyJoduIlL4DUeViqjBtadmLQ58,2844
2
+ samplesheet_parser/chemistry.py,sha256=EoT4q-d9PYwLiZ20T4B3-Pb5keGNRsw_BIvboZ8ryN0,12369
3
+ samplesheet_parser/cli.py,sha256=zL_JPj7wNj24ozB4CjQsXwskefAfxqq01osGqJ0S_QA,30815
3
4
  samplesheet_parser/converter.py,sha256=g4s5R6iB5mPDF-e8JD4Iezt2dMBBxgQ-OPL9vxJ2zM0,20236
4
5
  samplesheet_parser/diff.py,sha256=RruQhKRi0Ja6x5pq8CA-yafJ4JQJ3p0JXDp68RS53GE,15369
5
- samplesheet_parser/enums.py,sha256=ttYIXbn4a-F8TP-7NoJH7oBEQcn_fmGjrYsDVyh6yNo,1445
6
- samplesheet_parser/factory.py,sha256=hNTFiEnWFW2aT_tL26wx1C82ViHosa6nGWPWdG-bHCI,11752
6
+ samplesheet_parser/enums.py,sha256=SqxE5sRjBGRGk2J6lxpkgxb6luEqBTcdalok5lDFUS0,1790
7
+ samplesheet_parser/factory.py,sha256=XVkot7FM0jKSQKNnmsvTpjqCTSq97e6sk_gP97MG88w,12323
7
8
  samplesheet_parser/filter.py,sha256=4lkR_WJaawVVFdZPkxvVCYVG47AafFCwol4__WNhZdw,8161
8
9
  samplesheet_parser/index_utils.py,sha256=MWwVcQHO26oOuZdGNFA2g8OPrhP2rhkuYxzhbRaBXdY,6859
9
10
  samplesheet_parser/instruments.py,sha256=gUy2oCoWJmmxTI1cPtyIa84LrmEd1oA_GSkrHU27RIU,7529
@@ -11,13 +12,14 @@ samplesheet_parser/merger.py,sha256=UxQ8bmX7632S70Lko3GFQTjHqTZUt7aRch_UCSxVjsw,
11
12
  samplesheet_parser/protocol.py,sha256=YOT1iZ-727nDKDGvZXNTjVG-OAgGdq0F0y3Tzbk7bwM,3104
12
13
  samplesheet_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
13
14
  samplesheet_parser/splitter.py,sha256=QMmTTXg4HwZl3oUvA-4KKUVF62oIn4k2D1ko_dT1wS4,11314
14
- samplesheet_parser/validators.py,sha256=tezOkqrDtoDU8Euf-6ULFsogWXjt1-FPPSfZr7Y2VJM,19503
15
- samplesheet_parser/writer.py,sha256=8W_z2tI7bjiRH9Csra20NLOPC3h3U2Uz1wSHytINAS8,32761
15
+ samplesheet_parser/validators.py,sha256=pRHddhJJyCuN21zEIFkHMuBHMMxzCRyLOo2QsZcjFtA,27334
16
+ samplesheet_parser/writer.py,sha256=NQY0x28rKF-694w11FZTCqCXxlNiHnMspB5M33GoD0k,33541
16
17
  samplesheet_parser/parsers/__init__.py,sha256=N5ICN_46x-ARbG8kyrck6g1V_gOU0XacqzUJI-D6KX8,213
18
+ samplesheet_parser/parsers/element.py,sha256=7DrketMyQzPnEvAaaj6pstAiuvAJ6ljcFltsU-uymxs,11358
17
19
  samplesheet_parser/parsers/v1.py,sha256=MRt_BUJTmj763N2kByELNwQPY-_jcLKcwahG4jPBH98,23956
18
20
  samplesheet_parser/parsers/v2.py,sha256=pCd18DNcpIIh7vJNEB8asRleIriH2NSx7h7NAtsomug,27982
19
- samplesheet_parser-2.1.0.dist-info/METADATA,sha256=Ct0MKzDtdQ4cJeIpAt4TEMXL_8vYQp57M7G90jhH8Vc,26594
20
- samplesheet_parser-2.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
21
- samplesheet_parser-2.1.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
22
- samplesheet_parser-2.1.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
23
- samplesheet_parser-2.1.0.dist-info/RECORD,,
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,,