samplesheet-parser 1.2.0__py3-none-any.whl → 2.0.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.
@@ -41,20 +41,23 @@ from samplesheet_parser.index_utils import normalize_index_lengths
41
41
  from samplesheet_parser.merger import MergeResult, SampleSheetMerger
42
42
  from samplesheet_parser.parsers.v1 import SampleSheetV1
43
43
  from samplesheet_parser.parsers.v2 import SampleSheetV2
44
+ from samplesheet_parser.protocol import SampleSheetParser
44
45
  from samplesheet_parser.splitter import SampleSheetSplitter, SplitResult
45
- from samplesheet_parser.validators import SampleSheetValidator, ValidationResult
46
+ from samplesheet_parser.validators import SampleSheetValidator, ValidationResult, hamming_distance
46
47
  from samplesheet_parser.writer import SampleSheetWriter
47
48
 
48
49
  __all__ = [
49
50
  "SampleSheetV1",
50
51
  "SampleSheetV2",
51
52
  "SampleSheetFactory",
53
+ "SampleSheetParser",
52
54
  "SampleSheetVersion",
53
55
  "IndexType",
54
56
  "InstrumentPlatform",
55
57
  "UMILocation",
56
58
  "SampleSheetValidator",
57
59
  "ValidationResult",
60
+ "hamming_distance",
58
61
  "SampleSheetConverter",
59
62
  "SampleSheetDiff",
60
63
  "DiffResult",
samplesheet_parser/cli.py CHANGED
@@ -33,6 +33,7 @@ Usage
33
33
  samplesheet convert SampleSheet_v1.csv --to v2 --output SampleSheet_v2.csv
34
34
  samplesheet convert SampleSheet_v2.csv --to v1 --output SampleSheet_v1.csv
35
35
  samplesheet convert SampleSheet_v1.csv --to v2 --output out.csv --format json
36
+ samplesheet convert NovaSeq6000.v1.csv --to v2 --workflow b --output out.csv
36
37
 
37
38
  samplesheet diff old/SampleSheet.csv new/SampleSheet.csv
38
39
  samplesheet diff old/SampleSheet.csv new/SampleSheet.csv --format json
@@ -336,15 +337,37 @@ if _TYPER_AVAILABLE:
336
337
  to: _VersionOption = "v2",
337
338
  output: _OutputOption = Path("SampleSheet_converted.csv"),
338
339
  fmt: _FormatOption = "text",
340
+ workflow: Annotated[
341
+ str,
342
+ typer.Option(
343
+ "--workflow",
344
+ "-w",
345
+ help=(
346
+ "Instrument i5 orientation workflow: 'a' (MiSeq, HiSeq 2000/2500, "
347
+ "NovaSeq 6000 v1.0) or 'b' (NovaSeq X/X Plus, NextSeq, iSeq, "
348
+ "MiniSeq, HiSeq 3000/4000, NovaSeq 6000 v1.5). Overrides "
349
+ "auto-detection from the instrument header."
350
+ ),
351
+ metavar="{a,b}",
352
+ ),
353
+ ] = "",
339
354
  ) -> None:
340
355
  """Convert a sample sheet between V1 (IEM/bcl2fastq) and V2 (BCLConvert) formats.
341
356
 
342
- V2→V1 conversion is lossy: V2-only fields (OverrideCycles, InstrumentPlatform,
343
- etc.) are dropped with a warning.
357
+ V2→V1 conversion is lossy: V2-only fields (OverrideCycles, SoftwareVersion,
358
+ Cloud_Data, etc.) are dropped with a warning. InstrumentPlatform /
359
+ InstrumentType are preserved as the V1 'Instrument Type' header.
360
+
361
+ For workflow-B instruments (NovaSeq X/X Plus, NextSeq, iSeq, MiniSeq,
362
+ HiSeq 3000/4000), Index2 is reverse-complemented to match the target
363
+ demultiplexer's expected orientation. The workflow is auto-detected
364
+ from the instrument header; use --workflow to override (required for
365
+ NovaSeq 6000, which is chemistry-dependent).
344
366
 
345
367
  Exits 0 on success, 1 on conversion error, 2 on bad arguments.
346
368
  """
