samplesheet-parser 2.4.0__py3-none-any.whl → 2.5.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/cli.py CHANGED
@@ -29,6 +29,7 @@ Usage
29
29
  samplesheet validate SampleSheet.csv
30
30
  samplesheet validate SampleSheet.csv --format json
31
31
  samplesheet validate SampleSheet.csv --min-hamming 4
32
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
32
33
 
33
34
  samplesheet convert SampleSheet_v1.csv --to v2 --output SampleSheet_v2.csv
34
35
  samplesheet convert SampleSheet_v2.csv --to v1 --output SampleSheet_v1.csv
@@ -66,6 +67,7 @@ try:
66
67
  except ImportError: # pragma: no cover
67
68
  _TYPER_AVAILABLE = False
68
69
 
70
+ from samplesheet_parser.chemistry import ColorBalanceMode
69
71
  from samplesheet_parser.enums import SampleSheetVersion
70
72
  from samplesheet_parser.validators import MIN_HAMMING_DISTANCE as _MIN_HAMMING_DEFAULT
71
73
 
@@ -274,6 +276,18 @@ if _TYPER_AVAILABLE:
274
276
  ),
275
277
  ),
276
278
  ] = False,
279
+ color_balance_mode: Annotated[
280
+ ColorBalanceMode,
281
+ typer.Option(
282
+ "--color-balance-mode",
283
+ 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."
288
+ ),
289
+ ),
290
+ ] = ColorBalanceMode.VENDOR_FAITHFUL,
277
291
  instrument: Annotated[
278
292
  str | None,
279
293
  typer.Option(
@@ -318,6 +332,7 @@ if _TYPER_AVAILABLE:
318
332
  sheet,
319
333
  min_hamming_distance=min_hamming,
320
334
  check_color_balance=color_balance,
335
+ color_balance_mode=color_balance_mode,
321
336
  instrument=instrument,
322
337
  )
323
338
 
@@ -329,6 +344,7 @@ if _TYPER_AVAILABLE:
329
344
  "is_valid": result.is_valid,
330
345
  "min_hamming_distance": min_hamming,
331
346
  "color_balance_checked": color_balance,
347
+ "color_balance_mode": color_balance_mode.value if color_balance else None,
332
348
  "errors": [
333
349
  {"code": e.code, "message": e.message, "context": e.context}
334
350
  for e in result.errors
@@ -337,6 +353,10 @@ if _TYPER_AVAILABLE:
337
353
  {"code": w.code, "message": w.message, "context": w.context}
338
354
  for w in result.warnings
339
355
  ],
356
+ "notes": [
357
+ {"code": n.code, "message": n.message, "context": n.context}
358
+ for n in result.notes
359
+ ],
340
360
  "summary": result.summary(),
341
361
  }
342
362
  )
@@ -345,6 +365,11 @@ if _TYPER_AVAILABLE:
345
365
  typer.echo(f"Format: {version.value}")
346
366
  typer.echo(f"Result: {result.summary()}")
347
367
 
368
+ if result.notes:
369
+ typer.echo("\nNotes:")
370
+ for n in result.notes:
371
+ typer.echo(f" {n}")
372
+
348
373
  if result.warnings:
349
374
  typer.echo("\nWarnings:")
350
375
  for w in result.warnings:
@@ -79,7 +79,7 @@ class ValidationIssue:
79
79
  Attributes
80
80
  ----------
81
81
  level:
82
- ``"error"`` or ``"warning"``.
82
+ ``"error"``, ``"warning"``, or ``"note"``.
83
83
  code:
84
84
  Short machine-readable code (e.g. ``"DUPLICATE_INDEX"``).
85
85
  message:
@@ -105,17 +105,23 @@ class ValidationResult:
105
105
  Attributes
106
106
  ----------
107
107
  is_valid:
