samplesheet-parser 2.5.2__py3-none-any.whl → 2.6.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.
@@ -51,44 +51,72 @@ from samplesheet_parser.parsers.element import ElementRunManifest
51
51
  from samplesheet_parser.parsers.v1 import SampleSheetV1
52
52
  from samplesheet_parser.parsers.v2 import SampleSheetV2
53
53
  from samplesheet_parser.protocol import SampleSheetParser
54
+ from samplesheet_parser.schema import (
55
+ ILLUMINA_V2_SCHEMA,
56
+ ILLUMINA_V2_URN,
57
+ SAMSHEE_V2_URN,
58
+ build_registry,
59
+ sheet_to_sections,
60
+ )
54
61
  from samplesheet_parser.splitter import SampleSheetSplitter, SplitResult
55
62
  from samplesheet_parser.validators import (
56
63
  SampleSheetValidator,
64
+ Strictness,
65
+ ValidationIssue,
57
66
  ValidationResult,
67
+ Validator,
68
+ ValidatorError,
58
69
  hamming_distance,
70
+ illumina_v2_conformance,
71
+ illumina_v2_schema_validator,
59
72
  index_collision_distance,
73
+ json_schema_validator,
74
+ sheet_to_dict,
60
75
  )
61
76
  from samplesheet_parser.writer import SampleSheetWriter
62
77
 
63
78
  __all__ = [
64
- "SampleSheetV1",
65
- "SampleSheetV2",
66
- "ElementRunManifest",
67
- "SampleSheetFactory",
68
- "SampleSheetParser",
69
- "SampleSheetVersion",
70
- "IndexType",
71
- "InstrumentPlatform",
72
- "UMILocation",
73
- "SampleSheetValidator",
74
- "ValidationResult",
75
- "hamming_distance",
76
- "index_collision_distance",
79
+ "ILLUMINA_V2_SCHEMA",
80
+ "ILLUMINA_V2_URN",
81
+ "SAMSHEE_V2_URN",
77
82
  "Chemistry",
78
83
  "ColorBalanceMode",
79
84
  "ColorBalanceReport",
80
- "analyze_color_balance",
81
- "chemistry_for_instrument",
85
+ "DiffResult",
86
+ "ElementRunManifest",
87
+ "FilterResult",
88
+ "IndexType",
89
+ "InstrumentPlatform",
90
+ "MergeResult",
82
91
  "SampleSheetConverter",
83
92
  "SampleSheetDiff",
84
- "DiffResult",
85
- "SampleSheetWriter",
93
+ "SampleSheetFactory",
94
+ "SampleSheetFilter",
86
95
  "SampleSheetMerger",
87
- "MergeResult",
96
+ "SampleSheetParser",
88
97
  "SampleSheetSplitter",
98
+ "SampleSheetV1",
99
+ "SampleSheetV2",
100
+ "SampleSheetValidator",
101
+ "SampleSheetVersion",
102
+ "SampleSheetWriter",
89
103
  "SplitResult",
90
- "SampleSheetFilter",
91
- "FilterResult",
92
- "normalize_index_lengths",
104
+ "Strictness",
105
+ "UMILocation",
106
+ "ValidationIssue",
107
+ "ValidationResult",
108
+ "Validator",
109
+ "ValidatorError",
93
110
  "__version__",
111
+ "analyze_color_balance",
112
+ "build_registry",
113
+ "chemistry_for_instrument",
114
+ "hamming_distance",
115
+ "illumina_v2_conformance",
116
+ "illumina_v2_schema_validator",
117
+ "index_collision_distance",
118
+ "json_schema_validator",
119
+ "normalize_index_lengths",
120
+ "sheet_to_dict",
121
+ "sheet_to_sections",
94
122
  ]
samplesheet_parser/cli.py CHANGED
@@ -70,6 +70,7 @@ except ImportError: # pragma: no cover
70
70
  from samplesheet_parser.chemistry import ColorBalanceMode
71
71
  from samplesheet_parser.enums import SampleSheetVersion
72
72
  from samplesheet_parser.validators import MIN_HAMMING_DISTANCE as _MIN_HAMMING_DEFAULT
73
+ from samplesheet_parser.validators import Strictness
73
74
 
74
75
  if _TYPER_AVAILABLE:
75
76
  from importlib.metadata import PackageNotFoundError
