samplesheet-parser 2.2.0__tar.gz → 2.3.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 (145) hide show
  1. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.zenodo.json +1 -1
  2. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/CHANGELOG.md +28 -0
  3. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/CITATION.cff +2 -2
  4. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/PKG-INFO +99 -8
  5. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/README.md +96 -5
  6. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/examples.md +29 -1
  7. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/parsing.md +7 -6
  8. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/quickstart.md +2 -2
  9. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/validation.md +30 -0
  10. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/index.md +9 -7
  11. samplesheet_parser-2.3.0/examples/demo_color_balance.py +85 -0
  12. samplesheet_parser-2.3.0/examples/demo_element_aviti.py +57 -0
  13. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/README.md +35 -4
  14. samplesheet_parser-2.3.0/examples/sample_sheets/element_aviti_RunManifest.csv +16 -0
  15. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/pyproject.toml +3 -2
  16. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/__init__.py +14 -1
  17. samplesheet_parser-2.3.0/samplesheet_parser/chemistry.py +335 -0
  18. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/cli.py +30 -3
  19. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/enums.py +7 -0
  20. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/factory.py +11 -1
  21. samplesheet_parser-2.3.0/samplesheet_parser/parsers/element.py +329 -0
  22. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/validators.py +162 -0
  23. samplesheet_parser-2.3.0/tests/test_chemistry.py +109 -0
  24. samplesheet_parser-2.3.0/tests/test_parsers/test_element.py +115 -0
  25. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_validators/test_validators.py +62 -9
  26. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.github/workflows/ci.yml +0 -0
  27. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.github/workflows/copilot-instructions.md +0 -0
  28. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.gitignore +0 -0
  29. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.pre-commit-config.yaml +0 -0
  30. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.readthedocs.yaml +0 -0
  31. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/CONTRIBUTING.md +0 -0
  32. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/LICENSE +0 -0
  33. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/Makefile +0 -0
  34. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/api.md +0 -0
  35. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/changelog.md +0 -0
  36. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/ci.md +0 -0
  37. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/cli.md +0 -0
  38. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/contributing.md +0 -0
  39. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/conversion.md +0 -0
  40. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/diffing.md +0 -0
  41. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/filtering.md +0 -0
  42. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/index_utils.md +0 -0
  43. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/merging.md +0 -0
  44. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/splitting.md +0 -0
  45. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/writing.md +0 -0
  46. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/installation.md +0 -0
  47. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/requirements.txt +0 -0
  48. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_converter.py +0 -0
  49. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_diff.py +0 -0
  50. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_filter.py +0 -0
  51. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_index_utils.py +0 -0
  52. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_merger.py +0 -0
  53. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_splitter.py +0 -0
  54. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_writer.py +0 -0
  55. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/parse_examples.py +0 -0
  56. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  57. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  58. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  59. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  60. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/combined_clean.csv +0 -0
  61. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  62. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  63. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  64. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  65. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  66. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  67. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  68. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  69. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  70. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  71. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  72. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  73. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  74. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/images/samplesheet_parser_arch_v03.png +0 -0
  75. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/images/samplesheet_parser_overview.png +0 -0
  76. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/mkdocs.yml +0 -0
  77. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/environment.yml +0 -0
  78. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/main.nf +0 -0
  79. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/meta.yml +0 -0
  80. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +0 -0
  81. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/environment.yml +0 -0
  82. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/main.nf +0 -0
  83. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/meta.yml +0 -0
  84. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +0 -0
  85. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +0 -0
  86. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/environment.yml +0 -0
  87. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/main.nf +0 -0
  88. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/meta.yml +0 -0
  89. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +0 -0
  90. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
  91. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/environment.yml +0 -0
  92. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/main.nf +0 -0
  93. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/meta.yml +0 -0
  94. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +0 -0
  95. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +0 -0
  96. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/environment.yml +0 -0
  97. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/main.nf +0 -0
  98. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/meta.yml +0 -0
  99. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +0 -0
  100. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/environment.yml +0 -0
  101. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/main.nf +0 -0
  102. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/meta.yml +0 -0
  103. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +0 -0
  104. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/environment.yml +0 -0
  105. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/main.nf +0 -0
  106. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/meta.yml +0 -0
  107. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +0 -0
  108. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +0 -0
  109. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/recipes/meta.yaml +0 -0
  110. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/converter.py +0 -0
  111. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/diff.py +0 -0
  112. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/filter.py +0 -0
  113. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/index_utils.py +0 -0
  114. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/instruments.py +0 -0
  115. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/merger.py +0 -0
  116. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/parsers/__init__.py +0 -0
  117. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/parsers/v1.py +0 -0
  118. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/parsers/v2.py +0 -0
  119. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/protocol.py +0 -0
  120. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/py.typed +0 -0
  121. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/splitter.py +0 -0
  122. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/writer.py +0 -0
  123. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/scripts/demo_converter.py +0 -0
  124. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/scripts/demo_diff.py +0 -0
  125. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/scripts/demo_writer.py +0 -0
  126. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/__init__.py +0 -0
  127. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/conftest.py +0 -0
  128. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  129. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  130. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  131. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_cli.py +0 -0
  132. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_converter.py +0 -0
  133. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_diff.py +0 -0
  134. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_factory.py +0 -0
  135. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_filter.py +0 -0
  136. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_index_utils.py +0 -0
  137. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_instruments.py +0 -0
  138. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_merger.py +0 -0
  139. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_parsers/__init__.py +0 -0
  140. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_parsers/test_v1.py +0 -0
  141. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_parsers/test_v2.py +0 -0
  142. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_splitter.py +0 -0
  143. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_validators/__init__.py +0 -0
  144. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_validators/test_hamming.py +0 -0
  145. {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.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": "2.2.0",
7
+ "version": "2.3.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -10,6 +10,34 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
10
10
 
11
11
  _No unreleased changes._
12
12
 
13
+ ## [2.3.0] - 2026-06-15
14
+
15
+ ### Added
16
+
17
+ - **Per-cycle color-balance validation (`samplesheet_parser.chemistry`).** Models
18
+ the optical detection chemistry of each instrument (4-channel, 2-channel,
19
+ 1-channel) and scores an index pool cycle-by-cycle for signal balance. On
20
+ 2-/1-channel chemistry (NextSeq, NovaSeq, NovaSeq X, iSeq), a cycle where the
21
+ whole pool reads the dark base `G` produces no optical signal and fails to
22
+ register; the validator now reports this as a `COLOR_BALANCE_NO_SIGNAL` error.
23
+ Four-channel instruments (MiSeq/HiSeq and Element AVITI, which images four
24
+ avidite dyes per cycle) have no dark base, so zero-diversity index cycles are
25
+ reported as `COLOR_BALANCE_LOW` warnings instead. The check is **opt-in** via
26
+ `SampleSheetValidator.validate(..., check_color_balance=True)` and the
27
+ `samplesheet validate --color-balance` CLI flag, and is skipped silently for
28
+ unknown instruments. New public API: `Chemistry`, `chemistry_for_instrument`,
29
+ `analyze_color_balance`, `ColorBalanceReport`.
30
+ - **Multi-vendor support: Element Biosciences AVITI.** `SampleSheetFactory` now
31
+ auto-detects Element AVITI `RunManifest.csv` files and parses them through a
32
+ new `ElementRunManifest` parser that satisfies the existing
33
+ `SampleSheetParser` protocol, mapping manifest columns to the shared sample
34
+ schema. The validator (including color balance, with AVITI modelled as a
35
+ four-channel platform), diff, and filter tooling work across vendors without
36
+ special-casing. New format enum value: `SampleSheetVersion.ELEMENT_AVITI`.
37
+ - New examples: `examples/demo_color_balance.py`,
38
+ `examples/demo_element_aviti.py`, and
39
+ `examples/sample_sheets/element_aviti_RunManifest.csv`.
40
+
13
41
  ## [2.2.0] - 2026-06-10
14
42
 
15
43
  ### Fixed
@@ -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: 2.2.0
12
- date-released: 2026-06-10
11
+ version: 2.3.0
12
+ date-released: 2026-06-15
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"
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 2.2.0
4
- Summary: Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2
3
+ Version: 2.3.0
4
+ Summary: Multi-vendor, format-agnostic parser for sequencing sample sheets — Illumina IEM V1 & BCLConvert V2 plus Element AVITI run manifests, with index validation and color-balance checking
5
5
  Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
6
6
  Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
7
7
  Project-URL: Repository, https://github.com/chaitanyakasaraneni/samplesheet-parser
@@ -27,7 +27,7 @@ License: Apache License
27
27
  See the License for the specific language governing permissions and
28
28
  limitations under the License.
29
29
  License-File: LICENSE
30
- Keywords: bcl2fastq,bclconvert,bioinformatics,demultiplexing,genomics,illumina,ngs,samplesheet,sequencing
30
+ Keywords: aviti,bcl2fastq,bclconvert,bioinformatics,color-balance,demultiplexing,element,genomics,illumina,multi-vendor,ngs,run-manifest,samplesheet,sequencing
31
31
  Classifier: Development Status :: 5 - Production/Stable
32
32
  Classifier: Intended Audience :: Developers
33
33
  Classifier: Intended Audience :: Science/Research
@@ -58,7 +58,7 @@ Description-Content-Type: text/markdown
58
58
 
59
59
  **Format-agnostic parser for Illumina SampleSheet.csv files.**
60
60
 
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.
61
+ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — plus non-Illumina **Element AVITI** run manifests — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
62
62
 
63
63
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
64
64
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -74,15 +74,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
74
74
 
75
75
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
76
76
 
77
- *`SampleSheetFactory` auto-detects the format and routes to the correct parser. Both formats share a common interface — `SampleSheetConverter` handles bidirectional conversion, `SampleSheetValidator` catches index and adapter issues, `SampleSheetDiff` compares two sheets across any combination of V1/V2 formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
77
+ *`SampleSheetFactory` auto-detects the format — Illumina V1/V2 or an Element AVITI run manifest — and routes to the correct parser. All formats share a common interface — `SampleSheetConverter` handles bidirectional conversion between the Illumina formats, `SampleSheetValidator` catches index, adapter, and color-balance issues, `SampleSheetDiff` compares two sheets across any combination of formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
78
78
 
79
79
  ---
80
80
 
81
81
  ## The problem this solves
82
82
 
83
- Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce two incompatible SampleSheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section.
83
+ Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
84
84
 
85
- Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for both, converts between formats, validates index integrity (including Hamming distance), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
85
+ Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
86
86
 
87
87
  ---
88
88
 
@@ -110,7 +110,7 @@ from samplesheet_parser import SampleSheetFactory
110
110
  factory = SampleSheetFactory()
111
111
  sheet = factory.create_parser("SampleSheet.csv", parse=True)
112
112
 
113
- print(factory.version) # SampleSheetVersion.V1 or .V2
113
+ print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
114
114
  print(sheet.index_type()) # "dual", "single", or "none"
115
115
 
116
116
  for sample in sheet.samples():
@@ -368,6 +368,8 @@ The detector reads only as much of the file as needed — stopping after `[Heade
368
368
  | `INDEX_DISTANCE_TOO_LOW` | warning | Two indexes in the same lane have Hamming distance < 3, risking demultiplexing bleed-through |
369
369
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
370
370
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
371
+ | `COLOR_BALANCE_NO_SIGNAL` | error | An index cycle has no signal in an optical channel (2-/1-channel chemistry) — the index read will fail. *Opt-in.* |
372
+ | `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) — degraded base calls. *Opt-in.* |
371
373
 
