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.
Files changed (144) hide show
  1. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.zenodo.json +1 -1
  2. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/CHANGELOG.md +99 -0
  3. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/CITATION.cff +2 -2
  4. samplesheet_parser-2.0.0/Makefile +81 -0
  5. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/PKG-INFO +34 -8
  6. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/README.md +29 -5
  7. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/api.md +39 -1
  8. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/cli.md +14 -1
  9. samplesheet_parser-2.0.0/docs/guide/conversion.md +134 -0
  10. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/parsing.md +31 -2
  11. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/index.md +1 -1
  12. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/installation.md +6 -9
  13. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_converter.py +6 -3
  14. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/environment.yml +1 -1
  15. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/main.nf +4 -14
  16. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/meta.yml +31 -15
  17. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +10 -10
  18. {samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info → samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff}/environment.yml +1 -1
  19. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/main.nf +34 -0
  20. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/meta.yml +84 -0
  21. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +79 -0
  22. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +80 -0
  23. {samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate → samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter}/environment.yml +1 -1
  24. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/main.nf +38 -0
  25. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/meta.yml +91 -0
  26. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +57 -0
  27. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +5 -0
  28. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/info/environment.yml +6 -0
  29. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/info/main.nf +34 -0
  30. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/info/meta.yml +28 -13
  31. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +7 -7
  32. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +80 -0
  33. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/environment.yml +6 -0
  34. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/main.nf +43 -0
  35. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/meta.yml +90 -0
  36. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +88 -0
  37. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/environment.yml +6 -0
  38. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/main.nf +46 -0
  39. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/meta.yml +90 -0
  40. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/split/tests/main.nf.test +79 -0
  41. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
  42. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/validate/main.nf +34 -0
  43. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/validate/meta.yml +28 -13
  44. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +7 -7
  45. samplesheet_parser-2.0.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +80 -0
  46. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/pyproject.toml +15 -8
  47. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/recipes/meta.yaml +3 -3
  48. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/__init__.py +4 -1
  49. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/cli.py +32 -3
  50. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/converter.py +199 -50
  51. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/diff.py +44 -43
  52. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/enums.py +19 -15
  53. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/factory.py +75 -11
  54. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/filter.py +3 -2
  55. samplesheet_parser-2.0.0/samplesheet_parser/instruments.py +223 -0
  56. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/merger.py +5 -4
  57. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/parsers/v1.py +89 -93
  58. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/parsers/v2.py +178 -137
  59. samplesheet_parser-2.0.0/samplesheet_parser/protocol.py +102 -0
  60. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/splitter.py +3 -2
  61. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/validators.py +35 -28
  62. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/writer.py +6 -4
  63. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_cli.py +6 -0
  64. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_converter.py +404 -48
  65. samplesheet_parser-2.0.0/tests/test_instruments.py +126 -0
  66. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_parsers/test_v1.py +16 -19
  67. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_parsers/test_v2.py +20 -20
  68. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_validators/test_hamming.py +155 -70
  69. samplesheet_parser-1.2.0/docs/guide/conversion.md +0 -54
  70. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +0 -4
  71. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/main.nf +0 -45
  72. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +0 -4
  73. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/main.nf +0 -45
  74. samplesheet_parser-1.2.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +0 -4
  75. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.github/workflows/ci.yml +0 -0
  76. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.github/workflows/copilot-instructions.md +0 -0
  77. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.gitignore +0 -0
  78. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.pre-commit-config.yaml +0 -0
  79. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/.readthedocs.yaml +0 -0
  80. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/CONTRIBUTING.md +0 -0
  81. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/LICENSE +0 -0
  82. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/changelog.md +0 -0
  83. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/ci.md +0 -0
  84. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/contributing.md +0 -0
  85. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/examples.md +0 -0
  86. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/diffing.md +0 -0
  87. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/filtering.md +0 -0
  88. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/index_utils.md +0 -0
  89. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/merging.md +0 -0
  90. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/quickstart.md +0 -0
  91. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/splitting.md +0 -0
  92. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/validation.md +0 -0
  93. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/guide/writing.md +0 -0
  94. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/docs/requirements.txt +0 -0
  95. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_diff.py +0 -0
  96. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_filter.py +0 -0
  97. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_index_utils.py +0 -0
  98. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_merger.py +0 -0
  99. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_splitter.py +0 -0
  100. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/demo_writer.py +0 -0
  101. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/parse_examples.py +0 -0
  102. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  103. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  104. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  105. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  106. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/README.md +0 -0
  107. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/combined_clean.csv +0 -0
  108. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  109. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  110. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  111. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  112. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  113. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  114. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  115. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  116. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  117. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  118. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  119. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  120. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  121. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/images/samplesheet_parser_arch_v03.png +0 -0
  122. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/images/samplesheet_parser_overview.png +0 -0
  123. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/mkdocs.yml +0 -0
  124. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/index_utils.py +0 -0
  125. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/parsers/__init__.py +0 -0
  126. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/samplesheet_parser/py.typed +0 -0
  127. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/scripts/demo_converter.py +0 -0
  128. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/scripts/demo_diff.py +0 -0
  129. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/scripts/demo_writer.py +0 -0
  130. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/__init__.py +0 -0
  131. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/conftest.py +0 -0
  132. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  133. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  134. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  135. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_diff.py +0 -0
  136. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_factory.py +0 -0
  137. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_filter.py +0 -0
  138. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_index_utils.py +0 -0
  139. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_merger.py +0 -0
  140. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_parsers/__init__.py +0 -0
  141. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_splitter.py +0 -0
  142. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_validators/__init__.py +0 -0
  143. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_validators/test_validators.py +0 -0
  144. {samplesheet_parser-1.2.0 → samplesheet_parser-2.0.0}/tests/test_writer.py +0 -0
@@ -4,7 +4,7 @@
4
4
  "upload_type": "software",
5
5
  "access_right": "open",
6
6
  "license": "Apache-2.0",
7
- "version": "1.1.0",
7
+ "version": "2.0.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -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: 1.1.0
12
- date-released: 2026-04-05
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: 1.2.0
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.12
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
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
62
- [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
64
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
63
65
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
66
+ [![Install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
67
+
64
68
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
65
69
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
66
- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
67
70
  [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
71
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](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.12+. No mandatory runtime dependencies beyond `loguru`.
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)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return appropriate parser |
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.12'
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
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
8
- [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
8
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
9
9
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
10
+ [![Install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
11
+
10
12
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
11
13
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
12
- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
13
14
  [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
15
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](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.12+. No mandatory runtime dependencies beyond `loguru`.
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)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return appropriate parser |
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.12'
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
- | Method | Returns | Description |
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`, `InstrumentPlatform`, etc.) are dropped with a warning.
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
- | `samples()` | `list[dict]` | One record per unique sample |
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
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
8
- [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
8
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
9
9
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
10
10
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
11
11
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)