@@ -254,40 +255,69 @@ if _TYPER_AVAILABLE:
254
255
  def validate(
255
256
  path: Annotated[Path, typer.Argument(help="Path to SampleSheet.csv.", metavar="FILE")],
256
257
  fmt: _FormatOption = "text",
258
+ strictness: Annotated[
259
+ Strictness,
260
+ typer.Option(
261
+ "--strictness",
262
+ help=(
263
+ "Overall strictness. 'standard' is the default behaviour; "
264
+ "'lenient' loosens the index-distance threshold and skips "
265
+ "colour balance; 'strict' tightens them and enforces Illumina "
266
+ "v2 spec conformance, and also runs the bundled JSON Schema "
267
+ "when the [schema] extra is installed (otherwise a "
268
+ "SCHEMA_SKIPPED note is emitted). Explicit options below "
269
+ "override the level."
270
+ ),
271
+ ),
272
+ ] = Strictness.STANDARD,
273
+ schema: Annotated[
274
+ Path | None,
275
+ typer.Option(
276
+ "--schema",
277
+ help=(
278
+ "Path to a JSON Schema (draft 2020-12) to check the sheet "
279
+ "against, alongside the built-in checks. May $ref the bundled "
280
+ "Illumina v2 schema by URN. Requires the [schema] extra."
281
+ ),
282
+ metavar="FILE",
283
+ ),
284
+ ] = None,
257
285
  min_hamming: Annotated[
258
- int,
286
+ int | None,
259
287
  typer.Option(
260
288
  "--min-hamming",
261
289
  help=(
262
- f"Minimum Hamming distance between indexes "
263
- f"(default: {_MIN_HAMMING_DEFAULT}, must be >= 1)."
290
+ "Minimum Hamming distance between indexes (must be >= 1). "
291
+ f"Defaults to the --strictness level ({_MIN_HAMMING_DEFAULT} "
292
+ "at standard)."
264
293
  ),
265
294
  metavar="N",
266
295
  ),
267
- ] = _MIN_HAMMING_DEFAULT,
296
+ ] = None,
268
297
  color_balance: Annotated[
269
- bool,
298
+ bool | None,
270
299
  typer.Option(
271
300
  "--color-balance/--no-color-balance",
272
301
  help=(
273
- "Also check per-cycle index colour balance against the "
274
- "instrument's optical chemistry (flags dark/no-signal "
275
- "cycles on 2-/1-channel instruments). Off by default."
302
+ "Check per-cycle index colour balance against the "
303
+ "instrument's optical chemistry (flags dark/no-signal cycles "
304
+ "on 2-/1-channel instruments). Defaults to the --strictness "
305
+ "level (off except at strict)."
276
306
  ),
277
307
  ),
278
- ] = False,
308
+ ] = None,
279
309
  color_balance_mode: Annotated[
280
- ColorBalanceMode,
310
+ ColorBalanceMode | None,
281
311
  typer.Option(
282
312
  "--color-balance-mode",
283
313
  help=(
284
- "Strictness of the colour-balance check (only with "
285
- "--color-balance). 'vendor_faithful' encodes each platform's "
286
- "published rule; 'conservative' also fails single-channel and "
287
- "low-diversity cycles the vendor minimum permits."
314
+ "Strictness of the colour-balance check. 'vendor_faithful' "
315
+ "encodes each platform's published rule; 'conservative' also "
316
+ "fails single-channel and low-diversity cycles the vendor "
317
+ "minimum permits. Defaults to the --strictness level."
288
318
  ),
289
319
  ),
290
- ] = ColorBalanceMode.VENDOR_FAITHFUL,
320
+ ] = None,
291
321
  instrument: Annotated[
292
322
  str | None,
293
323
  typer.Option(
@@ -307,16 +337,48 @@ if _TYPER_AVAILABLE:
307
337
  Exits 2 on usage errors or unreadable files.
308
338
  """
309
339
  from samplesheet_parser.factory import SampleSheetFactory
310
- from samplesheet_parser.validators import SampleSheetValidator
340
+ from samplesheet_parser.validators import _STRICTNESS_PRESETS, SampleSheetValidator
311
341
 
312
342
  _validate_fmt(fmt)
313
- if min_hamming < 1:
343
+ if min_hamming is not None and min_hamming < 1:
314
344
  typer.echo(f"Error: --min-hamming must be >= 1, got {min_hamming}.", err=True)
315
345
  raise typer.Exit(code=2)
316
346
  if not path.exists():
317
347
  typer.echo(f"Error: file not found: {path}", err=True)
318
348
  raise typer.Exit(code=2)
319
349
 
350
+ schema_doc: dict[str, object] | None = None
351
+ if schema is not None:
352
+ if not schema.exists():
353
+ typer.echo(f"Error: schema file not found: {schema}", err=True)
354
+ raise typer.Exit(code=2)
355
+ # An explicit --schema is a hard requirement: if jsonschema is
356
+ # missing we fail rather than silently skip the user's own schema.
357
+ # (Strict mode's *bundled* schema degrades to a note instead, since
358
+ # its other checks still run; see the --strictness help.)
359
+ try:
360
+ import jsonschema # noqa: F401
361
+ except ImportError as exc:
362
+ typer.echo(
363
+ "Error: --schema requires jsonschema. Install it with "
364
+ "'pip install samplesheet-parser[schema]'.",
365
+ err=True,
366
+ )
367
+ raise typer.Exit(code=2) from exc
368
+ try:
369
+ loaded = json.loads(schema.read_text(encoding="utf-8"))
370
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
371
+ typer.echo(f"Error: could not read JSON schema {schema}: {exc}", err=True)
372
+ raise typer.Exit(code=2) from exc
373
+ if not isinstance(loaded, dict):
374
+ typer.echo(
375
+ f"Error: schema {schema} must be a JSON object, "
376
+ f"got {type(loaded).__name__}.",
377
+ err=True,
378
+ )
379
+ raise typer.Exit(code=2)
380
+ schema_doc = loaded
381
+
320
382
  try:
321
383
  factory = SampleSheetFactory()
322
384
  sheet = factory.create_parser(str(path), parse=True, clean=False)
@@ -330,21 +392,34 @@ if _TYPER_AVAILABLE:
330
392
 
331
393
  result = SampleSheetValidator().validate(
332
394
  sheet,
395
+ strictness=strictness,
396
+ schema=schema_doc,
333
397
  min_hamming_distance=min_hamming,
334
398
  check_color_balance=color_balance,
335
399
  color_balance_mode=color_balance_mode,
336
400
  instrument=instrument,
337
401
  )
338
402
 
403
+ # Resolve the effective settings (the preset the validator applied) for
404
+ # reporting, so output reflects what actually ran under --strictness.
405
+ preset = _STRICTNESS_PRESETS[strictness]
406
+ eff_min_hamming = preset["min_hamming_distance"] if min_hamming is None else min_hamming
407
+ eff_cb = preset["check_color_balance"] if color_balance is None else color_balance
408
+ eff_cb_mode = (
409
+ preset["color_balance_mode"] if color_balance_mode is None else color_balance_mode
410
+ )
411
+
339
412
  if fmt == "json":
340
413
  _print_json(
341
414
  {
342
415
  "file": str(path),
343
416
  "version": version.value,
344
417
  "is_valid": result.is_valid,
345
- "min_hamming_distance": min_hamming,
346
- "color_balance_checked": color_balance,
347
- "color_balance_mode": color_balance_mode.value if color_balance else None,
418
+ "strictness": strictness.value,
419
+ "schema": str(schema) if schema is not None else None,
420
+ "min_hamming_distance": eff_min_hamming,
421
+ "color_balance_checked": eff_cb,
422
+ "color_balance_mode": eff_cb_mode.value if eff_cb else None,
348
423
  "errors": [
349
424
  {"code": e.code, "message": e.message, "context": e.context}
350
425
  for e in result.errors
@@ -361,8 +436,13 @@ if _TYPER_AVAILABLE:
361
436
  }
362
437
  )
363
438
  else:
439
+ cb_desc = eff_cb_mode.value if eff_cb else "off"
364
440
  typer.echo(f"File: {path}")
365
441
  typer.echo(f"Format: {version.value}")
442
+ typer.echo(f"Mode: {strictness.value}")
443
+ typer.echo(f"Checks: min index distance {eff_min_hamming}, colour balance {cb_desc}")
444
+ if schema is not None:
445
+ typer.echo(f"Schema: {schema}")
366
446
  typer.echo(f"Result: {result.summary()}")
367
447
 
368
448
  if result.notes:
@@ -45,7 +45,7 @@ from __future__ import annotations
45
45
  import logging
46
46
  from collections.abc import Callable
47
47
  from pathlib import Path
48
- from typing import Any
48
+ from typing import Any, ClassVar
49
49
 
50
50
  from samplesheet_parser.enums import SampleSheetVersion
51
51
  from samplesheet_parser.parsers.element import ElementRunManifest
@@ -81,7 +81,7 @@ class SampleSheetFactory:
81
81
  # SampleSheetFactory instance in the process, and registration is not
82
82
  # synchronised, so register custom parsers at import or startup rather than
83
83
  # concurrently from worker threads. Call clear_registry() to reset it.
84
- _registry: list[tuple[Callable[[Path], bool], type[Any], SampleSheetVersion]] = []
84
+ _registry: ClassVar[list[tuple[Callable[[Path], bool], type[Any], SampleSheetVersion]]] = []
85
85
 
86
86
  def __init__(self) -> None:
87
87
  self.version: SampleSheetVersion | None = None
@@ -0,0 +1,176 @@
1
+ """Bundled Illumina v2 JSON Schema and a resolvable schema registry.
2
+
3
+ This module ships a full JSON Schema (draft 2020-12) for the Illumina
4
+ BCLConvert v2 sample sheet and a :mod:`referencing` registry that resolves it
5
+ by URN, so a user schema can ``$ref`` the bundled document offline (no network,
6
+ no extra files).
7
+
8
+ Two URNs resolve to the same bundled schema:
9
+
10
+ * ``urn:samplesheet-parser:illuminav2/v1`` - this project's own URN.
11
+ * ``urn:samshee:illuminav2/v1`` - a compatibility alias so a schema written for
12
+ `samshee <https://github.com/lit-regensburg/samshee>`_ that references that
13
+ URN keeps resolving. The bundled schema is **equivalent** to samshee's intent
14
+ (required fields, admissible values, index pattern), not byte-identical to it.
15
+
16
+ The schema is validated against the *sectioned* view of a sheet produced by
17
+ :func:`sheet_to_sections` (section names as top-level keys, Settings sections as
18
+ objects, Data sections as arrays of row objects), which mirrors how samshee
19
+ represents a sheet.
20
+
21
+ ``referencing`` ships with ``jsonschema`` (>= 4.18), so no dependency beyond the
22
+ optional ``samplesheet-parser[schema]`` extra is introduced. When ``jsonschema``
23
+ is absent, :func:`build_registry` returns ``None`` and callers skip schema
24
+ checks.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ from typing import Any
30
+
31
+ #: This project's URN for the bundled Illumina v2 schema.
32
+ ILLUMINA_V2_URN = "urn:samplesheet-parser:illuminav2/v1"
33
+
34
+ #: Compatibility alias so samshee-authored schemas that ``$ref`` this URN
35
+ #: continue to resolve against the bundled equivalent schema.
36
+ SAMSHEE_V2_URN = "urn:samshee:illuminav2/v1"
37
+
38
+ #: Full JSON Schema (draft 2020-12) for a BCLConvert v2 sample sheet, matching
39
+ #: the value types produced by :func:`sheet_to_sections`: ``[Header]`` /
40
+ #: ``[BCLConvert_Settings]`` values are strings, ``[Reads]`` values are
41
+ #: integers, and ``[BCLConvert_Data]`` rows are objects of strings. Unknown
42
+ #: fields and columns are allowed (``additionalProperties: true``) so newer or
43
+ #: optional columns - including a per-sample ``OverrideCycles`` - still validate.
44
+ ILLUMINA_V2_SCHEMA: dict[str, Any] = {
45
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
46
+ "$id": ILLUMINA_V2_URN,
47
+ "title": "Illumina Sample Sheet v2 (BCLConvert)",
48
+ "type": "object",
49
+ "required": ["Header", "Reads", "BCLConvert_Data"],
50
+ "properties": {
51
+ "Header": {
52
+ "type": "object",
53
+ "required": ["FileFormatVersion"],
54
+ "properties": {
55
+ "FileFormatVersion": {"type": "string", "enum": ["2"]},
56
+ "RunName": {"type": "string"},
57
+ "RunDescription": {"type": "string"},
58
+ "InstrumentPlatform": {"type": "string"},
59
+ "InstrumentType": {"type": "string"},
60
+ "ExperimentName": {"type": "string"},
61
+ },
62
+ "additionalProperties": True,
63
+ },
64
+ "Reads": {
65
+ "type": "object",
66
+ "required": ["Read1Cycles"],
67
+ "properties": {
68
+ "Read1Cycles": {"type": "integer", "minimum": 1},
69
+ "Read2Cycles": {"type": "integer", "minimum": 1},
70
+ "Index1Cycles": {"type": "integer", "minimum": 0},
71
+ "Index2Cycles": {"type": "integer", "minimum": 0},
72
+ },
73
+ "additionalProperties": True,
74
+ },
75
+ "Sequencing": {"type": "object", "additionalProperties": True},
76
+ "BCLConvert_Settings": {
77
+ "type": "object",
78
+ "properties": {
79
+ "SoftwareVersion": {"type": "string"},
80
+ "AdapterRead1": {"type": "string", "pattern": "^[ACGTNacgtn]*$"},
81
+ "AdapterRead2": {"type": "string", "pattern": "^[ACGTNacgtn]*$"},
82
+ "BarcodeMismatchesIndex1": {"type": "string"},
83
+ "BarcodeMismatchesIndex2": {"type": "string"},
84
+ },
85
+ "additionalProperties": True,
86
+ },
87
+ "BCLConvert_Data": {
88
+ "type": "array",
89
+ "minItems": 1,
90
+ "items": {
91
+ "type": "object",
92
+ "required": ["Sample_ID", "Index"],
93
+ "properties": {
94
+ "Sample_ID": {"type": "string", "minLength": 1},
95
+ "Sample_Name": {"type": "string"},
96
+ "Sample_Project": {"type": "string"},
97
+ "Lane": {"type": "string"},
98
+ "Index": {"type": "string", "pattern": "^[ACGTNacgtn]+$"},
99
+ "Index2": {"type": "string", "pattern": "^[ACGTNacgtn]*$"},
100
+ },
101
+ "additionalProperties": True,
102
+ },
103
+ },
104
+ },
105
+ "additionalProperties": True,
106
+ }
107
+
108
+
109
+ def sheet_to_sections(sheet: Any) -> dict[str, Any]:
110
+ """Return a sectioned view of a parsed sheet, as the v2 schema expects.
111
+
112
+ Section names are top-level keys. ``[Header]`` / ``[*_Settings]`` sections
113
+ are objects; ``[*_Data]`` sections are arrays of row objects with their
114
+ original column names (e.g. ``Sample_ID``, ``Index``), so a schema written
115
+ in terms of the sheet's real sections and columns applies directly.
116
+
117
+ Projects the recognized sections only: ``Header``, ``Reads``,
118
+ ``BCLConvert_Settings``, ``BCLConvert_Data`` (v2), and ``Cloud_Data``. A v2
119
+ sheet (``FileFormatVersion`` in ``[Header]``) always projects a
120
+ ``BCLConvert_Data`` array, even when empty, so a schema can tell an empty
121
+ data section from a missing one. Non-v2 sheets (e.g. IEM V1) emit their data
122
+ rows under a generic ``Data`` key. Other custom sections a sheet may carry
123
+ are not included in this view yet, so a schema requiring one of those cannot
124
+ be checked against it.
125
+ """
126
+ out: dict[str, Any] = {}
127
+
128
+ header = getattr(sheet, "header", None)
129
+ if header:
130
+ out["Header"] = dict(header)
131
+
132
+ reads = getattr(sheet, "reads", None)
133
+ if reads:
134
+ out["Reads"] = dict(reads)
135
+
136
+ settings = getattr(sheet, "settings", None)
137
+ if settings:
138
+ out["BCLConvert_Settings"] = dict(settings)
139
+
140
+ # Detect v2 by its header marker, not by the presence of a `records`
141
+ # attribute: V1 sheets expose `records` too. A v2 sheet always projects a
142
+ # BCLConvert_Data array (even empty) so an empty data section is
143
+ # distinguishable from a missing one.
144
+ is_v2 = header is not None and "FileFormatVersion" in header
145
+ records = getattr(sheet, "records", None)
146
+ if is_v2:
147
+ out["BCLConvert_Data"] = [dict(r) for r in (records or [])]
148
+ elif records:
149
+ out["Data"] = [dict(r) for r in records]
150
+ else:
151
+ samples = sheet.samples()
152
+ if samples:
153
+ out["Data"] = [dict(s) for s in samples]
154
+
155
+ cloud = getattr(sheet, "cloud_data", None)
156
+ if cloud:
157
+ out["Cloud_Data"] = [dict(r) for r in cloud]
158
+
159
+ return out
160
+
161
+
162
+ def build_registry() -> Any | None:
163
+ """Build a :mod:`referencing` registry resolving the bundled v2 schema.
164
+
165
+ The bundled :data:`ILLUMINA_V2_SCHEMA` is registered under both
166
+ :data:`ILLUMINA_V2_URN` and :data:`SAMSHEE_V2_URN`, so a ``$ref`` to either
167
+ resolves offline. Returns ``None`` when ``referencing`` / ``jsonschema`` is
168
+ not installed, so callers can degrade gracefully.
169
+ """
170
+ try:
171
+ from referencing import Registry, Resource
172
+ except ImportError:
173
+ return None
174
+
175
+ resource = Resource.from_contents(ILLUMINA_V2_SCHEMA)
176
+ return Registry().with_resources([(ILLUMINA_V2_URN, resource), (SAMSHEE_V2_URN, resource)])
@@ -19,7 +19,9 @@ from __future__ import annotations
19
19
 
20
20
  import logging
21
21
  import re
22
+ from collections.abc import Callable, Iterable, Mapping, Sequence
22
23
  from dataclasses import dataclass, field
24
+ from enum import Enum
23
25
  from typing import Any
24
26
 
25
27
  from samplesheet_parser.chemistry import (
@@ -31,6 +33,7 @@ from samplesheet_parser.chemistry import (
31
33
  chemistry_for_instrument,
32
34
  )
33
35
  from samplesheet_parser.protocol import SampleSheetParser
36
+ from samplesheet_parser.schema import ILLUMINA_V2_SCHEMA, build_registry, sheet_to_sections
34
37
 
35
38
  logger = logging.getLogger(__name__)
36
39
 
@@ -222,6 +225,338 @@ def index_collision_distance(a: str, b: str) -> int:
222
225
  )
223
226
 
224
227
 
228
+ # ---------------------------------------------------------------------------
229
+ # Pluggable validation: strictness dial, user-supplied validators, JSON Schema
230
+ # ---------------------------------------------------------------------------
231
+
232
+ #: A pluggable validator: given a parsed sheet, return an iterable of
233
+ #: :class:`ValidationIssue` (or ``None`` for "nothing to report"), or raise
234
+ #: :class:`ValidatorError` to signal a single error. User-supplied rules and
235
+ #: the built-in strict checks both use this shape, so their output merges into
236
+ #: the same :class:`ValidationResult` as the core checks.
237
+ Validator = Callable[[SampleSheetParser], Iterable[ValidationIssue] | None]
238
+
239
+
240
+ class Strictness(str, Enum):
241
+ """A single strict<->lenient dial that cascades to the core checks.
242
+
243
+ * ``LENIENT`` - looser index-distance threshold, no colour balance.
244
+ * ``STANDARD`` - the historical default behaviour.
245
+ * ``STRICT`` - tighter index distance, conservative colour balance, and
246
+ the built-in :func:`illumina_v2_conformance` validator turned on.
247
+
248
+ An explicit keyword to :meth:`SampleSheetValidator.validate` (e.g.
249
+ ``min_hamming_distance=5``) always overrides the level's preset, so the dial
250
+ sets defaults rather than locking values.
251
+ """
252
+
253
+ LENIENT = "lenient"
254
+ STANDARD = "standard"
255
+ STRICT = "strict"
256
+
257
+
258
+ class ValidatorError(Exception):
259
+ """Raise from a pluggable validator to report one error.
260
+
261
+ Lets a user-supplied function signal a violation without building a
262
+ :class:`ValidationIssue`; the runner turns it into an error on the result.
263
+
264
+ Examples
265
+ --------
266
+ >>> def require_project(sheet):
267
+ ... for s in sheet.samples():
268
+ ... if not s.get("sample_project"):
269
+ ... raise ValidatorError(
270
+ ... f"{s.get('sample_id')} has no Sample_Project",
271
+ ... code="LAB_MISSING_PROJECT",
272
+ ... )
273
+ ... return []
274
+ """
275
+
276
+ def __init__(self, message: str, code: str = "CUSTOM_VALIDATION", **context: Any) -> None:
277
+ super().__init__(message)
278
+ self.code = code
279
+ self.context = context
280
+
281
+
282
+ #: Strictness presets, applied to the core checks when the matching keyword is
283
+ #: left unset on :meth:`SampleSheetValidator.validate`.
284
+ _STRICTNESS_PRESETS: dict[Strictness, dict[str, Any]] = {
285
+ Strictness.LENIENT: {
286
+ "min_hamming_distance": 2,
287
+ "check_color_balance": False,
288
+ "color_balance_mode": ColorBalanceMode.VENDOR_FAITHFUL,
289
+ },
290
+ Strictness.STANDARD: {
291
+ "min_hamming_distance": MIN_HAMMING_DISTANCE,
292
+ "check_color_balance": False,
293
+ "color_balance_mode": ColorBalanceMode.VENDOR_FAITHFUL,
294
+ },
295
+ Strictness.STRICT: {
296
+ "min_hamming_distance": MIN_HAMMING_DISTANCE + 1,
297
+ "check_color_balance": True,
298
+ "color_balance_mode": ColorBalanceMode.CONSERVATIVE,
299
+ },
300
+ }
301
+
302
+
303
+ def _run_validator(
304
+ validator: Validator,
305
+ sheet: SampleSheetParser,
306
+ result: ValidationResult,
307
+ ) -> None:
308
+ """Run one pluggable validator and merge its output into ``result``."""
309
+ try:
310
+ issues = validator(sheet)
311
+ except ValidatorError as exc:
312
+ result.add_error(exc.code, str(exc), **exc.context)
313
+ return
314
+
315
+ for issue in issues or ():
316
+ if issue.level == "error":
317
+ result.add_error(issue.code, issue.message, **issue.context)
318
+ elif issue.level == "warning":
319
+ result.add_warning(issue.code, issue.message, **issue.context)
320
+ else:
321
+ result.add_note(issue.code, issue.message, **issue.context)
322
+
323
+
324
+ def sheet_to_dict(sheet: SampleSheetParser) -> dict[str, Any]:
325
+ """Return a minimal, flat JSON-friendly view of a parsed sheet.
326
+
327
+ A convenience view with lowercase keys - ``header``, ``reads``,
328
+ ``settings``, ``samples`` - and the natural seed for a fuller ``to_json()``
329
+ on the parsers. Note JSON Schema validation uses the *sectioned* view
330
+ (:func:`~samplesheet_parser.schema.sheet_to_sections`) instead, which keeps
331
+ the sheet's real section and column names; see :func:`json_schema_validator`.
332
+ """
333
+ return {
334
+ "header": dict(getattr(sheet, "header", None) or {}),
335
+ "reads": dict(getattr(sheet, "reads", None) or {}),
336
+ "settings": dict(getattr(sheet, "settings", None) or {}),
337
+ "samples": list(sheet.samples()),
338
+ }
339
+
340
+
341
+ def _sample_index(sample: Mapping[str, Any], *keys: str) -> str | None:
342
+ for key in keys:
343
+ value = sample.get(key)
344
+ if value:
345
+ return str(value)
346
+ return None
347
+
348
+
349
+ def illumina_v2_conformance(sheet: SampleSheetParser) -> list[ValidationIssue]:
350
+ """Flag a BCLConvert v2 sheet that departs from the Illumina v2 spec.
351
+
352
+ This is the strict counterpart to the lenient-by-default structural
353
+ behaviour: it enforces a subset of the Illumina v2 Settings specification
354
+ the way samshee's default validators do, expressed as a plain pluggable
355
+ validator. It is **not** part of the core checks; it is turned on by
356
+ :attr:`Strictness.STRICT` (or by passing it in ``extra_validators``), so
357
+ tolerant parsing - including per-sample ``OverrideCycles`` columns - stays
358
+ the default.
359
+
360
+ Checks
361
+ ------
362
+ * ``SPEC_NOT_APPLICABLE`` - no ``FileFormatVersion`` (V1 / AVITI): skipped.
363
+ * ``SPEC_BAD_FORMAT_VERSION`` - ``FileFormatVersion`` is not ``2``.
364
+ * ``SPEC_MISSING_RUNNAME`` - ``[Header]`` has no ``RunName`` (warning).
365
+ * ``SPEC_MISSING_READ1`` - ``[Reads]`` has no positive ``Read1Cycles``.
366
+ * ``SPEC_INDEX_LENGTH_MISMATCH`` - an index length does not match the
367
+ declared ``Index1Cycles`` / ``Index2Cycles``.
368
+ """
369
+ issues: list[ValidationIssue] = []
370
+
371
+ header: dict[str, Any] = dict(getattr(sheet, "header", None) or {})
372
+ reads: dict[str, Any] = dict(getattr(sheet, "reads", None) or {})
373
+
374
+ if "FileFormatVersion" not in header:
375
+ return [
376
+ ValidationIssue(
377
+ "note",
378
+ "SPEC_NOT_APPLICABLE",
379
+ "Illumina v2 conformance check skipped " "(no FileFormatVersion in [Header]).",
380
+ )
381
+ ]
382
+
383
+ if str(header.get("FileFormatVersion")) != "2":
384
+ issues.append(
385
+ ValidationIssue(
386
+ "error",
387
+ "SPEC_BAD_FORMAT_VERSION",
388
+ f"FileFormatVersion must be 2, found {header.get('FileFormatVersion')!r}.",
389
+ )
390
+ )
391
+
392
+ if not header.get("RunName"):
393
+ issues.append(
394
+ ValidationIssue(
395
+ "warning",
396
+ "SPEC_MISSING_RUNNAME",
397
+ "[Header] has no RunName (recommended by the Illumina v2 spec).",
398
+ )
399
+ )
400
+
401
+ read1 = reads.get("Read1Cycles")
402
+ if not read1 or int(read1) <= 0:
403
+ issues.append(
404
+ ValidationIssue(
405
+ "error",
406
+ "SPEC_MISSING_READ1",
407
+ "[Reads] must declare a positive Read1Cycles.",
408
+ )
409
+ )
410
+
411
+ index1_cycles = reads.get("Index1Cycles")
412
+ index2_cycles = reads.get("Index2Cycles")
413
+ for sample in sheet.samples():
414
+ sid = sample.get("sample_id") or sample.get("Sample_ID") or "?"
415
+ idx1 = _sample_index(sample, "index", "Index")
416
+ idx2 = _sample_index(sample, "index2", "Index2")
417
+ if idx1 and index1_cycles and len(idx1) != int(index1_cycles):
418
+ issues.append(
419
+ ValidationIssue(
420
+ "error",
421
+ "SPEC_INDEX_LENGTH_MISMATCH",
422
+ f"Index '{idx1}' ({len(idx1)} bp) does not match "
423
+ f"Index1Cycles={index1_cycles}.",
424
+ {"sample_id": sid, "field": "index"},
425
+ )
426
+ )
427
+ if idx2 and index2_cycles and len(idx2) != int(index2_cycles):
428
+ issues.append(
429
+ ValidationIssue(
430
+ "error",
431
+ "SPEC_INDEX_LENGTH_MISMATCH",
432
+ f"Index2 '{idx2}' ({len(idx2)} bp) does not match "
433
+ f"Index2Cycles={index2_cycles}.",
434
+ {"sample_id": sid, "field": "index2"},
435
+ )
436
+ )
437
+
438
+ return issues
439
+
440
+
441
+ def _validate_against_schema(
442
+ schema: Mapping[str, Any],
443
+ sheet: SampleSheetParser,
444
+ *,
445
+ error_code: str,
446
+ ) -> list[ValidationIssue]:
447
+ """Validate the sectioned view of ``sheet`` against a JSON Schema.
448
+
449
+ Resolves ``$ref`` against the bundled registry (so a reference to
450
+ :data:`~samplesheet_parser.schema.ILLUMINA_V2_URN` or
451
+ :data:`~samplesheet_parser.schema.SAMSHEE_V2_URN` works offline), and
452
+ degrades to a ``SCHEMA_SKIPPED`` note when ``jsonschema`` is absent.
453
+ """
454
+ try:
455
+ import jsonschema
456
+ except ImportError:
457
+ return [
458
+ ValidationIssue(
459
+ "note",
460
+ "SCHEMA_SKIPPED",
461
+ "jsonschema is not installed; the JSON Schema check was skipped. "
462
+ "Install `jsonschema` (or the `samplesheet-parser[schema]` extra) "
463
+ "to enable schema validation.",
464
+ )
465
+ ]
466
+
467
+ # Validate the schema itself first: the validator constructor does not
468
+ # reliably reject a malformed schema, so without this check a bad schema
469
+ # would instead surface later as a reference error with the wrong code.
470
+ try:
471
+ jsonschema.Draft202012Validator.check_schema(dict(schema))
472
+ except jsonschema.exceptions.SchemaError as exc:
473
+ return [ValidationIssue("error", "SCHEMA_INVALID", f"Invalid JSON Schema: {exc}")]
474
+
475
+ document = sheet_to_sections(sheet)
476
+ registry = build_registry()
477
+ if registry is not None:
478
+ validator = jsonschema.Draft202012Validator(dict(schema), registry=registry)
479
+ else:
480
+ validator = jsonschema.Draft202012Validator(dict(schema))
481
+
482
+ try:
483
+ errors = list(validator.iter_errors(document))
484
+ except Exception as exc: # unresolvable $ref
485
+ return [
486
+ ValidationIssue(
487
+ "error",
488
+ "SCHEMA_REF_UNRESOLVED",
489
+ f"Could not resolve a schema reference: {exc}",
490
+ )
491
+ ]
492
+
493
+ issues: list[ValidationIssue] = []
494
+ for error in sorted(errors, key=lambda e: list(e.absolute_path)):
495
+ issues.append(
496
+ ValidationIssue(
497
+ "error",
498
+ error_code,
499
+ str(error.message),
500
+ {"path": "/".join(str(p) for p in error.absolute_path)},
501
+ )
502
+ )
503
+ return issues
504
+
505
+
506
+ def json_schema_validator(schema: Mapping[str, Any]) -> Validator:
507
+ """Build a validator that checks the sheet against a JSON Schema.
508
+
509
+ The schema is checked against :func:`~samplesheet_parser.schema.sheet_to_sections`
510
+ (section names as top-level keys, Data sections as arrays of row objects),
511
+ which mirrors how samshee represents a sheet, so a samshee-authored schema
512
+ applies directly. A schema may ``$ref`` the bundled Illumina v2 document by
513
+ URN - ``urn:samplesheet-parser:illuminav2/v1`` or the samshee compatibility
514
+ alias ``urn:samshee:illuminav2/v1`` - and it resolves offline via the
515
+ bundled registry.
516
+
517
+ ``jsonschema`` is a **soft** dependency: when it is not installed the check
518
+ degrades to a ``SCHEMA_SKIPPED`` note instead of failing, keeping the core
519
+ dependency-free. Install it with ``pip install jsonschema`` (or the
520
+ ``samplesheet-parser[schema]`` extra) to enable the check.
521
+ """
522
+
523
+ def _validate(sheet: SampleSheetParser) -> list[ValidationIssue]:
524
+ return _validate_against_schema(schema, sheet, error_code="SCHEMA_VIOLATION")
525
+
526
+ return _validate
527
+
528
+
529
+ def illumina_v2_schema_validator() -> Validator:
530
+ """Build a validator that checks a sheet against the bundled Illumina v2 schema.
531
+
532
+ This is the schema-based counterpart to the procedural
533
+ :func:`illumina_v2_conformance`: it enforces the structural v2 spec
534
+ (required sections and fields, value types, index character set) from
535
+ :data:`~samplesheet_parser.schema.ILLUMINA_V2_SCHEMA`, while conformance adds
536
+ the cross-field checks a JSON Schema cannot express (e.g. index length vs
537
+ declared cycles). Both run at :attr:`Strictness.STRICT`.
538
+
539
+ Skips non-v2 sheets (no ``FileFormatVersion`` in ``[Header]``) with a
540
+ ``SPEC_NOT_APPLICABLE`` note, so V1 / AVITI sheets are not failed.
541
+ """
542
+
543
+ def _validate(sheet: SampleSheetParser) -> list[ValidationIssue]:
544
+ header = getattr(sheet, "header", None) or {}
545
+ if "FileFormatVersion" not in header:
546
+ return [
547
+ ValidationIssue(
548
+ "note",
549
+ "SPEC_NOT_APPLICABLE",
550
+ "Illumina v2 schema check skipped " "(no FileFormatVersion in [Header]).",
551
+ )
552
+ ]
553
+ return _validate_against_schema(
554
+ ILLUMINA_V2_SCHEMA, sheet, error_code="SPEC_SCHEMA_VIOLATION"
555
+ )
556
+
557
+ return _validate
558
+
559
+
225
560
  # ---------------------------------------------------------------------------
226
561
  # Validator
227
562
  # ---------------------------------------------------------------------------
@@ -277,10 +612,13 @@ class SampleSheetValidator:
277
612
  self,
278
613
  sheet: SampleSheetParser,
279
614
  *,
280
- min_hamming_distance: int = MIN_HAMMING_DISTANCE,
281
- check_color_balance: bool = False,
615
+ strictness: Strictness | str = Strictness.STANDARD,
616
+ extra_validators: Sequence[Validator] = (),
617
+ schema: Mapping[str, Any] | None = None,
618
+ min_hamming_distance: int | None = None,
619
+ check_color_balance: bool | None = None,
282
620
  instrument: str | None = None,
283
- color_balance_mode: ColorBalanceMode | str = ColorBalanceMode.VENDOR_FAITHFUL,
621
+ color_balance_mode: ColorBalanceMode | str | None = None,
284
622
  min_signal_fraction: float = DEFAULT_MIN_SIGNAL_FRACTION,
285
623
  ) -> ValidationResult:
286
624
  """Run all validation checks on a parsed sample sheet.
@@ -290,18 +628,38 @@ class SampleSheetValidator:
290
628
  sheet:
291
629
  A parsed :class:`SampleSheetV1` or :class:`SampleSheetV2`
292
630
  instance (i.e., :meth:`parse` has been called).
631
+ strictness:
632
+ The overall strict<->lenient level (see :class:`Strictness`).
633
+ Defaults to :attr:`Strictness.STANDARD`, which reproduces the
634
+ historical behaviour exactly. The level sets the defaults for
635
+ ``min_hamming_distance``, ``check_color_balance``, and
636
+ ``color_balance_mode`` when those are left unset, and
637
+ :attr:`Strictness.STRICT` additionally runs
638
+ :func:`illumina_v2_conformance`. Any explicit keyword below
639
+ overrides the level's preset.
640
+ extra_validators:
641
+ A sequence of pluggable validators (see :data:`Validator`) run
642
+ after the core checks. Each may return :class:`ValidationIssue`
643
+ objects or raise :class:`ValidatorError`; their output merges into
644
+ this result. Use this for lab-specific or project-specific rules.
645
+ schema:
646
+ An optional JSON Schema (draft 2020-12) checked against
647
+ :func:`sheet_to_dict`. Requires the soft ``jsonschema`` dependency;
648
+ without it the check becomes a ``SCHEMA_SKIPPED`` note. See
649
+ :func:`json_schema_validator`.
293
650
  min_hamming_distance:
294
651
  Minimum Hamming distance required between any two index sequences
295
652
  in the same lane. Pairs below this threshold produce an
296
- ``INDEX_DISTANCE_TOO_LOW`` warning. Defaults to
297
- :data:`MIN_HAMMING_DISTANCE` (3). Set higher (e.g. ``4``) for
653
+ ``INDEX_DISTANCE_TOO_LOW`` warning. When unset (``None``), resolved
654
+ from ``strictness`` (3 at STANDARD). Set higher (e.g. ``4``) for
298
655
  stricter demultiplexing requirements with longer indexes.
299
656
  check_color_balance:
300
657
  Opt in to per-cycle index colour-balance checking against the
301
658
  instrument's optical chemistry (see :meth:`_check_color_balance`).
302
- Off by default because it can turn an otherwise-valid low-plex
303
- pool into an error; enable it when the sheet declares (or you pass)
304
- a known instrument.
659
+ When unset (``None``), resolved from ``strictness`` (off except at
660
+ STRICT). Off by default because it can turn an otherwise-valid
661
+ low-plex pool into an error; enable it when the sheet declares (or
662
+ you pass) a known instrument.
305
663
  instrument:
306
664
  Instrument name used to resolve the optical chemistry for the
307
665
  colour-balance check. Defaults to the instrument declared in the
@@ -317,27 +675,54 @@ class SampleSheetValidator:
317
675
  ValidationResult
318
676
  Structured result with ``is_valid``, ``errors``, and ``warnings``.
319
677
  """
678
+ level = Strictness(strictness)
679
+ preset = _STRICTNESS_PRESETS[level]
680
+ resolved_min_distance: int = (
681
+ preset["min_hamming_distance"] if min_hamming_distance is None else min_hamming_distance
682
+ )
683
+ resolved_check_cb: bool = (
684
+ preset["check_color_balance"] if check_color_balance is None else check_color_balance
685
+ )
686
+ resolved_cb_mode: ColorBalanceMode | str = (
687
+ preset["color_balance_mode"] if color_balance_mode is None else color_balance_mode
688
+ )
689
+
320
690
  result = ValidationResult()
321
691
  samples = sheet.samples()
322
692
 
323
693
  self._check_empty(samples, result)
324
- if not samples:
325
- return result # no point continuing
326
-
327
- self._check_index_sequences(samples, result)
328
- self._check_duplicate_indices(samples, result)
329
- self._check_index_distances(samples, result, min_distance=min_hamming_distance)
330
- self._check_duplicate_sample_ids(samples, result)
331
- self._check_adapters(sheet, result)
332
- if check_color_balance:
333
- self._check_color_balance(
334
- sheet,
335
- samples,
336
- result,
337
- instrument=instrument,
338
- mode=color_balance_mode,
339
- min_signal_fraction=min_signal_fraction,
340
- )
694
+
695
+ # Sample-dependent core checks only run when there are samples; the
696
+ # pluggable and schema validators below still run on an empty sheet, so
697
+ # a strict schema (e.g. BCLConvert_Data minItems) or a user-supplied
698
+ # validator is not silently skipped.
699
+ if samples:
700
+ self._check_index_sequences(samples, result)
701
+ self._check_duplicate_indices(samples, result)
702
+ self._check_index_distances(samples, result, min_distance=resolved_min_distance)
703
+ self._check_duplicate_sample_ids(samples, result)
704
+ self._check_adapters(sheet, result)
705
+ if resolved_check_cb:
706
+ self._check_color_balance(
707
+ sheet,
708
+ samples,
709
+ result,
710
+ instrument=instrument,
711
+ mode=resolved_cb_mode,
712
+ min_signal_fraction=min_signal_fraction,
713
+ )
714
+
715
+ # Pluggable validators: strict spec conformance (at STRICT), then any
716
+ # user-supplied validators, then an optional JSON Schema.
717
+ chain: list[Validator] = []
718
+ if level is Strictness.STRICT:
719
+ chain.append(illumina_v2_conformance)
720
+ chain.append(illumina_v2_schema_validator())
721
+ chain.extend(extra_validators)
722
+ if schema is not None:
723
+ chain.append(json_schema_validator(schema))
724
+ for validator in chain:
725
+ _run_validator(validator, sheet, result)
341
726
 
342
727
  return result
343
728
 
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: samplesheet-parser
3
- Version: 2.5.2
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
3
+ Version: 2.6.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://samplesheet-parser.readthedocs.io
7
7
  Project-URL: Repository, https://github.com/chaitanyakasaraneni/samplesheet-parser
@@ -44,6 +44,7 @@ Provides-Extra: cli
44
44
  Requires-Dist: typer>=0.12; extra == 'cli'
45
45
  Provides-Extra: dev
46
46
  Requires-Dist: black>=24.0; extra == 'dev'
47
+ Requires-Dist: jsonschema>=4.18; extra == 'dev'
47
48
  Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
48
49
  Requires-Dist: mkdocs>=1.6; extra == 'dev'
49
50
  Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
@@ -52,13 +53,15 @@ Requires-Dist: pytest-cov>=4.1; extra == 'dev'
52
53
  Requires-Dist: pytest>=7.4; extra == 'dev'
53
54
  Requires-Dist: ruff>=0.3; extra == 'dev'
54
55
  Requires-Dist: typer>=0.12; extra == 'dev'
56
+ Provides-Extra: schema
57
+ Requires-Dist: jsonschema>=4.18; extra == 'schema'
55
58
  Description-Content-Type: text/markdown
56
59
 
57
60
  # samplesheet-parser
58
61
 
59
62
  **Multi-vendor, format-agnostic parser for sequencing sample sheets.**
60
63
 
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.
64
+ 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
65
 
63
66
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
64
67
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -72,17 +75,20 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
72
75
 
73
76
  **Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
74
77
 
75
- ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v2.3.png)
78
+ <picture>
79
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_latest_dark.png">
80
+ <img alt="samplesheet-parser overview" src="https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_latest.png">
81
+ </picture>
76
82
 
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.*
83
+ *`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 (with optional strictness levels and JSON Schema validation), `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
84
 
