samplesheet-parser 2.3.0__tar.gz → 2.4.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 (155) hide show
  1. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/.gitignore +6 -0
  2. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/.zenodo.json +1 -1
  3. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/CHANGELOG.md +30 -0
  4. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/CITATION.cff +2 -2
  5. samplesheet_parser-2.4.0/CODE_OF_CONDUCT.md +128 -0
  6. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/PKG-INFO +46 -26
  7. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/README.md +44 -24
  8. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/api.md +100 -5
  9. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/cli.md +4 -0
  10. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/validation.md +16 -6
  11. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/index.md +1 -1
  12. samplesheet_parser-2.4.0/eval/FINDINGS.md +194 -0
  13. samplesheet_parser-2.4.0/eval/README.md +130 -0
  14. samplesheet_parser-2.4.0/eval/__init__.py +8 -0
  15. samplesheet_parser-2.4.0/eval/generate_corpus.py +580 -0
  16. samplesheet_parser-2.4.0/eval/reference_rules.py +233 -0
  17. samplesheet_parser-2.4.0/eval/run_eval.py +533 -0
  18. samplesheet_parser-2.4.0/images/samplesheet_parser_arch_v2.3.png +0 -0
  19. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/mkdocs.yml +1 -1
  20. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/convert/meta.yml +1 -1
  21. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/diff/meta.yml +1 -1
  22. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/filter/meta.yml +1 -1
  23. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/info/meta.yml +1 -1
  24. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/merge/meta.yml +1 -1
  25. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/split/meta.yml +1 -1
  26. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/validate/meta.yml +1 -1
  27. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/pyproject.toml +2 -2
  28. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/__init__.py +2 -0
  29. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/chemistry.py +195 -63
  30. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/validators.py +106 -54
  31. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_chemistry.py +75 -13
  32. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_cli.py +0 -9
  33. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_converter.py +0 -5
  34. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_diff.py +0 -1
  35. samplesheet_parser-2.4.0/tests/test_eval.py +200 -0
  36. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_factory.py +1 -5
  37. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_index_utils.py +2 -7
  38. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_instruments.py +0 -3
  39. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_merger.py +0 -18
  40. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_parsers/test_v1.py +2 -9
  41. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_parsers/test_v2.py +2 -10
  42. samplesheet_parser-2.4.0/tests/test_reference_rules.py +136 -0
  43. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_validators/test_validators.py +53 -4
  44. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_writer.py +0 -5
  45. samplesheet_parser-2.3.0/recipes/meta.yaml +0 -56
  46. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/.github/workflows/ci.yml +0 -0
  47. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/.github/workflows/copilot-instructions.md +0 -0
  48. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/.pre-commit-config.yaml +0 -0
  49. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/.readthedocs.yaml +0 -0
  50. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/CONTRIBUTING.md +0 -0
  51. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/LICENSE +0 -0
  52. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/Makefile +0 -0
  53. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/changelog.md +0 -0
  54. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/ci.md +0 -0
  55. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/contributing.md +0 -0
  56. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/examples.md +0 -0
  57. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/conversion.md +0 -0
  58. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/diffing.md +0 -0
  59. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/filtering.md +0 -0
  60. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/index_utils.md +0 -0
  61. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/merging.md +0 -0
  62. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/parsing.md +0 -0
  63. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/quickstart.md +0 -0
  64. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/splitting.md +0 -0
  65. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/guide/writing.md +0 -0
  66. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/installation.md +0 -0
  67. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/docs/requirements.txt +0 -0
  68. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_color_balance.py +0 -0
  69. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_converter.py +0 -0
  70. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_diff.py +0 -0
  71. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_element_aviti.py +0 -0
  72. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_filter.py +0 -0
  73. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_index_utils.py +0 -0
  74. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_merger.py +0 -0
  75. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_splitter.py +0 -0
  76. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/demo_writer.py +0 -0
  77. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/parse_examples.py +0 -0
  78. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  79. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  80. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  81. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  82. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/README.md +0 -0
  83. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/combined_clean.csv +0 -0
  84. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  85. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  86. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/element_aviti_RunManifest.csv +0 -0
  87. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  88. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  89. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  90. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  91. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  92. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  93. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  94. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  95. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  96. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  97. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  98. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/images/samplesheet_parser_arch_v03.png +0 -0
  99. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/images/samplesheet_parser_overview.png +0 -0
  100. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/convert/environment.yml +0 -0
  101. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/convert/main.nf +0 -0
  102. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +0 -0
  103. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/diff/environment.yml +0 -0
  104. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/diff/main.nf +0 -0
  105. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +0 -0
  106. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +0 -0
  107. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/filter/environment.yml +0 -0
  108. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/filter/main.nf +0 -0
  109. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +0 -0
  110. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
  111. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/info/environment.yml +0 -0
  112. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/info/main.nf +0 -0
  113. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +0 -0
  114. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +0 -0
  115. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/merge/environment.yml +0 -0
  116. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/merge/main.nf +0 -0
  117. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +0 -0
  118. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/split/environment.yml +0 -0
  119. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/split/main.nf +0 -0
  120. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +0 -0
  121. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/validate/environment.yml +0 -0
  122. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/validate/main.nf +0 -0
  123. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +0 -0
  124. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +0 -0
  125. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/cli.py +0 -0
  126. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/converter.py +0 -0
  127. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/diff.py +0 -0
  128. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/enums.py +0 -0
  129. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/factory.py +0 -0
  130. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/filter.py +0 -0
  131. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/index_utils.py +0 -0
  132. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/instruments.py +0 -0
  133. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/merger.py +0 -0
  134. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/parsers/__init__.py +0 -0
  135. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/parsers/element.py +0 -0
  136. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/parsers/v1.py +0 -0
  137. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/parsers/v2.py +0 -0
  138. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/protocol.py +0 -0
  139. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/py.typed +0 -0
  140. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/splitter.py +0 -0
  141. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/samplesheet_parser/writer.py +0 -0
  142. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/scripts/demo_converter.py +0 -0
  143. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/scripts/demo_diff.py +0 -0
  144. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/scripts/demo_writer.py +0 -0
  145. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/__init__.py +0 -0
  146. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/conftest.py +0 -0
  147. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  148. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  149. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  150. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_filter.py +0 -0
  151. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_parsers/__init__.py +0 -0
  152. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_parsers/test_element.py +0 -0
  153. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_splitter.py +0 -0
  154. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_validators/__init__.py +0 -0
  155. {samplesheet_parser-2.3.0 → samplesheet_parser-2.4.0}/tests/test_validators/test_hamming.py +0 -0