347
369
  from samplesheet_parser.converter import SampleSheetConverter
370
+ from samplesheet_parser.instruments import parse_workflow
348
371
 
349
372
  _validate_fmt(fmt)
350
373
  if not path.exists():
@@ -354,7 +377,13 @@ if _TYPER_AVAILABLE:
354
377
  target = _resolve_version(to)
355
378
 
356
379
  try:
357
- converter = SampleSheetConverter(str(path))
380
+ wf = parse_workflow(workflow) if workflow else None
381
+ except ValueError as exc:
382
+ typer.echo(f"Error: {exc}", err=True)
383
+ raise typer.Exit(code=2) from exc
384
+
385
+ try:
386
+ converter = SampleSheetConverter(str(path), workflow=wf)
358
387
  if target == SampleSheetVersion.V2:
359
388
  out = converter.to_v2(str(output))
360
389
  else:
@@ -20,30 +20,56 @@ equivalent and are dropped with a warning:
20
20
  - ``OverrideCycles``
21
21
  - ``Cloud_Data`` / ``Cloud_Settings`` sections
22
22
  - Per-sample ``OverrideCycles`` column
23
- - ``InstrumentPlatform``, ``SoftwareVersion`` (BCLConvert-specific)
23
+ - ``FileFormatVersion`` (replaced by ``IEMFileVersion``)
24
+ - ``SoftwareVersion`` and other BCLConvert-specific settings
25
+
26
+ ``InstrumentPlatform`` / ``InstrumentType`` are mapped to the V1
27
+ ``Instrument Type`` header so the workflow signal survives a round
28
+ trip; they are not dropped.
29
+
30
+ Index 2 (i5) orientation
31
+ ------------------------
32
+ ``bcl2fastq`` and ``BCLConvert`` disagree on the orientation of i5 for
33
+ workflow-B instruments (NovaSeq X / X Plus, NextSeq 500/550/1000/2000,
34
+ iSeq 100, MiniSeq, HiSeq 3000/4000). For those instruments, ``Index2``
35
+ is reverse-complemented on conversion in both directions. The workflow
36
+ is auto-detected from the V1 ``Instrument Type`` or V2
37
+ ``InstrumentPlatform`` header; pass ``workflow=`` to override.
38
+
39
+ If the sheet has a non-empty Index2 column and the workflow cannot be
40
+ determined and no override is given, conversion fails with a clear
41
+ error rather than silently producing a wrong sheet. See
42
+ :mod:`samplesheet_parser.instruments`.
24
43
 
25
44
  Examples
26
45
  --------
27
46
  >>> from samplesheet_parser import SampleSheetConverter
28
47
  >>>
29
- >>> # V1 → V2
48
+ >>> # V1 → V2 — workflow auto-detected from [Header] Instrument Type
30
49
  >>> SampleSheetConverter("SampleSheet_v1.csv").to_v2("SampleSheet_v2.csv")
31
50
  >>>
32
- >>> # V2 → V1 (lossy)
33
- >>> SampleSheetConverter("SampleSheet_v2.csv").to_v1("SampleSheet_v1.csv")
51
+ >>> # V2 → V1 with explicit workflow override (e.g. NovaSeq 6000 v1.5)
52
+ >>> SampleSheetConverter("SampleSheet_v2.csv", workflow="b").to_v1("SampleSheet_v1.csv")
34
53
  """
35
54
 
36
55
  from __future__ import annotations
37
56
 
57
+ import logging
38
58
  from pathlib import Path
39
59
 
40
- from loguru import logger
41
-
42
60
  from samplesheet_parser.enums import SampleSheetVersion
43
61
  from samplesheet_parser.factory import SampleSheetFactory
62
+ from samplesheet_parser.instruments import (
63
+ Workflow,
64
+ detect_workflow,
65
+ parse_workflow,
66
+ reverse_complement,
67
+ )
44
68
  from samplesheet_parser.parsers.v1 import SampleSheetV1
45
69
  from samplesheet_parser.parsers.v2 import SampleSheetV2
46
70
 
71
+ logger = logging.getLogger(__name__)
72
+
47
73
  # ---------------------------------------------------------------------------
48
74
  # Field mappings
49
75
  # ---------------------------------------------------------------------------
@@ -60,10 +86,10 @@ _V2_ONLY_SETTINGS: set[str] = {
60
86
  "SoftwareVersion",
61
87
  }
62
88
 
89
+ # Fields that have no V1 counterpart and are dropped silently on V2 → V1.
90
+ # (FileFormatVersion is replaced by IEMFileVersion.)
63
91
  _V2_ONLY_HEADER: set[str] = {
64
92
  "FileFormatVersion",
65
- "InstrumentPlatform",
66
- "InstrumentType",
67
93
  }
68
94
 
69
95
  _V2_ONLY_DATA_COLUMNS: set[str] = {
@@ -75,6 +101,7 @@ _V2_ONLY_DATA_COLUMNS: set[str] = {
75
101
  # Converter
76
102
  # ---------------------------------------------------------------------------
77
103
 
104
+
78
105
  class SampleSheetConverter:
79
106
  """
