samplesheet-parser 1.2.0__tar.gz → 2.0.0__tar.gz
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-1.2.0 → samplesheet_parser-2.0.0}/.zenodo.json +1 -1
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/CHANGELOG.md +99 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/CITATION.cff +2 -2
- samplesheet_parser-2.0.0/Makefile +81 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/PKG-INFO +34 -8
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/README.md +29 -5
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/api.md +39 -1
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/cli.md +14 -1
- samplesheet_parser-2.0.0/docs/guide/conversion.md +134 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/parsing.md +31 -2
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/index.md +1 -1
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/installation.md +6 -9
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_converter.py +6 -3
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/environment.yml +1 -1
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/main.nf +4 -14
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/meta.yml +31 -15
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +10 -10
- {samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info → samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff}/environment.yml +1 -1
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/main.nf +34 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/meta.yml +84 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +79 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +80 -0
- {samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate → samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter}/environment.yml +1 -1
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/main.nf +38 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/meta.yml +91 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +57 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +5 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/info/environment.yml +6 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/info/main.nf +34 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/info/meta.yml +28 -13
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +7 -7
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +80 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/environment.yml +6 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/main.nf +43 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/meta.yml +90 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +88 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/environment.yml +6 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/main.nf +46 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/meta.yml +90 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/tests/main.nf.test +79 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/validate/main.nf +34 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/validate/meta.yml +28 -13
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +7 -7
- samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +80 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/pyproject.toml +15 -8
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/recipes/meta.yaml +3 -3
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/__init__.py +4 -1
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/cli.py +32 -3
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/converter.py +199 -50
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/diff.py +44 -43
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/enums.py +19 -15
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/factory.py +75 -11
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/filter.py +3 -2
- samplesheet_parser-2.0.0/samplesheet_parser/instruments.py +223 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/merger.py +5 -4
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/parsers/v1.py +89 -93
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/parsers/v2.py +178 -137
- samplesheet_parser-2.0.0/samplesheet_parser/protocol.py +102 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/splitter.py +3 -2
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/validators.py +35 -28
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/writer.py +6 -4
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_cli.py +6 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_converter.py +404 -48
- samplesheet_parser-2.0.0/tests/test_instruments.py +126 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_parsers/test_v1.py +16 -19
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_parsers/test_v2.py +20 -20
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_validators/test_hamming.py +155 -70
- samplesheet_parser-1.2.0/docs/guide/conversion.md +0 -54
- samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +0 -4
- samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/main.nf +0 -45
- samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +0 -4
- samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/main.nf +0 -45
- samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +0 -4
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.github/workflows/ci.yml +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.github/workflows/copilot-instructions.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.gitignore +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.pre-commit-config.yaml +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.readthedocs.yaml +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/CONTRIBUTING.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/LICENSE +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/changelog.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/ci.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/contributing.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/examples.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/diffing.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/filtering.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/index_utils.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/merging.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/quickstart.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/splitting.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/validation.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/writing.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/requirements.txt +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_diff.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_filter.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_index_utils.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_merger.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_splitter.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_writer.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/parse_examples.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/README.md +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/combined_clean.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_single_index.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/images/samplesheet_parser_arch_v03.png +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/images/samplesheet_parser_overview.png +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/mkdocs.yml +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/index_utils.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/parsers/__init__.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/py.typed +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/scripts/demo_converter.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/scripts/demo_diff.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/scripts/demo_writer.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/__init__.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/conftest.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_diff.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_factory.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_filter.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_index_utils.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_merger.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_parsers/__init__.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_splitter.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_validators/__init__.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_validators/test_validators.py +0 -0
- {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_writer.py +0 -0
|
@@ -8,6 +8,105 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
_No unreleased changes._
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## [2.0.0] - 2026-06-06
|
|
16
|
+
|
|
17
|
+
### Breaking changes
|
|
18
|
+
|
|
19
|
+
- **Python 3.10+ required** (was 3.12+). The `str, Enum` mixin replaces
|
|
20
|
+
`StrEnum` throughout `enums.py` and `instruments.py`, giving identical
|
|
21
|
+
behaviour on all supported versions.
|
|
22
|
+
- **`loguru` dependency removed.** The library now uses `logging.getLogger(__name__)`
|
|
23
|
+
in every module. Host applications retain full control of log configuration.
|
|
24
|
+
If you previously relied on `loguru` sinks seeing library log output, wire up
|
|
25
|
+
a standard `logging` handler instead.
|
|
26
|
+
- **`clean()` now returns the cleaned content as a `str` and never writes to
|
|
27
|
+
disk.** Previously `SampleSheetV1.clean()` and `SampleSheetV2.clean()` wrote
|
|
28
|
+
to the source file and created a `.backup` alongside it. The source file is
|
|
29
|
+
now untouched; the cleaned string is passed in-memory to `read()`. Callers
|
|
30
|
+
that relied on the side-effect (file written, `.backup` created) must adapt.
|
|
31
|
+
- **`samples()` deduplication key changed from `sample_id` to `(sample_id, lane)`.**
|
|
32
|
+
Multi-lane sheets where the same sample appears in multiple lanes now return
|
|
33
|
+
one record *per lane* rather than silently dropping all but the first row.
|
|
34
|
+
- **`SampleSheetFactory.create_parser()` return type is now `SampleSheetParser`**
|
|
35
|
+
(the new Protocol) rather than `SampleSheetV1 | SampleSheetV2`. Both concrete
|
|
36
|
+
types structurally satisfy the Protocol; the change only affects code with
|
|
37
|
+
explicit type annotations on the return value.
|
|
38
|
+
- **`_hamming_distance` renamed to `hamming_distance`** (underscore removed).
|
|
39
|
+
Import path: `from samplesheet_parser import hamming_distance` or
|
|
40
|
+
`from samplesheet_parser.validators import hamming_distance`.
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
|
|
44
|
+
- **V2 `parse_data()` no longer silently drops keys with empty-string values.**
|
|
45
|
+
The `{k: v for k, v in ... if v}` filter was removing keys whose value was
|
|
46
|
+
`""`, making V2 record dicts structurally inconsistent with V1. All keys are
|
|
47
|
+
now preserved; values are stripped of surrounding whitespace only.
|
|
48
|
+
- **`converter.to_v1()` bare `assert` replaced with explicit `TypeError`.**
|
|
49
|
+
`assert isinstance(sheet, SampleSheetV2)` is stripped by `python -O`; the
|
|
50
|
+
guard now raises `TypeError` unconditionally when the wrong type is passed.
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
|
|
54
|
+
- **`SampleSheetParser` Protocol** (`samplesheet_parser.protocol`) — a
|
|
55
|
+
`runtime_checkable` structural protocol satisfied by both `SampleSheetV1`
|
|
56
|
+
and `SampleSheetV2`. Third-party parsers that implement the same interface
|
|
57
|
+
can be registered with the factory without inheriting from any base class.
|
|
58
|
+
`isinstance(sheet, SampleSheetParser)` works at runtime.
|
|
59
|
+
- **`SampleSheetFactory.register(detector, parser_class, version)`** — class
|
|
60
|
+
method that registers a custom format detector. Registered detectors are
|
|
61
|
+
tried before the built-in V1/V2 detection in LIFO order. Useful for
|
|
62
|
+
supporting hypothetical V3 formats or vendor-specific variants.
|
|
63
|
+
- **`SampleSheetFactory.clear_registry()`** — removes all custom registrations.
|
|
64
|
+
Intended for use in tests to prevent cross-test contamination.
|
|
65
|
+
- **`detect_workflow()` accepts `extra_a` / `extra_b` keyword arguments** —
|
|
66
|
+
caller-supplied `frozenset[str]` of instrument names checked before the
|
|
67
|
+
built-in tables. Allows narrowing workflow classification without subclassing.
|
|
68
|
+
- **`hamming_distance` is now a public export** — available as
|
|
69
|
+
`from samplesheet_parser import hamming_distance` and documented in the API
|
|
70
|
+
reference.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## [1.3.0] - 2026-05-20
|
|
75
|
+
|
|
76
|
+
### Fixed
|
|
77
|
+
|
|
78
|
+
- **`SampleSheetConverter` now reverse-complements `Index2` for workflow-B
|
|
79
|
+
instruments** (NovaSeq X / X Plus, NextSeq 500/550/1000/2000, iSeq 100,
|
|
80
|
+
MiniSeq, HiSeq 3000/4000) on V1 ↔ V2 conversion. `bcl2fastq` records i5 as
|
|
81
|
+
read on the chip (reverse-complemented for workflow-B instruments) while
|
|
82
|
+
`BCLConvert` expects i5 in the forward orientation; previously the
|
|
83
|
+
converter passed `Index2` through verbatim, silently producing V2 sheets
|
|
84
|
+
that demultiplexed to the wrong samples ([#30]).
|
|
85
|
+
- The workflow is auto-detected from `[Header] Instrument Type` (V1) or
|
|
86
|
+
`InstrumentPlatform` / `InstrumentType` (V2). When the sheet has a
|
|
87
|
+
non-empty `Index2` column and the workflow cannot be determined, the
|
|
88
|
+
converter raises `ValueError` and the CLI exits non-zero rather than
|
|
89
|
+
guessing. **Behavior change:** dual-index sheets with no recognised
|
|
90
|
+
instrument header that previously converted (with silently wrong `Index2`)
|
|
91
|
+
will now fail loudly until `workflow=` / `--workflow` is supplied.
|
|
92
|
+
- V2 → V1 conversion now preserves the instrument as `Instrument Type` in
|
|
93
|
+
the V1 `[Header]` so the workflow signal survives a round trip.
|
|
94
|
+
|
|
95
|
+
### Added
|
|
96
|
+
|
|
97
|
+
- **`samplesheet_parser.instruments`** — public module exposing
|
|
98
|
+
`Workflow` (StrEnum: `A` / `B`), `WORKFLOW_A_INSTRUMENTS` /
|
|
99
|
+
`WORKFLOW_B_INSTRUMENTS` / `AMBIGUOUS_INSTRUMENTS` tables,
|
|
100
|
+
`detect_workflow()`, `parse_workflow()`, and `reverse_complement()`.
|
|
101
|
+
- **`SampleSheetConverter(path, *, workflow=...)`** — explicit workflow
|
|
102
|
+
override accepting `"a"`, `"b"`, or a `Workflow` enum value. Required for
|
|
103
|
+
ambiguous instruments such as `NovaSeq 6000` (workflow depends on v1.0
|
|
104
|
+
vs v1.5 chemistry).
|
|
105
|
+
- **`samplesheet convert --workflow {a,b}` / `-w`** — CLI override that
|
|
106
|
+
takes precedence over auto-detection.
|
|
107
|
+
|
|
108
|
+
[#30]: https://github.com/chaitanyakasaraneni/samplesheet-parser/issues/30
|
|
109
|
+
|
|
11
110
|
---
|
|
12
111
|
|
|
13
112
|
## [1.2.0] - 2026-04-14
|
|
@@ -8,8 +8,8 @@ abstract: >
|
|
|
8
8
|
Provides format auto-detection, bidirectional V1/V2 conversion,
|
|
9
9
|
structural and index validation, sheet diffing, and cross-project
|
|
10
10
|
merging with Hamming-distance collision detection.
|
|
11
|
-
version:
|
|
12
|
-
date-released: 2026-
|
|
11
|
+
version: 2.0.0
|
|
12
|
+
date-released: 2026-06-06
|
|
13
13
|
license: Apache-2.0
|
|
14
14
|
url: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
|
|
15
15
|
repository-code: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Makefile for samplesheet-parser
|
|
2
|
+
# Keeps the version in sync across pyproject.toml, CITATION.cff, and .zenodo.json.
|
|
3
|
+
# Portable to GNU Make 3.81 (macOS default) — recipes are single POSIX-sh lines.
|
|
4
|
+
|
|
5
|
+
PKG := samplesheet_parser
|
|
6
|
+
PYPROJECT := pyproject.toml
|
|
7
|
+
CITATION := CITATION.cff
|
|
8
|
+
ZENODO := .zenodo.json
|
|
9
|
+
CHANGELOG := CHANGELOG.md
|
|
10
|
+
|
|
11
|
+
CURRENT_VERSION := $(shell sed -n -E 's/^version = "([0-9]+\.[0-9]+\.[0-9]+)".*/\1/p' $(PYPROJECT) | head -1)
|
|
12
|
+
|
|
13
|
+
.DEFAULT_GOAL := help
|
|
14
|
+
.PHONY: help version major minor patch tag test lint build clean
|
|
15
|
+
|
|
16
|
+
help:
|
|
17
|
+
@echo "samplesheet-parser — current version: $(CURRENT_VERSION)"
|
|
18
|
+
@echo ""
|
|
19
|
+
@echo "Version bumping (syncs $(PYPROJECT), $(CITATION), $(ZENODO); rolls $(CHANGELOG)):"
|
|
20
|
+
@echo " make patch patch bump (x.y.Z)"
|
|
21
|
+
@echo " make minor minor bump (x.Y.0)"
|
|
22
|
+
@echo " make major major bump (X.0.0)"
|
|
23
|
+
@echo ""
|
|
24
|
+
@echo "Other targets:"
|
|
25
|
+
@echo " make version print the current version"
|
|
26
|
+
@echo " make tag create git tag v$(CURRENT_VERSION)"
|
|
27
|
+
@echo " make test run pytest"
|
|
28
|
+
@echo " make lint run ruff"
|
|
29
|
+
@echo " make build build sdist + wheel"
|
|
30
|
+
@echo " make clean remove build artifacts"
|
|
31
|
+
|
|
32
|
+
version:
|
|
33
|
+
@echo $(CURRENT_VERSION)
|
|
34
|
+
|
|
35
|
+
patch minor major:
|
|
36
|
+
@$(MAKE) --no-print-directory _bump PART=$@
|
|
37
|
+
|
|
38
|
+
# internal: bump the version part named by PART across all files (one shell line)
|
|
39
|
+
_bump:
|
|
40
|
+
@cur="$(CURRENT_VERSION)"; \
|
|
41
|
+
[ -n "$$cur" ] || { echo "error: could not read version from $(PYPROJECT)"; exit 1; }; \
|
|
42
|
+
MA=$${cur%%.*}; rest=$${cur#*.}; MI=$${rest%%.*}; PA=$${rest##*.}; \
|
|
43
|
+
case "$(PART)" in \
|
|
44
|
+
major) MA=$$((MA + 1)); MI=0; PA=0 ;; \
|
|
45
|
+
minor) MI=$$((MI + 1)); PA=0 ;; \
|
|
46
|
+
patch) PA=$$((PA + 1)) ;; \
|
|
47
|
+
*) echo "error: unknown bump part '$(PART)'"; exit 1 ;; \
|
|
48
|
+
esac; \
|
|
49
|
+
new="$$MA.$$MI.$$PA"; today="$$(date +%F)"; \
|
|
50
|
+
sed -E 's/^version = "[0-9]+\.[0-9]+\.[0-9]+"/version = "'"$$new"'"/' $(PYPROJECT) > $(PYPROJECT).tmp && mv $(PYPROJECT).tmp $(PYPROJECT); \
|
|
51
|
+
sed -E -e 's/^version: .*/version: '"$$new"'/' -e 's/^date-released: .*/date-released: '"$$today"'/' $(CITATION) > $(CITATION).tmp && mv $(CITATION).tmp $(CITATION); \
|
|
52
|
+
sed -E 's/("version": )"[0-9]+\.[0-9]+\.[0-9]+"/\1"'"$$new"'"/' $(ZENODO) > $(ZENODO).tmp && mv $(ZENODO).tmp $(ZENODO); \
|
|
53
|
+
cl_note=""; \
|
|
54
|
+
if [ -f $(CHANGELOG) ] && grep -q '^## \[Unreleased\]' $(CHANGELOG); then \
|
|
55
|
+
awk -v v="$$new" -v d="$$today" '!done && /^## \[Unreleased\]/ {print "## [Unreleased]"; print ""; print "_No unreleased changes._"; print ""; print "## [" v "] - " d; done=1; next} {print}' $(CHANGELOG) > $(CHANGELOG).tmp && mv $(CHANGELOG).tmp $(CHANGELOG); \
|
|
56
|
+
cl_note=", $(CHANGELOG)"; \
|
|
57
|
+
else \
|
|
58
|
+
cl_note=" (warning: no [Unreleased] section in $(CHANGELOG) — not rolled)"; \
|
|
59
|
+
fi; \
|
|
60
|
+
echo "Bumped $$cur -> $$new (date-released: $$today)"; \
|
|
61
|
+
echo " updated: $(PYPROJECT), $(CITATION), $(ZENODO)$$cl_note"; \
|
|
62
|
+
echo "Next: review $(CHANGELOG), then: git commit -am \"release v$$new\" && make tag && git push --follow-tags"
|
|
63
|
+
|
|
64
|
+
tag:
|
|
65
|
+
@v="$(CURRENT_VERSION)"; \
|
|
66
|
+
if git rev-parse "v$$v" >/dev/null 2>&1; then echo "tag v$$v already exists"; exit 1; fi; \
|
|
67
|
+
git tag -a "v$$v" -m "Release v$$v"; \
|
|
68
|
+
echo "created annotated tag v$$v (push with: git push --follow-tags)"
|
|
69
|
+
|
|
70
|
+
test:
|
|
71
|
+
@pytest
|
|
72
|
+
|
|
73
|
+
lint:
|
|
74
|
+
@ruff check $(PKG)/
|
|
75
|
+
|
|
76
|
+
build:
|
|
77
|
+
@python3 -m hatchling build
|
|
78
|
+
|
|
79
|
+
clean:
|
|
80
|
+
@rm -rf dist build *.egg-info
|
|
81
|
+
@find . -type d -name __pycache__ -prune -exec rm -rf {} +
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: samplesheet-parser
|
|
3
|
-
Version:
|
|
3
|
+
Version: 2.0.0
|
|
4
4
|
Summary: Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2
|
|
5
5
|
Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
|
|
6
6
|
Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
|
|
@@ -33,11 +33,13 @@ Classifier: Intended Audience :: Developers
|
|
|
33
33
|
Classifier: Intended Audience :: Science/Research
|
|
34
34
|
Classifier: License :: OSI Approved :: Apache Software License
|
|
35
35
|
Classifier: Programming Language :: Python :: 3
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
36
38
|
Classifier: Programming Language :: Python :: 3.12
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
37
40
|
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
38
41
|
Classifier: Typing :: Typed
|
|
39
|
-
Requires-Python: >=3.
|
|
40
|
-
Requires-Dist: loguru>=0.7
|
|
42
|
+
Requires-Python: >=3.10
|
|
41
43
|
Provides-Extra: cli
|
|
42
44
|
Requires-Dist: typer>=0.12; extra == 'cli'
|
|
43
45
|
Provides-Extra: dev
|
|
@@ -59,12 +61,14 @@ Description-Content-Type: text/markdown
|
|
|
59
61
|
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
60
62
|
|
|
61
63
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
62
|
-
[](https://www.python.org/downloads/)
|
|
63
65
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
66
|
+
[](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
|
|
67
|
+
|
|
64
68
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
65
69
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
66
|
-
[](https://doi.org/10.5281/zenodo.18989694)
|
|
67
70
|
[](https://illumina-samplesheet.readthedocs.io)
|
|
71
|
+
[](https://doi.org/10.5281/zenodo.18989694)
|
|
68
72
|
|
|
69
73
|
**Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
70
74
|
|
|
@@ -92,7 +96,7 @@ pip install samplesheet-parser
|
|
|
92
96
|
pip install "samplesheet-parser[cli]"
|
|
93
97
|
```
|
|
94
98
|
|
|
95
|
-
Requires Python 3.
|
|
99
|
+
Requires Python 3.10+. No mandatory runtime dependencies.
|
|
96
100
|
|
|
97
101
|
---
|
|
98
102
|
|
|
@@ -462,10 +466,21 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
462
466
|
|
|
463
467
|
| Method / attribute | Returns | Description |
|
|
464
468
|
|---|---|---|
|
|
465
|
-
| `create_parser(path, *, clean, experiment_id, parse)` | `
|
|
469
|
+
| `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return appropriate parser |
|
|
470
|
+
| `register(detector, parser_class, version)` | `None` | Register a custom format detector (class method, LIFO) |
|
|
471
|
+
| `clear_registry()` | `None` | Remove all custom registrations (class method) |
|
|
466
472
|
| `get_umi_length()` | `int` | UMI length from the current parser |
|
|
467
473
|
| `.version` | `SampleSheetVersion` | Detected format version |
|
|
468
474
|
|
|
475
|
+
### `SampleSheetParser` (Protocol)
|
|
476
|
+
|
|
477
|
+
A `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Third-party parsers that implement the same methods and attributes can be registered with `SampleSheetFactory.register()` without inheriting from any base class.
|
|
478
|
+
|
|
479
|
+
```python
|
|
480
|
+
from samplesheet_parser import SampleSheetParser, SampleSheetV1
|
|
481
|
+
assert isinstance(SampleSheetV1("sheet.csv"), SampleSheetParser)
|
|
482
|
+
```
|
|
483
|
+
|
|
469
484
|
### `SampleSheetV1` / `SampleSheetV2` (shared interface)
|
|
470
485
|
|
|
471
486
|
| Method / attribute | Returns | Description |
|
|
@@ -496,6 +511,17 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
496
511
|
| `validate(sheet)` | `ValidationResult` | Run all checks; returns structured result |
|
|
497
512
|
| `_check_index_distances(samples, result, min_distance=3)` | `None` | Hamming distance check (callable directly for custom thresholds) |
|
|
498
513
|
|
|
514
|
+
### `hamming_distance`
|
|
515
|
+
|
|
516
|
+
```python
|
|
517
|
+
from samplesheet_parser import hamming_distance
|
|
518
|
+
|
|
519
|
+
hamming_distance("ATTACTCG", "ATTACTCA") # → 1
|
|
520
|
+
hamming_distance("ATTACTCG", "GCTAGCTA") # → 6
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
Public helper for computing the Hamming distance between two index sequences. Sequences of unequal length are compared up to the shorter length.
|
|
524
|
+
|
|
499
525
|
### `SampleSheetWriter`
|
|
500
526
|
|
|
501
527
|
| Method / attribute | Returns | Description |
|
|
@@ -591,7 +617,7 @@ jobs:
|
|
|
591
617
|
|
|
592
618
|
- uses: actions/setup-python@v5
|
|
593
619
|
with:
|
|
594
|
-
python-version: '3.
|
|
620
|
+
python-version: '3.10'
|
|
595
621
|
|
|
596
622
|
- run: pip install "samplesheet-parser[cli]"
|
|
597
623
|
|
|
@@ -5,12 +5,14 @@
|
|
|
5
5
|
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
6
6
|
|
|
7
7
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
8
|
-
[](https://www.python.org/downloads/)
|
|
9
9
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
10
|
+
[](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
|
|
11
|
+
|
|
10
12
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
11
13
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
12
|
-
[](https://doi.org/10.5281/zenodo.18989694)
|
|
13
14
|
[](https://illumina-samplesheet.readthedocs.io)
|
|
15
|
+
[](https://doi.org/10.5281/zenodo.18989694)
|
|
14
16
|
|
|
15
17
|
**Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
16
18
|
|
|
@@ -38,7 +40,7 @@ pip install samplesheet-parser
|
|
|
38
40
|
pip install "samplesheet-parser[cli]"
|
|
39
41
|
```
|
|
40
42
|
|
|
41
|
-
Requires Python 3.
|
|
43
|
+
Requires Python 3.10+. No mandatory runtime dependencies.
|
|
42
44
|
|
|
43
45
|
---
|
|
44
46
|
|
|
@@ -408,10 +410,21 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
408
410
|
|
|
409
411
|
| Method / attribute | Returns | Description |
|
|
410
412
|
|---|---|---|
|
|
411
|
-
| `create_parser(path, *, clean, experiment_id, parse)` | `
|
|
413
|
+
| `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return appropriate parser |
|
|
414
|
+
| `register(detector, parser_class, version)` | `None` | Register a custom format detector (class method, LIFO) |
|
|
415
|
+
| `clear_registry()` | `None` | Remove all custom registrations (class method) |
|
|
412
416
|
| `get_umi_length()` | `int` | UMI length from the current parser |
|
|
413
417
|
| `.version` | `SampleSheetVersion` | Detected format version |
|
|
414
418
|
|
|
419
|
+
### `SampleSheetParser` (Protocol)
|
|
420
|
+
|
|
421
|
+
A `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Third-party parsers that implement the same methods and attributes can be registered with `SampleSheetFactory.register()` without inheriting from any base class.
|
|
422
|
+
|
|
423
|
+
```python
|
|
424
|
+
from samplesheet_parser import SampleSheetParser, SampleSheetV1
|
|
425
|
+
assert isinstance(SampleSheetV1("sheet.csv"), SampleSheetParser)
|
|
426
|
+
```
|
|
427
|
+
|
|
415
428
|
### `SampleSheetV1` / `SampleSheetV2` (shared interface)
|
|
416
429
|
|
|
417
430
|
| Method / attribute | Returns | Description |
|
|
@@ -442,6 +455,17 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
442
455
|
| `validate(sheet)` | `ValidationResult` | Run all checks; returns structured result |
|
|
443
456
|
| `_check_index_distances(samples, result, min_distance=3)` | `None` | Hamming distance check (callable directly for custom thresholds) |
|
|
444
457
|
|
|
458
|
+
### `hamming_distance`
|
|
459
|
+
|
|
460
|
+
```python
|
|
461
|
+
from samplesheet_parser import hamming_distance
|
|
462
|
+
|
|
463
|
+
hamming_distance("ATTACTCG", "ATTACTCA") # → 1
|
|
464
|
+
hamming_distance("ATTACTCG", "GCTAGCTA") # → 6
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
Public helper for computing the Hamming distance between two index sequences. Sequences of unequal length are compared up to the shorter length.
|
|
468
|
+
|
|
445
469
|
### `SampleSheetWriter`
|
|
446
470
|
|
|
447
471
|
| Method / attribute | Returns | Description |
|
|
@@ -537,7 +561,7 @@ jobs:
|
|
|
537
561
|
|
|
538
562
|
- uses: actions/setup-python@v5
|
|
539
563
|
with:
|
|
540
|
-
python-version: '3.
|
|
564
|
+
python-version: '3.10'
|
|
541
565
|
|
|
542
566
|
- run: pip install "samplesheet-parser[cli]"
|
|
543
567
|
|
|
@@ -51,11 +51,49 @@ from samplesheet_parser import (
|
|
|
51
51
|
|
|
52
52
|
## SampleSheetConverter
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
```python
|
|
55
|
+
SampleSheetConverter(path, *, workflow: Workflow | str | None = None)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| Method / attribute | Returns | Description |
|
|
55
59
|
|---|---|---|
|
|
56
60
|
| `to_v2(output_path)` | `Path` | Convert IEM V1 → BCLConvert V2 |
|
|
57
61
|
| `to_v1(output_path)` | `Path` | Convert BCLConvert V2 → IEM V1 (lossy) |
|
|
58
62
|
| `.source_version` | `SampleSheetVersion \| None` | Auto-detected format of the input |
|
|
63
|
+
| `.workflow_override` | `Workflow \| None` | Resolved workflow override, if any |
|
|
64
|
+
|
|
65
|
+
The `workflow` parameter accepts `"a"`, `"b"`, or a `Workflow` enum value
|
|
66
|
+
and overrides auto-detection of the i5 orientation workflow from the
|
|
67
|
+
instrument header. See
|
|
68
|
+
[Conversion → Index 2 orientation](guide/conversion.md#index-2-i5-orientation).
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## samplesheet_parser.instruments
|
|
73
|
+
|
|
74
|
+
i5 orientation workflow classification helpers.
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
from samplesheet_parser.instruments import (
|
|
78
|
+
Workflow,
|
|
79
|
+
detect_workflow,
|
|
80
|
+
parse_workflow,
|
|
81
|
+
reverse_complement,
|
|
82
|
+
WORKFLOW_A_INSTRUMENTS,
|
|
83
|
+
WORKFLOW_B_INSTRUMENTS,
|
|
84
|
+
AMBIGUOUS_INSTRUMENTS,
|
|
85
|
+
)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| Name | Kind | Description |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `Workflow` | `StrEnum` | `Workflow.A` (i5 forward) / `Workflow.B` (i5 RC'd on chip) |
|
|
91
|
+
| `detect_workflow(name)` | `Workflow \| None` | Classify an instrument name; `None` for unknown or ambiguous (e.g. `NovaSeq 6000`) |
|
|
92
|
+
| `parse_workflow(value)` | `Workflow \| None` | Coerce a CLI string (`"a"` / `"b"`) to `Workflow` |
|
|
93
|
+
| `reverse_complement(seq)` | `str` | Reverse-complement a DNA sequence (preserves `N`, case-preserving) |
|
|
94
|
+
| `WORKFLOW_A_INSTRUMENTS` | `frozenset[str]` | Normalised names of workflow-A instruments |
|
|
95
|
+
| `WORKFLOW_B_INSTRUMENTS` | `frozenset[str]` | Normalised names of workflow-B instruments |
|
|
96
|
+
| `AMBIGUOUS_INSTRUMENTS` | `frozenset[str]` | Instruments whose workflow depends on chemistry and require an explicit override |
|
|
59
97
|
|
|
60
98
|
---
|
|
61
99
|
|
|
@@ -100,6 +100,7 @@ Convert between V1 (IEM/bcl2fastq) and V2 (BCLConvert) formats.
|
|
|
100
100
|
samplesheet convert SampleSheet_v1.csv --to v2 --output SampleSheet_v2.csv
|
|
101
101
|
samplesheet convert SampleSheet_v2.csv --to v1 --output SampleSheet_v1.csv
|
|
102
102
|
samplesheet convert SampleSheet_v1.csv --to v2 --output out.csv --format json
|
|
103
|
+
samplesheet convert NovaSeq6000.v1.csv --to v2 --workflow b --output out.csv
|
|
103
104
|
```
|
|
104
105
|
|
|
105
106
|
**Options:**
|
|
@@ -109,9 +110,21 @@ samplesheet convert SampleSheet_v1.csv --to v2 --output out.csv --format json
|
|
|
109
110
|
| `--to` | `v2` | Target format: `v1` or `v2` |
|
|
110
111
|
| `--output` / `-o` | `SampleSheet_converted.csv` | Output file path |
|
|
111
112
|
| `--format` / `-f` | `text` | Output format: `text` or `json` |
|
|
113
|
+
| `--workflow` / `-w` | auto-detect | i5 orientation: `a` (MiSeq, HiSeq 2000/2500, NovaSeq 6000 v1.0) or `b` (NovaSeq X/X Plus, NextSeq, iSeq, MiniSeq, HiSeq 3000/4000, NovaSeq 6000 v1.5). Overrides header auto-detection. |
|
|
112
114
|
|
|
113
115
|
!!! warning "V2 → V1 is lossy"
|
|
114
|
-
V2-only fields (`OverrideCycles`, `
|
|
116
|
+
V2-only fields (`OverrideCycles`, `FileFormatVersion`, etc.) are dropped with a warning. `InstrumentPlatform` is preserved as `Instrument Type` in the V1 header.
|
|
117
|
+
|
|
118
|
+
!!! info "Index 2 (i5) orientation"
|
|
119
|
+
For workflow-B instruments, `Index2` is reverse-complemented to
|
|
120
|
+
match the target demultiplexer's expected orientation. The workflow
|
|
121
|
+
is auto-detected from the instrument header; pass `--workflow` to
|
|
122
|
+
override (required for `NovaSeq 6000`, which is chemistry-dependent).
|
|
123
|
+
|
|
124
|
+
If the sheet has dual indexes and the workflow cannot be determined
|
|
125
|
+
and no override is given, `convert` exits non-zero with a clear
|
|
126
|
+
error rather than producing a silently-wrong sheet. See
|
|
127
|
+
[Conversion → Index 2 orientation](guide/conversion.md#index-2-i5-orientation).
|
|
115
128
|
|
|
116
129
|
**JSON output:**
|
|
117
130
|
```json
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Conversion
|
|
2
|
+
|
|
3
|
+
## V1 → V2
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
from samplesheet_parser import SampleSheetConverter
|
|
7
|
+
|
|
8
|
+
converter = SampleSheetConverter("SampleSheet_v1.csv")
|
|
9
|
+
out = converter.to_v2("SampleSheet_v2.csv")
|
|
10
|
+
|
|
11
|
+
print(out) # Path("SampleSheet_v2.csv")
|
|
12
|
+
print(converter.source_version) # SampleSheetVersion.V1
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The converter maps IEM V1 fields to BCLConvert V2 equivalents:
|
|
16
|
+
|
|
17
|
+
| V1 field | V2 field |
|
|
18
|
+
|---|---|
|
|
19
|
+
| `IEMFileVersion` | `FileFormatVersion: 2` |
|
|
20
|
+
| `[Data]` section | `[BCLConvert_Data]` section |
|
|
21
|
+
| `Sample_ID` | `Sample_ID` |
|
|
22
|
+
| `index` | `Index` |
|
|
23
|
+
| `index2` | `Index2` |
|
|
24
|
+
| `[Reads]` lengths | `Read1Cycles` / `Read2Cycles` in `[Reads]` |
|
|
25
|
+
| `Adapter` in `[Settings]` | `AdapterRead1` in `[BCLConvert_Settings]` |
|
|
26
|
+
|
|
27
|
+
## V2 → V1 (lossy)
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
converter = SampleSheetConverter("SampleSheet_v2.csv")
|
|
31
|
+
out = converter.to_v1("SampleSheet_v1.csv")
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
!!! warning "Lossy conversion"
|
|
35
|
+
V2-only fields are dropped during V2 → V1 conversion:
|
|
36
|
+
|
|
37
|
+
- `OverrideCycles`
|
|
38
|
+
- `FileFormatVersion` (replaced by `IEMFileVersion`)
|
|
39
|
+
- `SoftwareVersion` and other `[BCLConvert_Settings]` keys with no V1 equivalent
|
|
40
|
+
- `[Cloud_Data]` / `[Cloud_Settings]` sections
|
|
41
|
+
|
|
42
|
+
A warning is logged for each dropped field.
|
|
43
|
+
|
|
44
|
+
!!! info "Instrument is preserved"
|
|
45
|
+
`InstrumentPlatform` and `InstrumentType` are **not** dropped —
|
|
46
|
+
their value is written to the V1 `[Header]` as `Instrument Type`
|
|
47
|
+
so the workflow signal survives a round trip. The original V2
|
|
48
|
+
header key itself is not kept (V1 uses a different key name).
|
|
49
|
+
|
|
50
|
+
## Round-trip
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
converter = SampleSheetConverter("SampleSheet_v1.csv")
|
|
54
|
+
converter.to_v2("temp_v2.csv")
|
|
55
|
+
|
|
56
|
+
converter2 = SampleSheetConverter("temp_v2.csv")
|
|
57
|
+
converter2.to_v1("roundtrip_v1.csv")
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Sample IDs survive a V1 → V2 → V1 round-trip. V2-only fields do not survive a V2 → V1 → V2 round-trip.
|
|
61
|
+
|
|
62
|
+
## Index 2 (i5) orientation
|
|
63
|
+
|
|
64
|
+
`bcl2fastq` and `BCLConvert` disagree on the orientation of `Index2`
|
|
65
|
+
(i5) for some instruments. Conversion handles this automatically when
|
|
66
|
+
the source sheet declares an instrument; for ambiguous cases pass
|
|
67
|
+
`workflow=` (Python) or `--workflow` (CLI).
|
|
68
|
+
|
|
69
|
+
### Workflow split
|
|
70
|
+
|
|
71
|
+
| Workflow | i5 on the chip | Instruments |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| **A** (i5 forward) | as written | MiSeq, HiSeq 2000, HiSeq 2500, NovaSeq 6000 (v1.0 chemistry) |
|
|
74
|
+
| **B** (i5 RC'd on chip) | reverse-complemented | NovaSeq X / X Plus, NextSeq 500/550/1000/2000, iSeq 100, MiniSeq, HiSeq 3000/4000, NovaSeq 6000 (v1.5 chemistry) |
|
|
75
|
+
|
|
76
|
+
- **Workflow A** — both demultiplexers expect i5 in the forward
|
|
77
|
+
orientation, so V1 ↔ V2 conversion leaves `Index2` unchanged.
|
|
78
|
+
- **Workflow B** — `bcl2fastq` (V1) records i5 reverse-complemented as
|
|
79
|
+
it was read; `BCLConvert` (V2) always expects the forward orientation.
|
|
80
|
+
The converter reverse-complements `Index2` in both directions so the
|
|
81
|
+
output is correct for the target demultiplexer.
|
|
82
|
+
|
|
83
|
+
### Auto-detection
|
|
84
|
+
|
|
85
|
+
The workflow is auto-detected from:
|
|
86
|
+
|
|
87
|
+
- V1 `[Header]` → `Instrument Type` (e.g. `NovaSeq X Plus`)
|
|
88
|
+
- V2 `[Header]` → `InstrumentPlatform` (e.g. `NovaSeqXSeries`),
|
|
89
|
+
falling back to `InstrumentType`
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
# V1 sheet declares "Instrument Type,NovaSeq X Plus"
|
|
93
|
+
# → workflow B detected; Index2 is reverse-complemented in the V2 output
|
|
94
|
+
SampleSheetConverter("novaseq_xplus.v1.csv").to_v2("novaseq_xplus.v2.csv")
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
V2 → V1 conversion preserves the instrument as `Instrument Type` in the
|
|
98
|
+
V1 `[Header]`, so a V1 → V2 → V1 round-trip restores the original
|
|
99
|
+
`Index2` exactly.
|
|
100
|
+
|
|
101
|
+
### Explicit override
|
|
102
|
+
|
|
103
|
+
Pass `workflow="a"` or `workflow="b"` to skip auto-detection. This is
|
|
104
|
+
**required** for `NovaSeq 6000`, whose i5 orientation depends on
|
|
105
|
+
chemistry (v1.0 = workflow A, v1.5 = workflow B) and cannot be inferred
|
|
106
|
+
from the instrument name alone.
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
# NovaSeq 6000 with v1.5 chemistry → workflow B
|
|
110
|
+
SampleSheetConverter("novaseq6000.csv", workflow="b").to_v2("out.csv")
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
CLI:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
samplesheet convert novaseq6000.v1.csv --to v2 --workflow b --output out.csv
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Failure mode
|
|
120
|
+
|
|
121
|
+
If the sheet has a non-empty `Index2` column **and** the workflow
|
|
122
|
+
cannot be determined **and** no override is given, conversion fails
|
|
123
|
+
loudly:
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
V1 → V2: cannot determine i5 orientation workflow for instrument <missing>.
|
|
127
|
+
The sheet has dual indexes, and workflow-A vs workflow-B instruments
|
|
128
|
+
record Index2 in opposite orientations. Pass workflow='a' or
|
|
129
|
+
workflow='b' explicitly (CLI: --workflow {a,b}).
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
This is intentional — silently passing i5 through would produce a V2
|
|
133
|
+
sheet that runs but quietly misassigns reads. Single-index sheets and
|
|
134
|
+
sheets whose `Index2` column is entirely empty are unaffected.
|
|
@@ -73,12 +73,41 @@ print(rs.read_structure)
|
|
|
73
73
|
|
|
74
74
|
## Shared interface
|
|
75
75
|
|
|
76
|
-
Both `SampleSheetV1` and `SampleSheetV2` expose:
|
|
76
|
+
Both `SampleSheetV1` and `SampleSheetV2` satisfy the `SampleSheetParser` Protocol and expose:
|
|
77
77
|
|
|
78
78
|
| Method / attribute | Returns | Description |
|
|
79
79
|
|---|---|---|
|
|
80
80
|
| `parse(do_clean=True)` | `None` | Parse all sections |
|
|
81
|
-
| `
|
|
81
|
+
| `clean()` | `str` | Return cleaned content as a string — source file is **never** modified |
|
|
82
|
+
| `samples()` | `list[dict]` | One record per unique `(sample_id, lane)` pair |
|
|
82
83
|
| `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
|
|
84
|
+
| `parse_custom_section(name, *, required=False)` | `dict[str, str]` | Parse any non-standard section as key/value pairs |
|
|
83
85
|
| `.adapters` | `list[str]` | Adapter sequences |
|
|
84
86
|
| `.experiment_name` | `str \| None` | Run/experiment name |
|
|
87
|
+
|
|
88
|
+
### In-memory cleaning
|
|
89
|
+
|
|
90
|
+
`parse(do_clean=True)` (the default) cleans the file content in memory before parsing — stripping BOM, quotes, stray whitespace, and normalising V2 section names. **The source file on disk is never modified and no `.backup` files are created.**
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
# Access the cleaned content directly
|
|
94
|
+
cleaned = sheet.clean() # returns str, no file I/O side-effects
|
|
95
|
+
|
|
96
|
+
# Parse with cleaning (default)
|
|
97
|
+
sheet.parse()
|
|
98
|
+
|
|
99
|
+
# Parse without cleaning (raw file)
|
|
100
|
+
sheet.parse(do_clean=False)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Multi-lane deduplication
|
|
104
|
+
|
|
105
|
+
`samples()` deduplicates by `(sample_id, lane)` pair, not by `sample_id` alone. A sample appearing across multiple lanes produces one record per lane.
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
sheet.parse()
|
|
109
|
+
samples = sheet.samples()
|
|
110
|
+
# Multi-lane sheet with Sample1 in lanes 1 and 2 → two records:
|
|
111
|
+
# [{"sample_id": "Sample1", "lane": "1", ...},
|
|
112
|
+
# {"sample_id": "Sample1", "lane": "2", ...}]
|
|
113
|
+
```
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, splitting, filtering, programmatic sheet creation, and a full-featured CLI.
|
|
6
6
|
|
|
7
7
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
8
|
-
[](https://www.python.org/downloads/)
|
|
9
9
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
10
10
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
11
11
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|