79
85
  ---
80
86
 
81
87
  ## The problem this solves
82
88
 
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.
89
+ 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
90
 
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.
91
+ 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
92
 
87
93
  ---
88
94
 
@@ -157,7 +163,7 @@ from samplesheet_parser import SampleSheetConverter
157
163
  # V1 → V2
158
164
  SampleSheetConverter("SampleSheet_v1.csv").to_v2("SampleSheet_v2.csv")
159
165
 
160
- # V2 → V1 (lossy — V2-only fields are dropped with a warning)
166
+ # V2 → V1 (lossy - V2-only fields are dropped with a warning)
161
167
  SampleSheetConverter("SampleSheet_v2.csv").to_v1("SampleSheet_v1.csv")
162
168
  ```
163
169
 
@@ -170,7 +176,7 @@ sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=True)
170
176
  result = SampleSheetValidator().validate(sheet)
171
177
 
172
178
  print(result.summary())
173
- # PASS — 0 error(s), 2 warning(s)
179
+ # PASS - 0 error(s), 2 warning(s)
174
180
 
175
181
  for w in result.warnings:
176
182
  print(w)
@@ -207,7 +213,7 @@ if result.has_changes:
207
213
  print(f"Added: {s['Sample_ID']}")
208
214
  ```
209
215
 