108
- ``True`` if no *errors* were raised (warnings do not affect
108
+ ``True`` if no *errors* were raised (warnings and notes do not affect
109
109
  this flag).
110
110
  errors:
111
111
  List of error-level :class:`ValidationIssue` objects.
112
112
  warnings:
113
113
  List of warning-level :class:`ValidationIssue` objects.
114
+ notes:
115
+ List of informational :class:`ValidationIssue` objects. Notes record
116
+ checks that were requested but not performed (e.g. a colour-balance
117
+ check skipped because the instrument was unknown), so a clean result
118
+ is not mistaken for a check that silently did nothing.
114
119
  """
115
120
 
116
121
  is_valid: bool = True
117
122
  errors: list[ValidationIssue] = field(default_factory=list)
118
123
  warnings: list[ValidationIssue] = field(default_factory=list)
124
+ notes: list[ValidationIssue] = field(default_factory=list)
119
125
 
120
126
  def add_error(self, code: str, message: str, **context: Any) -> None:
121
127
  self.is_valid = False
@@ -126,6 +132,11 @@ class ValidationResult:
126
132
  self.warnings.append(ValidationIssue("warning", code, message, dict(context)))
127
133
  logger.warning(f"{code}: {message}")
128
134
 
135
+ def add_note(self, code: str, message: str, **context: Any) -> None:
136
+ """Record an informational note (does not affect ``is_valid``)."""
137
+ self.notes.append(ValidationIssue("note", code, message, dict(context)))
138
+ logger.info(f"{code}: {message}")
139
+
129
140
  def to_dict(self) -> dict[str, Any]:
130
141
  return {
131
142
  "is_valid": self.is_valid,
@@ -135,6 +146,9 @@ class ValidationResult:
135
146
  "warnings": [
136
147
  {"code": w.code, "message": w.message, "context": w.context} for w in self.warnings
137
148
  ],
149
+ "notes": [
150
+ {"code": n.code, "message": n.message, "context": n.context} for n in self.notes
151
+ ],
138
152
  }
139
153
 
140
154
  def summary(self) -> str:
@@ -247,6 +261,10 @@ class SampleSheetValidator:
247
261
  in one channel (2-/1-channel) or no base
248
262
  diversity (4-channel), degrading base-call
249
263
  quality (warning only).
264
+ * **COLOR_BALANCE_SKIPPED** - Colour balance was requested but the
265
+ instrument chemistry could not be resolved, so
266
+ the check was not run (note only, so a clean
267
+ result is not mistaken for a passed check).
250
268
 
251
269
  Examples
252
270
  --------
@@ -575,7 +593,19 @@ class SampleSheetValidator:
575
593
  name = instrument or self._resolve_instrument(sheet)
576
594
  chemistry = chemistry_for_instrument(name)
577
595
  if chemistry is None:
578
- logger.debug("Skipping colour-balance check: unknown instrument %r.", name)
596
+ detail = (
597
+ f"instrument {name!r} is not recognised"
598
+ if name
599
+ else "no instrument is declared in the sheet or passed via --instrument"
600
+ )
601
+ result.add_note(
602
+ "COLOR_BALANCE_SKIPPED",
603
+ f"Colour balance was requested but not evaluated: {detail}, so the "
604
+ f"optical chemistry is unknown. A clean result here does not mean the "
605
+ f"index pool is colour balanced. Pass a known instrument to enable the "
606
+ f"check.",
607
+ instrument=name,
608
+ )
579
609
  return
580
610
 
581
611
  index1 = [(s.get("index") or s.get("Index") or "").upper() for s in samples]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 2.4.0
3
+ Version: 2.5.0
4
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
@@ -430,8 +430,9 @@ for err in result.errors:
430
430
  ```
431
431
 
432
432
  The chemistry is resolved from the instrument name; the check is **off by
433
- default** (it can legitimately fail a low-plex pool) and is skipped silently
434
- for unknown instruments. The same analysis is available standalone:
433
+ default** (it can legitimately fail a low-plex pool) and, for an unknown
434
+ instrument, is not run but reported as a `COLOR_BALANCE_SKIPPED` note rather than
435
+ passing silently. The same analysis is available standalone:
435
436
 
436
437
  ```python
437
438
  from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
@@ -448,12 +449,20 @@ From the CLI:
448
449
  ```bash
449
450
  samplesheet validate SampleSheet.csv --color-balance
450
451
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
452
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
451
453
  ```
452
454
 
455
+ When `--color-balance` is requested but the instrument cannot be resolved, the
456
+ check is not run (guessing the chemistry would be misleading). This is surfaced
457
+ as a `COLOR_BALANCE_SKIPPED` note (in text and JSON output) rather than a silent
458
+ pass, so a clean result is never mistaken for a passed color-balance check. Pass
459
+ `--instrument` to enable the check.
460
+
453
461
  #### Modes: `vendor_faithful` (default) and `conservative`
454
462
 
455
- Color balance has two modes, selectable via
456
- `validate(..., color_balance_mode=...)` or `analyze_color_balance(..., mode=...)`:
463
+ Color balance has two modes, selectable on the CLI via
464
+ `--color-balance-mode {vendor_faithful,conservative}` or in the library via
465
+ `validate(..., color_balance_mode=...)` / `analyze_color_balance(..., mode=...)`:
457
466
 
458
467
  - **`vendor_faithful`** (default) encodes each platform's *published* rule
459
468
  exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
@@ -821,6 +830,15 @@ Apache 2.0 — see [LICENSE](LICENSE).
821
830
 
822
831
  ---
823
832
 
833
+ ## AI-assisted development
834
+
835
+ Parts of this project's code, tests, and documentation were developed with the
836
+ assistance of generative AI tools (including GitHub Copilot). All AI-generated
837
+ output was reviewed, edited, and verified by the author, who is responsible for
838
+ the correctness of the final software.
839
+
840
+ ---
841
+
824
842
  ## Related resources
825
843
 
826
844
  - [Illumina IEM V1 SampleSheet reference (Knowledge Article #2204)](https://knowledge.illumina.com/software/on-premises-software/software-on-premises-software-reference_material-list/000002204)
@@ -1,6 +1,6 @@
1
1
  samplesheet_parser/__init__.py,sha256=eSlshig-sXWyxW70vbd__lu9u6nfqVTyv-48MUsmiZg,2890
2
2
  samplesheet_parser/chemistry.py,sha256=1I6jxzCmZqNqHitUzWQWo3JnuVHdASTVNUu-6jU4eoE,17631
3
- samplesheet_parser/cli.py,sha256=zL_JPj7wNj24ozB4CjQsXwskefAfxqq01osGqJ0S_QA,30815
3
+ samplesheet_parser/cli.py,sha256=GbYL0tTHP5ofGXLPVPzR5CNWVarUolzdoyOqsDl2WPg,31993
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
@@ -12,14 +12,14 @@ samplesheet_parser/merger.py,sha256=UxQ8bmX7632S70Lko3GFQTjHqTZUt7aRch_UCSxVjsw,
12
12
  samplesheet_parser/protocol.py,sha256=YOT1iZ-727nDKDGvZXNTjVG-OAgGdq0F0y3Tzbk7bwM,3104
13
13
  samplesheet_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
14
14
  samplesheet_parser/splitter.py,sha256=QMmTTXg4HwZl3oUvA-4KKUVF62oIn4k2D1ko_dT1wS4,11314
15
- samplesheet_parser/validators.py,sha256=60VSOIUuSijON0G9WuZCijAV_idRmc8ZIbKBQok526s,29496
15
+ samplesheet_parser/validators.py,sha256=hiMI8mFpmSmba2stIWBXwFFXL_Ldjn2QAT1lwdCAJxI,31124
16
16
  samplesheet_parser/writer.py,sha256=NQY0x28rKF-694w11FZTCqCXxlNiHnMspB5M33GoD0k,33541
17
17
  samplesheet_parser/parsers/__init__.py,sha256=N5ICN_46x-ARbG8kyrck6g1V_gOU0XacqzUJI-D6KX8,213
18
18
  samplesheet_parser/parsers/element.py,sha256=7DrketMyQzPnEvAaaj6pstAiuvAJ6ljcFltsU-uymxs,11358
19
19
  samplesheet_parser/parsers/v1.py,sha256=MRt_BUJTmj763N2kByELNwQPY-_jcLKcwahG4jPBH98,23956
20
20
  samplesheet_parser/parsers/v2.py,sha256=pCd18DNcpIIh7vJNEB8asRleIriH2NSx7h7NAtsomug,27982
21
- samplesheet_parser-2.4.0.dist-info/METADATA,sha256=f2P2WVRRDGIM3qAPVFTl61VoQnU-bhEWfhqX_LzPdIk,32706
22
- samplesheet_parser-2.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
23
- samplesheet_parser-2.4.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
24
- samplesheet_parser-2.4.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
25
- samplesheet_parser-2.4.0.dist-info/RECORD,,
21
+ samplesheet_parser-2.5.0.dist-info/METADATA,sha256=gxmeIQzX8iqquCjsX1G45_5urIVd6l00z0G4Nd_zTzs,33619
22
+ samplesheet_parser-2.5.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
23
+ samplesheet_parser-2.5.0.dist-info/entry_points.txt,sha256=jR2GOZmuJg60mY9vzOGunVh2-mYRxjpnlmC-4wGBfQ8,60
24
+ samplesheet_parser-2.5.0.dist-info/licenses/LICENSE,sha256=EIu8MSHMFea58nh2WwWsITEZ95TLW0PfRYCaYTE6HGk,781
25
+ samplesheet_parser-2.5.0.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: hatchling 1.30.1
2
+ Generator: hatchling 1.31.0
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any