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.
Files changed (140) hide show
  1. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.gitignore +1 -0
  2. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.pre-commit-config.yaml +1 -0
  3. samplesheet_parser-1.3.0/.readthedocs.yaml +17 -0
  4. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/CHANGELOG.md +144 -0
  5. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/CITATION.cff +2 -2
  6. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/PKG-INFO +11 -3
  7. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/README.md +5 -0
  8. samplesheet_parser-1.3.0/docs/api.md +253 -0
  9. samplesheet_parser-1.3.0/docs/changelog.md +5 -0
  10. samplesheet_parser-1.3.0/docs/ci.md +83 -0
  11. samplesheet_parser-1.3.0/docs/cli.md +263 -0
  12. samplesheet_parser-1.3.0/docs/contributing.md +5 -0
  13. samplesheet_parser-1.3.0/docs/examples.md +365 -0
  14. samplesheet_parser-1.3.0/docs/guide/conversion.md +134 -0
  15. samplesheet_parser-1.3.0/docs/guide/diffing.md +59 -0
  16. samplesheet_parser-1.3.0/docs/guide/filtering.md +101 -0
  17. samplesheet_parser-1.3.0/docs/guide/index_utils.md +60 -0
  18. samplesheet_parser-1.3.0/docs/guide/merging.md +87 -0
  19. samplesheet_parser-1.3.0/docs/guide/parsing.md +84 -0
  20. samplesheet_parser-1.3.0/docs/guide/quickstart.md +69 -0
  21. samplesheet_parser-1.3.0/docs/guide/splitting.md +102 -0
  22. samplesheet_parser-1.3.0/docs/guide/validation.md +59 -0
  23. samplesheet_parser-1.3.0/docs/guide/writing.md +82 -0
  24. samplesheet_parser-1.3.0/docs/index.md +59 -0
  25. samplesheet_parser-1.3.0/docs/installation.md +41 -0
  26. samplesheet_parser-1.3.0/docs/requirements.txt +4 -0
  27. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_converter.py +6 -3
  28. samplesheet_parser-1.3.0/examples/demo_filter.py +110 -0
  29. samplesheet_parser-1.3.0/examples/demo_splitter.py +87 -0
  30. samplesheet_parser-1.3.0/mkdocs.yml +80 -0
  31. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/environment.yml +6 -0
  32. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/main.nf +50 -0
  33. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/meta.yml +62 -0
  34. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/tests/main.nf.test +79 -0
  35. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/convert/tests/tags.yml +4 -0
  36. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/environment.yml +6 -0
  37. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/main.nf +45 -0
  38. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/meta.yml +69 -0
  39. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/tests/main.nf.test +79 -0
  40. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/diff/tests/tags.yml +4 -0
  41. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/environment.yml +6 -0
  42. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/main.nf +48 -0
  43. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/meta.yml +74 -0
  44. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/main.nf.test +57 -0
  45. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/nextflow.config +5 -0
  46. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/filter/tests/tags.yml +4 -0
  47. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/environment.yml +6 -0
  48. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/main.nf +45 -0
  49. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/meta.yml +61 -0
  50. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/tests/main.nf.test +76 -0
  51. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/info/tests/tags.yml +4 -0
  52. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/environment.yml +6 -0
  53. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/main.nf +53 -0
  54. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/meta.yml +73 -0
  55. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/tests/main.nf.test +88 -0
  56. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/merge/tests/tags.yml +4 -0
  57. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/environment.yml +6 -0
  58. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/main.nf +56 -0
  59. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/meta.yml +73 -0
  60. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/tests/main.nf.test +79 -0
  61. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/split/tests/tags.yml +4 -0
  62. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/environment.yml +6 -0
  63. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/main.nf +45 -0
  64. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/meta.yml +62 -0
  65. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/tests/main.nf.test +76 -0
  66. samplesheet_parser-1.3.0/modules/nf-core/samplesheetparser/validate/tests/tags.yml +4 -0
  67. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/pyproject.toml +6 -3
  68. samplesheet_parser-1.3.0/recipes/meta.yaml +56 -0
  69. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/__init__.py +6 -0
  70. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/cli.py +245 -6
  71. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/converter.py +191 -47
  72. samplesheet_parser-1.3.0/samplesheet_parser/filter.py +243 -0
  73. samplesheet_parser-1.3.0/samplesheet_parser/instruments.py +192 -0
  74. samplesheet_parser-1.3.0/samplesheet_parser/splitter.py +303 -0
  75. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/writer.py +190 -147
  76. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_cli.py +296 -0
  77. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_converter.py +404 -48
  78. samplesheet_parser-1.3.0/tests/test_filter.py +380 -0
  79. samplesheet_parser-1.3.0/tests/test_instruments.py +126 -0
  80. samplesheet_parser-1.3.0/tests/test_splitter.py +466 -0
  81. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.github/workflows/ci.yml +0 -0
  82. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.github/workflows/copilot-instructions.md +0 -0
  83. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/.zenodo.json +0 -0
  84. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/CONTRIBUTING.md +0 -0
  85. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/LICENSE +0 -0
  86. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_diff.py +0 -0
  87. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_index_utils.py +0 -0
  88. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_merger.py +0 -0
  89. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/demo_writer.py +0 -0
  90. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/parse_examples.py +0 -0
  91. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  92. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  93. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  94. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  95. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/README.md +0 -0
  96. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/combined_clean.csv +0 -0
  97. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  98. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  99. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  100. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  101. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  102. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  103. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  104. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  105. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  106. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  107. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  108. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  109. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  110. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/images/samplesheet_parser_arch_v03.png +0 -0
  111. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/images/samplesheet_parser_overview.png +0 -0
  112. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/diff.py +0 -0
  113. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/enums.py +0 -0
  114. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/factory.py +0 -0
  115. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/index_utils.py +0 -0
  116. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/merger.py +0 -0
  117. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/parsers/__init__.py +0 -0
  118. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/parsers/v1.py +0 -0
  119. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/parsers/v2.py +0 -0
  120. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/py.typed +0 -0
  121. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/samplesheet_parser/validators.py +0 -0
  122. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/scripts/demo_converter.py +0 -0
  123. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/scripts/demo_diff.py +0 -0
  124. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/scripts/demo_writer.py +0 -0
  125. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/__init__.py +0 -0
  126. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/conftest.py +0 -0
  127. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  128. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  129. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  130. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_diff.py +0 -0
  131. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_factory.py +0 -0
  132. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_index_utils.py +0 -0
  133. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_merger.py +0 -0
  134. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_parsers/__init__.py +0 -0
  135. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_parsers/test_v1.py +0 -0
  136. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_parsers/test_v2.py +0 -0
  137. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_validators/__init__.py +0 -0
  138. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_validators/test_hamming.py +0 -0
  139. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_validators/test_validators.py +0 -0
  140. {samplesheet_parser-1.1.0 → samplesheet_parser-1.3.0}/tests/test_writer.py +0 -0
