samplesheet-parser 2.4.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 (154) hide show
  1. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/.github/workflows/ci.yml +2 -1
  2. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/.zenodo.json +1 -1
  3. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/CHANGELOG.md +24 -0
  4. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/CITATION.cff +2 -2
  5. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/PKG-INFO +23 -5
  6. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/README.md +22 -4
  7. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/api.md +7 -3
  8. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/cli.md +8 -1
  9. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/validation.md +5 -3
  10. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/pyproject.toml +1 -1
  11. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/cli.py +25 -0
  12. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/validators.py +33 -3
  13. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_cli.py +105 -0
  14. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_validators/test_validators.py +27 -1
  15. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/.github/workflows/copilot-instructions.md +0 -0
  16. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/.gitignore +0 -0
  17. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/.pre-commit-config.yaml +0 -0
  18. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/.readthedocs.yaml +0 -0
  19. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/CODE_OF_CONDUCT.md +0 -0
  20. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/CONTRIBUTING.md +0 -0
  21. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/LICENSE +0 -0
  22. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/Makefile +0 -0
  23. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/changelog.md +0 -0
  24. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/ci.md +0 -0
  25. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/contributing.md +0 -0
  26. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/examples.md +0 -0
  27. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/conversion.md +0 -0
  28. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/diffing.md +0 -0
  29. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/filtering.md +0 -0
  30. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/index_utils.md +0 -0
  31. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/merging.md +0 -0
  32. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/parsing.md +0 -0
  33. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/quickstart.md +0 -0
  34. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/splitting.md +0 -0
  35. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/guide/writing.md +0 -0
  36. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/index.md +0 -0
  37. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/installation.md +0 -0
  38. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/docs/requirements.txt +0 -0
  39. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/eval/FINDINGS.md +0 -0
  40. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/eval/README.md +0 -0
  41. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/eval/__init__.py +0 -0
  42. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/eval/generate_corpus.py +0 -0
  43. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/eval/reference_rules.py +0 -0
  44. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/eval/run_eval.py +0 -0
  45. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_color_balance.py +0 -0
  46. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_converter.py +0 -0
  47. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_diff.py +0 -0
  48. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_element_aviti.py +0 -0
  49. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_filter.py +0 -0
  50. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_index_utils.py +0 -0
  51. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_merger.py +0 -0
  52. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_splitter.py +0 -0
  53. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/demo_writer.py +0 -0
  54. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/parse_examples.py +0 -0
  55. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  56. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  57. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  58. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  59. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/README.md +0 -0
  60. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_clean.csv +0 -0
  61. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  62. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  63. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/element_aviti_RunManifest.csv +0 -0
  64. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  65. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  66. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  67. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  68. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  69. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  70. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  71. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  72. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  73. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  74. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  75. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_arch_v03.png +0 -0
  76. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_arch_v2.3.png +0 -0
  77. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_overview.png +0 -0
  78. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/mkdocs.yml +0 -0
  79. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/environment.yml +0 -0
  80. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/main.nf +0 -0
  81. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/meta.yml +0 -0
  82. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +0 -0
  83. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/environment.yml +0 -0
  84. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/main.nf +0 -0
  85. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/meta.yml +0 -0
  86. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +0 -0
  87. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +0 -0
  88. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/environment.yml +0 -0
  89. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/main.nf +0 -0
  90. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/meta.yml +0 -0
  91. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +0 -0
  92. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
  93. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/environment.yml +0 -0
  94. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/main.nf +0 -0
  95. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/meta.yml +0 -0
  96. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +0 -0
  97. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +0 -0
  98. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/environment.yml +0 -0
  99. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/main.nf +0 -0
  100. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/meta.yml +0 -0
  101. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +0 -0
  102. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/environment.yml +0 -0
  103. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/main.nf +0 -0
  104. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/meta.yml +0 -0
  105. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +0 -0
  106. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/environment.yml +0 -0
  107. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/main.nf +0 -0
  108. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/meta.yml +0 -0
  109. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +0 -0
  110. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +0 -0
  111. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/__init__.py +0 -0
  112. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/chemistry.py +0 -0
  113. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/converter.py +0 -0
  114. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/diff.py +0 -0
  115. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/enums.py +0 -0
  116. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/factory.py +0 -0
  117. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/filter.py +0 -0
  118. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/index_utils.py +0 -0
  119. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/instruments.py +0 -0
  120. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/merger.py +0 -0
  121. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/__init__.py +0 -0
  122. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/element.py +0 -0
  123. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/v1.py +0 -0
  124. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/v2.py +0 -0
  125. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/protocol.py +0 -0
  126. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/py.typed +0 -0
  127. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/splitter.py +0 -0
  128. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/samplesheet_parser/writer.py +0 -0
  129. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/scripts/demo_converter.py +0 -0
  130. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/scripts/demo_diff.py +0 -0
  131. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/scripts/demo_writer.py +0 -0
  132. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/__init__.py +0 -0
  133. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/conftest.py +0 -0
  134. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  135. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  136. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  137. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_chemistry.py +0 -0
  138. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_converter.py +0 -0
  139. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_diff.py +0 -0
  140. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_eval.py +0 -0
  141. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_factory.py +0 -0
  142. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_filter.py +0 -0
  143. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_index_utils.py +0 -0
  144. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_instruments.py +0 -0
  145. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_merger.py +0 -0
  146. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_parsers/__init__.py +0 -0
  147. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_element.py +0 -0
  148. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_v1.py +0 -0
  149. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_v2.py +0 -0
  150. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_reference_rules.py +0 -0
  151. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_splitter.py +0 -0
  152. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_validators/__init__.py +0 -0
  153. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_validators/test_hamming.py +0 -0
  154. {samplesheet_parser-2.4.0 → samplesheet_parser-2.5.0}/tests/test_writer.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,7 +4,7 @@