80
107
  Converts Illumina sample sheets between IEM V1 and BCLConvert V2 formats.
@@ -84,6 +111,13 @@ class SampleSheetConverter:
84
111
  path:
85
112
  Path to the source ``SampleSheet.csv`` file. The format is
86
113
  auto-detected using :class:`~samplesheet_parser.SampleSheetFactory`.
114
+ workflow:
115
+ Instrument i5 workflow override. Accepts :class:`Workflow` or the
116
+ strings ``"a"`` / ``"b"``. When ``None`` (default), the workflow
117
+ is auto-detected from the V1 ``Instrument Type`` or V2
118
+ ``InstrumentPlatform`` header. Pass an explicit value for
119
+ chemistry-dependent instruments (e.g. NovaSeq 6000) or when the
120
+ instrument field is missing.
87
121
 
88
122
  Examples
89
123
  --------
@@ -93,14 +127,23 @@ class SampleSheetConverter:
93
127
 
94
128
  >>> conv = SampleSheetConverter("SampleSheet_v2.csv")
95
129
  >>> conv.to_v1("SampleSheet_v1.csv") # emits warnings for dropped fields
130
+
131
+ >>> # NovaSeq 6000 with v1.5 chemistry — must override (ambiguous)
132
+ >>> SampleSheetConverter("SampleSheet.csv", workflow="b").to_v2("out.csv")
96
133
  """
97
134
 
98
- def __init__(self, path: str | Path) -> None:
135
+ def __init__(
136
+ self,
137
+ path: str | Path,
138
+ *,
139
+ workflow: Workflow | str | None = None,
140
+ ) -> None:
99
141
  self.path = Path(path)
100
142
  factory = SampleSheetFactory()
101
143
  # clean=False: converter must never modify or back up the source file
102
144
  self._sheet = factory.create_parser(self.path, parse=True, clean=False)
103
145
  self.source_version: SampleSheetVersion = factory.version # type: ignore[assignment]
146
+ self.workflow_override: Workflow | None = parse_workflow(workflow)
104
147
  logger.info(f"SampleSheetConverter: detected {self.source_version} for {self.path}")
105
148
 
106
149
  # ------------------------------------------------------------------
@@ -126,9 +169,7 @@ class SampleSheetConverter:
126
169
  If the source sheet is already V2.
127
170
  """
128
171
  if self.source_version == SampleSheetVersion.V2:
129
- raise ValueError(
130
- "Source sheet is already V2. No conversion needed."
131
- )
172
+ raise ValueError("Source sheet is already V2. No conversion needed.")
132
173
 
133
174
  sheet = self._sheet
134
175
  if not isinstance(sheet, SampleSheetV1):
@@ -137,6 +178,16 @@ class SampleSheetConverter:
137
178
  f"got {type(sheet).__name__!r}."
138
179
  )
139
180
 
181
+ # Resolve workflow before writing any output — fail fast if the
182
+ # sheet has a non-empty Index2 column and we cannot tell whether
183
+ # to RC it. See _needs_i5_rc().
184
+ needs_rc = self._needs_i5_rc(
185
+ instrument=sheet.instrument_type,
186
+ records=sheet.records or [],
187
+ index2_key="index2",
188
+ direction="V1 → V2",
189
+ )
190
+
140
191
  out = Path(output_path)
141
192
  lines: list[str] = []
