samplesheet-parser 2.0.0__py3-none-any.whl → 2.2.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.
@@ -5,8 +5,8 @@ samplesheet-parser
5
5
  Format-agnostic parser for Illumina SampleSheet.csv files.
6
6
 
7
7
  Supports:
8
- - Illumina Experiment Manager (IEM) V1 format — bcl2fastq era
9
- - BCLConvert V2 format — NovaSeq X / modern era
8
+ - Illumina Experiment Manager (IEM) V1 format - bcl2fastq era
9
+ - BCLConvert V2 format - NovaSeq X / modern era
10
10
 
11
11
  Quickstart
12
12
  ----------
@@ -43,7 +43,12 @@ from samplesheet_parser.parsers.v1 import SampleSheetV1
43
43
  from samplesheet_parser.parsers.v2 import SampleSheetV2
44
44
  from samplesheet_parser.protocol import SampleSheetParser
45
45
  from samplesheet_parser.splitter import SampleSheetSplitter, SplitResult
46
- from samplesheet_parser.validators import SampleSheetValidator, ValidationResult, hamming_distance
46
+ from samplesheet_parser.validators import (
47
+ SampleSheetValidator,
48
+ ValidationResult,
49
+ hamming_distance,
50
+ index_collision_distance,
51
+ )
47
52
  from samplesheet_parser.writer import SampleSheetWriter
48
53
 
49
54
  __all__ = [
@@ -58,6 +63,7 @@ __all__ = [
58
63
  "SampleSheetValidator",
59
64
  "ValidationResult",
60
65
  "hamming_distance",
66
+ "index_collision_distance",
61
67
  "SampleSheetConverter",
62
68
  "SampleSheetDiff",
63
69
  "DiffResult",
samplesheet_parser/cli.py CHANGED
@@ -6,9 +6,9 @@ Entry point: ``samplesheet`` (configured in ``pyproject.toml``).
6
6
  Commands
7
7
  --------
8
8
  info Show a quick summary of a sample sheet.
9
- validate Validate a sheet — exit 0 if clean, exit 1 if errors.
9
+ validate Validate a sheet - exit 0 if clean, exit 1 if errors.
10
10
  convert Convert between V1 and V2 formats.
11
- diff Diff two sheets — exit 1 if changes detected.
11
+ diff Diff two sheets - exit 1 if changes detected.
12
12
  merge Merge multiple project sheets into one combined sheet.
13
13
  split Split a combined sheet into per-project or per-lane files.
14
14
  filter Extract a subset of samples by project, lane, or sample ID.
@@ -99,7 +99,6 @@ if _TYPER_AVAILABLE:
99
99
  help="Show version and exit.",
100
100
  callback=_version_callback,
101
101
  is_eager=True,
102
- is_flag=True,
103
102
  ),
104
103
  ] = False,
105
104
  ) -> None:
@@ -179,6 +178,7 @@ if _TYPER_AVAILABLE:
179
178
  """
180
179
  from samplesheet_parser.factory import SampleSheetFactory
181
180
  from samplesheet_parser.parsers.v1 import SampleSheetV1
181
+ from samplesheet_parser.parsers.v2 import SampleSheetV2
182
182
 
183
183
  _validate_fmt(fmt)
184
184
  if not path.exists():
@@ -201,10 +201,12 @@ if _TYPER_AVAILABLE:
201
201
  adapters: list[str] = getattr(sheet, "adapters", []) or []
202
202
  experiment_name: str | None = getattr(sheet, "experiment_name", None)
203
203
 
204
+ read_lengths: list[str] = []
205
+ instrument: str | None = None
204
206
  if isinstance(sheet, SampleSheetV1):
205
207
  read_lengths = [str(r) for r in (sheet.read_lengths or [])]
206
208
  instrument = sheet.instrument_type
207
- else:
209
+ elif isinstance(sheet, SampleSheetV2):
208
210
  reads_dict = sheet.reads or {}
209
211
  read_lengths = [
210
212
  str(reads_dict[k]) for k in ("Read1Cycles", "Read2Cycles") if k in reads_dict
@@ -720,7 +722,7 @@ if _TYPER_AVAILABLE:
720
722
  ) -> None:
721
723
  """Extract a subset of samples from a sheet by project, lane, or sample ID.
722
724
 
723
- Multiple criteria are ANDed — a sample must match all provided
725
+ Multiple criteria are ANDed - a sample must match all provided
724
726
  criteria. ``--sample-id`` supports glob patterns (e.g. ``'CTRL_*'``).