372
374
  ### Index distance checking
373
375
 
@@ -397,6 +399,95 @@ result = ValidationResult()
397
399
  SampleSheetValidator()._check_index_distances(samples, result, min_distance=4)
398
400
  ```
399
401
 
402
+ ### Color-balance checking (opt-in)
403
+
404
+ On 2-channel instruments (NextSeq, NovaSeq, NovaSeq X) and 1-channel
405
+ instruments (iSeq), bases are called from optical signal: `A` lights
406
+ both channels, `C` only red, `T` only green, and **`G` is a dark base with no
407
+ signal at all**. A cycle where the whole index pool reads `G` produces no
408
+ signal, so the instrument cannot register the tile and the index read fails —
409
+ a real, common cause of wrecked runs that a Hamming-distance check cannot see.
410
+
411
+ Because the sample sheet already contains every sample's index, this can be
412
+ predicted *before the run starts* with no sequencing data. The validator scores
413
+ the pool cycle-by-cycle: it transposes the indexes into columns and checks that
414
+ each column produces signal in both channels.
415
+
416
+ ```python
417
+ from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
418
+
419
+ sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=True)
420
+
421
+ # Opt in; the instrument is read from the sheet header (or pass instrument=...)
422
+ result = SampleSheetValidator().validate(sheet, check_color_balance=True)
423
+
424
+ for err in result.errors:
425
+ print(err)
426
+ # [ERROR] COLOR_BALANCE_NO_SIGNAL: On 2-channel chemistry (NovaSeqXSeries),
427
+ # index1 cycle 4 has no red or green signal across the pool: no sample
428
+ # carries a red or green base (A/C/T) at this cycle ... the index read will fail.
429
+ ```
430
+
431
+ The chemistry is resolved from the instrument name; the check is **off by
432
+ default** (it can legitimately fail a low-plex pool) and is skipped silently
433
+ for unknown instruments. The same analysis is available standalone:
434
+
435
+ ```python
436
+ from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
437
+
438
+ chem = chemistry_for_instrument("NovaSeqXSeries") # Chemistry.TWO_CHANNEL
439
+ report = analyze_color_balance(["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"],
440
+ chemistry=chem)
441
+ for cb in report.dark_cycles:
442
+ print(cb.read, cb.cycle, cb.base_counts) # index1 4 {'G': 4}
443
+ ```
444
+
445
+ From the CLI:
446
+
447
+ ```bash
448
+ samplesheet validate SampleSheet.csv --color-balance
449
+ samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
450
+ ```
451
+
452
+ | Chemistry | Instruments | What is flagged |
453
+ |---|---|---|
454
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000, Element AVITI | Zero-diversity cycles (warning) |
455
+ | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | Dark cycles / weak channels |
456
+ | 1-channel | iSeq 100 | Dark cycles / weak channels |
457
+
458
+ Element AVITI uses four-channel avidity chemistry (four images per cycle, one
459
+ per avidite dye — [Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7)),
460
+ so it has no dark base; color-balance checking flags low-diversity index
461
+ cycles rather than dark cycles.
462
+
463
+ ---
464
+
465
+ ## Multi-vendor support
466
+
467
+ The factory is not limited to Illumina. Any parser that implements the
468
+ `SampleSheetParser` protocol can be auto-detected, and **Element Biosciences
469
+ AVITI `RunManifest.csv`** files are supported out of the box — the same
470
+ `SampleSheetFactory` recognises them and returns a parser with the identical
471
+ interface:
472
+
473
+ ```python
474
+ from samplesheet_parser import SampleSheetFactory
475
+
476
+ factory = SampleSheetFactory()
477
+ sheet = factory.create_parser("RunManifest.csv", parse=True)
478
+
479
+ print(factory.version) # SampleSheetVersion.ELEMENT_AVITI
480
+ print(sheet.index_type()) # "dual"
481
+ for s in sheet.samples(): # same schema as Illumina: sample_id, index, index2, ...
482
+ print(s["sample_id"], s["index"], s["index2"])
483
+ ```
484
+
485
+ AVITI is a four-channel avidity platform, so color-balance validation applies
486
+ to it too (flagging low-diversity index cycles). Manifest columns
487
+ (`SampleName`, `Index1`, `Index2`, `Lane`, `Project`, `ExternalID`) are mapped
488
+ to the shared sample schema, so the validator, diff, and filter tooling work
489
+ across vendors without special-casing.
490
+
400
491
  ---
401
492
 
402
493
  ## Merger conflict and warning codes
@@ -2,7 +2,7 @@
2
2
 
3
3
  **Format-agnostic parser for Illumina SampleSheet.csv files.**
4
4
 
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.
5
+ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — plus non-Illumina **Element AVITI** run manifests — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, 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
8
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -18,15 +18,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
18
18
 
19
19
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
20
20
 
21
- *`SampleSheetFactory` auto-detects the format and routes to the correct parser. Both formats share a common interface — `SampleSheetConverter` handles bidirectional conversion, `SampleSheetValidator` catches index and adapter issues, `SampleSheetDiff` compares two sheets across any combination of V1/V2 formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
21
+ *`SampleSheetFactory` auto-detects the format — Illumina V1/V2 or an Element AVITI run manifest — and routes to the correct parser. All formats share a common interface — `SampleSheetConverter` handles bidirectional conversion between the Illumina formats, `SampleSheetValidator` catches index, adapter, and color-balance issues, `SampleSheetDiff` compares two sheets across any combination of formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
22
22
 
23
23
  ---
24
24
 
25
25
  ## The problem this solves
26
26
 
27
- Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce two incompatible SampleSheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section.
27
+ Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
28
28
 
29
- Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for both, converts between formats, validates index integrity (including Hamming distance), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
29
+ Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
30
30
 
31
31
  ---
32
32
 
@@ -54,7 +54,7 @@ from samplesheet_parser import SampleSheetFactory
54
54
  factory = SampleSheetFactory()
55
55
  sheet = factory.create_parser("SampleSheet.csv", parse=True)
56
56
 
57
- print(factory.version) # SampleSheetVersion.V1 or .V2
57
+ print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
58
58
  print(sheet.index_type()) # "dual", "single", or "none"
59
59
 
60
60
  for sample in sheet.samples():
@@ -312,6 +312,8 @@ The detector reads only as much of the file as needed — stopping after `[Heade
312
312
  | `INDEX_DISTANCE_TOO_LOW` | warning | Two indexes in the same lane have Hamming distance < 3, risking demultiplexing bleed-through |
313
313
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
314
314
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
315
+ | `COLOR_BALANCE_NO_SIGNAL` | error | An index cycle has no signal in an optical channel (2-/1-channel chemistry) — the index read will fail. *Opt-in.* |
316
+ | `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) — degraded base calls. *Opt-in.* |
315
317
 
316
318
  ### Index distance checking
317
319
 
@@ -341,6 +343,95 @@ result = ValidationResult()
341
343
  SampleSheetValidator()._check_index_distances(samples, result, min_distance=4)
342
344
  ```
343
345
 
346
+ ### Color-balance checking (opt-in)
347
+
348
+ On 2-channel instruments (NextSeq, NovaSeq, NovaSeq X) and 1-channel
349
+ instruments (iSeq), bases are called from optical signal: `A` lights
350
+ both channels, `C` only red, `T` only green, and **`G` is a dark base with no
351
+ signal at all**. A cycle where the whole index pool reads `G` produces no
352
+ signal, so the instrument cannot register the tile and the index read fails —
353
+ a real, common cause of wrecked runs that a Hamming-distance check cannot see.
354
+
355
+ Because the sample sheet already contains every sample's index, this can be
356
+ predicted *before the run starts* with no sequencing data. The validator scores
357
+ the pool cycle-by-cycle: it transposes the indexes into columns and checks that
358
+ each column produces signal in both channels.
359
+
360
+ ```python
361
+ from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
362
+
363
+ sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=True)
364
+
365
+ # Opt in; the instrument is read from the sheet header (or pass instrument=...)
366
+ result = SampleSheetValidator().validate(sheet, check_color_balance=True)
367
+
368
+ for err in result.errors:
369
+ print(err)
370
+ # [ERROR] COLOR_BALANCE_NO_SIGNAL: On 2-channel chemistry (NovaSeqXSeries),
371
+ # index1 cycle 4 has no red or green signal across the pool: no sample
372
+ # carries a red or green base (A/C/T) at this cycle ... the index read will fail.
373
+ ```
374
+
375
+ The chemistry is resolved from the instrument name; the check is **off by
376
+ default** (it can legitimately fail a low-plex pool) and is skipped silently
377
+ for unknown instruments. The same analysis is available standalone:
378
+
379
+ ```python
380
+ from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
381
+
382
+ chem = chemistry_for_instrument("NovaSeqXSeries") # Chemistry.TWO_CHANNEL
383
+ report = analyze_color_balance(["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"],
384
+ chemistry=chem)
385
+ for cb in report.dark_cycles:
386
+ print(cb.read, cb.cycle, cb.base_counts) # index1 4 {'G': 4}
387
+ ```
388
+
389
+ From the CLI:
390
+
391
+ ```bash
392
+ samplesheet validate SampleSheet.csv --color-balance
393
+ samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
394
+ ```
395
+
396
+ | Chemistry | Instruments | What is flagged |
397
+ |---|---|---|
398
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000, Element AVITI | Zero-diversity cycles (warning) |
399
+ | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | Dark cycles / weak channels |
400
+ | 1-channel | iSeq 100 | Dark cycles / weak channels |
401
+
402
+ Element AVITI uses four-channel avidity chemistry (four images per cycle, one
403
+ per avidite dye — [Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7)),
404
+ so it has no dark base; color-balance checking flags low-diversity index
405
+ cycles rather than dark cycles.
406
+
407
+ ---
408
+
409
+ ## Multi-vendor support
410
+
411
+ The factory is not limited to Illumina. Any parser that implements the
412
+ `SampleSheetParser` protocol can be auto-detected, and **Element Biosciences
413
+ AVITI `RunManifest.csv`** files are supported out of the box — the same
414
+ `SampleSheetFactory` recognises them and returns a parser with the identical
415
+ interface:
416
+
417
+ ```python
418
+ from samplesheet_parser import SampleSheetFactory
419
+
420
+ factory = SampleSheetFactory()
421
+ sheet = factory.create_parser("RunManifest.csv", parse=True)
422
+
423
+ print(factory.version) # SampleSheetVersion.ELEMENT_AVITI
424
+ print(sheet.index_type()) # "dual"
425
+ for s in sheet.samples(): # same schema as Illumina: sample_id, index, index2, ...
426
+ print(s["sample_id"], s["index"], s["index2"])
427
+ ```
428
+
429
+ AVITI is a four-channel avidity platform, so color-balance validation applies
430
+ to it too (flagging low-diversity index cycles). Manifest columns
431
+ (`SampleName`, `Index1`, `Index2`, `Lane`, `Project`, `ExternalID`) are mapped
432
+ to the shared sample schema, so the validator, diff, and filter tooling work
433
+ across vendors without special-casing.
434
+
344
435
  ---
345
436
 
346
437
  ## Merger conflict and warning codes
@@ -21,7 +21,7 @@ from samplesheet_parser import SampleSheetFactory
21
21
  factory = SampleSheetFactory()
22
22
  sheet = factory.create_parser("SampleSheet.csv", parse=True)
23
23
 
24
- print(factory.version) # SampleSheetVersion.V1 or .V2
24
+ print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
25
25
  print(sheet.index_type()) # "dual", "single", or "none"
26
26
  print(sheet.experiment_name)
27
27
 
@@ -52,6 +52,34 @@ for err in result.errors:
52
52
  result = SampleSheetValidator().validate(sheet, min_hamming_distance=4)
53
53
  ```
54
54
 
55
+ See `examples/demo_color_balance.py` for the opt-in per-cycle color-balance
56
+ check (`validate(..., check_color_balance=True)`).
57
+
58
+ ---
59
+
60
+ ## Multi-vendor (Element AVITI)
61
+
62
+ The same factory that detects Illumina V1/V2 sheets also auto-detects a
63
+ non-Illumina Element AVITI `RunManifest.csv` and returns a parser with the
64
+ identical interface. Demo: `examples/demo_element_aviti.py`.
65
+
66
+ ```python
67
+ from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
68
+
69
+ sheet = SampleSheetFactory().create_parser(
70
+ "examples/sample_sheets/element_aviti_RunManifest.csv", parse=True
71
+ )
72
+
73
+ print(sheet.index_type()) # "dual"
74
+ for s in sheet.samples():
75
+ print(s["sample_id"], s["index"], s["index2"])
76
+
77
+ # Color balance works here too — AVITI resolves to four-channel chemistry,
78
+ # so zero-diversity cycles surface as COLOR_BALANCE_LOW warnings.
79
+ result = SampleSheetValidator().validate(sheet, check_color_balance=True)
80
+ print(result.summary())
81
+ ```
82
+
55
83
  ---
56
84
 
57
85
  ## Conversion
@@ -2,13 +2,14 @@
2
2
 
3
3
  ## Format auto-detection
4
4
 
5
- `SampleSheetFactory` uses a three-step detection strategy — no format hints required from the caller:
5
+ `SampleSheetFactory` detects the format across vendors — no format hints required from the caller:
6
6
 
7
- 1. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
8
- 2. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
9
- 3. **Default** — fall back to V1 (broadest compatibility with legacy files)
7
+ 1. **Vendor manifest check** — recognize a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
8
+ 2. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
9
+ 3. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
10
+ 4. **Default** — fall back to V1 (broadest compatibility with legacy files)
10
11
 
11
- The detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
12
+ The detector reads only as much of the file as needed — stopping after `[Header]` in the common case for Illumina sheets.
12
13
 
13
14
  ```python
14
15
  from samplesheet_parser import SampleSheetFactory
@@ -16,7 +17,7 @@ from samplesheet_parser import SampleSheetFactory
16
17
  factory = SampleSheetFactory()
17
18
  sheet = factory.create_parser("SampleSheet.csv", parse=True)
18
19
 
19
- print(factory.version) # SampleSheetVersion.V1 or .V2
20
+ print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
20
21
  ```
21
22
 
22
23
  ## V1 parser
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Auto-detect format (recommended)
4
4
 
5
- The simplest entry point. `SampleSheetFactory` detects V1 vs V2 automatically using a three-step strategy and returns the correct parser.
5
+ The simplest entry point. `SampleSheetFactory` detects the format automatically — Illumina V1, V2, or an Element AVITI run manifest — and returns the correct parser.
6
6
 
7
7
  ```python
8
8
  from samplesheet_parser import SampleSheetFactory
@@ -10,7 +10,7 @@ from samplesheet_parser import SampleSheetFactory
10
10
  factory = SampleSheetFactory()
11
11
  sheet = factory.create_parser("SampleSheet.csv", parse=True)
12
12
 
13
- print(factory.version) # SampleSheetVersion.V1 or .V2
13
+ print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
14
14
  print(sheet.index_type()) # "dual", "single", or "none"
15
15
 
16
16
  for sample in sheet.samples():
@@ -31,6 +31,10 @@ for w in result.warnings:
31
31
  | `INDEX_DISTANCE_TOO_LOW` | warning | Hamming distance between two indexes < threshold |
32
32
  | `NO_ADAPTERS` | warning | No adapter sequences configured |
33
33
  | `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
34
+ | `COLOR_BALANCE_NO_SIGNAL` | error | A 2-/1-channel index cycle produces no optical signal (opt-in) |
35
+ | `COLOR_BALANCE_LOW` | warning | An index cycle has weak channel signal or zero diversity (opt-in) |
36
+
37
+ The last two checks are **opt-in** — see [Color-balance checking](#color-balance-checking) below.
34
38
 
35
39
  ## Index distance checking
36
40
 
@@ -50,6 +54,32 @@ result = SampleSheetValidator().validate(sheet, min_hamming_distance=4)
50
54
 
51
55
  The standalone helpers are also available: `hamming_distance(a, b)` for the literal Hamming distance and `index_collision_distance(a, b)` for the wildcard-aware per-index distance the validator uses.
52
56
 
57
+ ## Color-balance checking
58
+
59
+ Optical sequencers read each index base by its fluorescent signal, and the number of channels differs by instrument: four-channel (MiSeq, HiSeq, Element AVITI), two-channel (NextSeq, NovaSeq 6000, NovaSeq X), and one-channel (iSeq). On two-channel chemistry the base `G` is "dark" — no dye — so an index cycle where the **entire pool** reads `G` emits no signal and the cycle fails to register, miscalling every barcode at that position. A Hamming-distance check cannot catch this because the indexes may still be perfectly distinct.
60
+
61
+ `samplesheet-parser` models each instrument's chemistry and scores the pool cycle-by-cycle. The check is **opt-in** because it can turn a passing sheet into a failing one, and it needs to know the instrument:
62
+
63
+ ```python
64
+ result = SampleSheetValidator().validate(
65
+ sheet,
66
+ check_color_balance=True,
67
+ instrument="NovaSeq X", # optional; inferred from the sheet header when present
68
+ )
69
+ ```
70
+
71
+ - On **two-/one-channel** instruments, an all-`G` (no-signal) cycle is a `COLOR_BALANCE_NO_SIGNAL` error and a channel below `min_signal_fraction` (default 0.10) is a `COLOR_BALANCE_LOW` warning.
72
+ - On **four-channel** instruments (including Element AVITI, an avidity platform with no dark base), there is no no-signal failure mode; a zero-diversity cycle — where the whole pool reads one base — is reported as a `COLOR_BALANCE_LOW` warning instead.
73
+ - If the instrument is unknown, the check is skipped silently.
74
+
75
+ The CLI exposes the same check:
76
+
77
+ ```bash
78
+ samplesheet validate SampleSheet.csv --color-balance --instrument "NovaSeq X"
79
+ ```
80
+
81
+ The underlying API — `Chemistry`, `chemistry_for_instrument()`, and `analyze_color_balance()` returning a `ColorBalanceReport` — is public and usable on its own.
82
+
53
83
  ## Structured results
54
84
 
55
85
  ```python
@@ -1,8 +1,8 @@
1
1
  # samplesheet-parser
2
2
 
3
- **Format-agnostic parser for Illumina SampleSheet.csv files.**
3
+ **Multi-vendor, format-agnostic parser for sequencing sample sheets.**
4
4
 
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.
5
+ Supports the classic Illumina IEM V1 format (bcl2fastq era), the modern BCLConvert V2 format (NovaSeq X series), and non-Illumina **Element AVITI** run manifests behind one interface — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, 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
8
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -17,9 +17,9 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
17
17
 
18
18
  ## The problem this solves
19
19
 
20
- Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce two incompatible SampleSheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section.
20
+ Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
21
21
 
22
- Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for both, converts between formats, validates index integrity (including Hamming distance), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
22
+ Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
23
23
 
24
24
  ---
25
25
 
@@ -27,10 +27,12 @@ Existing tools either hard-code one format or require the caller to know which f
27
27
 
28
28
  | Feature | Description |
29
29
  |---|---|
30
- | **Auto-detection** | Three-step format detection — no hints required |
31
- | **V1 & V2 parsing** | Consistent `samples()` / `index_type()` interface for both formats |
30
+ | **Auto-detection** | Format detection across vendors — no hints required |
31
+ | **V1, V2 & AVITI parsing** | Consistent `samples()` / `index_type()` interface for Illumina V1/V2 and Element AVITI run manifests |
32
+ | **Multi-vendor** | Element Biosciences AVITI `RunManifest.csv` parsed through the same `SampleSheetParser` protocol |
32
33
  | **Bidirectional conversion** | V1 → V2 and V2 → V1 (lossy, with warnings) |
33
- | **Validation** | 9 checks covering index chars, length, duplicates, Hamming distance, adapters |
34
+ | **Validation** | Index chars, length, duplicates, Hamming distance, adapters |
35
+ | **Color balance** | Opt-in per-cycle optical-signal check against 4-/2-/1-channel instrument chemistry |
34
36
  | **Diff** | Cross-format structural comparison with per-field change records |
35
37
  | **Merge** | Combine multiple per-project sheets with collision detection |
36
38
  | **Split** | Divide a combined sheet into per-project or per-lane files |
@@ -0,0 +1,85 @@
1
+ """
2
+ Demo: colour-balance validation on a 2-channel instrument.
3
+
4
+ Colour balance is a property of the *index sequences* in the sheet, so it can
5
+ be predicted before a run starts - no sequencing data required. On 2-channel
6
+ chemistry (NextSeq, NovaSeq, AVITI) ``G`` is a dark base: a cycle where every
7
+ sample reads ``G`` produces no optical signal and the index read fails.
8
+
9
+ This builds a small NovaSeq X pool that is fine on Hamming distance but has a
10
+ dark cycle, and shows the validator catching it.
11
+
12
+ Run with: python3 examples/demo_color_balance.py
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import tempfile
18
+ from pathlib import Path
19
+
20
+ from samplesheet_parser import (
21
+ SampleSheetFactory,
22
+ SampleSheetValidator,
23
+ analyze_color_balance,
24
+ chemistry_for_instrument,
25
+ )
26
+
27
+ # A NovaSeq X (2-channel) pool. Look down each column of the I7 index:
28
+ # every sample reads 'G' at cycle 3 and cycle 4 -> a dark, no-signal cycle.
29
+ # The indexes are still far apart in Hamming distance, so the usual index
30
+ # checks would pass this sheet.
31
+ SHEET = """\
32
+ [Header]
33
+ FileFormatVersion,2
34
+ RunName,DarkCycleDemo
35
+ InstrumentPlatform,NovaSeqXSeries
36
+
37
+ [Reads]
38
+ Read1Cycles,151
39
+ Read2Cycles,151
40
+ Index1Cycles,8
41
+ Index2Cycles,8
42
+
43
+ [BCLConvert_Settings]
44
+ AdapterRead1,CTGTCTCTTATACACATCT
45
+
46
+ [BCLConvert_Data]
47
+ Sample_ID,Index,Index2
48
+ S1,ATGGCTAC,TATAGCCT
49
+ S2,CAGGTACG,ATAGAGGC
50
+ S3,TCGGACGT,CCTATCCT
51
+ S4,GATGGCTA,GGCTCTGA
52
+ """
53
+
54
+
55
+ def main() -> None:
56
+ print("Chemistry for 'NovaSeqXSeries':", chemistry_for_instrument("NovaSeqXSeries").value)
57
+ print()
58
+
59
+ # The standalone analyzer, straight on the index list:
60
+ index1 = ["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"]
61
+ report = analyze_color_balance(index1, chemistry=chemistry_for_instrument("NovaSeqXSeries"))
62
+ print(f"Pool of {report.pool_size} samples - per-cycle scan of I7:")
63
+ for cb in report.cycles:
64
+ flag = " <-- DARK (no signal)" if cb.is_dark else ""
65
+ print(
66
+ f" cycle {cb.cycle}: {cb.base_counts} "
67
+ f"red={cb.red_fraction:.0%} green={cb.green_fraction:.0%}{flag}"
68
+ )
69
+ print()
70
+
71
+ # End to end through the factory + validator:
72
+ with tempfile.TemporaryDirectory() as tmp:
73
+ path = Path(tmp) / "SampleSheet.csv"
74
+ path.write_text(SHEET)
75
+
76
+ sheet = SampleSheetFactory().create_parser(path, parse=True)
77
+ result = SampleSheetValidator().validate(sheet, check_color_balance=True)
78
+
79
+ print(result.summary())
80
+ for issue in result.errors + result.warnings:
81
+ print(f" {issue}")
82
+
83
+
84
+ if __name__ == "__main__":
85
+ main()