samplesheet-parser 2.3.0__tar.gz → 2.5.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.5.0}/.github/workflows/ci.yml +2 -1
  2. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.gitignore +6 -0
  3. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.zenodo.json +1 -1
  4. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/CHANGELOG.md +54 -0
  5. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/CITATION.cff +2 -2
  6. samplesheet_parser-2.5.0/CODE_OF_CONDUCT.md +128 -0
  7. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/PKG-INFO +66 -28
  8. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/README.md +64 -26
  9. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/api.md +104 -5
  10. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/cli.md +11 -0
  11. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/validation.md +21 -9
  12. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/index.md +1 -1
  13. samplesheet_parser-2.5.0/eval/FINDINGS.md +194 -0
  14. samplesheet_parser-2.5.0/eval/README.md +130 -0
  15. samplesheet_parser-2.5.0/eval/__init__.py +8 -0
  16. samplesheet_parser-2.5.0/eval/generate_corpus.py +580 -0
  17. samplesheet_parser-2.5.0/eval/reference_rules.py +233 -0
  18. samplesheet_parser-2.5.0/eval/run_eval.py +533 -0
  19. samplesheet_parser-2.5.0/images/samplesheet_parser_arch_v2.3.png +0 -0
  20. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/mkdocs.yml +1 -1
  21. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/meta.yml +1 -1
  22. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/meta.yml +1 -1
  23. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/meta.yml +1 -1
  24. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/meta.yml +1 -1
  25. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/meta.yml +1 -1
  26. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/meta.yml +1 -1
  27. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/meta.yml +1 -1
  28. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/pyproject.toml +2 -2
  29. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/__init__.py +2 -0
  30. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/chemistry.py +195 -63
  31. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/cli.py +25 -0
  32. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/validators.py +139 -57
  33. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_chemistry.py +75 -13
  34. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_cli.py +105 -9
  35. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_converter.py +0 -5
  36. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_diff.py +0 -1
  37. samplesheet_parser-2.5.0/tests/test_eval.py +200 -0
  38. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_factory.py +1 -5
  39. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_index_utils.py +2 -7
  40. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_instruments.py +0 -3
  41. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_merger.py +0 -18
  42. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_v1.py +2 -9
  43. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_v2.py +2 -10
  44. samplesheet_parser-2.5.0/tests/test_reference_rules.py +136 -0
  45. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_validators/test_validators.py +80 -5
  46. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_writer.py +0 -5
  47. samplesheet_parser-2.3.0/recipes/meta.yaml +0 -56
  48. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.github/workflows/copilot-instructions.md +0 -0
  49. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.pre-commit-config.yaml +0 -0
  50. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.readthedocs.yaml +0 -0
  51. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/CONTRIBUTING.md +0 -0
  52. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/LICENSE +0 -0
  53. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/Makefile +0 -0
  54. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/changelog.md +0 -0
  55. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/ci.md +0 -0
  56. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/contributing.md +0 -0
  57. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/examples.md +0 -0
  58. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/conversion.md +0 -0
  59. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/diffing.md +0 -0
  60. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/filtering.md +0 -0
  61. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/index_utils.md +0 -0
  62. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/merging.md +0 -0
  63. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/parsing.md +0 -0
  64. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/quickstart.md +0 -0
  65. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/splitting.md +0 -0
  66. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/writing.md +0 -0
  67. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/installation.md +0 -0
  68. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/requirements.txt +0 -0
  69. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_color_balance.py +0 -0
  70. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_converter.py +0 -0
  71. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_diff.py +0 -0
  72. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_element_aviti.py +0 -0
  73. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_filter.py +0 -0
  74. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_index_utils.py +0 -0
  75. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_merger.py +0 -0
  76. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_splitter.py +0 -0
  77. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_writer.py +0 -0
  78. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/parse_examples.py +0 -0
  79. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  80. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  81. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  82. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  83. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/README.md +0 -0
  84. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_clean.csv +0 -0
  85. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  86. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  87. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/element_aviti_RunManifest.csv +0 -0
  88. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  89. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  90. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  91. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  92. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  93. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  94. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  95. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  96. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  97. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  98. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  99. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_arch_v03.png +0 -0
  100. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_overview.png +0 -0
  101. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/environment.yml +0 -0
  102. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/main.nf +0 -0
  103. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +0 -0
  104. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/environment.yml +0 -0
  105. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/main.nf +0 -0
  106. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +0 -0
  107. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +0 -0
  108. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/environment.yml +0 -0
  109. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/main.nf +0 -0
  110. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +0 -0
  111. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
  112. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/environment.yml +0 -0
  113. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/main.nf +0 -0
  114. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +0 -0
  115. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +0 -0
  116. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/environment.yml +0 -0
  117. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/main.nf +0 -0
  118. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +0 -0
  119. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/environment.yml +0 -0
  120. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/main.nf +0 -0
  121. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +0 -0
  122. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/environment.yml +0 -0
  123. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/main.nf +0 -0
  124. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +0 -0
  125. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +0 -0
  126. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/converter.py +0 -0
  127. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/diff.py +0 -0
  128. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/enums.py +0 -0
  129. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/factory.py +0 -0
  130. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/filter.py +0 -0
  131. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/index_utils.py +0 -0
  132. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/instruments.py +0 -0
  133. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/merger.py +0 -0
  134. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/__init__.py +0 -0
  135. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/element.py +0 -0
  136. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/v1.py +0 -0
  137. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/v2.py +0 -0
  138. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/protocol.py +0 -0
  139. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/py.typed +0 -0
  140. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/splitter.py +0 -0
  141. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/writer.py +0 -0
  142. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/scripts/demo_converter.py +0 -0
  143. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/scripts/demo_diff.py +0 -0
  144. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/scripts/demo_writer.py +0 -0
  145. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/__init__.py +0 -0
  146. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/conftest.py +0 -0
  147. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  148. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  149. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  150. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_filter.py +0 -0
  151. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/__init__.py +0 -0
  152. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_element.py +0 -0
  153. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_splitter.py +0 -0
  154. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_validators/__init__.py +0 -0
  155. {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_validators/test_hamming.py +0 -0
@@ -12,8 +12,9 @@ jobs:
12
12
  test:
13
13
  runs-on: ubuntu-latest
14
14
  strategy:
15
+ fail-fast: false
15
16
  matrix:
16
- python-version: ["3.12"]
17
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
17
18
 
18
19
  steps:
19
20
  - uses: actions/checkout@v4
@@ -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.5.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -10,6 +10,60 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
10
10
 
11
11
  _No unreleased changes._
12
12
 
13
+ ## [2.5.0] - 2026-08-10
14
+
15
+ ### Added
16
+
17
+ - **CLI `--color-balance-mode` option** on `samplesheet validate`
18
+ (`vendor_faithful` default, or `conservative`), exposing the color-balance
19
+ strictness that was previously reachable only through the library. JSON output
20
+ now reports `color_balance_mode` when color balance is checked.
21
+ - **`ValidationResult.notes`** informational channel (with `add_note()`, included
22
+ in `to_dict()` and CLI text/JSON output). Notes do not affect `is_valid`.
23
+
24
+ ### Changed (behavioral)
25
+
26
+ - **Color balance no longer skips silently on an unknown instrument.** When
27
+ `--color-balance` (or `check_color_balance=True`) is requested but the
28
+ instrument chemistry cannot be resolved, the validator now emits a
29
+ `COLOR_BALANCE_SKIPPED` note instead of only a debug log, so a clean result is
30
+ not mistaken for a passed color-balance check.
31
+
32
+ ### CI
33
+
34
+ - **CI now tests the full supported Python range (3.10-3.13)** via a matrix,
35
+ matching the `pyproject.toml` classifiers (previously only 3.12 ran).
36
+
37
+ ## [2.4.0] - 2026-06-21
38
+
39
+ ### Changed (behavioral)
40
+
41
+ - **Color-balance checking now has two modes: `vendor_faithful` (new default)
42
+ and `conservative`.** `vendor_faithful` encodes each platform's published
43
+ rule exactly; `conservative` is the previous, stricter behavior (single-channel
44
+ 2-channel cycles and AVITI low-diversity treated as failures). Selectable via
45
+ `analyze_color_balance(..., mode=...)` and `SampleSheetValidator.validate(...,
46
+ color_balance_mode=...)`. **Callers relying on the old stricter results should
47
+ pass `color_balance_mode="conservative"`.**
48
+ - **Fixed a 4-channel color-balance bug (both modes):** Illumina four-channel
49
+ cycles are now failed when either laser group is absent (green `{G,T}` / red
50
+ `{A,C}`), e.g. an all-`G` or `G/T`-only cycle (red laser dark). Previously only
51
+ zero-diversity cycles were flagged.
52
+ - **Element AVITI is now modelled as its own `Chemistry.AVIDITY`** (per-base dye,
53
+ no laser-pair constraint), distinct from Illumina `FOUR_CHANNEL`;
54
+ `chemistry_for_instrument("AVITI")` now returns `Chemistry.AVIDITY`. AVITI low
55
+ diversity is an advisory (`COLOR_BALANCE_ADVISORY`), never a failure, in
56
+ `vendor_faithful` mode.
57
+
58
+ ### Documentation
59
+
60
+ - Refreshed stale docs after the multi-vendor / color-balance release: updated
61
+ the README tagline, format-detection steps (now vendor-aware), and citation
62
+ block (DOI); documented the `chemistry` module, `ElementRunManifest`,
63
+ the `SampleSheetVersion.ELEMENT_AVITI` enum, the `validate(...)`
64
+ color-balance parameters, and the `--color-balance` / `--instrument` CLI flags
65
+ in the API and CLI references.
66
+
13
67
  ## [2.3.0] - 2026-06-15
14
68
 
15
69
  ### 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.5.0
12
+ date-released: 2026-08-10
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.5.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
@@ -429,8 +430,9 @@ for err in result.errors:
429
430
  ```
430
431
 
431
432
  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:
433
+ default** (it can legitimately fail a low-plex pool) and, for an unknown
434
+ instrument, is not run but reported as a `COLOR_BALANCE_SKIPPED` note rather than
435
+ passing silently. The same analysis is available standalone:
434
436
 
435
437
  ```python
436
438
  from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
@@ -447,18 +449,42 @@ From the CLI:
447
449
  ```bash
448
450
  samplesheet validate SampleSheet.csv --color-balance
449
451
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
452
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
450
453
  ```
451
454
 
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.
455
+ When `--color-balance` is requested but the instrument cannot be resolved, the
456
+ check is not run (guessing the chemistry would be misleading). This is surfaced
457
+ as a `COLOR_BALANCE_SKIPPED` note (in text and JSON output) rather than a silent
458
+ pass, so a clean result is never mistaken for a passed color-balance check. Pass
459
+ `--instrument` to enable the check.
460
+
461
+ #### Modes: `vendor_faithful` (default) and `conservative`
462
+
463
+ Color balance has two modes, selectable on the CLI via
464
+ `--color-balance-mode {vendor_faithful,conservative}` or in the library via
465
+ `validate(..., color_balance_mode=...)` / `analyze_color_balance(..., mode=...)`:
466
+
467
+ - **`vendor_faithful`** (default) encodes each platform's *published* rule
468
+ exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
469
+ the both-lasers rule for 4-channel, and Element's permissive low-diversity
470
+ stance for AVITI.
471
+ - **`conservative`** is stricter than the published minimum: it also fails
472
+ single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
473
+ behavior before modes existed — pass `color_balance_mode="conservative"` to
474
+ keep it.)
475
+
476
+ | Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
477
+ |---|---|---|---|
478
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
479
+ | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
480
+ | 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
481
+ | avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
482
+
483
+ Element AVITI uses avidity chemistry — each base has its own avidite dye
484
+ ([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
485
+ — so it has no dark base and no laser-pair constraint. In `vendor_faithful`
486
+ mode, AVITI low diversity in the first cycles is an advisory
487
+ (`COLOR_BALANCE_ADVISORY`), never a failure.
462
488
 
463
489
  ---
464
490
 
@@ -785,14 +811,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
785
811
 
786
812
  ```bibtex
787
813
  @software{kasaraneni2026samplesheetparser,
788
- author = {Kasaraneni, Chaitanya},
789
- title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
814
+ author = {Kasaraneni, Chaitanya Krishna},
815
+ title = {samplesheet-parser: A multi-vendor parser, validator, and converter for sequencing sample sheets},
790
816
  year = {2026},
791
817
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
792
- version = {1.1.0}
818
+ doi = {10.5281/zenodo.18989694},
819
+ version = {2.4.0}
793
820
  }
794
821
  ```
795
822
 
823
+ See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
824
+
796
825
  ---
797
826
 
798
827
  ## License
@@ -801,6 +830,15 @@ Apache 2.0 — see [LICENSE](LICENSE).
801
830
 
802
831
  ---
803
832
 
833
+ ## AI-assisted development
834
+
835
+ Parts of this project's code, tests, and documentation were developed with the
836
+ assistance of generative AI tools (including GitHub Copilot). All AI-generated
837
+ output was reviewed, edited, and verified by the author, who is responsible for
838
+ the correctness of the final software.
839
+
840
+ ---
841
+
804
842
  ## Related resources
805
843
 
806
844
  - [Illumina IEM V1 SampleSheet reference (Knowledge Article #2204)](https://knowledge.illumina.com/software/on-premises-software/software-on-premises-software-reference_material-list/000002204)
@@ -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
@@ -373,8 +374,9 @@ for err in result.errors:
373
374
  ```
374
375
 
375
376
  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:
377
+ default** (it can legitimately fail a low-plex pool) and, for an unknown
378
+ instrument, is not run but reported as a `COLOR_BALANCE_SKIPPED` note rather than
379
+ passing silently. The same analysis is available standalone:
378
380
 
379
381
  ```python
380
382
  from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
@@ -391,18 +393,42 @@ From the CLI:
391
393
  ```bash
392
394
  samplesheet validate SampleSheet.csv --color-balance
393
395
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
396
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
394
397
  ```
395
398
 
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.
399
+ When `--color-balance` is requested but the instrument cannot be resolved, the
400
+ check is not run (guessing the chemistry would be misleading). This is surfaced
401
+ as a `COLOR_BALANCE_SKIPPED` note (in text and JSON output) rather than a silent
402
+ pass, so a clean result is never mistaken for a passed color-balance check. Pass
403
+ `--instrument` to enable the check.
404
+
405
+ #### Modes: `vendor_faithful` (default) and `conservative`
406
+
407
+ Color balance has two modes, selectable on the CLI via
408
+ `--color-balance-mode {vendor_faithful,conservative}` or in the library via
409
+ `validate(..., color_balance_mode=...)` / `analyze_color_balance(..., mode=...)`:
410
+
411
+ - **`vendor_faithful`** (default) encodes each platform's *published* rule
412
+ exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
413
+ the both-lasers rule for 4-channel, and Element's permissive low-diversity
414
+ stance for AVITI.
415
+ - **`conservative`** is stricter than the published minimum: it also fails
416
+ single-channel 2-channel cycles and AVITI low-diversity cycles. (This was the
417
+ behavior before modes existed — pass `color_balance_mode="conservative"` to
418
+ keep it.)
419
+
420
+ | Chemistry | Instruments | Failure rule (both modes) | Stricter in `conservative` |
421
+ |---|---|---|---|
422
+ | 4-channel | MiSeq, HiSeq 2000/2500/3000/4000 | a green `{G,T}` or red `{A,C}` laser is entirely absent | — |
423
+ | 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | all-`G` cycle (no signal either channel) | single-channel cycle also fails |
424
+ | 1-channel | iSeq 100 | all-`G` cycle | single-channel cycle also fails |
425
+ | avidity | Element AVITI | (no dark/laser failure) | low-diversity cycle fails |
426
+
427
+ Element AVITI uses avidity chemistry — each base has its own avidite dye
428
+ ([Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7))
429
+ — so it has no dark base and no laser-pair constraint. In `vendor_faithful`
430
+ mode, AVITI low diversity in the first cycles is an advisory
431
+ (`COLOR_BALANCE_ADVISORY`), never a failure.
406
432
 
407
433
  ---
408
434
 
@@ -729,14 +755,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
729
755
 
730
756
  ```bibtex
731
757
  @software{kasaraneni2026samplesheetparser,
732
- author = {Kasaraneni, Chaitanya},
733
- title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
758
+ author = {Kasaraneni, Chaitanya Krishna},
759
+ title = {samplesheet-parser: A multi-vendor parser, validator, and converter for sequencing sample sheets},
734
760
  year = {2026},
735
761
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
736
- version = {1.1.0}
762
+ doi = {10.5281/zenodo.18989694},
763
+ version = {2.4.0}
737
764
  }
738
765
  ```
739
766
 
767
+ See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
768
+
740
769
  ---
741
770
 
742
771
  ## License
@@ -745,6 +774,15 @@ Apache 2.0 — see [LICENSE](LICENSE).
745
774
 
746
775
  ---
747
776
 
777
+ ## AI-assisted development
778
+
779
+ Parts of this project's code, tests, and documentation were developed with the
780
+ assistance of generative AI tools (including GitHub Copilot). All AI-generated
781
+ output was reviewed, edited, and verified by the author, who is responsible for
782
+ the correctness of the final software.
783
+
784
+ ---
785
+
748
786
  ## Related resources
749
787
 
750
788
  - [Illumina IEM V1 SampleSheet reference (Knowledge Article #2204)](https://knowledge.illumina.com/software/on-premises-software/software-on-premises-software-reference_material-list/000002204)