@@ -45,3 +45,4 @@ env/
45
45
  *.backup
46
46
  *.tmp
47
47
 
48
+ site/
@@ -5,6 +5,7 @@ repos:
5
5
  - id: trailing-whitespace
6
6
  - id: end-of-file-fixer
7
7
  - id: check-yaml
8
+ exclude: ^recipes/
8
9
  - id: check-toml
9
10
  - id: check-merge-conflict
10
11
  - id: check-added-large-files
@@ -0,0 +1,17 @@
1
+ version: 2
2
+
3
+ build:
4
+ os: ubuntu-24.04
5
+ tools:
6
+ python: "3.12"
7
+
8
+ mkdocs:
9
+ configuration: mkdocs.yml
10
+
11
+ python:
12
+ install:
13
+ - method: pip
14
+ path: .
15
+ extra_requirements:
16
+ - cli
17
+ - requirements: docs/requirements.txt
@@ -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.1.0
12
- date-released: 2026-04-05
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.1.0
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.9; extra == 'cli'
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.9; extra == 'dev'
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
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
59
62
  [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
60
63
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
64
+ [![Install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
65
+
61
66
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
62
67
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
68
+ [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
63
69
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](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
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
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
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
8
8
  [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
9
9
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
10
+ [![Install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/samplesheet-parser/README.html)
11
+
10
12
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
11
13
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
14
+ [![Docs](https://readthedocs.org/projects/illumina-samplesheet/badge/)](https://illumina-samplesheet.readthedocs.io)
12
15
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18989694.svg)](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
  ![samplesheet-parser overview](https://raw.githubusercontent.com/chaitanyakasaraneni/samplesheet-parser/main/images/samplesheet_parser_arch_v03.png)
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,5 @@
1
+ # Changelog
2
+
3
+ The full changelog is maintained in the repository:
4
+
5
+ --8<-- "CHANGELOG.md"
@@ -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
+ ```