210
- Works across any combination of V1 and V2 — field names are normalised before
216
+ Works across any combination of V1 and V2 - field names are normalised before
211
217
  comparison so V1-only columns (`I7_Index_ID`, `Sample_Name`, etc.) do not
212
218
  generate spurious diffs.
213
219
 
@@ -237,7 +243,7 @@ editor.update_sample("SAMPLE_002", index="GGGGGGGGGG")
237
243
  editor.write("SampleSheet_updated.csv")
238
244
  ```
239
245
 
240
- `write()` runs `SampleSheetValidator` before writing by default — pass
246
+ `write()` runs `SampleSheetValidator` before writing by default - pass
241
247
  `validate=False` to skip. `from_sheet(sheet, version=SampleSheetVersion.V1)`
242
248
  converts format while editing.
243
249
 
@@ -263,7 +269,7 @@ result = (
263
269
  )
264
270
 
265
271
  print(result.summary())
266
- # Merged 3 sheet(s) → SampleSheet_combined.csv (12 samples) — 0 conflict(s), 0 warning(s)
272
+ # Merged 3 sheet(s) → SampleSheet_combined.csv (12 samples) - 0 conflict(s), 0 warning(s)
267
273
 
268
274
  if result.has_conflicts:
269
275
  for c in result.conflicts:
@@ -293,7 +299,7 @@ pip install "samplesheet-parser[cli]"
293
299
  ### validate
294
300
 
295
301
  ```bash