142
193
 
@@ -149,6 +200,10 @@ class SampleSheetConverter:
149
200
  description = getattr(sheet, "description", None) or ""
150
201
  if description:
151
202
  lines.append(f"RunDescription,{description}")
203
+ # Preserve Instrument Type → InstrumentType so the workflow signal
204
+ # survives a V1 → V2 → V1 round trip.
205
+ if sheet.instrument_type:
206
+ lines.append(f"InstrumentType,{sheet.instrument_type}")
152
207
  lines.append("")
153
208
 
154
209
  # [Reads]
@@ -176,8 +231,8 @@ class SampleSheetConverter:
176
231
  # section parseable by SampleSheetV2.parse_data()
177
232
  v2_columns = self._v1_data_columns_to_v2(sheet.columns)
178
233
  lines.append(",".join(v2_columns))
179
- for record in (sheet.records or []):
180
- row = self._v1_record_to_v2(record, v2_columns)
234
+ for record in sheet.records or []:
235
+ row = self._v1_record_to_v2(record, v2_columns, rc_index2=needs_rc)
181
236
  lines.append(",".join(row))
182
237
  lines.append("")
183
238
 
@@ -189,8 +244,10 @@ class SampleSheetConverter:
189
244
  """Convert a V2 sheet to IEM V1 format and write to *output_path*.
190
245
 
191
246
  This is a **lossy** conversion. V2-only fields (``OverrideCycles``,
192
- ``Cloud_Data``, ``InstrumentPlatform``, etc.) are dropped and a
193
- warning is logged for each dropped field.
247
+ ``Cloud_Data``, ``SoftwareVersion``, etc.) are dropped and a warning
248
+ is logged for each dropped field. ``InstrumentPlatform`` /
249
+ ``InstrumentType`` are preserved as the V1 ``Instrument Type``
250
+ header so the workflow signal survives a round trip.
194
251
 
195
252
  Parameters
196
253
  ----------
@@ -208,12 +265,26 @@ class SampleSheetConverter:
208
265
  If the source sheet is already V1.
209
266
  """
210
267
  if self.source_version == SampleSheetVersion.V1:
211
- raise ValueError(
212
- "Source sheet is already V1. No conversion needed."
213
- )
268
+ raise ValueError("Source sheet is already V1. No conversion needed.")
214
269
 
215
270
  sheet = self._sheet
216
- assert isinstance(sheet, SampleSheetV2)
271
+ if not isinstance(sheet, SampleSheetV2):
272
+ raise TypeError(
273
+ f"Expected SampleSheetV2 for V2 \N{RIGHTWARDS ARROW} V1 conversion, "
274
+ f"got {type(sheet).__name__!r}."
275
+ )
276
+
277
+ # Resolve workflow up front. Prefer InstrumentPlatform; fall back
278
+ # to InstrumentType (some V2 sheets only declare the latter).
279
+ instrument = sheet.instrument_platform or (
280
+ sheet.header.get("InstrumentType") if sheet.header else None
281
+ )
282
+ needs_rc = self._needs_i5_rc(
283
+ instrument=instrument,
284
+ records=sheet.records or [],
285
+ index2_key="Index2",
286
+ direction="V2 → V1",
287
+ )
217
288
 
218
289
  out = Path(output_path)
219
290
  lines: list[str] = []
@@ -224,9 +295,7 @@ class SampleSheetConverter:
224
295
  lines.append("IEMFileVersion,5")
225
296
 
226
297
  run_name = (
227
- sheet.experiment_name
228
- or (sheet.header.get("RunName") if sheet.header else None)
229
- or ""
298
+ sheet.experiment_name or (sheet.header.get("RunName") if sheet.header else None) or ""
230
299
  )
231
300
  if run_name:
232
301
  lines.append(f"Experiment Name,{run_name}")
@@ -235,6 +304,15 @@ class SampleSheetConverter:
235
304
  if run_desc:
236
305
  lines.append(f"Description,{run_desc}")
237
306
 
