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.
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.github/workflows/ci.yml +2 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.gitignore +6 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.zenodo.json +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/CHANGELOG.md +54 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/CITATION.cff +2 -2
- samplesheet_parser-2.5.0/CODE_OF_CONDUCT.md +128 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/PKG-INFO +66 -28
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/README.md +64 -26
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/api.md +104 -5
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/cli.md +11 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/validation.md +21 -9
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/index.md +1 -1
- samplesheet_parser-2.5.0/eval/FINDINGS.md +194 -0
- samplesheet_parser-2.5.0/eval/README.md +130 -0
- samplesheet_parser-2.5.0/eval/__init__.py +8 -0
- samplesheet_parser-2.5.0/eval/generate_corpus.py +580 -0
- samplesheet_parser-2.5.0/eval/reference_rules.py +233 -0
- samplesheet_parser-2.5.0/eval/run_eval.py +533 -0
- samplesheet_parser-2.5.0/images/samplesheet_parser_arch_v2.3.png +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/mkdocs.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/meta.yml +1 -1
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/pyproject.toml +2 -2
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/__init__.py +2 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/chemistry.py +195 -63
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/cli.py +25 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/validators.py +139 -57
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_chemistry.py +75 -13
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_cli.py +105 -9
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_converter.py +0 -5
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_diff.py +0 -1
- samplesheet_parser-2.5.0/tests/test_eval.py +200 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_factory.py +1 -5
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_index_utils.py +2 -7
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_instruments.py +0 -3
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_merger.py +0 -18
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_v1.py +2 -9
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_v2.py +2 -10
- samplesheet_parser-2.5.0/tests/test_reference_rules.py +136 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_validators/test_validators.py +80 -5
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_writer.py +0 -5
- samplesheet_parser-2.3.0/recipes/meta.yaml +0 -56
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.github/workflows/copilot-instructions.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.pre-commit-config.yaml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/.readthedocs.yaml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/CONTRIBUTING.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/LICENSE +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/Makefile +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/changelog.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/ci.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/contributing.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/examples.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/conversion.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/diffing.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/filtering.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/index_utils.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/merging.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/parsing.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/quickstart.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/splitting.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/guide/writing.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/installation.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/docs/requirements.txt +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_color_balance.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_converter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_diff.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_element_aviti.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_filter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_index_utils.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_merger.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_splitter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/demo_writer.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/parse_examples.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/README.md +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_clean.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/element_aviti_RunManifest.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_single_index.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_arch_v03.png +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/images/samplesheet_parser_overview.png +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/environment.yml +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/main.nf +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/converter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/diff.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/enums.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/factory.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/filter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/index_utils.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/instruments.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/merger.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/__init__.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/element.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/v1.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/parsers/v2.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/protocol.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/py.typed +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/splitter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/samplesheet_parser/writer.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/scripts/demo_converter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/scripts/demo_diff.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/scripts/demo_writer.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/__init__.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/conftest.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_filter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/__init__.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_parsers/test_element.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_splitter.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.0}/tests/test_validators/__init__.py +0 -0
- {samplesheet_parser-2.3.0 → samplesheet_parser-2.5.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__/
|
|
@@ -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.
|
|
12
|
-
date-released: 2026-
|
|
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
|
+
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://
|
|
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
|
-
**
|
|
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
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
69
69
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
70
|
-
[](https://samplesheet-parser.readthedocs.io)
|
|
71
71
|
[](https://doi.org/10.5281/zenodo.18989694)
|
|
72
72
|
|
|
73
|
-
**Docs:** https://
|
|
73
|
+
**Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
74
74
|
|
|
75
|
-

|
|
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
|
|
348
|
+
The factory detects the format across vendors — no format hints required from the caller:
|
|
349
349
|
|
|
350
|
-
1. **
|
|
351
|
-
2. **
|
|
352
|
-
3. **
|
|
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
|
-
|
|
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
|
|
414
|
-
|
|
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
|
|
433
|
-
|
|
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
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
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:
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
13
13
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
14
|
-
[](https://samplesheet-parser.readthedocs.io)
|
|
15
15
|
[](https://doi.org/10.5281/zenodo.18989694)
|
|
16
16
|
|
|
17
|
-
**Docs:** https://
|
|
17
|
+
**Docs:** https://samplesheet-parser.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
18
18
|
|
|
19
|
-

|
|
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
|
|
292
|
+
The factory detects the format across vendors — no format hints required from the caller:
|
|
293
293
|
|
|
294
|
-
1. **
|
|
295
|
-
2. **
|
|
296
|
-
3. **
|
|
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
|
-
|
|
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
|
|
358
|
-
|
|
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
|
|
377
|
-
|
|
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
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
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:
|
|
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
|
-
|
|
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)
|