296
- # Text output — exit 0 if clean, exit 1 if errors
302
+ # Text output - exit 0 if clean, exit 1 if errors
297
303
  samplesheet validate SampleSheet.csv
298
304
 
299
305
  # JSON output for CI pipelines
@@ -320,7 +326,7 @@ samplesheet diff old/SampleSheet.csv new/SampleSheet.csv --format json
320
326
  ### merge
321
327
 
322
328
  ```bash
323
- # Clean merge — exit 0
329
+ # Clean merge - exit 0
324
330
  samplesheet merge ProjectA.csv ProjectB.csv --output combined.csv
325
331
 
326
332
  # Merge three sheets to V1 format
@@ -345,14 +351,14 @@ samplesheet merge ProjectA.csv ProjectB.csv --output combined.csv --format json
345
351
 
346
352
  ## Format detection logic
347
353
 
348
- The factory detects the format across vendors — no format hints required from the caller:
354
+ The factory detects the format across vendors - no format hints required from the caller:
349
355
 
350
- 1. **Vendor manifest check** — recognise a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
351
- 2. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
352
- 3. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
353
- 4. **Default** — fall back to V1 (broadest compatibility with legacy files)
356
+ 1. **Vendor manifest check** - recognise a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
357
+ 2. **Header discriminator** - scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
358
+ 3. **Section name scan** - if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
359
+ 4. **Default** - fall back to V1 (broadest compatibility with legacy files)
354
360
 
355
- For Illumina sheets the detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
361
+ For Illumina sheets the detector reads only as much of the file as needed - stopping after `[Header]` in the common case.
356
362
 
357
363
  ---
358
364
 
@@ -369,8 +375,8 @@ For Illumina sheets the detector reads only as much of the file as needed — st
369
375
  | `INDEX_DISTANCE_TOO_LOW` | warning | Two indexes in the same lane have Hamming distance < 3, risking demultiplexing bleed-through |
370
376
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
371
377
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
372
- | `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.* |
373
- | `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) — degraded base calls. *Opt-in.* |
378
+ | `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.* |
379
+ | `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) - degraded base calls. *Opt-in.* |
374
380
 
375
381
  ### Index distance checking
376
382
 
@@ -406,7 +412,7 @@ On 2-channel instruments (NextSeq, NovaSeq, NovaSeq X) and 1-channel
406
412
  instruments (iSeq), bases are called from optical signal: `A` lights
407
413
  both channels, `C` only red, `T` only green, and **`G` is a dark base with no
408
414
  signal at all**. A cycle where the whole index pool reads `G` produces no
409
- signal, so the instrument cannot register the tile and the index read fails —
415
+ signal, so the instrument cannot register the tile and the index read fails -
410
416
  a real, common cause of wrecked runs that a Hamming-distance check cannot see.
411
417
 
412
418
  Because the sample sheet already contains every sample's index, this can be
@@ -465,24 +471,24 @@ Color balance has two modes, selectable on the CLI via
465
471
  `validate(..., color_balance_mode=...)` / `analyze_color_balance(..., mode=...)`:
466
472
 
467
473
  - **`vendor_faithful`** (default) encodes each platform's *published* rule
468
- exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
474
+ exactly - Illumina's "signal in at least one channel" minimum for 2-channel,
469
475
  the both-lasers rule for 4-channel, and Element's permissive low-diversity
470
476
  stance for AVITI.
471
477
  - **`conservative`** is stricter than the published minimum: it also fails
472
478
  single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
473
- behavior before modes existed — pass `color_balance_mode="conservative"` to
479
+ behavior before modes existed - pass `color_balance_mode="conservative"` to
474
480
  keep it.)
475
481
 
476
482
  | Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
477
483
  |---|---|---|---|
478
- | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
484
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | - |
479
485
  | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
480
486
  | 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
481
487
  | avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
482
488
 
483
- Element AVITI uses avidity chemistry — each base has its own avidite dye
489
+ Element AVITI uses avidity chemistry - each base has its own avidite dye
484
490
  ([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
485
- — so it has no dark base and no laser-pair constraint. In `vendor_faithful`
491
+ - so it has no dark base and no laser-pair constraint. In `vendor_faithful`
486
492
  mode, AVITI low diversity in the first cycles is an advisory
487
493
  (`COLOR_BALANCE_ADVISORY`), never a failure.
488
494
 
@@ -492,7 +498,7 @@ mode, AVITI low diversity in the first cycles is an advisory
492
498
 
493
499
  The factory is not limited to Illumina. Any parser that implements the
494
500
  `SampleSheetParser` protocol can be auto-detected, and **Element Biosciences
495
- AVITI `RunManifest.csv`** files are supported out of the box — the same
501
+ AVITI `RunManifest.csv`** files are supported out of the box - the same
496
502
  `SampleSheetFactory` recognises them and returns a parser with the identical
497
503
  interface:
498
504
 
@@ -534,7 +540,7 @@ across vendors without special-casing.
534
540
 
535
541
  ## Diff
536
542
 
537
- `SampleSheetDiff` compares two sheets — any combination of V1 and V2 — and
543
+ `SampleSheetDiff` compares two sheets - any combination of V1 and V2 - and
538
544
  returns a structured `DiffResult` across four dimensions:
539
545
 
540
546
  | Dimension | What is compared |
@@ -573,7 +579,7 @@ The V2 `OverrideCycles` field encodes read structure including UMI positions:
573
579
 
574
580
  | OverrideCycles | UMI length | UMI location |
575
581
  |---|---|---|
576
- | `Y151;I10;I10;Y151` | 0 | — |
582
+ | `Y151;I10;I10;Y151` | 0 | - |
577
583
  | `Y151;I10U9;I10;Y151` | 9 | `index2` |
578
584
  | `U5Y146;I8;I8;U5Y146` | 5 | `read1` |
579
585
 
@@ -650,13 +656,13 @@ Public helper for computing the Hamming distance between two index sequences. Se
650
656
 
651
657
  | Method / attribute | Returns | Description |
652
658
  |---|---|---|
653
- | `SampleSheetWriter(version=)` | — | Instantiate for `SampleSheetVersion.V1` or `.V2` |
659
+ | `SampleSheetWriter(version=)` | - | Instantiate for `SampleSheetVersion.V1` or `.V2` |
654
660
  | `from_sheet(sheet, version=)` | `SampleSheetWriter` | Load a parsed sheet for editing; optionally change output format |
655
661
  | `set_header(*, run_name, platform, ...)` | `self` | Set header fields (fluent) |
656
662
  | `set_reads(*, read1, read2, index1, index2)` | `self` | Set read cycle counts (fluent) |
657
663
  | `set_adapter(adapter_read1, adapter_read2)` | `self` | Set adapter sequences (fluent) |
658
- | `set_override_cycles(override)` | `self` | Set `OverrideCycles` string — V2 only (fluent) |
659
- | `set_software_version(version)` | `self` | Set `SoftwareVersion` — V2 only (fluent) |
664
+ | `set_override_cycles(override)` | `self` | Set `OverrideCycles` string - V2 only (fluent) |
665
+ | `set_software_version(version)` | `self` | Set `SoftwareVersion` - V2 only (fluent) |
660
666
  | `set_setting(key, value)` | `self` | Set an arbitrary settings key/value (fluent) |
661
667
  | `add_sample(sample_id, *, index, ...)` | `self` | Append a sample row (fluent) |
662
668
  | `remove_sample(sample_id, *, lane=)` | `self` | Remove sample(s) by ID, optionally scoped to a lane (fluent) |
@@ -695,7 +701,7 @@ Public helper for computing the Hamming distance between two index sequences. Se
695
701
 
696
702
  | Method / attribute | Returns | Description |
697
703
  |---|---|---|
698
- | `SampleSheetMerger(target_version=)` | — | Instantiate; default target is `SampleSheetVersion.V2` |
704
+ | `SampleSheetMerger(target_version=)` | - | Instantiate; default target is `SampleSheetVersion.V2` |
699
705
  | `add(path)` | `self` | Register an input sheet path (fluent) |
700
706
  | `merge(output_path, *, validate=True, abort_on_conflicts=True)` | `MergeResult` | Run the merge and write output |
701
707
 
@@ -816,7 +822,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
816
822
  year = {2026},
817
823
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
818
824
  doi = {10.5281/zenodo.18989694},
819
- version = {2.4.0}
825
+ version = {2.6.0}
820
826
  }
821
827
  ```