307
+ # Preserve instrument so the workflow signal survives a round trip.
308
+ # V2 may declare InstrumentType, InstrumentPlatform, or both —
309
+ # prefer the more specific InstrumentType when present.
310
+ v2_instrument = (sheet.header.get("InstrumentType") if sheet.header else None) or (
311
+ sheet.header.get("InstrumentPlatform") if sheet.header else None
312
+ )
313
+ if v2_instrument:
314
+ lines.append(f"Instrument Type,{v2_instrument}")
315
+
238
316
  # Track dropped V2-only header fields
239
317
  if sheet.header:
240
318
  for key in _V2_ONLY_HEADER:
@@ -285,8 +363,8 @@ class SampleSheetConverter:
285
363
  # Always emit column header even when records == [] to keep the
286
364
  # section parseable by SampleSheetV1.parse_data()
287
365
  lines.append(",".join(v1_columns))
288
- for record in (sheet.records or []):
289
- row = self._v2_record_to_v1(record, v1_columns)
366
+ for record in sheet.records or []:
367
+ row = self._v2_record_to_v1(record, v1_columns, rc_index2=needs_rc)
290
368
  lines.append(",".join(row))
291
369
  lines.append("")
292
370
 
@@ -312,18 +390,18 @@ class SampleSheetConverter:
312
390
  def _v1_data_columns_to_v2(self, v1_columns: list[str]) -> list[str]:
313
391
  """Map V1 [Data] column names to V2 [BCLConvert_Data] equivalents."""
314
392
  mapping = {
315
- "Sample_ID": "Sample_ID",
316
- "Sample_Name": "Sample_Name",
317
- "Lane": "Lane",
318
- "index": "Index",
319
- "index2": "Index2",
393
+ "Sample_ID": "Sample_ID",
394
+ "Sample_Name": "Sample_Name",
395
+ "Lane": "Lane",
396
+ "index": "Index",
397
+ "index2": "Index2",
320
398
  "Sample_Project": "Sample_Project",
321
399
  # Drop V1-only columns
322
- "I7_Index_ID": None,
323
- "I5_Index_ID": None,
324
- "Sample_Plate": None,
325
- "Sample_Well": None,
326
- "Description": None,
400
+ "I7_Index_ID": None,
401
+ "I5_Index_ID": None,
402
+ "Sample_Plate": None,
403
+ "Sample_Well": None,
404
+ "Description": None,
327
405
  }
328
406
  result = []
329
407
  for col in v1_columns:
@@ -336,35 +414,43 @@ class SampleSheetConverter:
336
414
  self,
337
415
  record: dict[str, str],
338
416
  v2_columns: list[str],
417
+ *,
418
+ rc_index2: bool = False,
339
419
  ) -> list[str]:
340
- """Convert a single V1 data record to a V2 row."""
420
+ """Convert a single V1 data record to a V2 row.
421
+
422
+ When *rc_index2* is True, the ``index2`` value is reverse-
423
+ complemented before being written under the V2 ``Index2`` column.
424
+ """
341
425
  col_map = {
342
- "index": "Index",
426
+ "index": "Index",
343
427
  "index2": "Index2",
344
428
  }
345
- # Build intermediate dict with V2 keys
346
429
  v2_record: dict[str, str] = {}
347
430
  for k, v in record.items():
348
431
  new_key = col_map.get(k, k)
349
- if new_key in v2_columns:
350
- v2_record[new_key] = v
432
+ if new_key not in v2_columns:
433
+ continue
434
+ if rc_index2 and k == "index2" and v:
435
+ v = reverse_complement(v)
436
+ v2_record[new_key] = v
351
437
 
352
438
  return [v2_record.get(col, "") for col in v2_columns]
353
439
 
354
440
  def _v2_data_columns_to_v1(self, v2_columns: list[str]) -> list[str]:
355
441
  """Map V2 [BCLConvert_Data] column names to V1 [Data] equivalents."""
356
442
  mapping = {
357
- "Sample_ID": "Sample_ID",
358
- "Sample_Name": "Sample_Name",
359
- "Lane": "Lane",
360
- "Index": "index",
361
- "Index2": "index2",
443
+ "Sample_ID": "Sample_ID",
444
+ "Sample_Name": "Sample_Name",
445
+ "Lane": "Lane",
446
+ "Index": "index",
447
+ "Index2": "index2",
362
448
  "Sample_Project": "Sample_Project",
363
449
  }