725
727
 
726
728
  Exits 0 if at least one sample matched.
@@ -45,7 +45,7 @@ Examples
45
45
  --------
46
46
  >>> from samplesheet_parser import SampleSheetConverter
47
47
  >>>
48
- >>> # V1 → V2 — workflow auto-detected from [Header] Instrument Type
48
+ >>> # V1 → V2 - workflow auto-detected from [Header] Instrument Type
49
49
  >>> SampleSheetConverter("SampleSheet_v1.csv").to_v2("SampleSheet_v2.csv")
50
50
  >>>
51
51
  >>> # V2 → V1 with explicit workflow override (e.g. NovaSeq 6000 v1.5)
@@ -74,7 +74,7 @@ logger = logging.getLogger(__name__)
74
74
  # Field mappings
75
75
  # ---------------------------------------------------------------------------
76
76
 
77
- # V2-only fields that have no V1 equivalent — dropped on V2 → V1
77
+ # V2-only fields that have no V1 equivalent - dropped on V2 → V1
78
78
  _V2_ONLY_SETTINGS: set[str] = {
79
79
  "OverrideCycles",
80
80
  "FastqCompressionFormat",
@@ -128,7 +128,7 @@ class SampleSheetConverter:
128
128
  >>> conv = SampleSheetConverter("SampleSheet_v2.csv")
129
129
  >>> conv.to_v1("SampleSheet_v1.csv") # emits warnings for dropped fields
130
130
 
131
- >>> # NovaSeq 6000 with v1.5 chemistry — must override (ambiguous)
131
+ >>> # NovaSeq 6000 with v1.5 chemistry - must override (ambiguous)
132
132
  >>> SampleSheetConverter("SampleSheet.csv", workflow="b").to_v2("out.csv")
133
133
  """
134
134
 
@@ -178,7 +178,7 @@ class SampleSheetConverter:
178
178
  f"got {type(sheet).__name__!r}."
179
179
  )
180
180
 
181
- # Resolve workflow before writing any output — fail fast if the
181
+ # Resolve workflow before writing any output - fail fast if the
182
182
  # sheet has a non-empty Index2 column and we cannot tell whether
183
183
  # to RC it. See _needs_i5_rc().
184
184
  needs_rc = self._needs_i5_rc(
@@ -220,7 +220,7 @@ class SampleSheetConverter:
220
220
  lines.append(f"AdapterRead1,{sheet.adapter_read1}")
221
221
  if sheet.adapter_read2:
222
222
  lines.append(f"AdapterRead2,{sheet.adapter_read2}")
223
- # Emit empty OverrideCycles — caller should fill in if using UMIs or custom cycle counts
223
+ # Emit empty OverrideCycles - caller should fill in if using UMIs or custom cycle counts
224
224
  lines.append("OverrideCycles,")
225
225
  lines.append("")
226
226
 
@@ -305,7 +305,7 @@ class SampleSheetConverter:
305
305
  lines.append(f"Description,{run_desc}")
306
306
 
307
307
  # Preserve instrument so the workflow signal survives a round trip.
308
- # V2 may declare InstrumentType, InstrumentPlatform, or both —
308
+ # V2 may declare InstrumentType, InstrumentPlatform, or both -
309
309
  # prefer the more specific InstrumentType when present.
310
310
  v2_instrument = (sheet.header.get("InstrumentType") if sheet.header else None) or (
311
311
  sheet.header.get("InstrumentPlatform") if sheet.header else None
@@ -371,7 +371,7 @@ class SampleSheetConverter:
371
371
  # Warn about dropped fields
372
372
  # Check cloud_data first so the warning fires even when it is the only lossy part
373
373
  if sheet.cloud_data:
374
- dropped.append("[Cloud_Data] section (entire section — no V1 equivalent)")
374
+ dropped.append("[Cloud_Data] section (entire section - no V1 equivalent)")
375
375
  if dropped:
376
376
  logger.warning(
377
377
  f"V2 → V1 conversion dropped {len(dropped)} field(s) with no V1 equivalent:"
@@ -450,7 +450,7 @@ class SampleSheetConverter:
450
450
  result = []
451
451
  for col in v2_columns:
452
452
  if col in _V2_ONLY_DATA_COLUMNS:
453
- continue # drop silently — already warned above
453
+ continue # drop silently - already warned above
454
454
  mapped = mapping.get(col, col)
455
455
  result.append(mapped)
456
456
  return result
@@ -502,7 +502,7 @@ class SampleSheetConverter:
502
502
  1. Explicit ``workflow=`` constructor override wins.
503
503
  2. Otherwise auto-detect from *instrument*.
504
504
  3. If detection fails and any record carries a non-empty
505
- ``index2_key``, raise ``ValueError`` — silently passing the
505
+ ``index2_key``, raise ``ValueError`` - silently passing the
506
506
  i5 through would produce a wrong sheet for workflow-B
507
507
  instruments.
508
508
  4. If no Index2 values are present, return ``False`` (no-op).
@@ -534,7 +534,7 @@ class SampleSheetConverter:
534
534
  f"samplesheet_parser.instruments for the full instrument table."
535
535
  )
536
536
 
537
- # No Index2 to convert — silent pass-through is safe.
537
+ # No Index2 to convert - silent pass-through is safe.
538
538
  logger.debug(f"{direction}: no Index2 values, skipping workflow detection.")
539
539
  return False
540
540
 
@@ -4,10 +4,10 @@ Diff engine for Illumina sample sheets.
4
4
  Compares two sample sheets (any combination of V1 / V2) and reports
5
5
  structured differences across four dimensions:
6
6
 
7
- - **Header** — key/value changes in [Header] / [BCLConvert_Settings]
8
- - **Reads** — changes in read lengths or cycle counts
9
- - **Samples added / removed** — keyed on ``Sample_ID`` + ``Lane``
10
- - **Sample fields changed** — per-sample field-level diffs (index
7
+ - **Header** - key/value changes in [Header] / [BCLConvert_Settings]
8
+ - **Reads** - changes in read lengths or cycle counts
9
+ - **Samples added / removed** - keyed on ``Sample_ID`` + ``Lane``
10
+ - **Sample fields changed** - per-sample field-level diffs (index
11
11
  changes, project reassignment, etc.)
12
12
 
13
13
  The comparison is format-aware: V1 ``index`` is compared against V2
@@ -58,13 +58,13 @@ _FIELD_ALIASES: dict[str, str] = {
58
58
  "sample_name": "Sample_Name",
59
59
  }
60
60
 
61
- # Fields to skip when comparing samples — these are metadata that differ
61
+ # Fields to skip when comparing samples - these are metadata that differ
62
62
  # between formats by design and do not represent meaningful changes.
63
63
  #
64
64
  # V1-only fields (no V2 equivalent):
65
- # I7_Index_ID / I5_Index_ID — index name columns; V2 stores index values only
66
- # Sample_Name — V1 carries a display name; V2 omits it
67
- # Sample_Plate / Sample_Well / Description — IEM metadata not present in V2
65
+ # I7_Index_ID / I5_Index_ID - index name columns; V2 stores index values only
66
+ # Sample_Name - V1 carries a display name; V2 omits it
67
+ # Sample_Plate / Sample_Well / Description - IEM metadata not present in V2
68
68
  _SKIP_FIELDS: frozenset[str] = frozenset(
69
69
  {
70
70
  "experiment_name",
@@ -118,8 +118,8 @@ class HeaderChange:
118
118
  section: str = "header" # "header" | "reads" | "settings"
119
119
 
120
120
  def __str__(self) -> str:
121
- old = repr(self.old_value) if self.old_value is not None else "—"
122
- new = repr(self.new_value) if self.new_value is not None else "—"
121
+ old = repr(self.old_value) if self.old_value is not None else "-"
122
+ new = repr(self.new_value) if self.new_value is not None else "-"
123
123
  return f"[{self.section}] {self.field}: {old} → {new}"
124
124
 
125
125
 
@@ -135,8 +135,8 @@ class SampleChange:
135
135
  def __str__(self) -> str:
136
136
  lines = [f"Sample {self.sample_id!r} (lane {self.lane}):"]
137
137
  for f, (old, new) in self.changes.items():
138
- old_s = repr(old) if old is not None else "—"
139
- new_s = repr(new) if new is not None else "—"
138
+ old_s = repr(old) if old is not None else "-"
139
+ new_s = repr(new) if new is not None else "-"
140
140
  lines.append(f" {f}: {old_s} → {new_s}")
141
141
  return "\n".join(lines)
142
142
 
@@ -8,10 +8,10 @@ from enum import Enum
8
8
  class SampleSheetVersion(str, Enum):
9
9
  """Illumina sample sheet format version.
10
10
 
11
- V1 — Illumina Experiment Manager (IEM) format, used with bcl2fastq.
11
+ V1 - Illumina Experiment Manager (IEM) format, used with bcl2fastq.
12
12
  Identified by ``IEMFileVersion`` in the [Header] section.
13
13
 
14
- V2 — BCLConvert format, used with BCLConvert and required for
14
+ V2 - BCLConvert format, used with BCLConvert and required for
15
15
  NovaSeq X series instruments.
16
16
  Identified by ``FileFormatVersion`` in the [Header] section,
17
17
  or by the presence of ``[BCLConvert_Settings]`` / ``[BCLConvert_Data]``
@@ -25,9 +25,9 @@ class SampleSheetVersion(str, Enum):
25
25
  class IndexType(str, Enum):
26
26
  """Sequencing index configuration.
27
27
 
28
- SINGLE — I7 index only (single-index libraries).
29
- DUAL — I7 + I5 indexes (dual-index libraries, standard for modern workflows).
30
- NONE — No index (rare; full-lane libraries).
28
+ SINGLE - I7 index only (single-index libraries).
29
+ DUAL - I7 + I5 indexes (dual-index libraries, standard for modern workflows).
30
+ NONE - No index (rare; full-lane libraries).
31
31
  """
32
32
 
33
33
  SINGLE = "single"
@@ -2,9 +2,9 @@
2
2
  Format-detection factory for Illumina sample sheets.
3
3
 
4
4
  The factory inspects the ``[Header]`` section and section names of a
5
- ``SampleSheet.csv`` to select the correct parser — :class:`SampleSheetV1`
5
+ ``SampleSheet.csv`` to select the correct parser - :class:`SampleSheetV1`
6
6
  for classic IEM / bcl2fastq files and :class:`SampleSheetV2` for
7
- BCLConvert files — without requiring the caller to know the format
7
+ BCLConvert files - without requiring the caller to know the format
8
8
  upfront.
9
9
 
10
10
  Detection logic
@@ -65,7 +65,7 @@ class SampleSheetFactory:
65
65
 
66
66
  Parameters
67
67
  ----------
68
- None — the factory is stateless until :meth:`create_parser` is called.
68
+ None - the factory is stateless until :meth:`create_parser` is called.
69
69
 
70
70
  Examples
71
71
  --------
@@ -76,6 +76,10 @@ class SampleSheetFactory:
76
76
  """
77
77
 
78
78
  # Class-level registry: (detector_fn, parser_class, version) tuples, LIFO.
79
+ # This is process-global shared state: registering a parser affects every
80
+ # SampleSheetFactory instance in the process, and registration is not
81
+ # synchronised, so register custom parsers at import or startup rather than
82
+ # concurrently from worker threads. Call clear_registry() to reset it.
79
83
  _registry: list[tuple[Callable[[Path], bool], type[Any], SampleSheetVersion]] = []
80
84
 
81
85
  def __init__(self) -> None:
@@ -96,7 +100,7 @@ class SampleSheetFactory:
96
100
  """Register a custom format detector and parser.
97
101
 
98
102
  Registered detectors are tried before the built-in V1/V2 detection,
99
- in LIFO order — the most recently registered detector wins when
103
+ in LIFO order - the most recently registered detector wins when
100
104
  multiple detectors match.
101
105
 
102
106
  Parameters
@@ -135,9 +139,9 @@ class SampleSheetFactory:
135
139
  """Detect the sample sheet format and return the appropriate parser.
136
140
 
137
141
  The returned parser shares the same interface:
138
- - :meth:`parse` — load and parse all sections
139
- - :meth:`samples` — return a list of sample records
140
- - :meth:`index_type` — return ``"dual"``, ``"single"``, or ``"none"``
142
+ - :meth:`parse` - load and parse all sections
143
+ - :meth:`samples` - return a list of sample records
144
+ - :meth:`index_type` - return ``"dual"``, ``"single"``, or ``"none"``
141
145
 
142
146
  Parameters
143
147
  ----------
@@ -176,7 +180,7 @@ class SampleSheetFactory:
176
180
  try:
177
181
  if detector(path):
178
182
  logger.info(
179
- f"Custom detector matched — using {parser_class.__name__!r} "
183
+ f"Custom detector matched - using {parser_class.__name__!r} "
180
184
  f"(version={ver.value!r})"
181
185
  )
182
186
  self.version = ver
@@ -184,17 +188,17 @@ class SampleSheetFactory:
184
188
  self.parser = parser
185
189
  return parser
186
190
  except Exception as exc:
187
- logger.debug(f"Custom detector {detector!r} raised {exc!r} for {path} — skipping.")
191
+ logger.debug(f"Custom detector {detector!r} raised {exc!r} for {path} - skipping.")
188
192
 
189
193
  # Built-in V1/V2 detection.
190
194
  detected = self._detect_version(path)
191
195
  self.version = detected
192
196
 
193
197
  if detected == SampleSheetVersion.V2:
194
- logger.info("Detected BCLConvert V2 format — using SampleSheetV2")
198
+ logger.info("Detected BCLConvert V2 format - using SampleSheetV2")
195
199
  parser = SampleSheetV2(path, **kwargs)
196
200
  else:
197
- logger.info("Detected IEM V1 format — using SampleSheetV1")
201
+ logger.info("Detected IEM V1 format - using SampleSheetV1")
198
202
  parser = SampleSheetV1(path, **kwargs)
199
203
 
200
204
  self.parser = parser
@@ -237,11 +241,15 @@ class SampleSheetFactory:
237
241
  def _detect_version(self, path: Path) -> SampleSheetVersion:
238
242
  """Inspect the file and return the appropriate SampleSheetVersion.
239
243
 
240
- Reads only as much of the file as needed:
244
+ Detection runs in three phases:
241
245
  1. Scan [Header] for FileFormatVersion / IEMFileVersion.
242
- 2. If undetermined, scan the full file for BCLConvert section names.
246
+ 2. If undetermined, scan the whole file for BCLConvert section names.
243
247
  3. Default to V1.
244
248
 
249
+ The full file is read once up front. Sample sheets are small (a few
250
+ KB), so this is cheap, and it guarantees Phase 2 sees BCLConvert
251
+ sections that appear after intervening sections such as [Reads].
252
+
245
253
  Parameters
246
254
  ----------
247
255
  path:
@@ -252,9 +260,10 @@ class SampleSheetFactory:
252
260
  SampleSheetVersion
253
261
  Detected version enum value.
254
262
  """
255
- # --- Phase 1: check [Header] section only ----------------------
256
- # Read lines until we leave the [Header] section (hit a new section
257
- # or EOF). Avoids loading the entire file for the common case.
263
+ # --- Phase 1: collect [Header] lines and the full file content ---
264
+ # header_lines collects only lines inside the [Header] section.
265
+ # full_content accumulates every line so Phase 2 can scan the whole
266
+ # file, not just the part read before the header ends.
258
267
  header_lines: list[str] = []
259
268
  full_content: list[str] = []
260
269
 
@@ -269,8 +278,9 @@ class SampleSheetFactory:
269
278
  continue
270
279
 
271
280
  if stripped.startswith("[") and in_header:
272
- # Leaving the header section
273
- break
281
+ # Left the header section; keep reading for Phase 2.
282
+ in_header = False
283
+ continue
274
284
 
275
285
  if in_header and stripped:
276
286
  header_lines.append(stripped)
@@ -285,14 +295,16 @@ class SampleSheetFactory:
285
295
  return SampleSheetVersion.V1
286
296
 
287
297
  # --- Phase 2: scan for BCLConvert section names ----------------
288
- # Use the already-read content — no second file open needed.
289
- content = "".join(full_content)
290
- if "[BCLConvert_Settings]" in content or "[BCLConvert_Data]" in content:
298
+ # Use the already-read content - no second file open needed. Compare
299
+ # case-insensitively because the V2 parser normalises section names
300
+ # that way, so e.g. "[bclconvert_data]" must also detect as V2.
301
+ content_lower = "".join(full_content).lower()
302
+ if "[bclconvert_settings]" in content_lower or "[bclconvert_data]" in content_lower:
291
303
  logger.debug("Discriminator: BCLConvert section names → V2")
292
304
  return SampleSheetVersion.V2
293
305
 
294
306
  # --- Phase 3: default to V1 ------------------------------------
295
- logger.debug("No discriminator found — defaulting to V1")
307
+ logger.debug("No discriminator found - defaulting to V1")
296
308
  return SampleSheetVersion.V1
297
309
 
298
310
  # ------------------------------------------------------------------
@@ -35,7 +35,7 @@ from samplesheet_parser.factory import SampleSheetFactory
35
35
 
36
36
  logger = logging.getLogger(__name__)
37
37
 
38
- # Raw record keys that are standard sample fields — not extra columns
38
+ # Raw record keys that are standard sample fields - not extra columns
39
39
  _STANDARD_SAMPLE_KEYS: frozenset[str] = frozenset(
40
40
  {
41
41
  "lane",
@@ -144,7 +144,7 @@ class SampleSheetFilter:
144
144
  ) -> FilterResult:
145
145
  """Write a filtered copy of the sheet to *output_path*.
146
146
 
147
- Multiple criteria are ANDed — a sample must match **all** provided
147
+ Multiple criteria are ANDed - a sample must match **all** provided
148
148
  criteria to be included. ``sample_id`` supports glob patterns (e.g.
149
149
  ``"CTRL_*"`` or ``"SAMPLE_00[1-3]"``).
150
150
 
@@ -235,7 +235,7 @@ class SampleSheetFilter:
235
235
  result.matched_count += 1
236
236
 
237
237
  if result.matched_count == 0:
238
- logger.warning("No samples matched the filter criteria — no output written.")
238
+ logger.warning("No samples matched the filter criteria - no output written.")
239
239
  return result
240
240
 
241
241
  out = writer.write(output_path, validate=validate)
@@ -53,13 +53,13 @@ def normalize_index_lengths(
53
53
  Parameters
54
54
  ----------
55
55
  samples:
56
- Output of ``sheet.samples()``. Not modified in place — the
56
+ Output of ``sheet.samples()``. Not modified in place - the
57
57
  function returns new dicts with the index values replaced.
58
58
  strategy:
59
- ``"trim"`` — trim all indexes to the length of the shortest
59
+ ``"trim"`` - trim all indexes to the length of the shortest
60
60
  sequence in *samples* (default).
61
61
 
62
- ``"pad"`` — pad all indexes to the length of the longest
62
+ ``"pad"`` - pad all indexes to the length of the longest
63
63
  sequence using ``"N"`` wildcard characters.
64
64
  index1_key:
65
65
  Override the dict key for the primary index (I7). Auto-detected
@@ -1,8 +1,8 @@
1
1
  """
2
2
  Illumina instrument workflow classification and i5 orientation helpers.
3
3
 
4
- The two demultiplexers — ``bcl2fastq`` (V1 sheets) and ``BCLConvert``
5
- (V2 sheets) — disagree on the orientation of index 2 (i5) for some
4
+ The two demultiplexers - ``bcl2fastq`` (V1 sheets) and ``BCLConvert``
5
+ (V2 sheets) - disagree on the orientation of index 2 (i5) for some
6
6
  instruments:
7
7
 
8
8
  * **Workflow A** instruments read i5 in the *forward* orientation. Both
@@ -73,11 +73,11 @@ WORKFLOW_A_INSTRUMENTS: frozenset[str] = frozenset(
73
73
  # ``Instrument Type`` strings and V2 ``InstrumentPlatform`` values.
74
74
  WORKFLOW_B_INSTRUMENTS: frozenset[str] = frozenset(
75
75
  {
76
- # NovaSeq X family — V2 sheets typically declare "NovaSeqXSeries"
76
+ # NovaSeq X family - V2 sheets typically declare "NovaSeqXSeries"
77
77
  "novaseqx",
78
78
  "novaseqxplus",
79
79
  "novaseqxseries",
80
- # NextSeq family — V2 sheets sometimes declare the combined
80
+ # NextSeq family - V2 sheets sometimes declare the combined
81
81
  # platform "NextSeq1000/2000", which normalises to "nextseq10002000".
82
82
  "nextseq500",
83
83
  "nextseq550",
@@ -147,7 +147,7 @@ def detect_workflow(
147
147
  Workflow | None
148
148
  :attr:`Workflow.A` or :attr:`Workflow.B` if the instrument is in
149
149
  one of the tables. ``None`` if *instrument* is empty, ambiguous
150
- (e.g. ``NovaSeq 6000`` — chemistry-dependent), or unrecognised.
150
+ (e.g. ``NovaSeq 6000`` - chemistry-dependent), or unrecognised.
151
151
 
152
152
  Examples
153
153
  --------
@@ -110,17 +110,17 @@ class MergeResult:
110
110
  def add_conflict(self, code: str, message: str, **context: Any) -> None:
111
111
  self.has_conflicts = True
112
112
  self.conflicts.append(MergeConflict("error", code, message, dict(context)))
113
- logger.error(f"Merge conflict — {code}: {message}")
113
+ logger.error(f"Merge conflict - {code}: {message}")
114
114
 
115
115
  def add_warning(self, code: str, message: str, **context: Any) -> None:
116
116
  self.warnings.append(MergeConflict("warning", code, message, dict(context)))
117
- logger.warning(f"Merge warning — {code}: {message}")
117
+ logger.warning(f"Merge warning - {code}: {message}")
118
118
 
119
119
  def summary(self) -> str:
120
120
  """Return a human-readable one-line summary."""
121
121
  status = "FAIL" if self.has_conflicts else "OK"
122
122
  return (
123
- f"{status} — {len(self.conflicts)} conflict(s), "
123
+ f"{status} - {len(self.conflicts)} conflict(s), "
124
124
  f"{len(self.warnings)} warning(s), "
125
125
  f"{self.sample_count} sample(s) merged"
126
126
  )
@@ -137,7 +137,7 @@ class MergeResult:
137
137
  _PRE_MERGE_CONFLICT_CODES: frozenset[str] = frozenset(
138
138
  {
139
139
  "INDEX_COLLISION", # covered by _check_index_collisions
140
- "DUPLICATE_INDEX", # same root cause — validator sees result of collision
140
+ "DUPLICATE_INDEX", # same root cause - validator sees result of collision
141
141
  }
142
142
  )
143
143
 
@@ -158,15 +158,15 @@ class SampleSheetMerger:
158
158
 
159
159
  Checks performed at merge time
160
160
  --------------------------------
161
- * **INDEX_COLLISION** — Same lane + index (or index pair) appears
161
+ * **INDEX_COLLISION** - Same lane + index (or index pair) appears
162
162
  in more than one input sheet → error.
163
- * **INDEX_DISTANCE_TOO_LOW** — Two indexes across sheets in the same lane
163
+ * **INDEX_DISTANCE_TOO_LOW** - Two indexes across sheets in the same lane
164
164
  have Hamming distance < 3 → warning.
165
- * **READ_LENGTH_CONFLICT** — Input sheets specify different read lengths
165
+ * **READ_LENGTH_CONFLICT** - Input sheets specify different read lengths
166
166
  → error.
167
- * **ADAPTER_CONFLICT** — Input sheets specify different adapter
167
+ * **ADAPTER_CONFLICT** - Input sheets specify different adapter
168
168
  sequences → warning.
169
- * **MIXED_FORMAT** — Input sheets are a mix of V1 and V2; all
169
+ * **MIXED_FORMAT** - Input sheets are a mix of V1 and V2; all
170
170
  are auto-converted to the target format →
171
171
  warning (not an error).
172
172
 
@@ -189,7 +189,7 @@ class SampleSheetMerger:
189
189
  >>> merger.add("ProjectB/SampleSheet.csv")
190
190
  >>> result = merger.merge("combined.csv")
191
191
  >>> print(result.summary())
192
- OK — 0 conflict(s), 1 warning(s), 48 samples merged
192
+ OK - 0 conflict(s), 1 warning(s), 48 samples merged
193
193
  """
194
194
 
195
195
  def __init__(
@@ -266,7 +266,7 @@ class SampleSheetMerger:
266
266
  two sheets are registered.
267
267
  """
268
268
  if not self._paths:
269
- raise ValueError("No input sheets registered — call add() first.")
269
+ raise ValueError("No input sheets registered - call add() first.")
270
270
  if len(self._paths) < 2:
271
271
  raise ValueError(
272
272
  "At least two input sheets are required for a merge. "
@@ -289,7 +289,7 @@ class SampleSheetMerger:
289
289
  # ── 3. Abort early if hard conflicts found ───────────────────────
290
290
  if result.has_conflicts and abort_on_conflicts:
291
291
  logger.error(
292
- f"Merge aborted — {len(result.conflicts)} conflict(s) found. "
292
+ f"Merge aborted - {len(result.conflicts)} conflict(s) found. "
293
293
  "Fix errors before merging."
294
294
  )
295
295
  return result
@@ -311,7 +311,7 @@ class SampleSheetMerger:
311
311
  return result
312
312
 
313
313
  # ------------------------------------------------------------------
314
- # Internal — parsing
314
+ # Internal - parsing
315
315
  # ------------------------------------------------------------------
316
316
 
317
317
  def _parse_all(
@@ -353,7 +353,7 @@ class SampleSheetMerger:
353
353
  return parsed
354
354
 
355
355
  # ------------------------------------------------------------------
356
- # Internal — conflict checks
356
+ # Internal - conflict checks
357
357
  # ------------------------------------------------------------------
358
358
 
359
359
  def _check_read_lengths(
@@ -386,7 +386,7 @@ class SampleSheetMerger:
386
386
  key = ",".join(str(rl) for rl in lengths) if lengths else "<NO_READS>"
387
387
  if key not in length_map:
388
388
  length_map[key] = (lengths, p)
389
- # else: same key — no conflict, do nothing
389
+ # else: same key - no conflict, do nothing
390
390
 
391
391
  if len(length_map) > 1:
392
392
  detail = "; ".join(
@@ -440,8 +440,8 @@ class SampleSheetMerger:
440
440
  """Error if two sheets place the same index in the same lane.
441
441
 
442
442
  Uses ``sheet.records`` (raw per-row dicts) rather than
443
- ``sheet.samples()`` so that multi-lane sheets — where the same
444
- ``Sample_ID`` appears in multiple lanes — are not silently
443
+ ``sheet.samples()`` so that multi-lane sheets - where the same
444
+ ``Sample_ID`` appears in multiple lanes - are not silently
445
445
  de-duplicated before the collision check. Falls back to
446
446
  ``sheet.samples()`` for any parser that doesn't expose ``.records``.
447
447
  """
@@ -459,7 +459,7 @@ class SampleSheetMerger:
459
459
  sid = raw_sid or "?"
460
460
  key = f"{idx1}+{idx2}" if idx2 else idx1
461
461
 
462
- # Silently skip incomplete rows — _build_writer will emit
462
+ # Silently skip incomplete rows - _build_writer will emit
463
463
  # INCOMPLETE_SAMPLE_RECORD for them; no collision warning here.
464
464
  # Mirror _build_writer()'s required-field criteria.
465
465
  if not idx1 or not raw_sid:
@@ -493,7 +493,7 @@ class SampleSheetMerger:
493
493
  """Warn if indexes from different sheets are too similar (Hamming).
494
494
 
495
495
  Uses ``sheet.records`` (raw per-row dicts) for the same reason as
496
- :meth:`_check_index_collisions` — to avoid losing multi-lane rows
496
+ :meth:`_check_index_collisions` - to avoid losing multi-lane rows
497
497
  that ``sheet.samples()`` de-duplicates by ``Sample_ID``.
498
498
  """
499
499
  # Build per-lane list of (sample_id, combined_index, source_path)
@@ -520,7 +520,7 @@ class SampleSheetMerger:
520
520
  sid_a, combined_a, path_a = entries[i]
521
521
  sid_b, combined_b, path_b = entries[j]
522
522
 
523
- # Skip pairs from the same sheet — intra-sheet distance
523
+ # Skip pairs from the same sheet - intra-sheet distance
524
524
  # is already checked by SampleSheetValidator
525
525
  if path_a == path_b:
526
526
  continue
@@ -546,7 +546,7 @@ class SampleSheetMerger:
546
546
  )
547
547
 
548
548
  # ------------------------------------------------------------------
549
- # Internal — building the merged writer
549
+ # Internal - building the merged writer
550
550
  # ------------------------------------------------------------------
551
551
 
552
552
  def _build_writer(
@@ -590,11 +590,11 @@ class SampleSheetMerger:
590
590
  writer = SampleSheetWriter.from_sheet(primary, version=self.target_version)
591
591
 
592
592
  # Keys that belong in [Header]/[BCLConvert_Settings] or are handled
593
- # explicitly below — must not leak into [Data]/[BCLConvert_Data] as
593
+ # explicitly below - must not leak into [Data]/[BCLConvert_Data] as
594
594
  # extra per-sample columns.
595
595
  _STANDARD_SAMPLE_KEYS: frozenset[str] = frozenset(
596
596
  {
597
- # core sample fields (lowercase — V1/V2 shared interface)
597
+ # core sample fields (lowercase - V1/V2 shared interface)
598
598
  "sample_id",
599
599
  "sample_name",
600
600
  "lane",
@@ -631,8 +631,8 @@ class SampleSheetMerger:
631
631
  )
632
632
 
633
633
  # Add samples from all other sheets.
634
- # Use per-row records (not samples()) so multi-lane sheets — where the
635
- # same Sample_ID appears in multiple lanes — are not de-duplicated
634
+ # Use per-row records (not samples()) so multi-lane sheets - where the
635
+ # same Sample_ID appears in multiple lanes - are not de-duplicated
636
636
  # before being written to the merged output.
637
637
  for p, sheet in parsed[1:]:
638
638
  logger.debug(f"Adding samples from {p.name}")