822
828
 
@@ -826,7 +832,7 @@ See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
826
832
 
827
833
  ## License
828
834
 
829
- Apache 2.0 — see [LICENSE](LICENSE).
835
+ Apache 2.0 - see [LICENSE](LICENSE).
830
836
 
831
837
  ---
832
838
 
@@ -1,25 +1,26 @@
1
- samplesheet_parser/__init__.py,sha256=eSlshig-sXWyxW70vbd__lu9u6nfqVTyv-48MUsmiZg,2890
1
+ samplesheet_parser/__init__.py,sha256=Y8_18mcPPaFNL5vzulTJAYzTlE_VgkMpwsVpPtYRCd8,3536
2
2
  samplesheet_parser/chemistry.py,sha256=1I6jxzCmZqNqHitUzWQWo3JnuVHdASTVNUu-6jU4eoE,17631
3
- samplesheet_parser/cli.py,sha256=3Rz1Q1r_AeDdIS2uaRyK2Y7yGdAlveZf7GCF_38i3jY,32145
3
+ samplesheet_parser/cli.py,sha256=Sh6pUpVukQurskEMLsdu4mGigiywsDezlXmN8nquzyc,36074
4
4
  samplesheet_parser/converter.py,sha256=g4s5R6iB5mPDF-e8JD4Iezt2dMBBxgQ-OPL9vxJ2zM0,20236