364
450
  result = []
365
451
  for col in v2_columns:
366
452
  if col in _V2_ONLY_DATA_COLUMNS:
367
- continue # drop silently — already warned above
453
+ continue # drop silently — already warned above
368
454
  mapped = mapping.get(col, col)
369
455
  result.append(mapped)
370
456
  return result
@@ -373,10 +459,16 @@ class SampleSheetConverter:
373
459
  self,
374
460
  record: dict[str, str],
375
461
  v1_columns: list[str],
462
+ *,
463
+ rc_index2: bool = False,
376
464
  ) -> list[str]:
377
- """Convert a single V2 data record to a V1 row."""
465
+ """Convert a single V2 data record to a V1 row.
466
+
467
+ When *rc_index2* is True, the ``Index2`` value is reverse-
468
+ complemented before being written under the V1 ``index2`` column.
469
+ """
378
470
  col_map = {
379
- "Index": "index",
471
+ "Index": "index",
380
472
  "Index2": "index2",
381
473
  }
382
474
  v1_record: dict[str, str] = {}
@@ -384,11 +476,68 @@ class SampleSheetConverter:
384
476
  if k in _V2_ONLY_DATA_COLUMNS:
385
477
  continue
386
478
  new_key = col_map.get(k, k)
387
- if new_key in v1_columns:
388
- v1_record[new_key] = v
479
+ if new_key not in v1_columns:
480
+ continue
481
+ if rc_index2 and k == "Index2" and v:
482
+ v = reverse_complement(v)
483
+ v1_record[new_key] = v
389
484
 
390
485
  return [v1_record.get(col, "") for col in v1_columns]
391
486
 
487
+ # ------------------------------------------------------------------
488
+ # Workflow / i5 orientation
489
+ # ------------------------------------------------------------------
490
+
491
+ def _needs_i5_rc(
492
+ self,
493
+ *,
494
+ instrument: str | None,
495
+ records: list[dict[str, str]],
496
+ index2_key: str,
497
+ direction: str,
498
+ ) -> bool:
499
+ """Decide whether ``Index2`` should be reverse-complemented.
500
+
501
+ Resolution order:
502
+ 1. Explicit ``workflow=`` constructor override wins.
503
+ 2. Otherwise auto-detect from *instrument*.
504
+ 3. If detection fails and any record carries a non-empty
505
+ ``index2_key``, raise ``ValueError`` — silently passing the
506
+ i5 through would produce a wrong sheet for workflow-B
507
+ instruments.
508
+ 4. If no Index2 values are present, return ``False`` (no-op).
509
+ """
510
+ has_index2_values = any(rec.get(index2_key) for rec in records)
511
+
512
+ def _log(wf: Workflow, source: str) -> None:
513
+ action = "be reverse-complemented" if wf == Workflow.B else "be passed through"
514
+ logger.info(f"{direction}: workflow={wf.value} ({source}); Index2 will {action}.")
515
+
516
+ if self.workflow_override is not None:
517
+ _log(self.workflow_override, "explicit override")
518
+ return self.workflow_override == Workflow.B
519
+
520
+ detected = detect_workflow(instrument)
521
+ if detected is not None:
522
+ _log(detected, f"auto-detected from {instrument!r}")
523
+ return detected == Workflow.B
524
+
525
+ # Workflow unknown.
526
+ if has_index2_values:
527
+ instr_repr = f"{instrument!r}" if instrument else "<missing>"
528
+ raise ValueError(
529
+ f"{direction}: cannot determine i5 orientation workflow for "
530
+ f"instrument {instr_repr}. The sheet has dual indexes, and "
531
+ f"workflow-A vs workflow-B instruments record Index2 in "
532
+ f"opposite orientations. Pass workflow='a' or workflow='b' "
533
+ f"explicitly (CLI: --workflow {{a,b}}). See "
534
+ f"samplesheet_parser.instruments for the full instrument table."
535
+ )
536
+
537
+ # No Index2 to convert — silent pass-through is safe.
538
+ logger.debug(f"{direction}: no Index2 values, skipping workflow detection.")
539
+ return False
540
+
392
541
  # ------------------------------------------------------------------
393
542
  # Dunder
394
543
  # ------------------------------------------------------------------