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.
- samplesheet_parser/__init__.py +16 -1
- samplesheet_parser/chemistry.py +467 -0
- samplesheet_parser/cli.py +30 -3
- samplesheet_parser/enums.py +7 -0
- samplesheet_parser/factory.py +11 -1
- samplesheet_parser/parsers/element.py +329 -0
- samplesheet_parser/validators.py +214 -0
- {samplesheet_parser-2.2.0.dist-info → samplesheet_parser-2.4.0.dist-info}/METADATA +132 -21
- {samplesheet_parser-2.2.0.dist-info → samplesheet_parser-2.4.0.dist-info}/RECORD +12 -10
- {samplesheet_parser-2.2.0.dist-info → samplesheet_parser-2.4.0.dist-info}/WHEEL +0 -0
- {samplesheet_parser-2.2.0.dist-info → samplesheet_parser-2.4.0.dist-info}/entry_points.txt +0 -0
- {samplesheet_parser-2.2.0.dist-info → samplesheet_parser-2.4.0.dist-info}/licenses/LICENSE +0 -0
samplesheet_parser/__init__.py
CHANGED
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
samplesheet-parser
|
|
3
3
|
====================
|
|
4
4
|
|
|
5
|
-
|
|
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(
|
|
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
|
# ---------------------------------------------------------------------------
|
samplesheet_parser/enums.py
CHANGED
|
@@ -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):
|
samplesheet_parser/factory.py
CHANGED
|
@@ -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}
|
|
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
|