samplesheet-parser 1.3.0__tar.gz → 2.1.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-1.3.0 → samplesheet_parser-2.1.0}/.github/workflows/ci.yml +2 -3
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.pre-commit-config.yaml +6 -2
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.zenodo.json +1 -1
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/CHANGELOG.md +114 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/CITATION.cff +2 -2
- samplesheet_parser-2.1.0/Makefile +81 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/PKG-INFO +48 -17
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/README.md +43 -14
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/api.md +41 -3
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/parsing.md +31 -2
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/validation.md +8 -4
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/index.md +1 -1
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/installation.md +2 -2
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/environment.yml +1 -1
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/main.nf +4 -14
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/meta.yml +31 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +10 -10
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/diff/environment.yml +1 -1
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/diff/main.nf +34 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/diff/meta.yml +28 -13
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +10 -10
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test.snap +80 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/environment.yml +1 -1
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/main.nf +5 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/meta.yml +32 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +5 -5
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/info/environment.yml +1 -1
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/info/main.nf +34 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/info/meta.yml +28 -13
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/info/tests/main.nf.test +7 -7
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test.snap +80 -0
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/merge/environment.yml +6 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/merge/main.nf +5 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/merge/meta.yml +32 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +10 -10
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/split/environment.yml +6 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/split/main.nf +5 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/split/meta.yml +32 -15
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/split/tests/main.nf.test +7 -7
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/validate/main.nf +34 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/validate/meta.yml +28 -13
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +7 -7
- samplesheet_parser-2.1.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test.snap +80 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/pyproject.toml +15 -8
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/__init__.py +12 -3
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/cli.py +7 -5
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/converter.py +18 -13
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/diff.py +56 -55
- samplesheet_parser-2.1.0/samplesheet_parser/enums.py +55 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/factory.py +106 -30
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/filter.py +6 -5
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/index_utils.py +3 -3
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/instruments.py +40 -9
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/merger.py +30 -29
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/parsers/v1.py +97 -101
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/parsers/v2.py +245 -168
- samplesheet_parser-2.1.0/samplesheet_parser/protocol.py +102 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/splitter.py +6 -5
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/validators.py +135 -72
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/writer.py +14 -12
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/conftest.py +2 -2
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_cli.py +6 -6
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_converter.py +4 -4
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_diff.py +101 -41
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_factory.py +72 -4
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_filter.py +11 -11
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_index_utils.py +7 -3
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_instruments.py +1 -1
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_merger.py +111 -84
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_parsers/test_v1.py +25 -28
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_parsers/test_v2.py +51 -24
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_splitter.py +11 -11
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_validators/test_hamming.py +289 -85
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_validators/test_validators.py +39 -11
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_writer.py +23 -8
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/main.nf +0 -45
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/main.nf +0 -45
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/environment.yml +0 -6
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/environment.yml +0 -6
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/environment.yml +0 -6
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/main.nf +0 -45
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +0 -4
- samplesheet_parser-1.3.0/samplesheet_parser/enums.py +0 -51
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.github/workflows/copilot-instructions.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.gitignore +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/.readthedocs.yaml +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/CONTRIBUTING.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/LICENSE +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/changelog.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/ci.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/cli.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/contributing.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/examples.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/conversion.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/diffing.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/filtering.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/index_utils.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/merging.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/quickstart.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/splitting.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/guide/writing.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/docs/requirements.txt +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_converter.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_diff.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_filter.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_index_utils.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_merger.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_splitter.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/demo_writer.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/parse_examples.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/README.md +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/combined_clean.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_single_index.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/images/samplesheet_parser_arch_v03.png +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/images/samplesheet_parser_overview.png +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/mkdocs.yml +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/recipes/meta.yaml +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/parsers/__init__.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/samplesheet_parser/py.typed +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/scripts/demo_converter.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/scripts/demo_diff.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/scripts/demo_writer.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/__init__.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_parsers/__init__.py +0 -0
- {samplesheet_parser-1.3.0 → samplesheet_parser-2.1.0}/tests/test_validators/__init__.py +0 -0
|
@@ -30,11 +30,10 @@ jobs:
|
|
|
30
30
|
run: ruff check samplesheet_parser/
|
|
31
31
|
|
|
32
32
|
- name: Type check with mypy
|
|
33
|
-
run: mypy samplesheet_parser/ --ignore-missing-imports
|
|
34
|
-
continue-on-error: true
|
|
33
|
+
run: mypy samplesheet_parser/ --strict --ignore-missing-imports
|
|
35
34
|
|
|
36
35
|
- name: Run tests
|
|
37
|
-
run: pytest tests/ -v --cov=samplesheet_parser --cov-report=xml
|
|
36
|
+
run: pytest tests/ -v -W error::DeprecationWarning --cov=samplesheet_parser --cov-report=xml
|
|
38
37
|
|
|
39
38
|
- name: Upload coverage to Codecov
|
|
40
39
|
uses: codecov/codecov-action@v4
|
|
@@ -26,5 +26,9 @@ repos:
|
|
|
26
26
|
rev: v1.13.0
|
|
27
27
|
hooks:
|
|
28
28
|
- id: mypy
|
|
29
|
-
additional_dependencies: [
|
|
30
|
-
|
|
29
|
+
additional_dependencies: [typer]
|
|
30
|
+
# Type-check the package only, matching CI. Tests are intentionally
|
|
31
|
+
# exempt (see the tests.* override in pyproject.toml); passing
|
|
32
|
+
# individual test file paths here would bypass that override.
|
|
33
|
+
pass_filenames: false
|
|
34
|
+
args: [--strict, --ignore-missing-imports, samplesheet_parser/]
|
|
@@ -8,6 +8,120 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
_No unreleased changes._
|
|
12
|
+
|
|
13
|
+
## [2.1.0] - 2026-06-09
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- **Format auto-detection now scans the whole file.** The V2 fallback that
|
|
18
|
+
looks for `[BCLConvert_Settings]` / `[BCLConvert_Data]` previously stopped
|
|
19
|
+
reading at the first section after `[Header]`, so a V2 sheet that lacked
|
|
20
|
+
`FileFormatVersion` and placed those sections after `[Reads]` was misdetected
|
|
21
|
+
as V1. Detection now reads the full file (sheets are small) before falling
|
|
22
|
+
back, and matches the BCLConvert section names case-insensitively so a sheet
|
|
23
|
+
using e.g. `[bclconvert_data]` is detected as V2.
|
|
24
|
+
- **Index-free libraries no longer raise `DUPLICATE_INDEX`.** A full-lane
|
|
25
|
+
library where every sample has an empty index was incorrectly flagged as a
|
|
26
|
+
duplicate. Samples with no index are now skipped in the duplicate-index
|
|
27
|
+
check.
|
|
28
|
+
- **Duplicate-index detection is now case-insensitive.** Indexes are
|
|
29
|
+
upper-cased before comparison, so the same barcode written with different
|
|
30
|
+
casing is correctly flagged as a duplicate, consistent with the index
|
|
31
|
+
distance and character checks.
|
|
32
|
+
- **`mypy --strict` passes again.** The `info` CLI command accessed
|
|
33
|
+
V2-only attributes on the parser protocol without narrowing; it now narrows
|
|
34
|
+
with `isinstance`.
|
|
35
|
+
- **CLI no longer emits Typer deprecation warnings.** Removed the deprecated
|
|
36
|
+
`is_flag=True` from the `--version` option, clearing the warnings that were
|
|
37
|
+
raised on every CLI invocation.
|
|
38
|
+
|
|
39
|
+
### Changed
|
|
40
|
+
|
|
41
|
+
- **Index distance checking is now a sum of per-index distances.** For dual
|
|
42
|
+
index sheets the validator adds the I7 mismatch count to the I5 mismatch
|
|
43
|
+
count instead of comparing the two indexes concatenated into one string.
|
|
44
|
+
The result is the same for uniform-length indexes but correct when samples
|
|
45
|
+
use different index lengths, and it keeps I7 and I5 positions aligned. The
|
|
46
|
+
`INDEX_DISTANCE_TOO_LOW` message now refers to a "combined distance" and the
|
|
47
|
+
`index_a` / `index_b` context values use an `I7+I5` separator.
|
|
48
|
+
- **`N` is treated as a wildcard in collision detection.** Index distance
|
|
49
|
+
checks now treat an `N` cycle as matching any base, so two indexes that
|
|
50
|
+
differ only at an `N` are reported as colliding. The pure `hamming_distance`
|
|
51
|
+
helper is unchanged.
|
|
52
|
+
|
|
53
|
+
### Added
|
|
54
|
+
|
|
55
|
+
- **`index_collision_distance(a, b)`** public helper: the wildcard-aware,
|
|
56
|
+
per-index distance the validator uses for collision detection.
|
|
57
|
+
|
|
58
|
+
### Documentation
|
|
59
|
+
|
|
60
|
+
- Formalised the `OverrideCycles` grammar in `SampleSheetV2._parse_override_cycles`,
|
|
61
|
+
documented how a `U` token is attributed to an index versus a read, clarified
|
|
62
|
+
that `umi_length` is the largest single UMI segment (not the sum), and made
|
|
63
|
+
malformed segments log a warning and decode on a best-effort basis instead of
|
|
64
|
+
being silently dropped.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## [2.0.0] - 2026-06-06
|
|
69
|
+
|
|
70
|
+
### Breaking changes
|
|
71
|
+
|
|
72
|
+
- **Python 3.10+ required** (was 3.12+). The `str, Enum` mixin replaces
|
|
73
|
+
`StrEnum` throughout `enums.py` and `instruments.py`, giving identical
|
|
74
|
+
behaviour on all supported versions.
|
|
75
|
+
- **`loguru` dependency removed.** The library now uses `logging.getLogger(__name__)`
|
|
76
|
+
in every module. Host applications retain full control of log configuration.
|
|
77
|
+
If you previously relied on `loguru` sinks seeing library log output, wire up
|
|
78
|
+
a standard `logging` handler instead.
|
|
79
|
+
- **`clean()` now returns the cleaned content as a `str` and never writes to
|
|
80
|
+
disk.** Previously `SampleSheetV1.clean()` and `SampleSheetV2.clean()` wrote
|
|
81
|
+
to the source file and created a `.backup` alongside it. The source file is
|
|
82
|
+
now untouched; the cleaned string is passed in-memory to `read()`. Callers
|
|
83
|
+
that relied on the side-effect (file written, `.backup` created) must adapt.
|
|
84
|
+
- **`samples()` deduplication key changed from `sample_id` to `(sample_id, lane)`.**
|
|
85
|
+
Multi-lane sheets where the same sample appears in multiple lanes now return
|
|
86
|
+
one record *per lane* rather than silently dropping all but the first row.
|
|
87
|
+
- **`SampleSheetFactory.create_parser()` return type is now `SampleSheetParser`**
|
|
88
|
+
(the new Protocol) rather than `SampleSheetV1 | SampleSheetV2`. Both concrete
|
|
89
|
+
types structurally satisfy the Protocol; the change only affects code with
|
|
90
|
+
explicit type annotations on the return value.
|
|
91
|
+
- **`_hamming_distance` renamed to `hamming_distance`** (underscore removed).
|
|
92
|
+
Import path: `from samplesheet_parser import hamming_distance` or
|
|
93
|
+
`from samplesheet_parser.validators import hamming_distance`.
|
|
94
|
+
|
|
95
|
+
### Fixed
|
|
96
|
+
|
|
97
|
+
- **V2 `parse_data()` no longer silently drops keys with empty-string values.**
|
|
98
|
+
The `{k: v for k, v in ... if v}` filter was removing keys whose value was
|
|
99
|
+
`""`, making V2 record dicts structurally inconsistent with V1. All keys are
|
|
100
|
+
now preserved; values are stripped of surrounding whitespace only.
|
|
101
|
+
- **`converter.to_v1()` bare `assert` replaced with explicit `TypeError`.**
|
|
102
|
+
`assert isinstance(sheet, SampleSheetV2)` is stripped by `python -O`; the
|
|
103
|
+
guard now raises `TypeError` unconditionally when the wrong type is passed.
|
|
104
|
+
|
|
105
|
+
### Added
|
|
106
|
+
|
|
107
|
+
- **`SampleSheetParser` Protocol** (`samplesheet_parser.protocol`) — a
|
|
108
|
+
`runtime_checkable` structural protocol satisfied by both `SampleSheetV1`
|
|
109
|
+
and `SampleSheetV2`. Third-party parsers that implement the same interface
|
|
110
|
+
can be registered with the factory without inheriting from any base class.
|
|
111
|
+
`isinstance(sheet, SampleSheetParser)` works at runtime.
|
|
112
|
+
- **`SampleSheetFactory.register(detector, parser_class, version)`** — class
|
|
113
|
+
method that registers a custom format detector. Registered detectors are
|
|
114
|
+
tried before the built-in V1/V2 detection in LIFO order. Useful for
|
|
115
|
+
supporting hypothetical V3 formats or vendor-specific variants.
|
|
116
|
+
- **`SampleSheetFactory.clear_registry()`** — removes all custom registrations.
|
|
117
|
+
Intended for use in tests to prevent cross-test contamination.
|
|
118
|
+
- **`detect_workflow()` accepts `extra_a` / `extra_b` keyword arguments** —
|
|
119
|
+
caller-supplied `frozenset[str]` of instrument names checked before the
|
|
120
|
+
built-in tables. Allows narrowing workflow classification without subclassing.
|
|
121
|
+
- **`hamming_distance` is now a public export** — available as
|
|
122
|
+
`from samplesheet_parser import hamming_distance` and documented in the API
|
|
123
|
+
reference.
|
|
124
|
+
|
|
11
125
|
---
|
|
12
126
|
|
|
13
127
|
## [1.3.0] - 2026-05-20
|
|
@@ -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: 1.
|
|
12
|
-
date-released: 2026-
|
|
11
|
+
version: 2.1.0
|
|
12
|
+
date-released: 2026-06-09
|
|
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,81 @@
|
|
|
1
|
+
# Makefile for samplesheet-parser
|
|
2
|
+
# Keeps the version in sync across pyproject.toml, CITATION.cff, and .zenodo.json.
|
|
3
|
+
# Portable to GNU Make 3.81 (macOS default) — recipes are single POSIX-sh lines.
|
|
4
|
+
|
|
5
|
+
PKG := samplesheet_parser
|
|
6
|
+
PYPROJECT := pyproject.toml
|
|
7
|
+
CITATION := CITATION.cff
|
|
8
|
+
ZENODO := .zenodo.json
|
|
9
|
+
CHANGELOG := CHANGELOG.md
|
|
10
|
+
|
|
11
|
+
CURRENT_VERSION := $(shell sed -n -E 's/^version = "([0-9]+\.[0-9]+\.[0-9]+)".*/\1/p' $(PYPROJECT) | head -1)
|
|
12
|
+
|
|
13
|
+
.DEFAULT_GOAL := help
|
|
14
|
+
.PHONY: help version major minor patch tag test lint build clean
|
|
15
|
+
|
|
16
|
+
help:
|
|
17
|
+
@echo "samplesheet-parser — current version: $(CURRENT_VERSION)"
|
|
18
|
+
@echo ""
|
|
19
|
+
@echo "Version bumping (syncs $(PYPROJECT), $(CITATION), $(ZENODO); rolls $(CHANGELOG)):"
|
|
20
|
+
@echo " make patch patch bump (x.y.Z)"
|
|
21
|
+
@echo " make minor minor bump (x.Y.0)"
|
|
22
|
+
@echo " make major major bump (X.0.0)"
|
|
23
|
+
@echo ""
|
|
24
|
+
@echo "Other targets:"
|
|
25
|
+
@echo " make version print the current version"
|
|
26
|
+
@echo " make tag create git tag v$(CURRENT_VERSION)"
|
|
27
|
+
@echo " make test run pytest"
|
|
28
|
+
@echo " make lint run ruff"
|
|
29
|
+
@echo " make build build sdist + wheel"
|
|
30
|
+
@echo " make clean remove build artifacts"
|
|
31
|
+
|
|
32
|
+
version:
|
|
33
|
+
@echo $(CURRENT_VERSION)
|
|
34
|
+
|
|
35
|
+
patch minor major:
|
|
36
|
+
@$(MAKE) --no-print-directory _bump PART=$@
|
|
37
|
+
|
|
38
|
+
# internal: bump the version part named by PART across all files (one shell line)
|
|
39
|
+
_bump:
|
|
40
|
+
@cur="$(CURRENT_VERSION)"; \
|
|
41
|
+
[ -n "$$cur" ] || { echo "error: could not read version from $(PYPROJECT)"; exit 1; }; \
|
|
42
|
+
MA=$${cur%%.*}; rest=$${cur#*.}; MI=$${rest%%.*}; PA=$${rest##*.}; \
|
|
43
|
+
case "$(PART)" in \
|
|
44
|
+
major) MA=$$((MA + 1)); MI=0; PA=0 ;; \
|
|
45
|
+
minor) MI=$$((MI + 1)); PA=0 ;; \
|
|
46
|
+
patch) PA=$$((PA + 1)) ;; \
|
|
47
|
+
*) echo "error: unknown bump part '$(PART)'"; exit 1 ;; \
|
|
48
|
+
esac; \
|
|
49
|
+
new="$$MA.$$MI.$$PA"; today="$$(date +%F)"; \
|
|
50
|
+
sed -E 's/^version = "[0-9]+\.[0-9]+\.[0-9]+"/version = "'"$$new"'"/' $(PYPROJECT) > $(PYPROJECT).tmp && mv $(PYPROJECT).tmp $(PYPROJECT); \
|
|
51
|
+
sed -E -e 's/^version: .*/version: '"$$new"'/' -e 's/^date-released: .*/date-released: '"$$today"'/' $(CITATION) > $(CITATION).tmp && mv $(CITATION).tmp $(CITATION); \
|
|
52
|
+
sed -E 's/("version": )"[0-9]+\.[0-9]+\.[0-9]+"/\1"'"$$new"'"/' $(ZENODO) > $(ZENODO).tmp && mv $(ZENODO).tmp $(ZENODO); \
|
|
53
|
+
cl_note=""; \
|
|
54
|
+
if [ -f $(CHANGELOG) ] && grep -q '^## \[Unreleased\]' $(CHANGELOG); then \
|
|
55
|
+
awk -v v="$$new" -v d="$$today" '!done && /^## \[Unreleased\]/ {print "## [Unreleased]"; print ""; print "_No unreleased changes._"; print ""; print "## [" v "] - " d; done=1; next} {print}' $(CHANGELOG) > $(CHANGELOG).tmp && mv $(CHANGELOG).tmp $(CHANGELOG); \
|
|
56
|
+
cl_note=", $(CHANGELOG)"; \
|
|
57
|
+
else \
|
|
58
|
+
cl_note=" (warning: no [Unreleased] section in $(CHANGELOG) — not rolled)"; \
|
|
59
|
+
fi; \
|
|
60
|
+
echo "Bumped $$cur -> $$new (date-released: $$today)"; \
|
|
61
|
+
echo " updated: $(PYPROJECT), $(CITATION), $(ZENODO)$$cl_note"; \
|
|
62
|
+
echo "Next: review $(CHANGELOG), then: git commit -am \"release v$$new\" && make tag && git push --follow-tags"
|
|
63
|
+
|
|
64
|
+
tag:
|
|
65
|
+
@v="$(CURRENT_VERSION)"; \
|
|
66
|
+
if git rev-parse "v$$v" >/dev/null 2>&1; then echo "tag v$$v already exists"; exit 1; fi; \
|
|
67
|
+
git tag -a "v$$v" -m "Release v$$v"; \
|
|
68
|
+
echo "created annotated tag v$$v (push with: git push --follow-tags)"
|
|
69
|
+
|
|
70
|
+
test:
|
|
71
|
+
@pytest
|
|
72
|
+
|
|
73
|
+
lint:
|
|
74
|
+
@ruff check $(PKG)/
|
|
75
|
+
|
|
76
|
+
build:
|
|
77
|
+
@python3 -m hatchling build
|
|
78
|
+
|
|
79
|
+
clean:
|
|
80
|
+
@rm -rf dist build *.egg-info
|
|
81
|
+
@find . -type d -name __pycache__ -prune -exec rm -rf {} +
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: samplesheet-parser
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 2.1.0
|
|
4
4
|
Summary: Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2
|
|
5
5
|
Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
|
|
6
6
|
Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
|
|
@@ -33,11 +33,13 @@ Classifier: Intended Audience :: Developers
|
|
|
33
33
|
Classifier: Intended Audience :: Science/Research
|
|
34
34
|
Classifier: License :: OSI Approved :: Apache Software License
|
|
35
35
|
Classifier: Programming Language :: Python :: 3
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
36
38
|
Classifier: Programming Language :: Python :: 3.12
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
37
40
|
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
38
41
|
Classifier: Typing :: Typed
|
|
39
|
-
Requires-Python: >=3.
|
|
40
|
-
Requires-Dist: loguru>=0.7
|
|
42
|
+
Requires-Python: >=3.10
|
|
41
43
|
Provides-Extra: cli
|
|
42
44
|
Requires-Dist: typer>=0.12; extra == 'cli'
|
|
43
45
|
Provides-Extra: dev
|
|
@@ -59,7 +61,7 @@ Description-Content-Type: text/markdown
|
|
|
59
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.
|
|
60
62
|
|
|
61
63
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
62
|
-
[](https://www.python.org/downloads/)
|
|
63
65
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
64
66
|
[](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
|
|
65
67
|
|
|
@@ -94,7 +96,7 @@ pip install samplesheet-parser
|
|
|
94
96
|
pip install "samplesheet-parser[cli]"
|
|
95
97
|
```
|
|
96
98
|
|
|
97
|
-
Requires Python 3.
|
|
99
|
+
Requires Python 3.10+. No mandatory runtime dependencies.
|
|
98
100
|
|
|
99
101
|
---
|
|
100
102
|
|
|
@@ -367,20 +369,27 @@ The detector reads only as much of the file as needed — stopping after `[Heade
|
|
|
367
369
|
| `NO_ADAPTERS` | warning | No adapter sequences configured |
|
|
368
370
|
| `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
|
|
369
371
|
|
|
370
|
-
###
|
|
372
|
+
### Index distance checking
|
|
371
373
|
|
|
372
374
|
Indexes that are too similar cause read bleed-through between samples during
|
|
373
|
-
demultiplexing
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
For dual-index sheets
|
|
379
|
-
|
|
380
|
-
|
|
375
|
+
demultiplexing, a common cause of low-quality runs that a simple duplicate
|
|
376
|
+
check does not catch. For every pair of samples within a lane the validator
|
|
377
|
+
computes a combined distance and warns when it falls below the recommended
|
|
378
|
+
minimum of 3.
|
|
379
|
+
|
|
380
|
+
For dual-index sheets the combined distance is the sum of the per-index
|
|
381
|
+
mismatch counts: the I7 distance plus the I5 distance. This equals the minimum
|
|
382
|
+
number of sequencing errors needed to read one sample's barcodes as another's
|
|
383
|
+
across both index reads, and summing per index (rather than concatenating the
|
|
384
|
+
two indexes into one string) keeps the I7 and I5 positions aligned even when
|
|
385
|
+
samples use different index lengths. So a pair that is close on I7 but
|
|
386
|
+
well-separated on I5, as most dual-index kits are designed, is not flagged.
|
|
387
|
+
|
|
388
|
+
Each per-index distance treats an `N` cycle as a wildcard that matches any
|
|
389
|
+
base, so two indexes that differ only at an `N` are reported as colliding.
|
|
381
390
|
|
|
382
391
|
```python
|
|
383
|
-
# Custom threshold
|
|
392
|
+
# Custom threshold: stricter than the default of 3
|
|
384
393
|
from samplesheet_parser.validators import SampleSheetValidator, ValidationResult
|
|
385
394
|
|
|
386
395
|
samples = sheet.samples()
|
|
@@ -464,10 +473,21 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
464
473
|
|
|
465
474
|
| Method / attribute | Returns | Description |
|
|
466
475
|
|---|---|---|
|
|
467
|
-
| `create_parser(path, *, clean, experiment_id, parse)` | `
|
|
476
|
+
| `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return appropriate parser |
|
|
477
|
+
| `register(detector, parser_class, version)` | `None` | Register a custom format detector (class method, LIFO) |
|
|
478
|
+
| `clear_registry()` | `None` | Remove all custom registrations (class method) |
|
|
468
479
|
| `get_umi_length()` | `int` | UMI length from the current parser |
|
|
469
480
|
| `.version` | `SampleSheetVersion` | Detected format version |
|
|
470
481
|
|
|
482
|
+
### `SampleSheetParser` (Protocol)
|
|
483
|
+
|
|
484
|
+
A `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Third-party parsers that implement the same methods and attributes can be registered with `SampleSheetFactory.register()` without inheriting from any base class.
|
|
485
|
+
|
|
486
|
+
```python
|
|
487
|
+
from samplesheet_parser import SampleSheetParser, SampleSheetV1
|
|
488
|
+
assert isinstance(SampleSheetV1("sheet.csv"), SampleSheetParser)
|
|
489
|
+
```
|
|
490
|
+
|
|
471
491
|
### `SampleSheetV1` / `SampleSheetV2` (shared interface)
|
|
472
492
|
|
|
473
493
|
| Method / attribute | Returns | Description |
|
|
@@ -498,6 +518,17 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
498
518
|
| `validate(sheet)` | `ValidationResult` | Run all checks; returns structured result |
|
|
499
519
|
| `_check_index_distances(samples, result, min_distance=3)` | `None` | Hamming distance check (callable directly for custom thresholds) |
|
|
500
520
|
|
|
521
|
+
### `hamming_distance`
|
|
522
|
+
|
|
523
|
+
```python
|
|
524
|
+
from samplesheet_parser import hamming_distance
|
|
525
|
+
|
|
526
|
+
hamming_distance("ATTACTCG", "ATTACTCA") # → 1
|
|
527
|
+
hamming_distance("ATTACTCG", "GCTAGCTA") # → 6
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
Public helper for computing the Hamming distance between two index sequences. Sequences of unequal length are compared up to the shorter length.
|
|
531
|
+
|
|
501
532
|
### `SampleSheetWriter`
|
|
502
533
|
|
|
503
534
|
| Method / attribute | Returns | Description |
|
|
@@ -593,7 +624,7 @@ jobs:
|
|
|
593
624
|
|
|
594
625
|
- uses: actions/setup-python@v5
|
|
595
626
|
with:
|
|
596
|
-
python-version: '3.
|
|
627
|
+
python-version: '3.10'
|
|
597
628
|
|
|
598
629
|
- run: pip install "samplesheet-parser[cli]"
|
|
599
630
|
|
|
@@ -5,7 +5,7 @@
|
|
|
5
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.
|
|
6
6
|
|
|
7
7
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
8
|
-
[](https://www.python.org/downloads/)
|
|
9
9
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
10
10
|
[](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
|
|
11
11
|
|
|
@@ -40,7 +40,7 @@ pip install samplesheet-parser
|
|
|
40
40
|
pip install "samplesheet-parser[cli]"
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
Requires Python 3.
|
|
43
|
+
Requires Python 3.10+. No mandatory runtime dependencies.
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
@@ -313,20 +313,27 @@ The detector reads only as much of the file as needed — stopping after `[Heade
|
|
|
313
313
|
| `NO_ADAPTERS` | warning | No adapter sequences configured |
|
|
314
314
|
| `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
|
|
315
315
|
|
|
316
|
-
###
|
|
316
|
+
### Index distance checking
|
|
317
317
|
|
|
318
318
|
Indexes that are too similar cause read bleed-through between samples during
|
|
319
|
-
demultiplexing
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
For dual-index sheets
|
|
325
|
-
|
|
326
|
-
|
|
319
|
+
demultiplexing, a common cause of low-quality runs that a simple duplicate
|
|
320
|
+
check does not catch. For every pair of samples within a lane the validator
|
|
321
|
+
computes a combined distance and warns when it falls below the recommended
|
|
322
|
+
minimum of 3.
|
|
323
|
+
|
|
324
|
+
For dual-index sheets the combined distance is the sum of the per-index
|
|
325
|
+
mismatch counts: the I7 distance plus the I5 distance. This equals the minimum
|
|
326
|
+
number of sequencing errors needed to read one sample's barcodes as another's
|
|
327
|
+
across both index reads, and summing per index (rather than concatenating the
|
|
328
|
+
two indexes into one string) keeps the I7 and I5 positions aligned even when
|
|
329
|
+
samples use different index lengths. So a pair that is close on I7 but
|
|
330
|
+
well-separated on I5, as most dual-index kits are designed, is not flagged.
|
|
331
|
+
|
|
332
|
+
Each per-index distance treats an `N` cycle as a wildcard that matches any
|
|
333
|
+
base, so two indexes that differ only at an `N` are reported as colliding.
|
|
327
334
|
|
|
328
335
|
```python
|
|
329
|
-
# Custom threshold
|
|
336
|
+
# Custom threshold: stricter than the default of 3
|
|
330
337
|
from samplesheet_parser.validators import SampleSheetValidator, ValidationResult
|
|
331
338
|
|
|
332
339
|
samples = sheet.samples()
|
|
@@ -410,10 +417,21 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
410
417
|
|
|
411
418
|
| Method / attribute | Returns | Description |
|
|
412
419
|
|---|---|---|
|
|
413
|
-
| `create_parser(path, *, clean, experiment_id, parse)` | `
|
|
420
|
+
| `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return appropriate parser |
|
|
421
|
+
| `register(detector, parser_class, version)` | `None` | Register a custom format detector (class method, LIFO) |
|
|
422
|
+
| `clear_registry()` | `None` | Remove all custom registrations (class method) |
|
|
414
423
|
| `get_umi_length()` | `int` | UMI length from the current parser |
|
|
415
424
|
| `.version` | `SampleSheetVersion` | Detected format version |
|
|
416
425
|
|
|
426
|
+
### `SampleSheetParser` (Protocol)
|
|
427
|
+
|
|
428
|
+
A `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Third-party parsers that implement the same methods and attributes can be registered with `SampleSheetFactory.register()` without inheriting from any base class.
|
|
429
|
+
|
|
430
|
+
```python
|
|
431
|
+
from samplesheet_parser import SampleSheetParser, SampleSheetV1
|
|
432
|
+
assert isinstance(SampleSheetV1("sheet.csv"), SampleSheetParser)
|
|
433
|
+
```
|
|
434
|
+
|
|
417
435
|
### `SampleSheetV1` / `SampleSheetV2` (shared interface)
|
|
418
436
|
|
|
419
437
|
| Method / attribute | Returns | Description |
|
|
@@ -444,6 +462,17 @@ sheet.get_read_structure() # → ReadStructure dataclass
|
|
|
444
462
|
| `validate(sheet)` | `ValidationResult` | Run all checks; returns structured result |
|
|
445
463
|
| `_check_index_distances(samples, result, min_distance=3)` | `None` | Hamming distance check (callable directly for custom thresholds) |
|
|
446
464
|
|
|
465
|
+
### `hamming_distance`
|
|
466
|
+
|
|
467
|
+
```python
|
|
468
|
+
from samplesheet_parser import hamming_distance
|
|
469
|
+
|
|
470
|
+
hamming_distance("ATTACTCG", "ATTACTCA") # → 1
|
|
471
|
+
hamming_distance("ATTACTCG", "GCTAGCTA") # → 6
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
Public helper for computing the Hamming distance between two index sequences. Sequences of unequal length are compared up to the shorter length.
|
|
475
|
+
|
|
447
476
|
### `SampleSheetWriter`
|
|
448
477
|
|
|
449
478
|
| Method / attribute | Returns | Description |
|
|
@@ -539,7 +568,7 @@ jobs:
|
|
|
539
568
|
|
|
540
569
|
- uses: actions/setup-python@v5
|
|
541
570
|
with:
|
|
542
|
-
python-version: '3.
|
|
571
|
+
python-version: '3.10'
|
|
543
572
|
|
|
544
573
|
- run: pip install "samplesheet-parser[cli]"
|
|
545
574
|
|
|
@@ -5,6 +5,7 @@ All public classes are importable directly from the top-level package:
|
|
|
5
5
|
```python
|
|
6
6
|
from samplesheet_parser import (
|
|
7
7
|
SampleSheetFactory,
|
|
8
|
+
SampleSheetParser,
|
|
8
9
|
SampleSheetV1,
|
|
9
10
|
SampleSheetV2,
|
|
10
11
|
SampleSheetConverter,
|
|
@@ -15,6 +16,7 @@ from samplesheet_parser import (
|
|
|
15
16
|
SampleSheetSplitter,
|
|
16
17
|
SampleSheetFilter,
|
|
17
18
|
normalize_index_lengths,
|
|
19
|
+
hamming_distance,
|
|
18
20
|
)
|
|
19
21
|
```
|
|
20
22
|
|
|
@@ -24,19 +26,37 @@ from samplesheet_parser import (
|
|
|
24
26
|
|
|
25
27
|
| Method / attribute | Returns | Description |
|
|
26
28
|
|---|---|---|
|
|
27
|
-
| `create_parser(path, *, clean, experiment_id, parse)` | `
|
|
29
|
+
| `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetParser` | Auto-detect format and return the appropriate parser |
|
|
28
30
|
| `get_umi_length()` | `int` | UMI length from the current parser |
|
|
31
|
+
| `register(detector, parser_class, version)` | `None` | Register a custom format detector; tried before built-in detection in LIFO order |
|
|
32
|
+
| `clear_registry()` | `None` | Remove all custom registrations (useful in tests) |
|
|
29
33
|
| `.version` | `SampleSheetVersion \| None` | Detected format version |
|
|
30
34
|
|
|
31
35
|
---
|
|
32
36
|
|
|
37
|
+
## SampleSheetParser Protocol
|
|
38
|
+
|
|
39
|
+
`SampleSheetParser` is a `runtime_checkable` structural protocol satisfied by both `SampleSheetV1` and `SampleSheetV2`. Use it as a type hint wherever either parser is accepted, or implement it in a third-party parser and register it with the factory.
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from samplesheet_parser import SampleSheetParser
|
|
43
|
+
|
|
44
|
+
isinstance(sheet, SampleSheetParser) # True for V1 and V2 instances
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
33
49
|
## SampleSheetV1 / SampleSheetV2 (shared interface)
|
|
34
50
|
|
|
51
|
+
Both parsers satisfy `SampleSheetParser` and expose:
|
|
52
|
+
|
|
35
53
|
| Method / attribute | Returns | Description |
|
|
36
54
|
|---|---|---|
|
|
37
55
|
| `parse(do_clean=True)` | `None` | Parse all sections |
|
|
38
|
-
| `
|
|
56
|
+
| `clean()` | `str` | Return cleaned content as a string — source file is **never** modified |
|
|
57
|
+
| `samples()` | `list[dict]` | One record per unique `(sample_id, lane)` pair |
|
|
39
58
|
| `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
|
|
59
|
+
| `parse_custom_section(name, *, required=False)` | `dict[str, str]` | Parse any non-standard section as key/value pairs |
|
|
40
60
|
| `.adapters` | `list[str]` | Adapter sequences |
|
|
41
61
|
| `.experiment_name` | `str \| None` | Run/experiment name |
|
|
42
62
|
|
|
@@ -87,7 +107,7 @@ from samplesheet_parser.instruments import (
|
|
|
87
107
|
|
|
88
108
|
| Name | Kind | Description |
|
|
89
109
|
|---|---|---|
|
|
90
|
-
| `Workflow` | `
|
|
110
|
+
| `Workflow` | `str, Enum` | `Workflow.A` (i5 forward) / `Workflow.B` (i5 RC'd on chip) |
|
|
91
111
|
| `detect_workflow(name)` | `Workflow \| None` | Classify an instrument name; `None` for unknown or ambiguous (e.g. `NovaSeq 6000`) |
|
|
92
112
|
| `parse_workflow(value)` | `Workflow \| None` | Coerce a CLI string (`"a"` / `"b"`) to `Workflow` |
|
|
93
113
|
| `reverse_complement(seq)` | `str` | Reverse-complement a DNA sequence (preserves `N`, case-preserving) |
|
|
@@ -243,6 +263,24 @@ Normalizes index sequence lengths across a list of sample dicts. See [Index Util
|
|
|
243
263
|
|
|
244
264
|
---
|
|
245
265
|
|
|
266
|
+
## hamming_distance
|
|
267
|
+
|
|
268
|
+
```python
|
|
269
|
+
from samplesheet_parser import hamming_distance
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Computes the Hamming distance between two equal-length index sequences, counting `N` wildcards as matches:
|
|
273
|
+
|
|
274
|
+
```python
|
|
275
|
+
hamming_distance("ATTACTCG", "ATTACTCG") # 0
|
|
276
|
+
hamming_distance("ATTACTCG", "ATTACTCC") # 1
|
|
277
|
+
hamming_distance("ATTNCNCG", "ATTACTCG") # 0 — N matches anything
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
Used internally by `SampleSheetValidator` when checking index collision thresholds. Accepts sequences of different lengths (returns `None`) but in practice all samples in a valid sheet have uniform index lengths after normalization.
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
246
284
|
## Enums
|
|
247
285
|
|
|
248
286
|
```python
|
|
@@ -73,12 +73,41 @@ print(rs.read_structure)
|
|
|
73
73
|
|
|
74
74
|
## Shared interface
|
|
75
75
|
|
|
76
|
-
Both `SampleSheetV1` and `SampleSheetV2` expose:
|
|
76
|
+
Both `SampleSheetV1` and `SampleSheetV2` satisfy the `SampleSheetParser` Protocol and expose:
|
|
77
77
|
|
|
78
78
|
| Method / attribute | Returns | Description |
|
|
79
79
|
|---|---|---|
|
|
80
80
|
| `parse(do_clean=True)` | `None` | Parse all sections |
|
|
81
|
-
| `
|
|
81
|
+
| `clean()` | `str` | Return cleaned content as a string — source file is **never** modified |
|
|
82
|
+
| `samples()` | `list[dict]` | One record per unique `(sample_id, lane)` pair |
|
|
82
83
|
| `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
|
|
84
|
+
| `parse_custom_section(name, *, required=False)` | `dict[str, str]` | Parse any non-standard section as key/value pairs |
|
|
83
85
|
| `.adapters` | `list[str]` | Adapter sequences |
|
|
84
86
|
| `.experiment_name` | `str \| None` | Run/experiment name |
|
|
87
|
+
|
|
88
|
+
### In-memory cleaning
|
|
89
|
+
|
|
90
|
+
`parse(do_clean=True)` (the default) cleans the file content in memory before parsing — stripping BOM, quotes, stray whitespace, and normalising V2 section names. **The source file on disk is never modified and no `.backup` files are created.**
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
# Access the cleaned content directly
|
|
94
|
+
cleaned = sheet.clean() # returns str, no file I/O side-effects
|
|
95
|
+
|
|
96
|
+
# Parse with cleaning (default)
|
|
97
|
+
sheet.parse()
|
|
98
|
+
|
|
99
|
+
# Parse without cleaning (raw file)
|
|
100
|
+
sheet.parse(do_clean=False)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Multi-lane deduplication
|
|
104
|
+
|
|
105
|
+
`samples()` deduplicates by `(sample_id, lane)` pair, not by `sample_id` alone. A sample appearing across multiple lanes produces one record per lane.
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
sheet.parse()
|
|
109
|
+
samples = sheet.samples()
|
|
110
|
+
# Multi-lane sheet with Sample1 in lanes 1 and 2 → two records:
|
|
111
|
+
# [{"sample_id": "Sample1", "lane": "1", ...},
|
|
112
|
+
# {"sample_id": "Sample1", "lane": "2", ...}]
|
|
113
|
+
```
|
|
@@ -32,20 +32,24 @@ for w in result.warnings:
|
|
|
32
32
|
| `NO_ADAPTERS` | warning | No adapter sequences configured |
|
|
33
33
|
| `ADAPTER_MISMATCH` | warning | Adapter is non-standard |
|
|
34
34
|
|
|
35
|
-
##
|
|
35
|
+
## Index distance checking
|
|
36
36
|
|
|
37
|
-
Indexes that are too similar cause read bleed-through between samples during demultiplexing
|
|
37
|
+
Indexes that are too similar cause read bleed-through between samples during demultiplexing, a common cause of low-quality runs that a simple duplicate check does not catch.
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
For every pair of samples within a lane, the validator computes a combined distance: the I7 (index) mismatch count plus the I5 (index2) mismatch count. This sum equals the minimum number of sequencing errors needed to read one sample's barcodes as another's across both index reads, which is the quantity that governs misassignment risk. Summing the per-index distances (rather than concatenating the two indexes into one string) keeps the I7 and I5 positions aligned even when samples use different index lengths. A pair is flagged when the combined distance is below the threshold.
|
|
40
|
+
|
|
41
|
+
Each per-index distance treats an `N` cycle as a wildcard that matches any base, matching how demultiplexers handle `N`. Two indexes that differ only where one carries an `N` are therefore reported as colliding. Sequences of different lengths are compared up to the length of the shorter sequence.
|
|
40
42
|
|
|
41
43
|
```python
|
|
42
44
|
# Default threshold: 3
|
|
43
45
|
result = SampleSheetValidator().validate(sheet)
|
|
44
46
|
|
|
45
|
-
# Custom threshold
|
|
47
|
+
# Custom threshold: stricter for longer indexes
|
|
46
48
|
result = SampleSheetValidator().validate(sheet, min_hamming_distance=4)
|
|
47
49
|
```
|
|
48
50
|
|
|
51
|
+
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
|
+
|
|
49
53
|
## Structured results
|
|
50
54
|
|
|
51
55
|
```python
|