4
4
  "upload_type": "software",
5
5
  "access_right": "open",
6
6
  "license": "Apache-2.0",
7
- "version": "2.4.0",
7
+ "version": "2.5.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -10,6 +10,30 @@ 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
+
13
37
  ## [2.4.0] - 2026-06-21
14
38
 
15
39
  ### Changed (behavioral)
@@ -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.4.0
12
- date-released: 2026-06-21
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"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 2.4.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
6
  Project-URL: Documentation, https://samplesheet-parser.readthedocs.io
@@ -430,8 +430,9 @@ for err in result.errors:
430
430
  ```
431
431
 
432
432
  The chemistry is resolved from the instrument name; the check is **off by
433
- default** (it can legitimately fail a low-plex pool) and is skipped silently
434
- 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:
435
436
 
436
437
  ```python
437
438
  from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
@@ -448,12 +449,20 @@ From the CLI:
448
449
  ```bash
449
450
  samplesheet validate SampleSheet.csv --color-balance
450
451
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
452
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
451
453
  ```
452
454
 
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
+
453
461
  #### Modes: `vendor_faithful` (default) and `conservative`
454
462
 
455
- Color balance has two modes, selectable via
456
- `validate(..., color_balance_mode=...)` or `analyze_color_balance(..., mode=...)`:
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=...)`:
457
466
 
458
467
  - **`vendor_faithful`** (default) encodes each platform's *published* rule
459
468
  exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
@@ -821,6 +830,15 @@ Apache 2.0 — see [LICENSE](LICENSE).
821
830
 
822
831
  ---
823
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
+
824
842
  ## Related resources
825
843
 
826
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)
@@ -374,8 +374,9 @@ for err in result.errors:
374
374
  ```
375
375
 
376
376
  The chemistry is resolved from the instrument name; the check is **off by
377
- default** (it can legitimately fail a low-plex pool) and is skipped silently
378
- 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:
379
380
 