5
5
  samplesheet_parser/diff.py,sha256=RruQhKRi0Ja6x5pq8CA-yafJ4JQJ3p0JXDp68RS53GE,15369
6
6
  samplesheet_parser/enums.py,sha256=SqxE5sRjBGRGk2J6lxpkgxb6luEqBTcdalok5lDFUS0,1790
7
- samplesheet_parser/factory.py,sha256=XVkot7FM0jKSQKNnmsvTpjqCTSq97e6sk_gP97MG88w,12323
7
+ samplesheet_parser/factory.py,sha256=WmRXN6QWblMm6Phrz6yN72PewieLa51CWK4NgXCpcik,12343
8
8
  samplesheet_parser/filter.py,sha256=4lkR_WJaawVVFdZPkxvVCYVG47AafFCwol4__WNhZdw,8161
9
9
  samplesheet_parser/index_utils.py,sha256=MWwVcQHO26oOuZdGNFA2g8OPrhP2rhkuYxzhbRaBXdY,6859
10
10
  samplesheet_parser/instruments.py,sha256=gUy2oCoWJmmxTI1cPtyIa84LrmEd1oA_GSkrHU27RIU,7529
11
11
  samplesheet_parser/merger.py,sha256=UxQ8bmX7632S70Lko3GFQTjHqTZUt7aRch_UCSxVjsw,31065
