samplesheet-parser 1.1.0__tar.gz → 1.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-1.1.0 → samplesheet_parser-1.3.0}/.gitignore +1 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.pre-commit-config.yaml +1 -0
- samplesheet_parser-1.3.0/.readthedocs.yaml +17 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/CHANGELOG.md +144 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/CITATION.cff +2 -2
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/PKG-INFO +11 -3
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/README.md +5 -0
- samplesheet_parser-1.3.0/docs/api.md +253 -0
- samplesheet_parser-1.3.0/docs/changelog.md +5 -0
- samplesheet_parser-1.3.0/docs/ci.md +83 -0
- samplesheet_parser-1.3.0/docs/cli.md +263 -0
- samplesheet_parser-1.3.0/docs/contributing.md +5 -0
- samplesheet_parser-1.3.0/docs/examples.md +365 -0
- samplesheet_parser-1.3.0/docs/guide/conversion.md +134 -0
- samplesheet_parser-1.3.0/docs/guide/diffing.md +59 -0
- samplesheet_parser-1.3.0/docs/guide/filtering.md +101 -0
- samplesheet_parser-1.3.0/docs/guide/index_utils.md +60 -0
- samplesheet_parser-1.3.0/docs/guide/merging.md +87 -0
- samplesheet_parser-1.3.0/docs/guide/parsing.md +84 -0
- samplesheet_parser-1.3.0/docs/guide/quickstart.md +69 -0
- samplesheet_parser-1.3.0/docs/guide/splitting.md +102 -0
- samplesheet_parser-1.3.0/docs/guide/validation.md +59 -0
- samplesheet_parser-1.3.0/docs/guide/writing.md +82 -0
- samplesheet_parser-1.3.0/docs/index.md +59 -0
- samplesheet_parser-1.3.0/docs/installation.md +41 -0
- samplesheet_parser-1.3.0/docs/requirements.txt +4 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_converter.py +6 -3
- samplesheet_parser-1.3.0/examples/demo_filter.py +110 -0
- samplesheet_parser-1.3.0/examples/demo_splitter.py +87 -0
- samplesheet_parser-1.3.0/mkdocs.yml +80 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/main.nf +50 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/meta.yml +62 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +79 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +4 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/main.nf +45 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/meta.yml +69 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +79 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/tests/tags.yml +4 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/main.nf +48 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/meta.yml +74 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +57 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +5 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/tags.yml +4 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/main.nf +45 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/meta.yml +61 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test +76 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +4 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/main.nf +53 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/meta.yml +73 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +88 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/tests/tags.yml +4 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/main.nf +56 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/meta.yml +73 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/tests/main.nf.test +79 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/tests/tags.yml +4 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/main.nf +45 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/meta.yml +62 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +76 -0
- samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +4 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/pyproject.toml +6 -3
- samplesheet_parser-1.3.0/recipes/meta.yaml +56 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/__init__.py +6 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/cli.py +245 -6
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/converter.py +191 -47
- samplesheet_parser-1.3.0/samplesheet_parser/filter.py +243 -0
- samplesheet_parser-1.3.0/samplesheet_parser/instruments.py +192 -0
- samplesheet_parser-1.3.0/samplesheet_parser/splitter.py +303 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/writer.py +190 -147
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_cli.py +296 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_converter.py +404 -48
- samplesheet_parser-1.3.0/tests/test_filter.py +380 -0
- samplesheet_parser-1.3.0/tests/test_instruments.py +126 -0
- samplesheet_parser-1.3.0/tests/test_splitter.py +466 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.github/workflows/ci.yml +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.github/workflows/copilot-instructions.md +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.zenodo.json +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/CONTRIBUTING.md +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/LICENSE +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_diff.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_index_utils.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_merger.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_writer.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/parse_examples.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/README.md +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/combined_clean.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_single_index.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/images/samplesheet_parser_arch_v03.png +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/images/samplesheet_parser_overview.png +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/diff.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/enums.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/factory.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/index_utils.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/merger.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/parsers/__init__.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/parsers/v1.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/parsers/v2.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/py.typed +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/validators.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/scripts/demo_converter.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/scripts/demo_diff.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/scripts/demo_writer.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/__init__.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/conftest.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_diff.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_factory.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_index_utils.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_merger.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_parsers/__init__.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_parsers/test_v1.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_parsers/test_v2.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_validators/__init__.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_validators/test_hamming.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_validators/test_validators.py +0 -0
- {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_writer.py +0 -0
|
@@ -6,6 +6,150 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [Unreleased]
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## [1.3.0] - 2026-05-20
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- **`SampleSheetConverter` now reverse-complements `Index2` for workflow-B
|
|
18
|
+
instruments** (NovaSeq X / X Plus, NextSeq 500/550/1000/2000, iSeq 100,
|
|
19
|
+
MiniSeq, HiSeq 3000/4000) on V1 ↔ V2 conversion. `bcl2fastq` records i5 as
|
|
20
|
+
read on the chip (reverse-complemented for workflow-B instruments) while
|
|
21
|
+
`BCLConvert` expects i5 in the forward orientation; previously the
|
|
22
|
+
converter passed `Index2` through verbatim, silently producing V2 sheets
|
|
23
|
+
that demultiplexed to the wrong samples ([#30]).
|
|
24
|
+
- The workflow is auto-detected from `[Header] Instrument Type` (V1) or
|
|
25
|
+
`InstrumentPlatform` / `InstrumentType` (V2). When the sheet has a
|
|
26
|
+
non-empty `Index2` column and the workflow cannot be determined, the
|
|
27
|
+
converter raises `ValueError` and the CLI exits non-zero rather than
|
|
28
|
+
guessing. **Behavior change:** dual-index sheets with no recognised
|
|
29
|
+
instrument header that previously converted (with silently wrong `Index2`)
|
|
30
|
+
will now fail loudly until `workflow=` / `--workflow` is supplied.
|
|
31
|
+
- V2 → V1 conversion now preserves the instrument as `Instrument Type` in
|
|
32
|
+
the V1 `[Header]` so the workflow signal survives a round trip.
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
|
|
36
|
+
- **`samplesheet_parser.instruments`** — public module exposing
|
|
37
|
+
`Workflow` (StrEnum: `A` / `B`), `WORKFLOW_A_INSTRUMENTS` /
|
|
38
|
+
`WORKFLOW_B_INSTRUMENTS` / `AMBIGUOUS_INSTRUMENTS` tables,
|
|
39
|
+
`detect_workflow()`, `parse_workflow()`, and `reverse_complement()`.
|
|
40
|
+
- **`SampleSheetConverter(path, *, workflow=...)`** — explicit workflow
|
|
41
|
+
override accepting `"a"`, `"b"`, or a `Workflow` enum value. Required for
|
|
42
|
+
ambiguous instruments such as `NovaSeq 6000` (workflow depends on v1.0
|
|
43
|
+
vs v1.5 chemistry).
|
|
44
|
+
- **`samplesheet convert --workflow {a,b}` / `-w`** — CLI override that
|
|
45
|
+
takes precedence over auto-detection.
|
|
46
|
+
|
|
47
|
+
[#30]: https://github.com/chaitanyakasaraneni/samplesheet-parser/issues/30
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## [1.2.0] - 2026-04-14
|
|
52
|
+
|
|
53
|
+
### Changed
|
|
54
|
+
|
|
55
|
+
- Minimum `typer` version raised from `>=0.9` to `>=0.12` to ensure
|
|
56
|
+
compatibility with `click >=8.2` (`make_metavar` signature change).
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
|
|
60
|
+
- **`SampleSheetSplitter` and `SplitResult`** — splits a combined sheet into
|
|
61
|
+
one file per project or per lane (the inverse of `SampleSheetMerger`).
|
|
62
|
+
- `SampleSheetSplitter(path, *, by="project"|"lane", target_version=None, unassigned_label="unassigned")`
|
|
63
|
+
- `split(output_dir, *, prefix="", suffix="_SampleSheet.csv", validate=True) → SplitResult`
|
|
64
|
+
- Header, reads, and settings are copied into every output file; only sample
|
|
65
|
+
rows are divided. Samples with no project/lane are grouped under a
|
|
66
|
+
configurable `unassigned_label`.
|
|
67
|
+
- Incomplete records (missing `Sample_ID` or `Index`) are skipped with a
|
|
68
|
+
warning. Groups that produce no valid samples are omitted with a warning.
|
|
69
|
+
- `SampleSheetSplitter` and `SplitResult` are exported from the top-level
|
|
70
|
+
package.
|
|
71
|
+
|
|
72
|
+
- **`SampleSheetFilter` and `FilterResult`** — extracts a subset of samples
|
|
73
|
+
from a sheet by project, lane, or sample ID (with glob support).
|
|
74
|
+
- `SampleSheetFilter(path, *, target_version=None)`
|
|
75
|
+
- `filter(output_path, *, project=None, lane=None, sample_id=None, validate=True) → FilterResult`
|
|
76
|
+
- Multiple criteria are ANDed — a sample must match all provided criteria.
|
|
77
|
+
- `sample_id` supports glob patterns (e.g. `"CTRL_*"`, `"SAMPLE_00[1-3]"`)
|
|
78
|
+
via `fnmatch.fnmatchcase` for consistent case-sensitive behavior across
|
|
79
|
+
platforms.
|
|
80
|
+
- No file is written when no samples match; `FilterResult.output_path` is
|
|
81
|
+
`None` in that case.
|
|
82
|
+
- `SampleSheetFilter` and `FilterResult` are exported from the top-level
|
|
83
|
+
package.
|
|
84
|
+
|
|
85
|
+
- **`samplesheet split` CLI command** — splits a combined sheet into per-group
|
|
86
|
+
files. Accepts `--by project|lane`, `--output-dir / -d`, `--to v1|v2`,
|
|
87
|
+
`--format json|text`, and `--prefix`. Exits 0 on clean split, 1 if warnings
|
|
88
|
+
were produced, 2 on bad arguments or unreadable files.
|
|
89
|
+
|
|
90
|
+
- **`samplesheet filter` CLI command** — filters samples by `--project / -p`,
|
|
91
|
+
`--lane / -l`, and `--sample-id / -s` (glob patterns supported). Accepts
|
|
92
|
+
`--output / -o`, `--to v1|v2`, and `--format json|text`. Exits 0 when
|
|
93
|
+
samples match, 1 when no samples match, 2 on bad arguments.
|
|
94
|
+
|
|
95
|
+
- **`SampleSheetWriter.clear_samples()`** — public method to remove all samples
|
|
96
|
+
from a writer while preserving header, reads, and settings. Enables the
|
|
97
|
+
copy-metadata-then-repopulate pattern without accessing the private
|
|
98
|
+
`_samples` attribute.
|
|
99
|
+
|
|
100
|
+
- **`--format json` for `samplesheet convert`** — the convert command now accepts
|
|
101
|
+
`--format json` and emits a structured JSON object with `input`, `output`,
|
|
102
|
+
`source_version`, and `target_version` keys. All seven CLI subcommands now
|
|
103
|
+
support `--format json` uniformly.
|
|
104
|
+
|
|
105
|
+
- **Bioconda recipe (`recipes/meta.yaml`)** — a `noarch: python` conda recipe
|
|
106
|
+
with `loguru` as the only runtime dependency. Python version is not pinned
|
|
107
|
+
(noarch packages rely on the conda solver for compatibility). The CLI extra
|
|
108
|
+
(`typer`) is intentionally omitted from the base recipe so the conda package
|
|
109
|
+
stays lightweight; users who need the `samplesheet` CLI can
|
|
110
|
+
`conda install typer` alongside.
|
|
111
|
+
|
|
112
|
+
- **nf-core compatible Nextflow modules** — three modules following
|
|
113
|
+
nf-core/modules conventions, each with `main.nf`, `meta.yml`,
|
|
114
|
+
`environment.yml`, nf-test tests, and `tags.yml`:
|
|
115
|
+
- `SAMPLESHEETPARSER_VALIDATE` — validates V1/V2 sheets and emits a
|
|
116
|
+
structured JSON report; exits 1 on errors so pipelines fail before
|
|
117
|
+
demultiplexing.
|
|
118
|
+
- `SAMPLESHEETPARSER_CONVERT` — bidirectional V1↔V2 conversion with target
|
|
119
|
+
version passed as a channel value.
|
|
120
|
+
- `SAMPLESHEETPARSER_INFO` — emits a JSON metadata summary (format, sample
|
|
121
|
+
count, lanes, index type, read lengths, adapters) for run logging and
|
|
122
|
+
conditional pipeline branching.
|
|
123
|
+
|
|
124
|
+
- **Example scripts** — `examples/demo_splitter.py` and
|
|
125
|
+
`examples/demo_filter.py` demonstrating the new split and filter APIs with
|
|
126
|
+
three and four runnable scenarios respectively.
|
|
127
|
+
|
|
128
|
+
### Tests
|
|
129
|
+
|
|
130
|
+
- **`tests/test_splitter.py`** — 46 tests covering: split by project and lane,
|
|
131
|
+
header/reads/settings preservation, unassigned samples (custom label),
|
|
132
|
+
incomplete records (missing `Sample_ID` or `Index`, all-incomplete group),
|
|
133
|
+
empty input, target version override, custom prefix/suffix, output directory
|
|
134
|
+
creation, `SplitResult` summary and `source_version`, and error conditions
|
|
135
|
+
(`FileNotFoundError`, `ValueError` on invalid `--by`).
|
|
136
|
+
|
|
137
|
+
- **`tests/test_filter.py`** — 46 tests covering: filter by project, lane
|
|
138
|
+
(string and int), and sample ID (exact and glob); multiple ANDed criteria;
|
|
139
|
+
no-match behaviour (no file written, `matched_count == 0`); header/settings
|
|
140
|
+
preservation; target version override; `FilterResult` attributes; incomplete
|
|
141
|
+
records; and error conditions (`ValueError`, `FileNotFoundError`).
|
|
142
|
+
|
|
143
|
+
- **`TestCLISplit` and `TestCLIFilter`** in `tests/test_cli.py` — 13 tests each
|
|
144
|
+
covering happy paths, JSON output, warning exit codes, error exit codes,
|
|
145
|
+
exception paths (via `monkeypatch`), and text output formatting.
|
|
146
|
+
|
|
147
|
+
- Three new `TestCLIConvert` tests covering `--format json` exit code,
|
|
148
|
+
JSON output structure (`source_version`, `target_version`, `input`, `output`
|
|
149
|
+
keys), and the `--format xml` invalid-format guard.
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
9
153
|
## [1.1.0] - 2026-04-05
|
|
10
154
|
|
|
11
155
|
### Added
|
|
@@ -8,8 +8,8 @@ abstract: >
|
|
|
8
8
|
Provides format auto-detection, bidirectional V1/V2 conversion,
|
|
9
9
|
structural and index validation, sheet diffing, and cross-project
|
|
10
10
|
merging with Hamming-distance collision detection.
|
|
11
|
-
version: 1.
|
|
12
|
-
date-released: 2026-
|
|
11
|
+
version: 1.3.0
|
|
12
|
+
date-released: 2026-05-20
|
|
13
13
|
license: Apache-2.0
|
|
14
14
|
url: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
|
|
15
15
|
repository-code: "https://github.com/chaitanyakasaraneni/samplesheet-parser"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: samplesheet-parser
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.3.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
|
|
@@ -39,14 +39,17 @@ Classifier: Typing :: Typed
|
|
|
39
39
|
Requires-Python: >=3.12
|
|
40
40
|
Requires-Dist: loguru>=0.7
|
|
41
41
|
Provides-Extra: cli
|
|
42
|
-
Requires-Dist: typer>=0.
|
|
42
|
+
Requires-Dist: typer>=0.12; extra == 'cli'
|
|
43
43
|
Provides-Extra: dev
|
|
44
44
|
Requires-Dist: black>=24.0; extra == 'dev'
|
|
45
|
+
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
|
|
46
|
+
Requires-Dist: mkdocs>=1.6; extra == 'dev'
|
|
47
|
+
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
|
|
45
48
|
Requires-Dist: mypy>=1.8; extra == 'dev'
|
|
46
49
|
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
|
|
47
50
|
Requires-Dist: pytest>=7.4; extra == 'dev'
|
|
48
51
|
Requires-Dist: ruff>=0.3; extra == 'dev'
|
|
49
|
-
Requires-Dist: typer>=0.
|
|
52
|
+
Requires-Dist: typer>=0.12; extra == 'dev'
|
|
50
53
|
Description-Content-Type: text/markdown
|
|
51
54
|
|
|
52
55
|
# samplesheet-parser
|
|
@@ -58,10 +61,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
|
|
|
58
61
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
59
62
|
[](https://www.python.org/downloads/)
|
|
60
63
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
64
|
+
[](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
|
|
65
|
+
|
|
61
66
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
62
67
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
68
|
+
[](https://illumina-samplesheet.readthedocs.io)
|
|
63
69
|
[](https://doi.org/10.5281/zenodo.18989694)
|
|
64
70
|
|
|
71
|
+
**Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
72
|
+
|
|
65
73
|

|
|
66
74
|
|
|
67
75
|
*`SampleSheetFactory` auto-detects the format and routes to the correct parser. Both formats share a common interface — `SampleSheetConverter` handles bidirectional conversion, `SampleSheetValidator` catches index and adapter issues, `SampleSheetDiff` compares two sheets across any combination of V1/V2 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.*
|
|
@@ -7,10 +7,15 @@ Supports both the classic IEM V1 format (bcl2fastq era) and the modern BCLConver
|
|
|
7
7
|
[](https://pypi.org/project/samplesheet-parser/)
|
|
8
8
|
[](https://www.python.org/downloads/)
|
|
9
9
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
10
|
+
[](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
|
|
11
|
+
|
|
10
12
|
[](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
|
|
11
13
|
[](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
|
|
14
|
+
[](https://illumina-samplesheet.readthedocs.io)
|
|
12
15
|
[](https://doi.org/10.5281/zenodo.18989694)
|
|
13
16
|
|
|
17
|
+
**Docs:** https://illumina-samplesheet.readthedocs.io/ | **PyPI:** https://pypi.org/project/samplesheet-parser/
|
|
18
|
+
|
|
14
19
|

|
|
15
20
|
|
|
16
21
|
*`SampleSheetFactory` auto-detects the format and routes to the correct parser. Both formats share a common interface — `SampleSheetConverter` handles bidirectional conversion, `SampleSheetValidator` catches index and adapter issues, `SampleSheetDiff` compares two sheets across any combination of V1/V2 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.*
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
All public classes are importable directly from the top-level package:
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
from samplesheet_parser import (
|
|
7
|
+
SampleSheetFactory,
|
|
8
|
+
SampleSheetV1,
|
|
9
|
+
SampleSheetV2,
|
|
10
|
+
SampleSheetConverter,
|
|
11
|
+
SampleSheetValidator,
|
|
12
|
+
SampleSheetDiff,
|
|
13
|
+
SampleSheetWriter,
|
|
14
|
+
SampleSheetMerger,
|
|
15
|
+
SampleSheetSplitter,
|
|
16
|
+
SampleSheetFilter,
|
|
17
|
+
normalize_index_lengths,
|
|
18
|
+
)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## SampleSheetFactory
|
|
24
|
+
|
|
25
|
+
| Method / attribute | Returns | Description |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `create_parser(path, *, clean, experiment_id, parse)` | `SampleSheetV1 \| SampleSheetV2` | Auto-detect format and return the appropriate parser |
|
|
28
|
+
| `get_umi_length()` | `int` | UMI length from the current parser |
|
|
29
|
+
| `.version` | `SampleSheetVersion \| None` | Detected format version |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## SampleSheetV1 / SampleSheetV2 (shared interface)
|
|
34
|
+
|
|
35
|
+
| Method / attribute | Returns | Description |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `parse(do_clean=True)` | `None` | Parse all sections |
|
|
38
|
+
| `samples()` | `list[dict]` | One record per unique sample |
|
|
39
|
+
| `index_type()` | `str` | `"dual"`, `"single"`, or `"none"` |
|
|
40
|
+
| `.adapters` | `list[str]` | Adapter sequences |
|
|
41
|
+
| `.experiment_name` | `str \| None` | Run/experiment name |
|
|
42
|
+
|
|
43
|
+
### V2-only
|
|
44
|
+
|
|
45
|
+
| Method | Returns | Description |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `get_umi_length()` | `int` | UMI length from `OverrideCycles` |
|
|
48
|
+
| `get_read_structure()` | `ReadStructure` | Parsed read structure dataclass |
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## SampleSheetConverter
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
SampleSheetConverter(path, *, workflow: Workflow | str | None = None)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| Method / attribute | Returns | Description |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `to_v2(output_path)` | `Path` | Convert IEM V1 → BCLConvert V2 |
|
|
61
|
+
| `to_v1(output_path)` | `Path` | Convert BCLConvert V2 → IEM V1 (lossy) |
|
|
62
|
+
| `.source_version` | `SampleSheetVersion \| None` | Auto-detected format of the input |
|
|
63
|
+
| `.workflow_override` | `Workflow \| None` | Resolved workflow override, if any |
|
|
64
|
+
|
|
65
|
+
The `workflow` parameter accepts `"a"`, `"b"`, or a `Workflow` enum value
|
|
66
|
+
and overrides auto-detection of the i5 orientation workflow from the
|
|
67
|
+
instrument header. See
|
|
68
|
+
[Conversion → Index 2 orientation](guide/conversion.md#index-2-i5-orientation).
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## samplesheet_parser.instruments
|
|
73
|
+
|
|
74
|
+
i5 orientation workflow classification helpers.
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
from samplesheet_parser.instruments import (
|
|
78
|
+
Workflow,
|
|
79
|
+
detect_workflow,
|
|
80
|
+
parse_workflow,
|
|
81
|
+
reverse_complement,
|
|
82
|
+
WORKFLOW_A_INSTRUMENTS,
|
|
83
|
+
WORKFLOW_B_INSTRUMENTS,
|
|
84
|
+
AMBIGUOUS_INSTRUMENTS,
|
|
85
|
+
)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| Name | Kind | Description |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `Workflow` | `StrEnum` | `Workflow.A` (i5 forward) / `Workflow.B` (i5 RC'd on chip) |
|
|
91
|
+
| `detect_workflow(name)` | `Workflow \| None` | Classify an instrument name; `None` for unknown or ambiguous (e.g. `NovaSeq 6000`) |
|
|
92
|
+
| `parse_workflow(value)` | `Workflow \| None` | Coerce a CLI string (`"a"` / `"b"`) to `Workflow` |
|
|
93
|
+
| `reverse_complement(seq)` | `str` | Reverse-complement a DNA sequence (preserves `N`, case-preserving) |
|
|
94
|
+
| `WORKFLOW_A_INSTRUMENTS` | `frozenset[str]` | Normalised names of workflow-A instruments |
|
|
95
|
+
| `WORKFLOW_B_INSTRUMENTS` | `frozenset[str]` | Normalised names of workflow-B instruments |
|
|
96
|
+
| `AMBIGUOUS_INSTRUMENTS` | `frozenset[str]` | Instruments whose workflow depends on chemistry and require an explicit override |
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## SampleSheetValidator
|
|
101
|
+
|
|
102
|
+
| Method | Returns | Description |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| `validate(sheet, *, min_hamming_distance=3)` | `ValidationResult` | Run all checks; returns structured result |
|
|
105
|
+
|
|
106
|
+
### ValidationResult
|
|
107
|
+
|
|
108
|
+
| Attribute / method | Type | Description |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `is_valid` | `bool` | `False` if any errors present |
|
|
111
|
+
| `errors` | `list[ValidationIssue]` | Structured error records |
|
|
112
|
+
| `warnings` | `list[ValidationIssue]` | Structured warning records |
|
|
113
|
+
| `summary()` | `str` | One-line human-readable summary |
|
|
114
|
+
|
|
115
|
+
### ValidationIssue
|
|
116
|
+
|
|
117
|
+
| Attribute | Type | Description |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `code` | `str` | e.g. `"DUPLICATE_INDEX"` |
|
|
120
|
+
| `message` | `str` | Human-readable description |
|
|
121
|
+
| `context` | `dict` | Relevant sample IDs, lane, etc. |
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## SampleSheetDiff
|
|
126
|
+
|
|
127
|
+
| Method | Returns | Description |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| `compare()` | `DiffResult` | Full comparison across header, reads, settings, and samples |
|
|
130
|
+
|
|
131
|
+
### DiffResult
|
|
132
|
+
|
|
133
|
+
| Attribute / method | Type | Description |
|
|
134
|
+
|---|---|---|
|
|
135
|
+
| `has_changes` | `bool` | `True` if any difference detected |
|
|
136
|
+
| `summary()` | `str` | Human-readable one-paragraph summary |
|
|
137
|
+
| `header_changes` | `list[HeaderChange]` | Header, reads, and settings diffs |
|
|
138
|
+
| `samples_added` | `list[dict]` | Records present in new sheet only |
|
|
139
|
+
| `samples_removed` | `list[dict]` | Records present in old sheet only |
|
|
140
|
+
| `sample_changes` | `list[SampleChange]` | Per-sample field-level diffs |
|
|
141
|
+
| `source_version` | `SampleSheetVersion` | Format of the old sheet |
|
|
142
|
+
| `target_version` | `SampleSheetVersion` | Format of the new sheet |
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## SampleSheetWriter
|
|
147
|
+
|
|
148
|
+
| Method / attribute | Returns | Description |
|
|
149
|
+
|---|---|---|
|
|
150
|
+
| `SampleSheetWriter(version=)` | — | Instantiate for `SampleSheetVersion.V1` or `.V2` |
|
|
151
|
+
| `from_sheet(sheet, version=)` | `SampleSheetWriter` | Load a parsed sheet for editing; optionally change format |
|
|
152
|
+
| `set_header(*, run_name, platform, ...)` | `self` | Set header fields (fluent) |
|
|
153
|
+
| `set_reads(*, read1, read2, index1, index2)` | `self` | Set read cycle counts (fluent) |
|
|
154
|
+
| `set_adapter(adapter_read1, adapter_read2)` | `self` | Set adapter sequences (fluent) |
|
|
155
|
+
| `set_override_cycles(override)` | `self` | Set `OverrideCycles` — V2 only (fluent) |
|
|
156
|
+
| `set_software_version(version)` | `self` | Set `SoftwareVersion` — V2 only (fluent) |
|
|
157
|
+
| `set_setting(key, value)` | `self` | Set an arbitrary settings key/value (fluent) |
|
|
158
|
+
| `add_sample(sample_id, *, index, ...)` | `self` | Append a sample row (fluent) |
|
|
159
|
+
| `remove_sample(sample_id, *, lane=)` | `self` | Remove sample(s) by ID, optionally scoped to a lane (fluent) |
|
|
160
|
+
| `update_sample(sample_id, *, lane=, **fields)` | `self` | Update fields on an existing sample in-place (fluent) |
|
|
161
|
+
| `clear_samples()` | `self` | Remove all samples while preserving header/reads/settings (fluent) |
|
|
162
|
+
| `write(path, *, validate=True)` | `Path` | Serialise to disk; validates first by default |
|
|
163
|
+
| `to_string()` | `str` | Serialise to string without writing to disk |
|
|
164
|
+
| `.sample_count` | `int` | Number of samples currently in the writer |
|
|
165
|
+
| `.sample_ids` | `list[str]` | Sample IDs currently in the writer |
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## SampleSheetMerger
|
|
170
|
+
|
|
171
|
+
| Method / attribute | Returns | Description |
|
|
172
|
+
|---|---|---|
|
|
173
|
+
| `SampleSheetMerger(target_version=, min_hamming_distance=3)` | — | Instantiate with target format and optional Hamming threshold |
|
|
174
|
+
| `add(path)` | `self` | Register an input sheet path (fluent) |
|
|
175
|
+
| `merge(output_path, *, validate=True, abort_on_conflicts=True)` | `MergeResult` | Run the merge and write output |
|
|
176
|
+
|
|
177
|
+
### MergeResult
|
|
178
|
+
|
|
179
|
+
| Attribute / method | Type | Description |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| `has_conflicts` | `bool` | `True` if any conflict recorded |
|
|
182
|
+
| `sample_count` | `int` | Samples in the merged output |
|
|
183
|
+
| `output_path` | `Path \| None` | Path written; `None` if write was aborted |
|
|
184
|
+
| `source_versions` | `dict[str, str]` | Per-input-file detected version |
|
|
185
|
+
| `conflicts` | `list[MergeConflict]` | Structured conflict records |
|
|
186
|
+
| `warnings` | `list[MergeConflict]` | Structured warning records |
|
|
187
|
+
| `summary()` | `str` | One-line human-readable summary |
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## SampleSheetSplitter
|
|
192
|
+
|
|
193
|
+
| Method / attribute | Returns | Description |
|
|
194
|
+
|---|---|---|
|
|
195
|
+
| `SampleSheetSplitter(path, *, by="project", target_version=None, unassigned_label="unassigned")` | — | Instantiate with input path and grouping strategy |
|
|
196
|
+
| `split(output_dir, *, prefix="", suffix="_SampleSheet.csv", validate=True)` | `SplitResult` | Parse input and write one file per group |
|
|
197
|
+
|
|
198
|
+
### SplitResult
|
|
199
|
+
|
|
200
|
+
| Attribute / method | Type | Description |
|
|
201
|
+
|---|---|---|
|
|
202
|
+
| `output_files` | `dict[str, Path]` | Group key → path of the written file |
|
|
203
|
+
| `sample_counts` | `dict[str, int]` | Group key → number of samples written |
|
|
204
|
+
| `warnings` | `list[str]` | Non-fatal issues (incomplete records, unassigned samples) |
|
|
205
|
+
| `source_version` | `str` | `"V1"` or `"V2"` |
|
|
206
|
+
| `summary()` | `str` | One-line human-readable summary |
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## SampleSheetFilter
|
|
211
|
+
|
|
212
|
+
| Method / attribute | Returns | Description |
|
|
213
|
+
|---|---|---|
|
|
214
|
+
| `SampleSheetFilter(path, *, target_version=None)` | — | Instantiate with input path |
|
|
215
|
+
| `filter(output_path, *, project=None, lane=None, sample_id=None, validate=True)` | `FilterResult` | Write filtered copy to `output_path`; at least one criterion required |
|
|
216
|
+
|
|
217
|
+
`sample_id` supports glob patterns (e.g. `"CTRL_*"`) via `fnmatch.fnmatchcase` — matching is always case-sensitive.
|
|
218
|
+
|
|
219
|
+
### FilterResult
|
|
220
|
+
|
|
221
|
+
| Attribute / method | Type | Description |
|
|
222
|
+
|---|---|---|
|
|
223
|
+
| `matched_count` | `int` | Samples that passed all filter criteria |
|
|
224
|
+
| `total_count` | `int` | Total samples in the input sheet |
|
|
225
|
+
| `output_path` | `Path \| None` | Path written; `None` when no samples matched |
|
|
226
|
+
| `source_version` | `str` | `"V1"` or `"V2"` |
|
|
227
|
+
| `summary()` | `str` | One-line human-readable summary |
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## normalize_index_lengths
|
|
232
|
+
|
|
233
|
+
```python
|
|
234
|
+
normalize_index_lengths(
|
|
235
|
+
samples: list[dict],
|
|
236
|
+
strategy: str, # "trim" or "pad"
|
|
237
|
+
index1_key: str | None = None, # auto-detected if None
|
|
238
|
+
index2_key: str | None = None, # auto-detected if None
|
|
239
|
+
) -> list[dict]
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Normalizes index sequence lengths across a list of sample dicts. See [Index Utilities](guide/index_utils.md) for details.
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Enums
|
|
247
|
+
|
|
248
|
+
```python
|
|
249
|
+
from samplesheet_parser.enums import SampleSheetVersion, InstrumentPlatform, UMILocation
|
|
250
|
+
|
|
251
|
+
SampleSheetVersion.V1 # IEM / bcl2fastq
|
|
252
|
+
SampleSheetVersion.V2 # BCLConvert
|
|
253
|
+
```
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# CI Integration
|
|
2
|
+
|
|
3
|
+
The CLI exits with meaningful codes (`0` = clean, `1` = issues, `2` = error), making it easy to wire into automated pipelines.
|
|
4
|
+
|
|
5
|
+
## GitHub Actions
|
|
6
|
+
|
|
7
|
+
Add a validation step to any workflow that touches `SampleSheet.csv`:
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
# .github/workflows/validate-samplesheet.yml
|
|
11
|
+
name: Validate SampleSheet
|
|
12
|
+
|
|
13
|
+
on:
|
|
14
|
+
push:
|
|
15
|
+
paths:
|
|
16
|
+
- '**/SampleSheet.csv'
|
|
17
|
+
pull_request:
|
|
18
|
+
paths:
|
|
19
|
+
- '**/SampleSheet.csv'
|
|
20
|
+
|
|
21
|
+
jobs:
|
|
22
|
+
validate:
|
|
23
|
+
runs-on: ubuntu-latest
|
|
24
|
+
steps:
|
|
25
|
+
- uses: actions/checkout@v4
|
|
26
|
+
|
|
27
|
+
- uses: actions/setup-python@v5
|
|
28
|
+
with:
|
|
29
|
+
python-version: '3.12'
|
|
30
|
+
|
|
31
|
+
- run: pip install "samplesheet-parser[cli]"
|
|
32
|
+
|
|
33
|
+
- name: Validate SampleSheet
|
|
34
|
+
run: samplesheet validate SampleSheet.csv --format json
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## pre-commit hook
|
|
38
|
+
|
|
39
|
+
Gate commits that touch any `SampleSheet.csv` in the repository:
|
|
40
|
+
|
|
41
|
+
```yaml
|
|
42
|
+
# .pre-commit-config.yaml
|
|
43
|
+
repos:
|
|
44
|
+
- repo: local
|
|
45
|
+
hooks:
|
|
46
|
+
- id: samplesheet-validate
|
|
47
|
+
name: Validate SampleSheet.csv
|
|
48
|
+
entry: samplesheet validate
|
|
49
|
+
language: python
|
|
50
|
+
additional_dependencies: ["samplesheet-parser[cli]"]
|
|
51
|
+
files: SampleSheet\.csv$
|
|
52
|
+
pass_filenames: true
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Install and run once to verify:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install pre-commit
|
|
59
|
+
pre-commit install
|
|
60
|
+
pre-commit run samplesheet-validate --all-files
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Stricter Hamming distance in CI
|
|
64
|
+
|
|
65
|
+
If your lab uses longer indexes (10 bp+), raise the minimum Hamming distance threshold to catch borderline cases earlier:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
samplesheet validate SampleSheet.csv --min-hamming 4
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Using JSON output in scripts
|
|
72
|
+
|
|
73
|
+
All commands support `--format json` for machine-readable output:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
result=$(samplesheet validate SampleSheet.csv --format json)
|
|
77
|
+
is_valid=$(echo "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['is_valid'])")
|
|
78
|
+
|
|
79
|
+
if [ "$is_valid" != "True" ]; then
|
|
80
|
+
echo "SampleSheet validation failed"
|
|
81
|
+
exit 1
|
|
82
|
+
fi
|
|
83
|
+
```
|