380
381
  ```python
381
382
  from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
@@ -392,12 +393,20 @@ From the CLI:
392
393
  ```bash
393
394
  samplesheet validate SampleSheet.csv --color-balance
394
395
  samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
396
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
395
397
  ```
396
398
 
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
+
397
405
  #### Modes: `vendor_faithful` (default) and `conservative`
398
406
 
399
- Color balance has two modes, selectable via
400
- `validate(..., color_balance_mode=...)` or `analyze_color_balance(..., mode=...)`:
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=...)`:
401
410
 
402
411
  - **`vendor_faithful`** (default) encodes each platform's *published* rule
403
412
  exactly — Illumina's "signal in at least one channel" minimum for 2-channel,
@@ -765,6 +774,15 @@ Apache 2.0 — see [LICENSE](LICENSE).
765
774
 
766
775
  ---
767
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
+
768
786
  ## Related resources
769
787
 
770
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)
@@ -131,11 +131,13 @@ from samplesheet_parser.instruments import (
131
131
 
132
132
  Color-balance checking is **opt-in** via `check_color_balance=True`. The
133
133
  instrument is read from the sheet header when present, or supplied with
134
- `instrument=`; the check is skipped silently for unknown instruments.
134
+ `instrument=`; for an unknown instrument the check is not run and a
135
+ `COLOR_BALANCE_SKIPPED` note is added (rather than passing silently).
135
136
  `color_balance_mode` is `"vendor_faithful"` (default) or `"conservative"` (see
136
137
  [`ColorBalanceMode`](#samplesheet_parserchemistry)). It emits
137
- `COLOR_BALANCE_NO_SIGNAL` (error), `COLOR_BALANCE_LOW` (warning), and
138
- `COLOR_BALANCE_ADVISORY` (warning, AVITI) issues — see
138
+ `COLOR_BALANCE_NO_SIGNAL` (error), `COLOR_BALANCE_LOW` (warning),
139
+ `COLOR_BALANCE_ADVISORY` (warning, AVITI), and `COLOR_BALANCE_SKIPPED` (note)
140
+ issues — see
139
141
  [Validation → Color-balance checking](guide/validation.md#color-balance-checking).
140
142
 
141
143
  ### ValidationResult
@@ -145,6 +147,8 @@ instrument is read from the sheet header when present, or supplied with
145
147
  | `is_valid` | `bool` | `False` if any errors present |
146
148
  | `errors` | `list[ValidationIssue]` | Structured error records |
147
149
  | `warnings` | `list[ValidationIssue]` | Structured warning records |
150
+ | `notes` | `list[ValidationIssue]` | Informational records (e.g. a skipped check); do not affect `is_valid` |
151
+ | `to_dict()` | `dict` | Serializable `is_valid` / `errors` / `warnings` / `notes` |
148
152
  | `summary()` | `str` | One-line human-readable summary |
149
153
 
150
154
  ### ValidationIssue
@@ -81,6 +81,7 @@ samplesheet validate SampleSheet.csv --format json
81
81
  samplesheet validate SampleSheet.csv --min-hamming 4
82
82
  samplesheet validate SampleSheet.csv --color-balance
83
83
  samplesheet validate SampleSheet.csv --color-balance --instrument "NovaSeq X"
84
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
84
85
  ```
85
86
 
86
87
  **Options:**
@@ -89,9 +90,15 @@ samplesheet validate SampleSheet.csv --color-balance --instrument "NovaSeq X"
89
90
  |---|---|---|
90
91
  | `--format` / `-f` | `text` | Output format: `text` or `json` |
91
92
  | `--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
+ | `--color-balance` / `--no-color-balance` | off | Also run per-cycle color-balance checking against the instrument's optical chemistry (opt-in) |
94
+ | `--color-balance-mode` | `vendor_faithful` | Strictness of the color-balance check: `vendor_faithful` (each platform's published rule) or `conservative` (also fails single-channel and low-diversity cycles the vendor minimum permits) |
93
95
  | `--instrument` | from header | Instrument name used to resolve chemistry for the color-balance check |
94
96
 
97
+ When `--color-balance` is requested but the instrument cannot be resolved, the
98
+ check is not run and a `COLOR_BALANCE_SKIPPED` note is emitted (in both text and
99
+ JSON output) rather than passing silently, so a clean result is not mistaken for
100
+ a passed color-balance check. Pass `--instrument` to enable the check.
101
+
95
102
  **Exit codes:** `0` = valid, `1` = errors found, `2` = parse/usage error.
96
103
 
97
104
  ---
@@ -34,8 +34,9 @@ for w in result.warnings:
34
34
  | `COLOR_BALANCE_NO_SIGNAL` | error | An index cycle has no optical signal (2-/1-channel dark, or a 4-channel laser absent), or a conservative-mode escalation (opt-in) |
35
35
  | `COLOR_BALANCE_LOW` | warning | An index cycle has weak or single-channel signal (opt-in) |
36
36
  | `COLOR_BALANCE_ADVISORY` | warning | AVITI low-diversity advisory in `vendor_faithful` mode (opt-in) |
37
+ | `COLOR_BALANCE_SKIPPED` | note | Color balance was requested but the instrument chemistry could not be resolved, so the check was not run (opt-in) |
37
38
 
38
- The last two checks are **opt-in** — see [Color-balance checking](#color-balance-checking) below.
39
+ The color-balance checks are **opt-in** — see [Color-balance checking](#color-balance-checking) below. Notes are informational and do not affect `is_valid`; they appear in a `notes` list on the result (and in JSON output).
39
40
 
40
41
  ## Index distance checking
41
42
 
@@ -80,12 +81,13 @@ result = SampleSheetValidator().validate(
80
81
  - **Two-/one-channel**: an all-`G` (no-signal) cycle is a `COLOR_BALANCE_NO_SIGNAL` error in both modes. A single-channel cycle (one channel present, the other dark) meets Illumina's "at least one channel" minimum, so it is a `COLOR_BALANCE_LOW` warning in `vendor_faithful` but an error in `conservative`. A both-present-but-faint channel (below `min_signal_fraction`, default 0.10) is a `COLOR_BALANCE_LOW` warning.
81
82
  - **Four-channel** (Illumina MiSeq/HiSeq): the green laser reads `{G,T}` and the red laser reads `{A,C}`; a cycle missing either laser group (e.g. all-`G`, or `G/T`-only) is a `COLOR_BALANCE_NO_SIGNAL` error in **both** modes.
82
83
  - **Avidity** (Element AVITI): each base has its own dye and there is no laser-pair constraint, so low diversity never fails. In `vendor_faithful` it is a `COLOR_BALANCE_ADVISORY` warning (first cycles only); in `conservative` it is escalated to an error.
83
- - If the instrument is unknown, the check is skipped silently.
84
+ - If the instrument is unknown, the check is not run (guessing the chemistry would be misleading), and a `COLOR_BALANCE_SKIPPED` note is added so a clean result is not mistaken for a passed check.
84
85
 
85
- The CLI exposes the same check:
86
+ The CLI exposes the same check, including the mode:
86
87
 
87
88
  ```bash
88
89
  samplesheet validate SampleSheet.csv --color-balance --instrument "NovaSeq X"
90
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
89
91
  ```
90
92
 
91
93
  The underlying API — `Chemistry`, `ColorBalanceMode`, `chemistry_for_instrument()`, and `analyze_color_balance(..., mode=...)` returning a `ColorBalanceReport` — is public and usable on its own.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "samplesheet-parser"
7
- version = "2.4.0"
7
+ version = "2.5.0"
8
8
  description = "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"
9
9
  readme = "README.md"
10
10
  license = { file = "LICENSE" }
@@ -29,6 +29,7 @@ Usage
29
29
  samplesheet validate SampleSheet.csv
30
30
  samplesheet validate SampleSheet.csv --format json
31
31
  samplesheet validate SampleSheet.csv --min-hamming 4
32
+ samplesheet validate SampleSheet.csv --color-balance --color-balance-mode conservative
32
33
 
33
34
  samplesheet convert SampleSheet_v1.csv --to v2 --output SampleSheet_v2.csv
34
35
  samplesheet convert SampleSheet_v2.csv --to v1 --output SampleSheet_v1.csv
@@ -66,6 +67,7 @@ try:
66
67
  except ImportError: # pragma: no cover
67
68
  _TYPER_AVAILABLE = False
68
69
 
70
+ from samplesheet_parser.chemistry import ColorBalanceMode
69
71
  from samplesheet_parser.enums import SampleSheetVersion
70
72
  from samplesheet_parser.validators import MIN_HAMMING_DISTANCE as _MIN_HAMMING_DEFAULT
71
73
 
@@ -274,6 +276,18 @@ if _TYPER_AVAILABLE:
274
276
  ),
275
277
  ),
276
278
  ] = False,
279
+ color_balance_mode: Annotated[
280
+ ColorBalanceMode,
281
+ typer.Option(
282
+ "--color-balance-mode",
283
+ help=(
284
+ "Strictness of the colour-balance check (only with "
285
+ "--color-balance). 'vendor_faithful' encodes each platform's "
286
+ "published rule; 'conservative' also fails single-channel and "
287
+ "low-diversity cycles the vendor minimum permits."
288
+ ),
289
+ ),
290
+ ] = ColorBalanceMode.VENDOR_FAITHFUL,
277
291
  instrument: Annotated[
278
292
  str | None,
279
293
  typer.Option(
@@ -318,6 +332,7 @@ if _TYPER_AVAILABLE:
318
332
  sheet,
319
333
  min_hamming_distance=min_hamming,
320
334
  check_color_balance=color_balance,
335
+ color_balance_mode=color_balance_mode,
321
336
  instrument=instrument,
322
337
  )
323
338
 
@@ -329,6 +344,7 @@ if _TYPER_AVAILABLE:
329
344
  "is_valid": result.is_valid,
330
345
  "min_hamming_distance": min_hamming,
331
346
  "color_balance_checked": color_balance,
347
+ "color_balance_mode": color_balance_mode.value if color_balance else None,
332
348
  "errors": [
333
349
  {"code": e.code, "message": e.message, "context": e.context}
334
350
  for e in result.errors
@@ -337,6 +353,10 @@ if _TYPER_AVAILABLE:
337
353
  {"code": w.code, "message": w.message, "context": w.context}
338
354
  for w in result.warnings
339
355
  ],
356
+ "notes": [
357
+ {"code": n.code, "message": n.message, "context": n.context}
358
+ for n in result.notes
359
+ ],
340
360
  "summary": result.summary(),
341
361
  }
342
362
  )
@@ -345,6 +365,11 @@ if _TYPER_AVAILABLE:
345
365
  typer.echo(f"Format: {version.value}")
346
366
  typer.echo(f"Result: {result.summary()}")
347
367
 
368
+ if result.notes:
369
+ typer.echo("\nNotes:")
370
+ for n in result.notes:
371
+ typer.echo(f" {n}")
372
+
348
373
  if result.warnings:
349
374
  typer.echo("\nWarnings:")
350
375
  for w in result.warnings:
@@ -79,7 +79,7 @@ class ValidationIssue:
79
79
  Attributes
80
80
  ----------
81
81
  level:
82
- ``"error"`` or ``"warning"``.
82
+ ``"error"``, ``"warning"``, or ``"note"``.
83
83
  code:
84
84
  Short machine-readable code (e.g. ``"DUPLICATE_INDEX"``).
85
85
  message:
@@ -105,17 +105,23 @@ class ValidationResult:
105
105
  Attributes
106
106
  ----------
107
107
  is_valid:
108
- ``True`` if no *errors* were raised (warnings do not affect
108
+ ``True`` if no *errors* were raised (warnings and notes do not affect
109
109
  this flag).
110
110
  errors:
111
111
  List of error-level :class:`ValidationIssue` objects.
112
112
  warnings:
113
113
  List of warning-level :class:`ValidationIssue` objects.
114
+ notes:
115
+ List of informational :class:`ValidationIssue` objects. Notes record
116
+ checks that were requested but not performed (e.g. a colour-balance
117
+ check skipped because the instrument was unknown), so a clean result
118
+ is not mistaken for a check that silently did nothing.
114
119
  """
115
120
 
116
121
  is_valid: bool = True
117
122
  errors: list[ValidationIssue] = field(default_factory=list)
118
123
  warnings: list[ValidationIssue] = field(default_factory=list)
124
+ notes: list[ValidationIssue] = field(default_factory=list)
119
125
 
120
126
  def add_error(self, code: str, message: str, **context: Any) -> None:
121
127
  self.is_valid = False
@@ -126,6 +132,11 @@ class ValidationResult:
126
132
  self.warnings.append(ValidationIssue("warning", code, message, dict(context)))
127
133
  logger.warning(f"{code}: {message}")
128
134
 
135
+ def add_note(self, code: str, message: str, **context: Any) -> None:
136
+ """Record an informational note (does not affect ``is_valid``)."""
137
+ self.notes.append(ValidationIssue("note", code, message, dict(context)))
138
+ logger.info(f"{code}: {message}")
139
+
129
140
  def to_dict(self) -> dict[str, Any]:
130
141
  return {
131
142
  "is_valid": self.is_valid,
@@ -135,6 +146,9 @@ class ValidationResult:
135
146
  "warnings": [
136
147
  {"code": w.code, "message": w.message, "context": w.context} for w in self.warnings
137
148
  ],
149
+ "notes": [
150
+ {"code": n.code, "message": n.message, "context": n.context} for n in self.notes
151
+ ],
138
152
  }
139
153
 
140
154
  def summary(self) -> str:
@@ -247,6 +261,10 @@ class SampleSheetValidator:
247
261
  in one channel (2-/1-channel) or no base
248
262
  diversity (4-channel), degrading base-call
249
263
  quality (warning only).
264
+ * **COLOR_BALANCE_SKIPPED** - Colour balance was requested but the
265
+ instrument chemistry could not be resolved, so
266
+ the check was not run (note only, so a clean
267
+ result is not mistaken for a passed check).
250
268
 
251
269
  Examples
252
270
  --------
@@ -575,7 +593,19 @@ class SampleSheetValidator:
575
593
  name = instrument or self._resolve_instrument(sheet)
576
594
  chemistry = chemistry_for_instrument(name)
577
595
  if chemistry is None:
578
- logger.debug("Skipping colour-balance check: unknown instrument %r.", name)
596
+ detail = (
597
+ f"instrument {name!r} is not recognised"
598
+ if name
599
+ else "no instrument is declared in the sheet or passed via --instrument"
600
+ )
601
+ result.add_note(
602
+ "COLOR_BALANCE_SKIPPED",
603
+ f"Colour balance was requested but not evaluated: {detail}, so the "
604
+ f"optical chemistry is unknown. A clean result here does not mean the "
605
+ f"index pool is colour balanced. Pass a known instrument to enable the "
606
+ f"check.",
607
+ instrument=name,
608
+ )
579
609
  return
580
610
 
581
611
  index1 = [(s.get("index") or s.get("Index") or "").upper() for s in samples]
@@ -149,6 +149,32 @@ Lane,Sample_ID,Index,Index2,Sample_Project
149
149
  1,SampleC2,TAAGTTGGGT,TGGAACGCTA,ProjectC
150
150
  """
151
151
 
152
+ # V2 sheet whose index1 cycle 1 is all G/T across the pool (green present, red
153
+ # {A,C} absent): a single-channel 2-channel cycle. On NovaSeqXSeries this is a
154
+ # COLOR_BALANCE_LOW warning under vendor_faithful (exit 0) but a
155
+ # COLOR_BALANCE_NO_SIGNAL error under conservative (exit 1).
156
+ _V2_SINGLE_CHANNEL = """\
157
+ [Header]
158
+ FileFormatVersion,2
159
+ RunName,SingleChannel
160
+ InstrumentPlatform,NovaSeqXSeries
161
+
162
+ [Reads]
163
+ Read1Cycles,151
164
+ Read2Cycles,151
165
+ Index1Cycles,8
166
+
167
+ [BCLConvert_Settings]
168
+ AdapterRead1,CTGTCTCTTATACACATCT
169
+
170
+ [BCLConvert_Data]
171
+ Sample_ID,Index
172
+ S1,GACATACG
173
+ S2,TAACGTAC
174
+ S3,GAGTACGA
175
+ S4,TATGCGTT
176
+ """
177
+
152
178
  # V1 sheet with same samples as _V1_A but SampleA1 has a different index -
153
179
  # used to trigger sample_changes in diff text output (lines 301-305)
154
180
  _V1_A_FIELD_CHANGED = """\
@@ -495,6 +521,85 @@ class TestCLIValidate:
495
521
  result = runner.invoke(app, ["validate", str(p), "--min-hamming", "-1"])
496
522
  assert result.exit_code == 2
497
523
 
524
+ def test_color_balance_vendor_faithful_single_channel_passes(self, tmp_path: Path) -> None:
525
+ """A single-channel cycle is a warning (exit 0) in default vendor_faithful mode."""
526
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
527
+ result = runner.invoke(app, ["validate", str(p), "--color-balance"])
528
+ assert result.exit_code == 0
529
+ assert "COLOR_BALANCE_LOW" in result.output
530
+
531
+ def test_color_balance_conservative_single_channel_fails(self, tmp_path: Path) -> None:
532
+ """--color-balance-mode conservative escalates the single-channel cycle to an error."""
533
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
534
+ result = runner.invoke(
535
+ app,
536
+ ["validate", str(p), "--color-balance", "--color-balance-mode", "conservative"],
537
+ )
538
+ assert result.exit_code == 1
539
+ assert "COLOR_BALANCE_NO_SIGNAL" in result.output
540
+
541
+ def test_color_balance_mode_in_json(self, tmp_path: Path) -> None:
542
+ """JSON output records the mode used when color balance is checked."""
543
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
544
+ result = runner.invoke(
545
+ app,
546
+ [
547
+ "validate",
548
+ str(p),
549
+ "--format",
550
+ "json",
551
+ "--color-balance",
552
+ "--color-balance-mode",
553
+ "conservative",
554
+ ],
555
+ )
556
+ data = json.loads(result.output)
557
+ assert data["color_balance_mode"] == "conservative"
558
+
559
+ def test_color_balance_mode_null_in_json_when_not_checked(self, tmp_path: Path) -> None:
560
+ """Mode is null in JSON when color balance was not requested."""
561
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
562
+ result = runner.invoke(app, ["validate", str(p), "--format", "json"])
563
+ data = json.loads(result.output)
564
+ assert data["color_balance_mode"] is None
565
+
566
+ def test_color_balance_invalid_mode_exits_2(self, tmp_path: Path) -> None:
567
+ """An unrecognized mode value is rejected by typer with exit 2."""
568
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
569
+ result = runner.invoke(
570
+ app, ["validate", str(p), "--color-balance", "--color-balance-mode", "nonsense"]
571
+ )
572
+ assert result.exit_code == 2
573
+
574
+ def test_color_balance_unknown_instrument_surfaces_skip_note(self, tmp_path: Path) -> None:
575
+ """An unknown instrument surfaces a visible COLOR_BALANCE_SKIPPED note,
576
+ not a silent pass."""
577
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
578
+ result = runner.invoke(
579
+ app,
580
+ ["validate", str(p), "--color-balance", "--instrument", "MysterySeq 9000"],
581
+ )
582
+ assert result.exit_code == 0
583
+ assert "COLOR_BALANCE_SKIPPED" in result.output
584
+
585
+ def test_color_balance_skip_note_in_json(self, tmp_path: Path) -> None:
586
+ """The skip note appears in the JSON notes list."""
587
+ p = _write(tmp_path, "sheet.csv", _V2_SINGLE_CHANNEL)
588
+ result = runner.invoke(
589
+ app,
590
+ [
591
+ "validate",
592
+ str(p),
593
+ "--format",
594
+ "json",
595
+ "--color-balance",
596
+ "--instrument",
597
+ "MysterySeq 9000",
598
+ ],
599
+ )
600
+ data = json.loads(result.output)
601
+ assert any(n["code"] == "COLOR_BALANCE_SKIPPED" for n in data["notes"])
602
+
498
603
 
499
604
  # ---------------------------------------------------------------------------
500
605
  # convert
@@ -102,12 +102,38 @@ class TestColorBalance:
102
102
  codes = [e.code for e in result.errors]
103
103
  assert "COLOR_BALANCE_NO_SIGNAL" in codes
104
104
 
105
- def test_unknown_instrument_skips_silently(self, tmp_path):
105
+ def test_unknown_instrument_skips_without_error(self, tmp_path):
106
106
  sheet = _parse_v2(tmp_path / "s.csv", _DARK_CYCLE_V2)
107
107
  result = SampleSheetValidator().validate(
108
108
  sheet, check_color_balance=True, instrument="MysterySeq 9000"
109
109
  )
110
+ # Unknown chemistry: no colour-balance error is raised (would be guessing)...
110
111
  assert not any(e.code.startswith("COLOR_BALANCE") for e in result.errors)
112
+ assert result.is_valid
113
+
114
+ def test_unknown_instrument_surfaces_skip_note(self, tmp_path):
115
+ # ...but the skip is surfaced as a note so a clean result is not mistaken
116
+ # for a passed colour-balance check.
117
+ sheet = _parse_v2(tmp_path / "s.csv", _DARK_CYCLE_V2)
118
+ result = SampleSheetValidator().validate(
119
+ sheet, check_color_balance=True, instrument="MysterySeq 9000"
120
+ )
121
+ assert any(n.code == "COLOR_BALANCE_SKIPPED" for n in result.notes)
122
+ note = next(n for n in result.notes if n.code == "COLOR_BALANCE_SKIPPED")
123
+ assert note.context.get("instrument") == "MysterySeq 9000"
124
+ assert "COLOR_BALANCE_SKIPPED" in [n["code"] for n in result.to_dict()["notes"]]
125
+
126
+ def test_no_skip_note_when_color_balance_not_requested(self, tmp_path):
127
+ sheet = _parse_v2(tmp_path / "s.csv", _DARK_CYCLE_V2)
128
+ result = SampleSheetValidator().validate(sheet, instrument="MysterySeq 9000")
129
+ assert result.notes == []
130
+
131
+ def test_known_instrument_produces_no_skip_note(self, tmp_path):
132
+ sheet = _parse_v2(tmp_path / "s.csv", _DARK_CYCLE_V2)
133
+ result = SampleSheetValidator().validate(
134
+ sheet, check_color_balance=True, instrument="NovaSeqXSeries"
135
+ )
136
+ assert not any(n.code == "COLOR_BALANCE_SKIPPED" for n in result.notes)
111
137
 
112
138
  def test_avidity_override_makes_all_g_advisory_not_error(self, tmp_path):
113
139
  # Force AVITI (avidity): all-G index cycles are advisory, never errors.