@@ -4,6 +4,12 @@ tests/fixtures/outputs/
4
4
  demo_output.txt
5
5
  **/CSBJ Submission/
6
6
  **/.claude/
7
+ eval/results/
8
+ corpus/**
9
+ paper.md
10
+ paper.bib
11
+ images/gen_arch_excalidraw.py
12
+ images/samplesheet_parser_arch_v2.3.excalidraw
7
13
 
8
14
  # Cache and build artifacts
9
15
  __pycache__/
@@ -4,7 +4,7 @@
4
4
  "upload_type": "software",
5
5
  "access_right": "open",
6
6
  "license": "Apache-2.0",
7
- "version": "2.3.0",
7
+ "version": "2.4.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -10,6 +10,36 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
10
10
 
11
11
  _No unreleased changes._
12
12
 
13
+ ## [2.4.0] - 2026-06-21
14
+
15
+ ### Changed (behavioral)
16
+
17
+ - **Color-balance checking now has two modes: `vendor_faithful` (new default)
18
+ and `conservative`.** `vendor_faithful` encodes each platform's published
19
+ rule exactly; `conservative` is the previous, stricter behavior (single-channel
20
+ 2-channel cycles and AVITI low-diversity treated as failures). Selectable via
21
+ `analyze_color_balance(..., mode=...)` and `SampleSheetValidator.validate(...,
22
+ color_balance_mode=...)`. **Callers relying on the old stricter results should
23
+ pass `color_balance_mode="conservative"`.**
24
+ - **Fixed a 4-channel color-balance bug (both modes):** Illumina four-channel
25
+ cycles are now failed when either laser group is absent (green `{G,T}` / red
26
+ `{A,C}`), e.g. an all-`G` or `G/T`-only cycle (red laser dark). Previously only
27
+ zero-diversity cycles were flagged.
28
+ - **Element AVITI is now modelled as its own `Chemistry.AVIDITY`** (per-base dye,
29
+ no laser-pair constraint), distinct from Illumina `FOUR_CHANNEL`;
30
+ `chemistry_for_instrument("AVITI")` now returns `Chemistry.AVIDITY`. AVITI low
31
+ diversity is an advisory (`COLOR_BALANCE_ADVISORY`), never a failure, in
32
+ `vendor_faithful` mode.
33
+
34
+ ### Documentation
35
+
36
+ - Refreshed stale docs after the multi-vendor / color-balance release: updated
37
+ the README tagline, format-detection steps (now vendor-aware), and citation
38
+ block (DOI); documented the `chemistry` module, `ElementRunManifest`,
39
+ the `SampleSheetVersion.ELEMENT_AVITI` enum, the `validate(...)`
40
+ color-balance parameters, and the `--color-balance` / `--instrument` CLI flags
41
+ in the API and CLI references.
42
+
13
43
  ## [2.3.0] - 2026-06-15
14
44
 
15
45
  ### Added
@@ -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.3.0
12
- date-released: 2026-06-15
11
+ version: 2.4.0
12
+ date-released: 2026-06-21
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,128 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and leaders pledge to make participation in our
6
+ community a harassment-free experience for everyone, regardless of age, body
7
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
8
+ identity and expression, level of experience, education, socio-economic status,
9
+ nationality, personal appearance, race, religion, or sexual identity
10
+ and orientation.
11
+
12
+ We pledge to act and interact in ways that contribute to an open, welcoming,
13
+ diverse, inclusive, and healthy community.
14
+
15
+ ## Our Standards
16
+
17
+ Examples of behavior that contributes to a positive environment for our
18
+ community include:
19
+
20
+ * Demonstrating empathy and kindness toward other people
21
+ * Being respectful of differing opinions, viewpoints, and experiences
22
+ * Giving and gracefully accepting constructive feedback
23
+ * Accepting responsibility and apologizing to those affected by our mistakes,
24
+ and learning from the experience
25
+ * Focusing on what is best not just for us as individuals, but for the
26
+ overall community
27
+
28
+ Examples of unacceptable behavior include:
29
+
30
+ * The use of sexualized language or imagery, and sexual attention or
31
+ advances of any kind
32
+ * Trolling, insulting or derogatory comments, and personal or political attacks
33
+ * Public or private harassment
34
+ * Publishing others' private information, such as a physical or email
35
+ address, without their explicit permission
36
+ * Other conduct which could reasonably be considered inappropriate in a
37
+ professional setting
38
+
39
+ ## Enforcement Responsibilities
40
+
41
+ Community leaders are responsible for clarifying and enforcing our standards of
42
+ acceptable behavior and will take appropriate and fair corrective action in
43
+ response to any behavior that they deem inappropriate, threatening, offensive,
44
+ or harmful.
45
+
46
+ Community leaders have the right and responsibility to remove, edit, or reject
47
+ comments, commits, code, wiki edits, issues, and other contributions that are
48
+ not aligned to this Code of Conduct, and will communicate reasons for moderation
49
+ decisions when appropriate.
50
+
51
+ ## Scope
52
+
53
+ This Code of Conduct applies within all community spaces, and also applies when
54
+ an individual is officially representing the community in public spaces.
55
+ Examples of representing our community include using an official e-mail address,
56
+ posting via an official social media account, or acting as an appointed
57
+ representative at an online or offline event.
58
+
59
+ ## Enforcement
60
+
61
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
62
+ reported to the community leaders responsible for enforcement at
63
+ contact.ckasaraneni@gmail.com.
64
+ All complaints will be reviewed and investigated promptly and fairly.
65
+
66
+ All community leaders are obligated to respect the privacy and security of the
67
+ reporter of any incident.
68
+
69
+ ## Enforcement Guidelines
70
+
71
+ Community leaders will follow these Community Impact Guidelines in determining
72
+ the consequences for any action they deem in violation of this Code of Conduct:
73
+
74
+ ### 1. Correction
75
+
76
+ **Community Impact**: Use of inappropriate language or other behavior deemed
77
+ unprofessional or unwelcome in the community.
78
+
79
+ **Consequence**: A private, written warning from community leaders, providing
80
+ clarity around the nature of the violation and an explanation of why the
81
+ behavior was inappropriate. A public apology may be requested.
82
+
83
+ ### 2. Warning
84
+
85
+ **Community Impact**: A violation through a single incident or series
86
+ of actions.
87
+
88
+ **Consequence**: A warning with consequences for continued behavior. No
89
+ interaction with the people involved, including unsolicited interaction with
90
+ those enforcing the Code of Conduct, for a specified period of time. This
91
+ includes avoiding interactions in community spaces as well as external channels
92
+ like social media. Violating these terms may lead to a temporary or
93
+ permanent ban.
94
+
95
+ ### 3. Temporary Ban
96
+
97
+ **Community Impact**: A serious violation of community standards, including
98
+ sustained inappropriate behavior.
99
+
100
+ **Consequence**: A temporary ban from any sort of interaction or public
101
+ communication with the community for a specified period of time. No public or
102
+ private interaction with the people involved, including unsolicited interaction
103
+ with those enforcing the Code of Conduct, is allowed during this period.
104
+ Violating these terms may lead to a permanent ban.
105
+
106
+ ### 4. Permanent Ban
107
+
108
+ **Community Impact**: Demonstrating a pattern of violation of community
109
+ standards, including sustained inappropriate behavior, harassment of an
110
+ individual, or aggression toward or disparagement of classes of individuals.
111
+
112
+ **Consequence**: A permanent ban from any sort of public interaction within
113
+ the community.
114
+
115
+ ## Attribution
116
+
117
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118
+ version 2.0, available at
119
+ https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120
+
121
+ Community Impact Guidelines were inspired by [Mozilla's code of conduct
122
+ enforcement ladder](https://github.com/mozilla/diversity).
123
+
124
+ [homepage]: https://www.contributor-covenant.org
125
+
126
+ For answers to common questions about this code of conduct, see the FAQ at
127
+ https://www.contributor-covenant.org/faq. Translations are available at
128
+ https://www.contributor-covenant.org/translations.
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 2.3.0
3
+ Version: 2.4.0
4
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
- Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
6
+ Project-URL: Documentation, https://samplesheet-parser.readthedocs.io
7
7
  Project-URL: Repository, https://github.com/chaitanyakasaraneni/samplesheet-parser
8
8
  Project-URL: Issues, https://github.com/chaitanyakasaraneni/samplesheet-parser/issues
9
9
  Author-email: Chaitanya Kasaraneni <kc.kasaraneni@gmail.com>
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
56
56
 
57
57
  # samplesheet-parser
58
58
 
59
- **Format-agnostic parser for Illumina SampleSheet.csv files.**
59
+ **Multi-vendor, format-agnostic parser for sequencing sample sheets.**
60
60
 
61
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
 
@@ -67,12 +67,12 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
67
67
 
68
68
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
69
69
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
70
- [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
70
+ [![Docs](https://readthedocs.org/projects/samplesheet-parser/badge/)](https://samplesheet-parser.readthedocs.io)
71
71
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
72
72
 
73
- **Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
73
+ **Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
74
74
 
75
- ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
75
+ ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v2.3.png)
76
76
 
77
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
 
@@ -345,13 +345,14 @@ samplesheet merge ProjectA.csv ProjectB.csv --output combined.csv --format json
345
345
 
346
346
  ## Format detection logic
347
347
 
348
- The factory uses a three-step detection strategy — no format hints required from the caller:
348
+ The factory detects the format across vendors — no format hints required from the caller:
349
349
 
350
- 1. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
351
- 2. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
352
- 3. **Default** — fall back to V1 (broadest compatibility with legacy files)
350
+ 1. **Vendor manifest check** — recognise a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
351
+ 2. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
352
+ 3. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
353
+ 4. **Default** — fall back to V1 (broadest compatibility with legacy files)
353
354
 
354
- The detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
355
+ For Illumina sheets the detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
355
356
 
356
357
  ---
357
358
 
@@ -410,8 +411,8 @@ a real, common cause of wrecked runs that a Hamming-distance check cannot see.
410
411
 
411
412
  Because the sample sheet already contains every sample's index, this can be
412
413
  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.
414
+ the pool cycle-by-cycle against the instrument's chemistry, with the exact rule
415
+ depending on the chemistry and the selected mode (see below).
415
416
 
416
417
  ```python
417
418
  from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
@@ -449,16 +450,32 @@ samplesheet validate SampleSheet.csv --color-balance
449
450
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
450
451
  ```
451
452
 
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.
453
+ #### Modes: `vendor_faithful` (default) and `conservative`
454
+
455
+ Color balance has two modes, selectable via
456
+ `validate(..., color_balance_mode=...)` or `analyze_color_balance(..., mode=...)`:
457
+
458
+ - **`vendor_faithful`** (default) encodes each platform's *published* rule
459
+ exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
460
+ the both-lasers rule for 4-channel, and Element's permissive low-diversity
461
+ stance for AVITI.
462
+ - **`conservative`** is stricter than the published minimum: it also fails
463
+ single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
464
+ behavior before modes existed — pass `color_balance_mode="conservative"` to
465
+ keep it.)
466
+
467
+ | Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
468
+ |---|---|---|---|
469
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
470
+ | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
471
+ | 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
472
+ | avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
473
+
474
+ Element AVITI uses avidity chemistry — each base has its own avidite dye
475
+ ([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
476
+ — so it has no dark base and no laser-pair constraint. In `vendor_faithful`
477
+ mode, AVITI low diversity in the first cycles is an advisory
478
+ (`COLOR_BALANCE_ADVISORY`), never a failure.
462
479
 
463
480
  ---
464
481
 
@@ -785,14 +802,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
785
802
 
786
803
  ```bibtex
787
804
  @software{kasaraneni2026samplesheetparser,
788
- author = {Kasaraneni, Chaitanya},
789
- title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
805
+ author = {Kasaraneni, Chaitanya Krishna},
806
+ title = {samplesheet-parser: A multi-vendor parser, validator, and converter for sequencing sample sheets},
790
807
  year = {2026},
791
808
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
792
- version = {1.1.0}
809
+ doi = {10.5281/zenodo.18989694},
810
+ version = {2.4.0}
793
811
  }
794
812
  ```
795
813
 
814
+ See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
815
+
796
816
  ---
797
817
 
798
818
  ## License
@@ -1,6 +1,6 @@
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
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
 
@@ -11,12 +11,12 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
11
11
 
12
12
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
13
13
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
14
- [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
14
+ [![Docs](https://readthedocs.org/projects/samplesheet-parser/badge/)](https://samplesheet-parser.readthedocs.io)
15
15
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](https://doi.org/10.5281/zenodo.18989694)
16
16
 
17
- **Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
17
+ **Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
18
18
 
19
- ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
19
+ ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v2.3.png)
20
20
 
21
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
 
@@ -289,13 +289,14 @@ samplesheet merge ProjectA.csv ProjectB.csv --output combined.csv --format json
289
289
 
290
290
  ## Format detection logic
291
291
 
292
- The factory uses a three-step detection strategy — no format hints required from the caller:
292
+ The factory detects the format across vendors — no format hints required from the caller:
293
293
 
294
- 1. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
295
- 2. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
296
- 3. **Default** — fall back to V1 (broadest compatibility with legacy files)
294
+ 1. **Vendor manifest check** — recognise a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
295
+ 2. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
296
+ 3. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
297
+ 4. **Default** — fall back to V1 (broadest compatibility with legacy files)
297
298
 
298
- The detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
299
+ For Illumina sheets the detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
299
300
 
300
301
  ---
301
302
 
@@ -354,8 +355,8 @@ a real, common cause of wrecked runs that a Hamming-distance check cannot see.
354
355
 
355
356
  Because the sample sheet already contains every sample's index, this can be
356
357
  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.
358
+ the pool cycle-by-cycle against the instrument's chemistry, with the exact rule
359
+ depending on the chemistry and the selected mode (see below).
359
360
 
360
361
  ```python
361
362
  from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
@@ -393,16 +394,32 @@ samplesheet validate SampleSheet.csv --color-balance
393
394
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
394
395
  ```
395
396
 
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.
397
+ #### Modes: `vendor_faithful` (default) and `conservative`
398
+
399
+ Color balance has two modes, selectable via
400
+ `validate(..., color_balance_mode=...)` or `analyze_color_balance(..., mode=...)`:
401
+
402
+ - **`vendor_faithful`** (default) encodes each platform's *published* rule
403
+ exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
404
+ the both-lasers rule for 4-channel, and Element's permissive low-diversity
405
+ stance for AVITI.
406
+ - **`conservative`** is stricter than the published minimum: it also fails
407
+ single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
408
+ behavior before modes existed — pass `color_balance_mode="conservative"` to
409
+ keep it.)
410
+
411
+ | Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
412
+ |---|---|---|---|
413
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
414
+ | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
415
+ | 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
416
+ | avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
417
+
418
+ Element AVITI uses avidity chemistry — each base has its own avidite dye
419
+ ([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
420
+ — so it has no dark base and no laser-pair constraint. In `vendor_faithful`
421
+ mode, AVITI low diversity in the first cycles is an advisory
422
+ (`COLOR_BALANCE_ADVISORY`), never a failure.
406
423
 
407
424
  ---
408
425
 
@@ -729,14 +746,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
729
746
 
730
747
  ```bibtex
731
748
  @software{kasaraneni2026samplesheetparser,
732
- author = {Kasaraneni, Chaitanya},
733
- title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
749
+ author = {Kasaraneni, Chaitanya Krishna},
750
+ title = {samplesheet-parser: A multi-vendor parser, validator, and converter for sequencing sample sheets},
734
751
  year = {2026},
735
752
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
736
- version = {1.1.0}
753
+ doi = {10.5281/zenodo.18989694},
754
+ version = {2.4.0}
737
755
  }
738
756
  ```
739
757
 
758
+ See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
759
+
740
760
  ---
741
761
 
742
762
  ## License
@@ -15,6 +15,12 @@ from samplesheet_parser import (
15
15
  SampleSheetMerger,
16
16
  SampleSheetSplitter,
17
17
  SampleSheetFilter,
18
+ ElementRunManifest,
19
+ Chemistry,
20
+ ColorBalanceMode,
21
+ chemistry_for_instrument,
22
+ analyze_color_balance,
23
+ ColorBalanceReport,
18
24
  normalize_index_lengths,
19
25
  hamming_distance,
20
26
  )
@@ -36,12 +42,12 @@ from samplesheet_parser import (
36
42
 
37
43
  ## SampleSheetParser Protocol
38
44
 
39
- `SampleSheetParser` is a `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Use it as a type hint wherever either parser is accepted, or implement it in a third-party parser and register it with the factory.
45
+ `SampleSheetParser` is a `runtime_checkable` structural protocol satisfied by `SampleSheetV1`, `SampleSheetV2`, and the non-Illumina `ElementRunManifest`. Use it as a type hint wherever any parser is accepted, or implement it in a third-party parser and register it with the factory.
40
46
 
41
47
  ```python
42
48
  from samplesheet_parser import SampleSheetParser
43
49
 
44
- isinstance(sheet, SampleSheetParser) # True for V1 and V2 instances
50
+ isinstance(sheet, SampleSheetParser) # True for V1, V2, and AVITI instances
45
51
  ```
46
52
 
47
53
  ---
@@ -121,7 +127,16 @@ from samplesheet_parser.instruments import (
121
127
 
122
128
  | Method | Returns | Description |
123
129
  |---|---|---|
124
- | `validate(sheet, *, min_hamming_distance=3)` | `ValidationResult` | Run all checks; returns structured result |
130
+ | `validate(sheet, *, min_hamming_distance=3, check_color_balance=False, instrument=None, color_balance_mode="vendor_faithful", min_signal_fraction=0.1)` | `ValidationResult` | Run all checks; returns structured result |
131
+
132
+ Color-balance checking is **opt-in** via `check_color_balance=True`. The
133
+ instrument is read from the sheet header when present, or supplied with
134
+ `instrument=`; the check is skipped silently for unknown instruments.
135
+ `color_balance_mode` is `"vendor_faithful"` (default) or `"conservative"` (see
136
+ [`ColorBalanceMode`](#samplesheet_parserchemistry)). It emits
137
+ `COLOR_BALANCE_NO_SIGNAL` (error), `COLOR_BALANCE_LOW` (warning), and
138
+ `COLOR_BALANCE_ADVISORY` (warning, AVITI) issues — see
139
+ [Validation → Color-balance checking](guide/validation.md#color-balance-checking).
125
140
 
126
141
  ### ValidationResult
127
142
 
@@ -248,6 +263,85 @@ from samplesheet_parser.instruments import (
248
263
 
249
264
  ---
250
265
 
266
+ ## ElementRunManifest
267
+
268
+ Non-Illumina parser for Element Biosciences AVITI `RunManifest.csv` files. It
269
+ satisfies the `SampleSheetParser` protocol, so it works with the validator,
270
+ diff, splitter, and filter just like the Illumina parsers. The factory
271
+ auto-detects manifests, so you rarely instantiate this directly.
272
+
273
+ ```python
274
+ from samplesheet_parser import ElementRunManifest
275
+
276
+ sheet = ElementRunManifest("RunManifest.csv")
277
+ sheet.parse()
278
+ ```
279
+
280
+ | Method / attribute | Returns | Description |
281
+ |---|---|---|
282
+ | `parse(do_clean=True)` | `None` | Parse `[RUNVALUES]` / `[SETTINGS]` / `[SAMPLES]` sections |
283
+ | `samples()` | `list[dict]` | Manifest rows mapped to the shared schema (`sample_id`, `index`, `index2`, `lane`, `sample_project`) |
284
+ | `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
285
+ | `parse_custom_section(name, *, required=False)` | `dict[str, str]` | Parse any manifest section as key/value pairs |
286
+ | `.adapters` | `list[str]` | Adapter sequences from `[SETTINGS]` |
287
+ | `is_manifest(path)` | `bool` | Static detector used by the factory (`[SAMPLES]` + `[RUNVALUES]`/`SampleName`) |
288
+
289
+ Manifest columns map as `SampleName → sample_id`, `Index1 → index`,
290
+ `Index2 → index2`, `Lane → lane`, `Project → sample_project`; other columns
291
+ (e.g. `ExternalID`) are preserved as passthrough fields.
292
+
293
+ ---
294
+
295
+ ## samplesheet_parser.chemistry
296
+
297
+ Per-cycle color-balance analysis against an instrument's optical detection
298
+ chemistry.
299
+
300
+ ```python
301
+ from samplesheet_parser import (
302
+ Chemistry,
303
+ ColorBalanceMode,
304
+ chemistry_for_instrument,
305
+ analyze_color_balance,
306
+ ColorBalanceReport,
307
+ )
308
+ ```
309
+
310
+ | Name | Kind | Description |
311
+ |---|---|---|
312
+ | `Chemistry` | `str, Enum` | `ONE_CHANNEL` / `TWO_CHANNEL` / `FOUR_CHANNEL` (Illumina two-laser) / `AVIDITY` (Element AVITI) |
313
+ | `ColorBalanceMode` | `str, Enum` | `VENDOR_FAITHFUL` (default, published rule) / `CONSERVATIVE` (stricter) |
314
+ | `chemistry_for_instrument(name)` | `Chemistry \| None` | Resolve an instrument name to its chemistry; `None` if unknown. `"AVITI"` → `AVIDITY` |
315
+ | `analyze_color_balance(index1, index2=None, *, chemistry, mode="vendor_faithful", min_signal_fraction=0.1)` | `ColorBalanceReport` | Score index pools cycle-by-cycle |
316
+
317
+ Rules by chemistry: **2-/1-channel** — all-`G` cycle fails (both modes); a
318
+ single-channel cycle fails only in `conservative` (Illumina's minimum is "at
319
+ least one channel"). **4-channel** — a cycle missing the green `{G,T}` or red
320
+ `{A,C}` laser fails (both modes). **avidity** — low diversity is an advisory in
321
+ `vendor_faithful`, a failure in `conservative`.
322
+
323
+ ### ColorBalanceReport
324
+
325
+ | Attribute / method | Type | Description |
326
+ |---|---|---|
327
+ | `chemistry` | `Chemistry` | Chemistry the pool was scored against |
328
+ | `mode` | `ColorBalanceMode` | Mode the pool was scored under |
329
+ | `pool_size` | `int` | Number of indexes analysed |
330
+ | `cycles` | `list[CycleBalance]` | Per-cycle signal breakdown |
331
+ | `dark_cycles` | `list[CycleBalance]` | Failing cycles (no signal / laser absent / conservative escalations) |
332
+ | `weak_cycles` | `list[CycleBalance]` | Non-failing warnings (single-channel or below-threshold) |
333
+ | `advisory_cycles` | `list[CycleBalance]` | AVITI low-diversity advisories (vendor_faithful) |
334
+ | `is_balanced` | `bool` | `True` when there are no **dark** (failing) cycles |
335
+
336
+ ```python
337
+ chem = chemistry_for_instrument("NovaSeq X") # Chemistry.TWO_CHANNEL
338
+ report = analyze_color_balance(["ATGC", "CAGT", "TCGA", "GATG"], chemistry=chem)
339
+ for cb in report.dark_cycles:
340
+ print(cb.read, cb.cycle, cb.base_counts)
341
+ ```
342
+
343
+ ---
344
+
251
345
  ## normalize_index_lengths
252
346
 
253
347
  ```python
@@ -286,6 +380,7 @@ Used internally by `SampleSheetValidator` when checking index collision threshol
286
380
  ```python
287
381
  from samplesheet_parser.enums import SampleSheetVersion, InstrumentPlatform, UMILocation
288
382
 
289
- SampleSheetVersion.V1 # IEM / bcl2fastq
290
- SampleSheetVersion.V2 # BCLConvert
383
+ SampleSheetVersion.V1 # IEM / bcl2fastq
384
+ SampleSheetVersion.V2 # BCLConvert
385
+ SampleSheetVersion.ELEMENT_AVITI # Element AVITI RunManifest (non-Illumina)
291
386
  ```
@@ -79,6 +79,8 @@ Validate a sheet for index, adapter, and structural issues.
79
79
  samplesheet validate SampleSheet.csv
80
80
  samplesheet validate SampleSheet.csv --format json
81
81
  samplesheet validate SampleSheet.csv --min-hamming 4
82
+ samplesheet validate SampleSheet.csv --color-balance
83
+ samplesheet validate SampleSheet.csv --color-balance --instrument "NovaSeq X"
82
84
  ```
83
85
 
84
86
  **Options:**
@@ -87,6 +89,8 @@ samplesheet validate SampleSheet.csv --min-hamming 4
87
89
  |---|---|---|
88
90
  | `--format` / `-f` | `text` | Output format: `text` or `json` |
89
91
  | `--min-hamming` | `3` | Minimum Hamming distance between indexes |
92
+ | `--color-balance` / `--no-color-balance` | off | Also run per-cycle color-balance checking against the instrument's optical chemistry (opt-in; skipped silently for unknown instruments) |
93
+ | `--instrument` | from header | Instrument name used to resolve chemistry for the color-balance check |
90
94
 
91
95
  **Exit codes:** `0` = valid, `1` = errors found, `2` = parse/usage error.
92
96