samplesheet-parser 2.2.0__tar.gz → 2.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.zenodo.json +1 -1
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/CHANGELOG.md +28 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/CITATION.cff +2 -2
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/PKG-INFO +99 -8
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/README.md +96 -5
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/examples.md +29 -1
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/parsing.md +7 -6
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/quickstart.md +2 -2
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/validation.md +30 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/index.md +9 -7
- samplesheet_parser-2.3.0/examples/demo_color_balance.py +85 -0
- samplesheet_parser-2.3.0/examples/demo_element_aviti.py +57 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/README.md +35 -4
- samplesheet_parser-2.3.0/examples/sample_sheets/element_aviti_RunManifest.csv +16 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/pyproject.toml +3 -2
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/__init__.py +14 -1
- samplesheet_parser-2.3.0/samplesheet_parser/chemistry.py +335 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/cli.py +30 -3
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/enums.py +7 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/factory.py +11 -1
- samplesheet_parser-2.3.0/samplesheet_parser/parsers/element.py +329 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/validators.py +162 -0
- samplesheet_parser-2.3.0/tests/test_chemistry.py +109 -0
- samplesheet_parser-2.3.0/tests/test_parsers/test_element.py +115 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_validators/test_validators.py +62 -9
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.github/workflows/ci.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.github/workflows/copilot-instructions.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.gitignore +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.pre-commit-config.yaml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/.readthedocs.yaml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/CONTRIBUTING.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/LICENSE +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/Makefile +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/api.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/changelog.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/ci.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/cli.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/contributing.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/conversion.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/diffing.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/filtering.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/index_utils.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/merging.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/splitting.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/guide/writing.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/installation.md +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/docs/requirements.txt +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_converter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_diff.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_filter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_index_utils.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_merger.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_splitter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/demo_writer.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/parse_examples.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/combined_clean.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_single_index.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/images/samplesheet_parser_arch_v03.png +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/images/samplesheet_parser_overview.png +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/mkdocs.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/environment.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/main.nf +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/meta.yml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/recipes/meta.yaml +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/converter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/diff.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/filter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/index_utils.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/instruments.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/merger.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/parsers/__init__.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/parsers/v1.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/parsers/v2.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/protocol.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/py.typed +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/splitter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/samplesheet_parser/writer.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/scripts/demo_converter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/scripts/demo_diff.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/scripts/demo_writer.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/__init__.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/conftest.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_cli.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_converter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_diff.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_factory.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_filter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_index_utils.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_instruments.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_merger.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_parsers/__init__.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_parsers/test_v1.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_parsers/test_v2.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_splitter.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_validators/__init__.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_validators/test_hamming.py +0 -0
- {samplesheet_parser-2.2.0 → samplesheet_parser-2.3.0}/tests/test_writer.py +0 -0
|
@@ -10,6 +10,34 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|
|
10
10
|
|
|
11
11
|
_No unreleased changes._
|
|
12
12
|
|
|
13
|
+
## [2.3.0] - 2026-06-15
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **Per-cycle color-balance validation (`samplesheet_parser.chemistry`).** Models
|
|
18
|
+
the optical detection chemistry of each instrument (4-channel, 2-channel,
|
|
19
|
+
1-channel) and scores an index pool cycle-by-cycle for signal balance. On
|
|
20
|
+
2-/1-channel chemistry (NextSeq, NovaSeq, NovaSeq X, iSeq), a cycle where the
|
|
21
|
+
whole pool reads the dark base `G` produces no optical signal and fails to
|
|
22
|
+
register; the validator now reports this as a `COLOR_BALANCE_NO_SIGNAL` error.
|
|
23
|
+
Four-channel instruments (MiSeq/HiSeq and Element AVITI, which images four
|
|
24
|
+
avidite dyes per cycle) have no dark base, so zero-diversity index cycles are
|
|
25
|
+
reported as `COLOR_BALANCE_LOW` warnings instead. The check is **opt-in** via
|
|
26
|
+
`SampleSheetValidator.validate(..., check_color_balance=True)` and the
|
|
27
|
+
`samplesheet validate --color-balance` CLI flag, and is skipped silently for
|
|
28
|
+
unknown instruments. New public API: `Chemistry`, `chemistry_for_instrument`,
|
|
29
|
+
`analyze_color_balance`, `ColorBalanceReport`.
|
|
30
|
+
- **Multi-vendor support: Element Biosciences AVITI.** `SampleSheetFactory` now
|
|
31
|
+
auto-detects Element AVITI `RunManifest.csv` files and parses them through a
|
|
32
|
+
new `ElementRunManifest` parser that satisfies the existing
|
|
33
|
+
`SampleSheetParser` protocol, mapping manifest columns to the shared sample
|
|
34
|
+
schema. The validator (including color balance, with AVITI modelled as a
|
|
35
|
+
four-channel platform), diff, and filter tooling work across vendors without
|
|
36
|
+
special-casing. New format enum value: `SampleSheetVersion.ELEMENT_AVITI`.
|
|
37
|
+
- New examples: `examples/demo_color_balance.py`,
|
|
38
|
+
`examples/demo_element_aviti.py`, and
|
|
39
|
+
`examples/sample_sheets/element_aviti_RunManifest.csv`.
|
|
40
|
+
|
|
13
41
|
## [2.2.0] - 2026-06-10
|
|
14
42
|
|
|
15
43
|
### Fixed
|
|
@@ -8,8 +8,8 @@ abstract: >
|
|
|
8
8
|
Provides format auto-detection, bidirectional V1/V2 conversion,
|
|
9
9
|
structural and index validation, sheet diffing, and cross-project
|
|
10
10
|
merging with Hamming-distance collision detection.
|
|
11
|
-
version: 2.
|
|
12
|
-
date-released: 2026-06-
|
|
11
|
+
version: 2.3.0
|
|
12
|
+
date-released: 2026-06-15
|
|
13
13
|
license: Apache-2.0
|
|
14
14
|
url: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
|
|
15
15
|
repository-code: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: samplesheet-parser
|
|
3
|
-
Version: 2.
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 2.3.0
|
|
4
|
+
Summary: Multi-vendor, format-agnostic parser for sequencing sample sheets — Illumina IEM V1 & BCLConvert V2 plus Element AVITI run manifests, with index validation and color-balance checking
|
|
5
5
|
Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
|
|
6
6
|
Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
|
|
7
7
|
Project-URL: Repository, https://github.com/chaitanyakasaraneni/samplesheet-parser
|
|
@@ -27,7 +27,7 @@ License: Apache License
|
|
|
27
27
|
See the License for the specific language governing permissions and
|
|
28
28
|
limitations under the License.
|
|
29
29
|
License-File: LICENSE
|
|
30
|
-
Keywords: bcl2fastq,bclconvert,bioinformatics,demultiplexing,genomics,illumina,ngs,samplesheet,sequencing
|
|
30
|
+
Keywords: aviti,bcl2fastq,bclconvert,bioinformatics,color-balance,demultiplexing,element,genomics,illumina,multi-vendor,ngs,run-manifest,samplesheet,sequencing
|
|
31
31
|
Classifier: Development Status :: 5 - Production/Stable
|
|
32
32
|
Classifier: Intended Audience :: Developers
|
|
33
33
|
Classifier: Intended Audience :: Science/Research
|
|
@@ -58,7 +58,7 @@ Description-Content-Type: text/markdown
|
|
|
58
58
|
|
|
59
59
|
**Format-agnostic parser for Illumina SampleSheet.csv files.**
|
|
60
60
|
|
|
61
|
-
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
61
|
+
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — plus non-Illumina **Element AVITI** run manifests — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
62
62
|
|
|
63
63
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
64
64
|
[](https://www.python.org/downloads/)
|
|
@@ -74,15 +74,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
|
|
|
74
74
|
|
|
75
75
|

|
|
76
76
|
|
|
77
|
-
*`SampleSheetFactory` auto-detects the format and routes to the correct parser.
|
|
77
|
+
*`SampleSheetFactory` auto-detects the format — Illumina V1/V2 or an Element AVITI run manifest — and routes to the correct parser. All formats share a common interface — `SampleSheetConverter` handles bidirectional conversion between the Illumina formats, `SampleSheetValidator` catches index, adapter, and color-balance issues, `SampleSheetDiff` compares two sheets across any combination of formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
|
|
78
78
|
|
|
79
79
|
---
|
|
80
80
|
|
|
81
81
|
## The problem this solves
|
|
82
82
|
|
|
83
|
-
Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce
|
|
83
|
+
Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
|
|
84
84
|
|
|
85
|
-
Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for
|
|
85
|
+
Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
|
|
86
86
|
|
|
87
87
|
---
|
|
88
88
|
|
|
@@ -110,7 +110,7 @@ from samplesheet_parser import SampleSheetFactory
|
|
|
110
110
|
factory = SampleSheetFactory()
|
|
111
111
|
sheet = factory.create_parser("SampleSheet.csv", parse=True)
|
|
112
112
|
|
|
113
|
-
print(factory.version) # SampleSheetVersion.V1 or .
|
|
113
|
+
print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
|
|
114
114
|
print(sheet.index_type()) # "dual", "single", or "none"
|
|
115
115
|
|
|
116
116
|
for sample in sheet.samples():
|
|
@@ -368,6 +368,8 @@ The detector reads only as much of the file as needed — stopping after `[Heade
|
|
|
368
368
|
| `INDEX_DISTANCE_TOO_LOW` | warning | Two indexes in the same lane have Hamming distance < 3, risking demultiplexing bleed-through |
|
|
369
369
|
| `NO_ADAPTERS` | warning | No adapter sequences configured |
|
|
370
370
|
| `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
|
|
371
|
+
| `COLOR_BALANCE_NO_SIGNAL` | error | An index cycle has no signal in an optical channel (2-/1-channel chemistry) — the index read will fail. *Opt-in.* |
|
|
372
|
+
| `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) — degraded base calls. *Opt-in.* |
|
|
371
373
|
|
|
372
374
|
### Index distance checking
|
|
373
375
|
|
|
@@ -397,6 +399,95 @@ result = ValidationResult()
|
|
|
397
399
|
SampleSheetValidator()._check_index_distances(samples, result, min_distance=4)
|
|
398
400
|
```
|
|
399
401
|
|
|
402
|
+
### Color-balance checking (opt-in)
|
|
403
|
+
|
|
404
|
+
On 2-channel instruments (NextSeq, NovaSeq, NovaSeq X) and 1-channel
|
|
405
|
+
instruments (iSeq), bases are called from optical signal: `A` lights
|
|
406
|
+
both channels, `C` only red, `T` only green, and **`G` is a dark base with no
|
|
407
|
+
signal at all**. A cycle where the whole index pool reads `G` produces no
|
|
408
|
+
signal, so the instrument cannot register the tile and the index read fails —
|
|
409
|
+
a real, common cause of wrecked runs that a Hamming-distance check cannot see.
|
|
410
|
+
|
|
411
|
+
Because the sample sheet already contains every sample's index, this can be
|
|
412
|
+
predicted *before the run starts* with no sequencing data. The validator scores
|
|
413
|
+
the pool cycle-by-cycle: it transposes the indexes into columns and checks that
|
|
414
|
+
each column produces signal in both channels.
|
|
415
|
+
|
|
416
|
+
```python
|
|
417
|
+
from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
|
|
418
|
+
|
|
419
|
+
sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=True)
|
|
420
|
+
|
|
421
|
+
# Opt in; the instrument is read from the sheet header (or pass instrument=...)
|
|
422
|
+
result = SampleSheetValidator().validate(sheet, check_color_balance=True)
|
|
423
|
+
|
|
424
|
+
for err in result.errors:
|
|
425
|
+
print(err)
|
|
426
|
+
# [ERROR] COLOR_BALANCE_NO_SIGNAL: On 2-channel chemistry (NovaSeqXSeries),
|
|
427
|
+
# index1 cycle 4 has no red or green signal across the pool: no sample
|
|
428
|
+
# carries a red or green base (A/C/T) at this cycle ... the index read will fail.
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
The chemistry is resolved from the instrument name; the check is **off by
|
|
432
|
+
default** (it can legitimately fail a low-plex pool) and is skipped silently
|
|
433
|
+
for unknown instruments. The same analysis is available standalone:
|
|
434
|
+
|
|
435
|
+
```python
|
|
436
|
+
from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
|
|
437
|
+
|
|
438
|
+
chem = chemistry_for_instrument("NovaSeqXSeries") # Chemistry.TWO_CHANNEL
|
|
439
|
+
report = analyze_color_balance(["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"],
|
|
440
|
+
chemistry=chem)
|
|
441
|
+
for cb in report.dark_cycles:
|
|
442
|
+
print(cb.read, cb.cycle, cb.base_counts) # index1 4 {'G': 4}
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
From the CLI:
|
|
446
|
+
|
|
447
|
+
```bash
|
|
448
|
+
samplesheet validate SampleSheet.csv --color-balance
|
|
449
|
+
samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
| Chemistry | Instruments | What is flagged |
|
|
453
|
+
|---|---|---|
|
|
454
|
+
| 4-channel | MiSeq, HiSeq 2000/2500/3000/4000, Element AVITI | Zero-diversity cycles (warning) |
|
|
455
|
+
| 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | Dark cycles / weak channels |
|
|
456
|
+
| 1-channel | iSeq 100 | Dark cycles / weak channels |
|
|
457
|
+
|
|
458
|
+
Element AVITI uses four-channel avidity chemistry (four images per cycle, one
|
|
459
|
+
per avidite dye — [Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7)),
|
|
460
|
+
so it has no dark base; color-balance checking flags low-diversity index
|
|
461
|
+
cycles rather than dark cycles.
|
|
462
|
+
|
|
463
|
+
---
|
|
464
|
+
|
|
465
|
+
## Multi-vendor support
|
|
466
|
+
|
|
467
|
+
The factory is not limited to Illumina. Any parser that implements the
|
|
468
|
+
`SampleSheetParser` protocol can be auto-detected, and **Element Biosciences
|
|
469
|
+
AVITI `RunManifest.csv`** files are supported out of the box — the same
|
|
470
|
+
`SampleSheetFactory` recognises them and returns a parser with the identical
|
|
471
|
+
interface:
|
|
472
|
+
|
|
473
|
+
```python
|
|
474
|
+
from samplesheet_parser import SampleSheetFactory
|
|
475
|
+
|
|
476
|
+
factory = SampleSheetFactory()
|
|
477
|
+
sheet = factory.create_parser("RunManifest.csv", parse=True)
|
|
478
|
+
|
|
479
|
+
print(factory.version) # SampleSheetVersion.ELEMENT_AVITI
|
|
480
|
+
print(sheet.index_type()) # "dual"
|
|
481
|
+
for s in sheet.samples(): # same schema as Illumina: sample_id, index, index2, ...
|
|
482
|
+
print(s["sample_id"], s["index"], s["index2"])
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
AVITI is a four-channel avidity platform, so color-balance validation applies
|
|
486
|
+
to it too (flagging low-diversity index cycles). Manifest columns
|
|
487
|
+
(`SampleName`, `Index1`, `Index2`, `Lane`, `Project`, `ExternalID`) are mapped
|
|
488
|
+
to the shared sample schema, so the validator, diff, and filter tooling work
|
|
489
|
+
across vendors without special-casing.
|
|
490
|
+
|
|
400
491
|
---
|
|
401
492
|
|
|
402
493
|
## Merger conflict and warning codes
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**Format-agnostic parser for Illumina SampleSheet.csv files.**
|
|
4
4
|
|
|
5
|
-
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
5
|
+
Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConvert V2 format (NovaSeq X series) — plus non-Illumina **Element AVITI** run manifests — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, diff comparison, multi-sheet merging, programmatic sheet creation, and a full-featured CLI.
|
|
6
6
|
|
|
7
7
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
8
8
|
[](https://www.python.org/downloads/)
|
|
@@ -18,15 +18,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
|
|
|
18
18
|
|
|
19
19
|

|
|
20
20
|
|
|
21
|
-
*`SampleSheetFactory` auto-detects the format and routes to the correct parser.
|
|
21
|
+
*`SampleSheetFactory` auto-detects the format — Illumina V1/V2 or an Element AVITI run manifest — and routes to the correct parser. All formats share a common interface — `SampleSheetConverter` handles bidirectional conversion between the Illumina formats, `SampleSheetValidator` catches index, adapter, and color-balance issues, `SampleSheetDiff` compares two sheets across any combination of formats, `SampleSheetMerger` combines multiple per-project sheets into one, and `SampleSheetWriter` builds or edits sheets programmatically. The `samplesheet` CLI exposes all of this from the shell.*
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
25
25
|
## The problem this solves
|
|
26
26
|
|
|
27
|
-
Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce
|
|
27
|
+
Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
|
|
28
28
|
|
|
29
|
-
Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for
|
|
29
|
+
Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
|
|
30
30
|
|
|
31
31
|
---
|
|
32
32
|
|
|
@@ -54,7 +54,7 @@ from samplesheet_parser import SampleSheetFactory
|
|
|
54
54
|
factory = SampleSheetFactory()
|
|
55
55
|
sheet = factory.create_parser("SampleSheet.csv", parse=True)
|
|
56
56
|
|
|
57
|
-
print(factory.version) # SampleSheetVersion.V1 or .
|
|
57
|
+
print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
|
|
58
58
|
print(sheet.index_type()) # "dual", "single", or "none"
|
|
59
59
|
|
|
60
60
|
for sample in sheet.samples():
|
|
@@ -312,6 +312,8 @@ The detector reads only as much of the file as needed — stopping after `[Heade
|
|
|
312
312
|
| `INDEX_DISTANCE_TOO_LOW` | warning | Two indexes in the same lane have Hamming distance < 3, risking demultiplexing bleed-through |
|
|
313
313
|
| `NO_ADAPTERS` | warning | No adapter sequences configured |
|
|
314
314
|
| `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
|
|
315
|
+
| `COLOR_BALANCE_NO_SIGNAL` | error | An index cycle has no signal in an optical channel (2-/1-channel chemistry) — the index read will fail. *Opt-in.* |
|
|
316
|
+
| `COLOR_BALANCE_LOW` | warning | An index cycle has weak signal in a channel, or no base diversity (4-channel) — degraded base calls. *Opt-in.* |
|
|
315
317
|
|
|
316
318
|
### Index distance checking
|
|
317
319
|
|
|
@@ -341,6 +343,95 @@ result = ValidationResult()
|
|
|
341
343
|
SampleSheetValidator()._check_index_distances(samples, result, min_distance=4)
|
|
342
344
|
```
|
|
343
345
|
|
|
346
|
+
### Color-balance checking (opt-in)
|
|
347
|
+
|
|
348
|
+
On 2-channel instruments (NextSeq, NovaSeq, NovaSeq X) and 1-channel
|
|
349
|
+
instruments (iSeq), bases are called from optical signal: `A` lights
|
|
350
|
+
both channels, `C` only red, `T` only green, and **`G` is a dark base with no
|
|
351
|
+
signal at all**. A cycle where the whole index pool reads `G` produces no
|
|
352
|
+
signal, so the instrument cannot register the tile and the index read fails —
|
|
353
|
+
a real, common cause of wrecked runs that a Hamming-distance check cannot see.
|
|
354
|
+
|
|
355
|
+
Because the sample sheet already contains every sample's index, this can be
|
|
356
|
+
predicted *before the run starts* with no sequencing data. The validator scores
|
|
357
|
+
the pool cycle-by-cycle: it transposes the indexes into columns and checks that
|
|
358
|
+
each column produces signal in both channels.
|
|
359
|
+
|
|
360
|
+
```python
|
|
361
|
+
from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
|
|
362
|
+
|
|
363
|
+
sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=True)
|
|
364
|
+
|
|
365
|
+
# Opt in; the instrument is read from the sheet header (or pass instrument=...)
|
|
366
|
+
result = SampleSheetValidator().validate(sheet, check_color_balance=True)
|
|
367
|
+
|
|
368
|
+
for err in result.errors:
|
|
369
|
+
print(err)
|
|
370
|
+
# [ERROR] COLOR_BALANCE_NO_SIGNAL: On 2-channel chemistry (NovaSeqXSeries),
|
|
371
|
+
# index1 cycle 4 has no red or green signal across the pool: no sample
|
|
372
|
+
# carries a red or green base (A/C/T) at this cycle ... the index read will fail.
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
The chemistry is resolved from the instrument name; the check is **off by
|
|
376
|
+
default** (it can legitimately fail a low-plex pool) and is skipped silently
|
|
377
|
+
for unknown instruments. The same analysis is available standalone:
|
|
378
|
+
|
|
379
|
+
```python
|
|
380
|
+
from samplesheet_parser import analyze_color_balance, chemistry_for_instrument
|
|
381
|
+
|
|
382
|
+
chem = chemistry_for_instrument("NovaSeqXSeries") # Chemistry.TWO_CHANNEL
|
|
383
|
+
report = analyze_color_balance(["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"],
|
|
384
|
+
chemistry=chem)
|
|
385
|
+
for cb in report.dark_cycles:
|
|
386
|
+
print(cb.read, cb.cycle, cb.base_counts) # index1 4 {'G': 4}
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
From the CLI:
|
|
390
|
+
|
|
391
|
+
```bash
|
|
392
|
+
samplesheet validate SampleSheet.csv --color-balance
|
|
393
|
+
samplesheet validate SampleSheet.csv --color-balance --instrument NovaSeqXSeries
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
| Chemistry | Instruments | What is flagged |
|
|
397
|
+
|---|---|---|
|
|
398
|
+
| 4-channel | MiSeq, HiSeq 2000/2500/3000/4000, Element AVITI | Zero-diversity cycles (warning) |
|
|
399
|
+
| 2-channel | NextSeq, NovaSeq 6000, NovaSeq X, MiniSeq | Dark cycles / weak channels |
|
|
400
|
+
| 1-channel | iSeq 100 | Dark cycles / weak channels |
|
|
401
|
+
|
|
402
|
+
Element AVITI uses four-channel avidity chemistry (four images per cycle, one
|
|
403
|
+
per avidite dye — [Arslan et al., *Nat. Biotechnol.* 2023](https://www.nature.com/articles/s41587-023-01750-7)),
|
|
404
|
+
so it has no dark base; color-balance checking flags low-diversity index
|
|
405
|
+
cycles rather than dark cycles.
|
|
406
|
+
|
|
407
|
+
---
|
|
408
|
+
|
|
409
|
+
## Multi-vendor support
|
|
410
|
+
|
|
411
|
+
The factory is not limited to Illumina. Any parser that implements the
|
|
412
|
+
`SampleSheetParser` protocol can be auto-detected, and **Element Biosciences
|
|
413
|
+
AVITI `RunManifest.csv`** files are supported out of the box — the same
|
|
414
|
+
`SampleSheetFactory` recognises them and returns a parser with the identical
|
|
415
|
+
interface:
|
|
416
|
+
|
|
417
|
+
```python
|
|
418
|
+
from samplesheet_parser import SampleSheetFactory
|
|
419
|
+
|
|
420
|
+
factory = SampleSheetFactory()
|
|
421
|
+
sheet = factory.create_parser("RunManifest.csv", parse=True)
|
|
422
|
+
|
|
423
|
+
print(factory.version) # SampleSheetVersion.ELEMENT_AVITI
|
|
424
|
+
print(sheet.index_type()) # "dual"
|
|
425
|
+
for s in sheet.samples(): # same schema as Illumina: sample_id, index, index2, ...
|
|
426
|
+
print(s["sample_id"], s["index"], s["index2"])
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
AVITI is a four-channel avidity platform, so color-balance validation applies
|
|
430
|
+
to it too (flagging low-diversity index cycles). Manifest columns
|
|
431
|
+
(`SampleName`, `Index1`, `Index2`, `Lane`, `Project`, `ExternalID`) are mapped
|
|
432
|
+
to the shared sample schema, so the validator, diff, and filter tooling work
|
|
433
|
+
across vendors without special-casing.
|
|
434
|
+
|
|
344
435
|
---
|
|
345
436
|
|
|
346
437
|
## Merger conflict and warning codes
|
|
@@ -21,7 +21,7 @@ from samplesheet_parser import SampleSheetFactory
|
|
|
21
21
|
factory = SampleSheetFactory()
|
|
22
22
|
sheet = factory.create_parser("SampleSheet.csv", parse=True)
|
|
23
23
|
|
|
24
|
-
print(factory.version) # SampleSheetVersion.V1 or .
|
|
24
|
+
print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
|
|
25
25
|
print(sheet.index_type()) # "dual", "single", or "none"
|
|
26
26
|
print(sheet.experiment_name)
|
|
27
27
|
|
|
@@ -52,6 +52,34 @@ for err in result.errors:
|
|
|
52
52
|
result = SampleSheetValidator().validate(sheet, min_hamming_distance=4)
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
+
See `examples/demo_color_balance.py` for the opt-in per-cycle color-balance
|
|
56
|
+
check (`validate(..., check_color_balance=True)`).
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Multi-vendor (Element AVITI)
|
|
61
|
+
|
|
62
|
+
The same factory that detects Illumina V1/V2 sheets also auto-detects a
|
|
63
|
+
non-Illumina Element AVITI `RunManifest.csv` and returns a parser with the
|
|
64
|
+
identical interface. Demo: `examples/demo_element_aviti.py`.
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
|
|
68
|
+
|
|
69
|
+
sheet = SampleSheetFactory().create_parser(
|
|
70
|
+
"examples/sample_sheets/element_aviti_RunManifest.csv", parse=True
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
print(sheet.index_type()) # "dual"
|
|
74
|
+
for s in sheet.samples():
|
|
75
|
+
print(s["sample_id"], s["index"], s["index2"])
|
|
76
|
+
|
|
77
|
+
# Color balance works here too — AVITI resolves to four-channel chemistry,
|
|
78
|
+
# so zero-diversity cycles surface as COLOR_BALANCE_LOW warnings.
|
|
79
|
+
result = SampleSheetValidator().validate(sheet, check_color_balance=True)
|
|
80
|
+
print(result.summary())
|
|
81
|
+
```
|
|
82
|
+
|
|
55
83
|
---
|
|
56
84
|
|
|
57
85
|
## Conversion
|
|
@@ -2,13 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## Format auto-detection
|
|
4
4
|
|
|
5
|
-
`SampleSheetFactory`
|
|
5
|
+
`SampleSheetFactory` detects the format across vendors — no format hints required from the caller:
|
|
6
6
|
|
|
7
|
-
1. **
|
|
8
|
-
2. **
|
|
9
|
-
3. **
|
|
7
|
+
1. **Vendor manifest check** — recognize a non-Illumina Element AVITI `RunManifest.csv` by its `[SAMPLES]` section combined with a `[RUNVALUES]` section or a `SampleName` column (→ `ELEMENT_AVITI`)
|
|
8
|
+
2. **Header discriminator** — scan `[Header]` for `FileFormatVersion` (→ V2) or `IEMFileVersion` (→ V1)
|
|
9
|
+
3. **Section name scan** — if no header key found, look for `[BCLConvert_Settings]` / `[BCLConvert_Data]` in the full file (→ V2)
|
|
10
|
+
4. **Default** — fall back to V1 (broadest compatibility with legacy files)
|
|
10
11
|
|
|
11
|
-
The detector reads only as much of the file as needed — stopping after `[Header]` in the common case.
|
|
12
|
+
The detector reads only as much of the file as needed — stopping after `[Header]` in the common case for Illumina sheets.
|
|
12
13
|
|
|
13
14
|
```python
|
|
14
15
|
from samplesheet_parser import SampleSheetFactory
|
|
@@ -16,7 +17,7 @@ from samplesheet_parser import SampleSheetFactory
|
|
|
16
17
|
factory = SampleSheetFactory()
|
|
17
18
|
sheet = factory.create_parser("SampleSheet.csv", parse=True)
|
|
18
19
|
|
|
19
|
-
print(factory.version) # SampleSheetVersion.V1 or .
|
|
20
|
+
print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
|
|
20
21
|
```
|
|
21
22
|
|
|
22
23
|
## V1 parser
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Auto-detect format (recommended)
|
|
4
4
|
|
|
5
|
-
The simplest entry point. `SampleSheetFactory` detects V1
|
|
5
|
+
The simplest entry point. `SampleSheetFactory` detects the format automatically — Illumina V1, V2, or an Element AVITI run manifest — and returns the correct parser.
|
|
6
6
|
|
|
7
7
|
```python
|
|
8
8
|
from samplesheet_parser import SampleSheetFactory
|
|
@@ -10,7 +10,7 @@ from samplesheet_parser import SampleSheetFactory
|
|
|
10
10
|
factory = SampleSheetFactory()
|
|
11
11
|
sheet = factory.create_parser("SampleSheet.csv", parse=True)
|
|
12
12
|
|
|
13
|
-
print(factory.version) # SampleSheetVersion.V1 or .
|
|
13
|
+
print(factory.version) # SampleSheetVersion.V1, .V2, or .ELEMENT_AVITI
|
|
14
14
|
print(sheet.index_type()) # "dual", "single", or "none"
|
|
15
15
|
|
|
16
16
|
for sample in sheet.samples():
|
|
@@ -31,6 +31,10 @@ for w in result.warnings:
|
|
|
31
31
|
| `INDEX_DISTANCE_TOO_LOW` | warning | Hamming distance between two indexes < threshold |
|
|
32
32
|
| `NO_ADAPTERS` | warning | No adapter sequences configured |
|
|
33
33
|
| `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
|
|
34
|
+
| `COLOR_BALANCE_NO_SIGNAL` | error | A 2-/1-channel index cycle produces no optical signal (opt-in) |
|
|
35
|
+
| `COLOR_BALANCE_LOW` | warning | An index cycle has weak channel signal or zero diversity (opt-in) |
|
|
36
|
+
|
|
37
|
+
The last two checks are **opt-in** — see [Color-balance checking](#color-balance-checking) below.
|
|
34
38
|
|
|
35
39
|
## Index distance checking
|
|
36
40
|
|
|
@@ -50,6 +54,32 @@ result = SampleSheetValidator().validate(sheet, min_hamming_distance=4)
|
|
|
50
54
|
|
|
51
55
|
The standalone helpers are also available: `hamming_distance(a, b)` for the literal Hamming distance and `index_collision_distance(a, b)` for the wildcard-aware per-index distance the validator uses.
|
|
52
56
|
|
|
57
|
+
## Color-balance checking
|
|
58
|
+
|
|
59
|
+
Optical sequencers read each index base by its fluorescent signal, and the number of channels differs by instrument: four-channel (MiSeq, HiSeq, Element AVITI), two-channel (NextSeq, NovaSeq 6000, NovaSeq X), and one-channel (iSeq). On two-channel chemistry the base `G` is "dark" — no dye — so an index cycle where the **entire pool** reads `G` emits no signal and the cycle fails to register, miscalling every barcode at that position. A Hamming-distance check cannot catch this because the indexes may still be perfectly distinct.
|
|
60
|
+
|
|
61
|
+
`samplesheet-parser` models each instrument's chemistry and scores the pool cycle-by-cycle. The check is **opt-in** because it can turn a passing sheet into a failing one, and it needs to know the instrument:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
result = SampleSheetValidator().validate(
|
|
65
|
+
sheet,
|
|
66
|
+
check_color_balance=True,
|
|
67
|
+
instrument="NovaSeq X", # optional; inferred from the sheet header when present
|
|
68
|
+
)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- On **two-/one-channel** instruments, an all-`G` (no-signal) cycle is a `COLOR_BALANCE_NO_SIGNAL` error and a channel below `min_signal_fraction` (default 0.10) is a `COLOR_BALANCE_LOW` warning.
|
|
72
|
+
- On **four-channel** instruments (including Element AVITI, an avidity platform with no dark base), there is no no-signal failure mode; a zero-diversity cycle — where the whole pool reads one base — is reported as a `COLOR_BALANCE_LOW` warning instead.
|
|
73
|
+
- If the instrument is unknown, the check is skipped silently.
|
|
74
|
+
|
|
75
|
+
The CLI exposes the same check:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
samplesheet validate SampleSheet.csv --color-balance --instrument "NovaSeq X"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The underlying API — `Chemistry`, `chemistry_for_instrument()`, and `analyze_color_balance()` returning a `ColorBalanceReport` — is public and usable on its own.
|
|
82
|
+
|
|
53
83
|
## Structured results
|
|
54
84
|
|
|
55
85
|
```python
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# samplesheet-parser
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Multi-vendor, format-agnostic parser for sequencing sample sheets.**
|
|
4
4
|
|
|
5
|
-
Supports
|
|
5
|
+
Supports the classic Illumina IEM V1 format (bcl2fastq era), the modern BCLConvert V2 format (NovaSeq X series), and non-Illumina **Element AVITI** run manifests behind one interface — with automatic format detection, bidirectional conversion, index validation, Hamming distance checking, **per-cycle color-balance validation** against the instrument's optical chemistry, diff comparison, multi-sheet merging, splitting, filtering, programmatic sheet creation, and a full-featured CLI.
|
|
6
6
|
|
|
7
7
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
8
8
|
[](https://www.python.org/downloads/)
|
|
@@ -17,9 +17,9 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
|
|
|
17
17
|
|
|
18
18
|
## The problem this solves
|
|
19
19
|
|
|
20
|
-
Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series — produce
|
|
20
|
+
Labs running mixed instrument fleets — older NovaSeq 6000 alongside newer NovaSeq X series, and increasingly non-Illumina platforms like the Element AVITI — produce several incompatible sample-sheet formats. BCLConvert V2 sheets use `[BCLConvert_Settings]` / `[BCLConvert_Data]` sections, `OverrideCycles` for UMI encoding, and `FileFormatVersion` in the header. IEM V1 sheets use `IEMFileVersion` and a flat `[Data]` section. Element AVITI ships a `RunManifest.csv` with an entirely different layout.
|
|
21
21
|
|
|
22
|
-
Existing tools either hard-code one format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format, exposes a consistent interface for
|
|
22
|
+
Existing tools either hard-code one vendor's format or require the caller to know which format they have. `samplesheet-parser` auto-detects the format across vendors, exposes a consistent interface for all of them, converts between the Illumina formats, validates index integrity (including Hamming distance and per-cycle color balance against each instrument's optical chemistry), diffs sheets to catch accidental changes before a run starts, and writes new sheets programmatically — so you never have to hand-edit a CSV again.
|
|
23
23
|
|
|
24
24
|
---
|
|
25
25
|
|
|
@@ -27,10 +27,12 @@ Existing tools either hard-code one format or require the caller to know which f
|
|
|
27
27
|
|
|
28
28
|
| Feature | Description |
|
|
29
29
|
|---|---|
|
|
30
|
-
| **Auto-detection** |
|
|
31
|
-
| **V1 &
|
|
30
|
+
| **Auto-detection** | Format detection across vendors — no hints required |
|
|
31
|
+
| **V1, V2 & AVITI parsing** | Consistent `samples()` / `index_type()` interface for Illumina V1/V2 and Element AVITI run manifests |
|
|
32
|
+
| **Multi-vendor** | Element Biosciences AVITI `RunManifest.csv` parsed through the same `SampleSheetParser` protocol |
|
|
32
33
|
| **Bidirectional conversion** | V1 → V2 and V2 → V1 (lossy, with warnings) |
|
|
33
|
-
| **Validation** |
|
|
34
|
+
| **Validation** | Index chars, length, duplicates, Hamming distance, adapters |
|
|
35
|
+
| **Color balance** | Opt-in per-cycle optical-signal check against 4-/2-/1-channel instrument chemistry |
|
|
34
36
|
| **Diff** | Cross-format structural comparison with per-field change records |
|
|
35
37
|
| **Merge** | Combine multiple per-project sheets with collision detection |
|
|
36
38
|
| **Split** | Divide a combined sheet into per-project or per-lane files |
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Demo: colour-balance validation on a 2-channel instrument.
|
|
3
|
+
|
|
4
|
+
Colour balance is a property of the *index sequences* in the sheet, so it can
|
|
5
|
+
be predicted before a run starts - no sequencing data required. On 2-channel
|
|
6
|
+
chemistry (NextSeq, NovaSeq, AVITI) ``G`` is a dark base: a cycle where every
|
|
7
|
+
sample reads ``G`` produces no optical signal and the index read fails.
|
|
8
|
+
|
|
9
|
+
This builds a small NovaSeq X pool that is fine on Hamming distance but has a
|
|
10
|
+
dark cycle, and shows the validator catching it.
|
|
11
|
+
|
|
12
|
+
Run with: python3 examples/demo_color_balance.py
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import tempfile
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
from samplesheet_parser import (
|
|
21
|
+
SampleSheetFactory,
|
|
22
|
+
SampleSheetValidator,
|
|
23
|
+
analyze_color_balance,
|
|
24
|
+
chemistry_for_instrument,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
# A NovaSeq X (2-channel) pool. Look down each column of the I7 index:
|
|
28
|
+
# every sample reads 'G' at cycle 3 and cycle 4 -> a dark, no-signal cycle.
|
|
29
|
+
# The indexes are still far apart in Hamming distance, so the usual index
|
|
30
|
+
# checks would pass this sheet.
|
|
31
|
+
SHEET = """\
|
|
32
|
+
[Header]
|
|
33
|
+
FileFormatVersion,2
|
|
34
|
+
RunName,DarkCycleDemo
|
|
35
|
+
InstrumentPlatform,NovaSeqXSeries
|
|
36
|
+
|
|
37
|
+
[Reads]
|
|
38
|
+
Read1Cycles,151
|
|
39
|
+
Read2Cycles,151
|
|
40
|
+
Index1Cycles,8
|
|
41
|
+
Index2Cycles,8
|
|
42
|
+
|
|
43
|
+
[BCLConvert_Settings]
|
|
44
|
+
AdapterRead1,CTGTCTCTTATACACATCT
|
|
45
|
+
|
|
46
|
+
[BCLConvert_Data]
|
|
47
|
+
Sample_ID,Index,Index2
|
|
48
|
+
S1,ATGGCTAC,TATAGCCT
|
|
49
|
+
S2,CAGGTACG,ATAGAGGC
|
|
50
|
+
S3,TCGGACGT,CCTATCCT
|
|
51
|
+
S4,GATGGCTA,GGCTCTGA
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def main() -> None:
|
|
56
|
+
print("Chemistry for 'NovaSeqXSeries':", chemistry_for_instrument("NovaSeqXSeries").value)
|
|
57
|
+
print()
|
|
58
|
+
|
|
59
|
+
# The standalone analyzer, straight on the index list:
|
|
60
|
+
index1 = ["ATGGCTAC", "CAGGTACG", "TCGGACGT", "GATGGCTA"]
|
|
61
|
+
report = analyze_color_balance(index1, chemistry=chemistry_for_instrument("NovaSeqXSeries"))
|
|
62
|
+
print(f"Pool of {report.pool_size} samples - per-cycle scan of I7:")
|
|
63
|
+
for cb in report.cycles:
|
|
64
|
+
flag = " <-- DARK (no signal)" if cb.is_dark else ""
|
|
65
|
+
print(
|
|
66
|
+
f" cycle {cb.cycle}: {cb.base_counts} "
|
|
67
|
+
f"red={cb.red_fraction:.0%} green={cb.green_fraction:.0%}{flag}"
|
|
68
|
+
)
|
|
69
|
+
print()
|
|
70
|
+
|
|
71
|
+
# End to end through the factory + validator:
|
|
72
|
+
with tempfile.TemporaryDirectory() as tmp:
|
|
73
|
+
path = Path(tmp) / "SampleSheet.csv"
|
|
74
|
+
path.write_text(SHEET)
|
|
75
|
+
|
|
76
|
+
sheet = SampleSheetFactory().create_parser(path, parse=True)
|
|
77
|
+
result = SampleSheetValidator().validate(sheet, check_color_balance=True)
|
|
78
|
+
|
|
79
|
+
print(result.summary())
|
|
80
|
+
for issue in result.errors + result.warnings:
|
|
81
|
+
print(f" {issue}")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
if __name__ == "__main__":
|
|
85
|
+
main()
|