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.
- samplesheet_parser/__init__.py +49 -21
- samplesheet_parser/cli.py +100 -20
- samplesheet_parser/factory.py +2 -2
- samplesheet_parser/schema.py +176 -0
- samplesheet_parser/validators.py +410 -25
- {samplesheet_parser-2.5.2.dist-info → samplesheet_parser-2.6.0.dist-info}/METADATA +43 -37
- {samplesheet_parser-2.5.2.dist-info → samplesheet_parser-2.6.0.dist-info}/RECORD +10 -9
- {samplesheet_parser-2.5.2.dist-info → samplesheet_parser-2.6.0.dist-info}/WHEEL +1 -1
- {samplesheet_parser-2.5.2.dist-info → samplesheet_parser-2.6.0.dist-info}/entry_points.txt +0 -0
- {samplesheet_parser-2.5.2.dist-info → samplesheet_parser-2.6.0.dist-info}/licenses/LICENSE +0 -0
samplesheet_parser/__init__.py
CHANGED
|
@@ -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
|
-
"
|
|
65
|
-
"
|
|
66
|
-
"
|
|
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
|
-
"
|
|
81
|
-
"
|
|
85
|
+
"DiffResult",
|
|
86
|
+
"ElementRunManifest",
|
|
87
|
+
"FilterResult",
|
|
88
|
+
"IndexType",
|
|
89
|
+
"InstrumentPlatform",
|
|
90
|
+
"MergeResult",
|
|
82
91
|
"SampleSheetConverter",
|
|
83
92
|
"SampleSheetDiff",
|
|
84
|
-
"
|
|
85
|
-
"
|
|
93
|
+
"SampleSheetFactory",
|
|
94
|
+
"SampleSheetFilter",
|
|
86
95
|
"SampleSheetMerger",
|
|
87
|
-
"
|
|
96
|
+
"SampleSheetParser",
|
|
88
97
|
"SampleSheetSplitter",
|
|
98
|
+
"SampleSheetV1",
|
|
99
|
+
"SampleSheetV2",
|
|
100
|
+
"SampleSheetValidator",
|
|
101
|
+
"SampleSheetVersion",
|
|
102
|
+
"SampleSheetWriter",
|
|
89
103
|
"SplitResult",
|
|
90
|
-
"
|
|
91
|
-
"
|
|
92
|
-
"
|
|
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
|
-
|
|
263
|
-
f"(
|
|
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
|
-
] =
|
|
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
|
-
"
|
|
274
|
-
"instrument's optical chemistry (flags dark/no-signal "
|
|
275
|
-
"
|
|
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
|
-
] =
|
|
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
|
|
285
|
-
"
|
|
286
|
-
"
|
|
287
|
-
"
|
|
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
|
-
] =
|
|
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
|
-
"
|
|
346
|
-
"
|
|
347
|
-
"
|
|
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:
|
samplesheet_parser/factory.py
CHANGED
|
@@ -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)])
|
samplesheet_parser/validators.py
CHANGED
|
@@ -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
|
-
|
|
281
|
-
|
|
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 =
|
|
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.
|
|
297
|
-
|
|
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
|
-
|
|
303
|
-
|
|
304
|
-
|
|
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
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
self.
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
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.
|
|
4
|
-
Summary: Multi-vendor, format-agnostic parser for sequencing sample sheets
|
|
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)
|
|
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
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
64
67
|
[](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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
354
|
+
The factory detects the format across vendors - no format hints required from the caller:
|
|
349
355
|
|
|
350
|
-
1. **Vendor manifest check**
|
|
351
|
-
2. **Header discriminator**
|
|
352
|
-
3. **Section name scan**
|
|
353
|
-
4. **Default**
|
|
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
|
|
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)
|
|
373
|
-
| `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel)
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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=)` |
|
|
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
|
|
659
|
-
| `set_software_version(version)` | `self` | Set `SoftwareVersion`
|
|
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=)` |
|
|
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.
|
|
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
|
|
835
|
+
Apache 2.0 - see [LICENSE](LICENSE).
|
|
830
836
|
|
|
831
837
|
---
|
|
832
838
|
|
|
@@ -1,25 +1,26 @@
|
|
|
1
|
-
samplesheet_parser/__init__.py,sha256=
|
|
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=
|
|
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=
|
|
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=
|
|
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.
|
|
22
|
-
samplesheet_parser-2.
|
|
23
|
-
samplesheet_parser-2.
|
|
24
|
-
samplesheet_parser-2.
|
|
25
|
-
samplesheet_parser-2.
|
|
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,,
|
|
File without changes
|
|
File without changes
|