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.
- samplesheet_parser/__init__.py +9 -3
- samplesheet_parser/cli.py +7 -5
- samplesheet_parser/converter.py +10 -10
- samplesheet_parser/diff.py +12 -12
- samplesheet_parser/enums.py +5 -5
- samplesheet_parser/factory.py +34 -22
- samplesheet_parser/filter.py +3 -3
- samplesheet_parser/index_utils.py +3 -3
- samplesheet_parser/instruments.py +5 -5
- samplesheet_parser/merger.py +25 -25
- samplesheet_parser/parsers/v1.py +11 -11
- samplesheet_parser/parsers/v2.py +71 -35
- samplesheet_parser/protocol.py +1 -1
- samplesheet_parser/splitter.py +3 -3
- samplesheet_parser/validators.py +107 -47
- samplesheet_parser/writer.py +28 -10
- {samplesheet_parser-2.0.0.dist-info → samplesheet_parser-2.2.0.dist-info}/METADATA +18 -11
- samplesheet_parser-2.2.0.dist-info/RECORD +23 -0
- samplesheet_parser-2.0.0.dist-info/RECORD +0 -23
- {samplesheet_parser-2.0.0.dist-info → samplesheet_parser-2.2.0.dist-info}/WHEEL +0 -0
- {samplesheet_parser-2.0.0.dist-info → samplesheet_parser-2.2.0.dist-info}/entry_points.txt +0 -0
- {samplesheet_parser-2.0.0.dist-info → samplesheet_parser-2.2.0.dist-info}/licenses/LICENSE +0 -0
samplesheet_parser/__init__.py
CHANGED
|
@@ -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
|
|
9
|
-
- BCLConvert V2 format
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
samplesheet_parser/converter.py
CHANGED
|
@@ -45,7 +45,7 @@ Examples
|
|
|
45
45
|
--------
|
|
46
46
|
>>> from samplesheet_parser import SampleSheetConverter
|
|
47
47
|
>>>
|
|
48
|
-
>>> # V1 → V2
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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``
|
|
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
|
|
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
|
|
samplesheet_parser/diff.py
CHANGED
|
@@ -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**
|
|
8
|
-
- **Reads**
|
|
9
|
-
- **Samples added / removed**
|
|
10
|
-
- **Sample fields changed**
|
|
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
|
|
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
|
|
66
|
-
# Sample_Name
|
|
67
|
-
# Sample_Plate / Sample_Well / Description
|
|
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
|
|
samplesheet_parser/enums.py
CHANGED
|
@@ -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
|
|
11
|
+
V1 - Illumina Experiment Manager (IEM) format, used with bcl2fastq.
|
|
12
12
|
Identified by ``IEMFileVersion`` in the [Header] section.
|
|
13
13
|
|
|
14
|
-
V2
|
|
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
|
|
29
|
-
DUAL
|
|
30
|
-
NONE
|
|
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"
|
samplesheet_parser/factory.py
CHANGED
|
@@ -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
|
|
5
|
+
``SampleSheet.csv`` to select the correct parser - :class:`SampleSheetV1`
|
|
6
6
|
for classic IEM / bcl2fastq files and :class:`SampleSheetV2` for
|
|
7
|
-
BCLConvert files
|
|
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
|
|
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
|
|
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`
|
|
139
|
-
- :meth:`samples`
|
|
140
|
-
- :meth:`index_type`
|
|
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
|
|
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}
|
|
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
|
|
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
|
|
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
|
-
|
|
244
|
+
Detection runs in three phases:
|
|
241
245
|
1. Scan [Header] for FileFormatVersion / IEMFileVersion.
|
|
242
|
-
2. If undetermined, scan the
|
|
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:
|
|
256
|
-
#
|
|
257
|
-
#
|
|
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
|
-
#
|
|
273
|
-
|
|
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
|
|
289
|
-
|
|
290
|
-
|
|
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
|
|
307
|
+
logger.debug("No discriminator found - defaulting to V1")
|
|
296
308
|
return SampleSheetVersion.V1
|
|
297
309
|
|
|
298
310
|
# ------------------------------------------------------------------
|
samplesheet_parser/filter.py
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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"``
|
|
59
|
+
``"trim"`` - trim all indexes to the length of the shortest
|
|
60
60
|
sequence in *samples* (default).
|
|
61
61
|
|
|
62
|
-
``"pad"``
|
|
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
|
|
5
|
-
(V2 sheets)
|
|
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
|
|
76
|
+
# NovaSeq X family - V2 sheets typically declare "NovaSeqXSeries"
|
|
77
77
|
"novaseqx",
|
|
78
78
|
"novaseqxplus",
|
|
79
79
|
"novaseqxseries",
|
|
80
|
-
# NextSeq family
|
|
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``
|
|
150
|
+
(e.g. ``NovaSeq 6000`` - chemistry-dependent), or unrecognised.
|
|
151
151
|
|
|
152
152
|
Examples
|
|
153
153
|
--------
|
samplesheet_parser/merger.py
CHANGED
|
@@ -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
|
|
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
|
|
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}
|
|
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
|
|
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**
|
|
161
|
+
* **INDEX_COLLISION** - Same lane + index (or index pair) appears
|
|
162
162
|
in more than one input sheet → error.
|
|
163
|
-
* **INDEX_DISTANCE_TOO_LOW**
|
|
163
|
+
* **INDEX_DISTANCE_TOO_LOW** - Two indexes across sheets in the same lane
|
|
164
164
|
have Hamming distance < 3 → warning.
|
|
165
|
-
* **READ_LENGTH_CONFLICT**
|
|
165
|
+
* **READ_LENGTH_CONFLICT** - Input sheets specify different read lengths
|
|
166
166
|
→ error.
|
|
167
|
-
* **ADAPTER_CONFLICT**
|
|
167
|
+
* **ADAPTER_CONFLICT** - Input sheets specify different adapter
|
|
168
168
|
sequences → warning.
|
|
169
|
-
* **MIXED_FORMAT**
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
444
|
-
``Sample_ID`` appears in multiple lanes
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
635
|
-
# same Sample_ID appears in multiple lanes
|
|
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}")
|