12
12
  samplesheet_parser/protocol.py,sha256=YOT1iZ-727nDKDGvZXNTjVG-OAgGdq0F0y3Tzbk7bwM,3104
13
13
  samplesheet_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
14
+ samplesheet_parser/schema.py,sha256=6NZiwJzGIQ5b_WD4YXOz6A4LiTuWGdYCD9abKdgUzAw,7443
14
15
  samplesheet_parser/splitter.py,sha256=QMmTTXg4HwZl3oUvA-4KKUVF62oIn4k2D1ko_dT1wS4,11314
15
- samplesheet_parser/validators.py,sha256=hiMI8mFpmSmba2stIWBXwFFXL_Ldjn2QAT1lwdCAJxI,31124
16
+ samplesheet_parser/validators.py,sha256=Oy7WigK85UIrs2_KiAV33FcLzEAvooQM3UGwIuS2M5o,46883
16
17
  samplesheet_parser/writer.py,sha256=NQY0x28rKF-694w11FZTCqCXxlNiHnMspB5M33GoD0k,33541
17
18
  samplesheet_parser/parsers/__init__.py,sha256=N5ICN_46x-ARbG8kyrck6g1V_gOU0XacqzUJI-D6KX8,213
18
19
  samplesheet_parser/parsers/element.py,sha256=7DrketMyQzPnEvAaaj6pstAiuvAJ6ljcFltsU-uymxs,11358
19
20
  samplesheet_parser/parsers/v1.py,sha256=MRt_BUJTmj763N2kByELNwQPY-_jcLKcwahG4jPBH98,23956
20
21
  samplesheet_parser/parsers/v2.py,sha256=pCd18DNcpIIh7vJNEB8asRleIriH2NSx7h7NAtsomug,27982
21
- samplesheet_parser-2.5.2.dist-info/METADATA,sha256=hkCh6kpMgWXQp6LUjs4RE5WWat8osCRYEuKhq9GSiNY,33619
22
- samplesheet_parser-2.5.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
23
- samplesheet_parser-2.5.2.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
24
- samplesheet_parser-2.5.2.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
25
- samplesheet_parser-2.5.2.dist-info/RECORD,,
22
+ samplesheet_parser-2.6.0.dist-info/METADATA,sha256=lf23eMwPZfaXlYEv2dL43ksLlIBbCsuMoJq8wECbHLw,33945
23
+ samplesheet_parser-2.6.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
24
+ samplesheet_parser-2.6.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
25
+ samplesheet_parser-2.6.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
26
+ samplesheet_parser-2.6.0.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: hatchling 1.32.0
2
+ Generator: hatchling 1.33.0
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any