samplesheet-parser 0.3.4__tar.gz → 1.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.
Files changed (74) hide show
  1. samplesheet_parser-1.1.0/.pre-commit-config.yaml +29 -0
  2. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/.zenodo.json +1 -1
  3. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/CHANGELOG.md +93 -0
  4. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/CITATION.cff +2 -2
  5. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/CONTRIBUTING.md +1 -1
  6. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/PKG-INFO +5 -5
  7. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/README.md +3 -3
  8. samplesheet_parser-1.1.0/examples/demo_converter.py +117 -0
  9. samplesheet_parser-1.1.0/examples/demo_diff.py +144 -0
  10. samplesheet_parser-1.1.0/examples/demo_index_utils.py +123 -0
  11. samplesheet_parser-1.1.0/examples/demo_writer.py +170 -0
  12. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/pyproject.toml +5 -2
  13. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/__init__.py +4 -2
  14. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/cli.py +115 -79
  15. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/factory.py +6 -4
  16. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/index_utils.py +3 -2
  17. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/merger.py +85 -62
  18. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_cli.py +148 -42
  19. samplesheet_parser-1.1.0/tests/test_validators/__init__.py +0 -0
  20. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/.github/workflows/ci.yml +0 -0
  21. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/.github/workflows/copilot-instructions.md +0 -0
  22. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/.gitignore +0 -0
  23. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/LICENSE +0 -0
  24. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/demo_merger.py +0 -0
  25. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/parse_examples.py +0 -0
  26. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/ProjectAlpha_SampleSheet.csv +0 -0
  27. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/ProjectBeta_SampleSheet.csv +0 -0
  28. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/ProjectDelta_SampleSheet_collision.csv +0 -0
  29. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/ProjectGamma_SampleSheet.csv +0 -0
  30. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/README.md +0 -0
  31. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/combined_clean.csv +0 -0
  32. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/combined_collision_forced.csv +0 -0
  33. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/combined_mixed_formats.csv +0 -0
  34. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v1_dual_index.csv +0 -0
  35. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v1_multi_lane.csv +0 -0
  36. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v1_single_index.csv +0 -0
  37. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v1_with_lab_qc_settings.csv +0 -0
  38. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v1_with_manifests.csv +0 -0
  39. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v2_nextseq_single_index.csv +0 -0
  40. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v2_novaseq_x_dual_index.csv +0 -0
  41. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v2_with_cloud_settings.csv +0 -0
  42. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v2_with_index_umi.csv +0 -0
  43. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v2_with_pipeline_settings.csv +0 -0
  44. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/examples/sample_sheets/v2_with_read_umi.csv +0 -0
  45. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/images/samplesheet_parser_arch_v03.png +0 -0
  46. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/images/samplesheet_parser_overview.png +0 -0
  47. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/converter.py +0 -0
  48. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/diff.py +0 -0
  49. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/enums.py +0 -0
  50. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/parsers/__init__.py +0 -0
  51. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/parsers/v1.py +0 -0
  52. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/parsers/v2.py +0 -0
  53. /samplesheet_parser-0.3.4/tests/__init__.py → /samplesheet_parser-1.1.0/samplesheet_parser/py.typed +0 -0
  54. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/validators.py +0 -0
  55. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/samplesheet_parser/writer.py +0 -0
  56. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/scripts/demo_converter.py +0 -0
  57. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/scripts/demo_diff.py +0 -0
  58. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/scripts/demo_writer.py +0 -0
  59. {samplesheet_parser-0.3.4/tests/test_parsers → samplesheet_parser-1.1.0/tests}/__init__.py +0 -0
  60. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/conftest.py +0 -0
  61. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/fixtures/SampleSheet_v1_dual_index.csv +0 -0
  62. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/fixtures/SampleSheet_v2_dual_index.csv +0 -0
  63. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/fixtures/SampleSheet_v2_modified.csv +0 -0
  64. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_converter.py +0 -0
  65. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_diff.py +0 -0
  66. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_factory.py +0 -0
  67. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_index_utils.py +0 -0
  68. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_merger.py +0 -0
  69. {samplesheet_parser-0.3.4/tests/test_validators → samplesheet_parser-1.1.0/tests/test_parsers}/__init__.py +0 -0
  70. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_parsers/test_v1.py +0 -0
  71. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_parsers/test_v2.py +0 -0
  72. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_validators/test_hamming.py +0 -0
  73. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_validators/test_validators.py +0 -0
  74. {samplesheet_parser-0.3.4 → samplesheet_parser-1.1.0}/tests/test_writer.py +0 -0
@@ -0,0 +1,29 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v5.0.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-yaml
8
+ - id: check-toml
9
+ - id: check-merge-conflict
10
+ - id: check-added-large-files
11
+
12
+ - repo: https://github.com/psf/black
13
+ rev: 24.10.0
14
+ hooks:
15
+ - id: black
16
+ language_version: python3.12
17
+
18
+ - repo: https://github.com/astral-sh/ruff-pre-commit
19
+ rev: v0.9.0
20
+ hooks:
21
+ - id: ruff
22
+ args: [--fix]
23
+
24
+ - repo: https://github.com/pre-commit/mirrors-mypy
25
+ rev: v1.13.0
26
+ hooks:
27
+ - id: mypy
28
+ additional_dependencies: [loguru, typer]
29
+ args: [--ignore-missing-imports]
@@ -4,7 +4,7 @@
4
4
  "upload_type": "software",
5
5
  "access_right": "open",
6
6
  "license": "Apache-2.0",
7
- "version": "0.3.1",
7
+ "version": "1.1.0",
8
8
  "keywords": [
9
9
  "bioinformatics", "Illumina", "SampleSheet", "BCLConvert",
10
10
  "demultiplexing", "genomics", "sequencing", "Python"
@@ -6,6 +6,99 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
6
6
 
7
7
  ---
8
8
 
9
+ ## [1.1.0] - 2026-04-05
10
+
11
+ ### Added
12
+
13
+ - **`--version` / `-V` CLI flag** — prints the installed package version
14
+ and exits. Reads the version via `importlib.metadata` so the full package
15
+ is not loaded just to print a version string.
16
+
17
+ - **`demo_converter.py`** — runnable example covering V1→V2 conversion,
18
+ V2→V1 (lossy) conversion, and a full V1→V2→V1 roundtrip with sample
19
+ identity verification.
20
+
21
+ - **`demo_diff.py`** — runnable example covering five diff scenarios:
22
+ identical sheets, header change, sample added, index correction, and
23
+ cross-format (V1 vs its V2 conversion) diff.
24
+
25
+ - **`demo_writer.py`** — runnable example covering the fluent
26
+ `SampleSheetWriter` API: building V1 and V2 sheets from scratch,
27
+ correcting a sample index on an existing sheet, and removing a sample
28
+ before submission.
29
+
30
+ - **`demo_index_utils.py`** — runnable example covering
31
+ `normalize_index_lengths` with trim and pad strategies, dual-index
32
+ normalization, and a real-sheet walkthrough.
33
+
34
+ ### Fixed
35
+
36
+ - `SampleSheetFactory.create_parser()` now returns a typed local variable
37
+ instead of `self.parser`, resolving a mypy `return-value` error caused
38
+ by the instance attribute being typed as `SampleSheetV1 | SampleSheetV2
39
+ | None`.
40
+
41
+ - `cli.py` fallback type aliases (`_FormatOption`, `_OutputOption`,
42
+ `_VersionOption`) reduced from `type: ignore[assignment,misc]` to
43
+ `type: ignore[misc]` — the `assignment` suppression was unused under
44
+ current mypy.
45
+
46
+ ### Tests
47
+
48
+ - `TestCLIVersion` — four new tests covering `--version` exit code, `-V`
49
+ short flag, package name in output, version string in output, and
50
+ `PackageNotFoundError` fallback to `"unknown"`.
51
+
52
+ - Five Copilot PR #23 review comments resolved: long test signatures and
53
+ `runner.invoke(...)` calls wrapped to the 100-char line limit.
54
+
55
+ ---
56
+
57
+ ## [1.0.0] - 2026-04-05
58
+
59
+ ### Added
60
+
61
+ - **`py.typed` marker** — package now ships inline type information per
62
+ PEP 561, enabling mypy and pyright to type-check downstream code without
63
+ extra configuration.
64
+
65
+ - **`InstrumentPlatform` and `UMILocation` enums exported** — both were
66
+ already defined in `enums.py` but not part of the public API. They are now
67
+ importable directly from the top-level package and listed in `__all__`.
68
+
69
+ - **`.pre-commit-config.yaml`** — pre-commit hook configuration included in
70
+ the repository (black, ruff with `--fix`, mypy, and standard file hygiene
71
+ hooks) so contributors get the same checks locally that CI enforces.
72
+
73
+ ### Fixed
74
+
75
+ - `SampleSheetFactory.create_parser()` now returns a typed local variable
76
+ instead of `self.parser`, resolving a mypy `return-value` error caused by
77
+ the instance attribute being typed as `SampleSheetV1 | SampleSheetV2 | None`.
78
+
79
+ - `SampleSheetMerger._parse_all()` guards against `factory.version` being
80
+ `None` before accessing `.value`, fixing a potential `AttributeError` on
81
+ unexpected parse paths.
82
+
83
+ - Removed redundant `type: ignore[assignment]` suppressions in
84
+ `index_utils.py` that were no longer needed under strict mypy.
85
+
86
+ ### Changed
87
+
88
+ - Development status classifier updated from `3 - Alpha` to
89
+ `5 - Production/Stable`.
90
+
91
+ - Ruff config adds `[tool.ruff.lint.per-file-ignores]` to suppress E402 for
92
+ `samplesheet_parser/__init__.py`, where the version-detection block
93
+ intentionally precedes the package re-exports.
94
+
95
+ - **Stability guarantee** — `1.0.0` marks the first stable release.
96
+ The public API (all names in `__init__.__all__`) is now subject to
97
+ semantic versioning: breaking changes will not be made without a major
98
+ version bump.
99
+
100
+ ---
101
+
9
102
  ## [0.3.4] - 2026-04-04
10
103
 
11
104
  ### 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: 0.3.2
12
- date-released: 2026-03-12
11
+ version: 1.1.0
12
+ date-released: 2026-04-05
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"
@@ -28,7 +28,7 @@ Thanks for contributing! This guide explains how to set up a local development e
28
28
  git clone https://github.com/chaitanyakasaraneni/samplesheet-parser.git
29
29
  cd samplesheet-parser
30
30
 
31
- # 2. Create a virtual environment (Python 3.10+)
31
+ # 2. Create a virtual environment (Python 3.12+)
32
32
  python -m venv .venv
33
33
  source .venv/bin/activate # Windows: .venv\Scripts\activate
34
34
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: samplesheet-parser
3
- Version: 0.3.4
3
+ Version: 1.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
@@ -28,7 +28,7 @@ License: Apache License
28
28
  limitations under the License.
29
29
  License-File: LICENSE
30
30
  Keywords: bcl2fastq,bclconvert,bioinformatics,demultiplexing,genomics,illumina,ngs,samplesheet,sequencing
31
- Classifier: Development Status :: 3 - Alpha
31
+ Classifier: Development Status :: 5 - Production/Stable
32
32
  Classifier: Intended Audience :: Developers
33
33
  Classifier: Intended Audience :: Science/Research
34
34
  Classifier: License :: OSI Approved :: Apache Software License
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
56
56
  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.
57
57
 
58
58
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
59
- [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
59
+ [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
60
60
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
61
61
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
62
62
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
@@ -86,7 +86,7 @@ pip install samplesheet-parser
86
86
  pip install "samplesheet-parser[cli]"
87
87
  ```
88
88
 
89
- Requires Python 3.10+. No mandatory runtime dependencies beyond `loguru`.
89
+ Requires Python 3.12+. No mandatory runtime dependencies beyond `loguru`.
90
90
 
91
91
  ---
92
92
 
@@ -659,7 +659,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
659
659
  title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
660
660
  year = {2026},
661
661
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
662
- version = {0.3.4}
662
+ version = {1.1.0}
663
663
  }
664
664
  ```
665
665
 
@@ -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
  [![PyPI version](https://img.shields.io/pypi/v/samplesheet-parser.svg)](https://pypi.org/project/samplesheet-parser/)
8
- [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
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
10
  [![Tests](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/chaitanyakasaraneni/samplesheet-parser/actions)
11
11
  [![codecov](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser/branch/main/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/chaitanyakasaraneni/samplesheet-parser)
@@ -35,7 +35,7 @@ pip install samplesheet-parser
35
35
  pip install "samplesheet-parser[cli]"
36
36
  ```
37
37
 
38
- Requires Python 3.10+. No mandatory runtime dependencies beyond `loguru`.
38
+ Requires Python 3.12+. No mandatory runtime dependencies beyond `loguru`.
39
39
 
40
40
  ---
41
41
 
@@ -608,7 +608,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local testing guide and PR c
608
608
  title = {samplesheet-parser: Format-agnostic parser for Illumina SampleSheet.csv},
609
609
  year = {2026},
610
610
  url = {https://github.com/chaitanyakasaraneni/samplesheet-parser},
611
- version = {0.3.4}
611
+ version = {1.1.0}
612
612
  }
613
613
  ```
614
614
 
@@ -0,0 +1,117 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ demo_converter.py — SampleSheetConverter usage examples.
4
+
5
+ Demonstrates bidirectional conversion between V1 (IEM / bcl2fastq) and
6
+ V2 (BCLConvert) formats.
7
+
8
+ Scenario 1: V1 → V2 — classic dual-index sheet converted for NovaSeq X
9
+ Scenario 2: V2 → V1 — BCLConvert sheet converted back for bcl2fastq
10
+ Scenario 3: Roundtrip — V1 → V2 → V1 to inspect what is preserved / lost
11
+
12
+ Run from the repo root::
13
+
14
+ python3 examples/demo_converter.py
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import sys
20
+ from pathlib import Path
21
+
22
+ sys.path.insert(0, str(Path(__file__).parent.parent))
23
+
24
+ from samplesheet_parser import SampleSheetConverter, SampleSheetFactory
25
+
26
+ SHEETS = Path(__file__).parent / "sample_sheets"
27
+ OUT = Path(__file__).parent / "sample_sheets"
28
+
29
+
30
+ def _print_summary(label: str, path: Path) -> None:
31
+ factory = SampleSheetFactory()
32
+ sheet = factory.create_parser(path, parse=True)
33
+ samples = sheet.samples()
34
+ print(f" [{label}]")
35
+ print(f" Format : {factory.version.value if factory.version else 'unknown'}")
36
+ print(f" Samples : {len(samples)}")
37
+ print(f" Index : {sheet.index_type()}")
38
+ first = samples[0] if samples else {}
39
+ idx = first.get("index") or first.get("Index") or "—"
40
+ print(f" 1st idx : {idx}")
41
+ print()
42
+
43
+
44
+ # ---------------------------------------------------------------------------
45
+ # Scenario 1: V1 → V2
46
+ # ---------------------------------------------------------------------------
47
+
48
+ print("=" * 60)
49
+ print("Scenario 1: V1 → V2")
50
+ print("=" * 60)
51
+
52
+ src_v1 = SHEETS / "v1_dual_index.csv"
53
+ out_v2 = OUT / "converted_v1_to_v2.csv"
54
+
55
+ converter = SampleSheetConverter(str(src_v1))
56
+ result_path = converter.to_v2(str(out_v2))
57
+
58
+ print(f" Input : {src_v1.name} ({converter.source_version.value})")
59
+ print(f" Output : {result_path.name}")
60
+ print()
61
+ _print_summary("before", src_v1)
62
+ _print_summary("after", result_path)
63
+
64
+ # ---------------------------------------------------------------------------
65
+ # Scenario 2: V2 → V1
66
+ # ---------------------------------------------------------------------------
67
+
68
+ print("=" * 60)
69
+ print("Scenario 2: V2 → V1")
70
+ print("=" * 60)
71
+
72
+ src_v2 = SHEETS / "v2_novaseq_x_dual_index.csv"
73
+ out_v1 = OUT / "converted_v2_to_v1.csv"
74
+
75
+ converter = SampleSheetConverter(str(src_v2))
76
+ result_path = converter.to_v1(str(out_v1))
77
+
78
+ print(f" Input : {src_v2.name} ({converter.source_version.value})")
79
+ print(f" Output : {result_path.name}")
80
+ print(" Note : V2→V1 is lossy — OverrideCycles, UMI fields are dropped.")
81
+ print()
82
+ _print_summary("before", src_v2)
83
+ _print_summary("after", result_path)
84
+
85
+ # ---------------------------------------------------------------------------
86
+ # Scenario 3: Roundtrip V1 → V2 → V1
87
+ # ---------------------------------------------------------------------------
88
+
89
+ print("=" * 60)
90
+ print("Scenario 3: Roundtrip V1 → V2 → V1")
91
+ print("=" * 60)
92
+
93
+ tmp_v2 = OUT / "roundtrip_v2.csv"
94
+ tmp_v1 = OUT / "roundtrip_v1.csv"
95
+
96
+ SampleSheetConverter(str(src_v1)).to_v2(str(tmp_v2))
97
+ SampleSheetConverter(str(tmp_v2)).to_v1(str(tmp_v1))
98
+
99
+ factory_orig = SampleSheetFactory()
100
+ sheet_orig = factory_orig.create_parser(src_v1, parse=True)
101
+ factory_rt = SampleSheetFactory()
102
+ sheet_rt = factory_rt.create_parser(tmp_v1, parse=True)
103
+
104
+ orig_samples = {s["sample_id"] for s in sheet_orig.samples()}
105
+ rt_samples = {s["sample_id"] for s in sheet_rt.samples()}
106
+
107
+ print(f" Original format : {factory_orig.version.value if factory_orig.version else 'unknown'}")
108
+ print(f" Roundtrip format : {factory_rt.version.value if factory_rt.version else 'unknown'}")
109
+ print(f" Samples preserved: {orig_samples == rt_samples}")
110
+ print(f" Original IDs : {sorted(s for s in orig_samples if s)}")
111
+ print(f" Roundtrip IDs: {sorted(s for s in rt_samples if s)}")
112
+
113
+ # Clean up temp files
114
+ tmp_v2.unlink(missing_ok=True)
115
+ tmp_v1.unlink(missing_ok=True)
116
+ (OUT / "converted_v1_to_v2.csv").unlink(missing_ok=True)
117
+ (OUT / "converted_v2_to_v1.csv").unlink(missing_ok=True)
@@ -0,0 +1,144 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ demo_diff.py — SampleSheetDiff usage examples.
4
+
5
+ Demonstrates comparing two sample sheets — same format or cross-format —
6
+ to detect header changes, added/removed samples, and per-field sample diffs.
7
+
8
+ Scenario 1: Identical sheets — diff reports no changes (exit-0 analogue)
9
+ Scenario 2: Header change — experiment name updated between runs
10
+ Scenario 3: Sample added — a new sample appears in the newer sheet
11
+ Scenario 4: Sample field change — an index was corrected
12
+ Scenario 5: Cross-format diff — compare a V1 sheet against its V2 conversion
13
+
14
+ Run from the repo root::
15
+
16
+ python3 examples/demo_diff.py
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import sys
22
+ import textwrap
23
+ from pathlib import Path
24
+
25
+ sys.path.insert(0, str(Path(__file__).parent.parent))
26
+
27
+ from samplesheet_parser import SampleSheetDiff
28
+
29
+ SHEETS = Path(__file__).parent / "sample_sheets"
30
+
31
+ _V1_BASE = textwrap.dedent(
32
+ """\
33
+ [Header]
34
+ IEMFileVersion,5
35
+ Experiment Name,Run_001
36
+ Date,2024-01-15
37
+ Workflow,GenerateFASTQ
38
+ Chemistry,Amplicon
39
+
40
+ [Reads]
41
+ 151
42
+ 151
43
+
44
+ [Settings]
45
+ Adapter,AGATCGGAAGAGCACACGTCTGAACTCCAGTCA
46
+
47
+ [Data]
48
+ Lane,Sample_ID,Sample_Name,index,index2,Sample_Project
49
+ 1,SampleA,SampleAlpha,CAAGACAGAT,ACTATAGCCT,ProjectX
50
+ 1,SampleB,SampleBeta,TGAACCTGAT,TGATACGTCC,ProjectX
51
+ """
52
+ )
53
+
54
+
55
+ def _write_tmp(name: str, content: str) -> Path:
56
+ p = Path("/tmp") / name
57
+ p.write_text(content, encoding="utf-8")
58
+ return p
59
+
60
+
61
+ def _print_diff(label: str, old: Path, new: Path) -> None:
62
+ print(f"\n{'='*60}")
63
+ print(f" {label}")
64
+ print(f" old: {old.name} new: {new.name}")
65
+ print("=" * 60)
66
+
67
+ result = SampleSheetDiff(str(old), str(new)).compare()
68
+ print(f" Has changes : {result.has_changes}")
69
+ print(f" Summary : {result.summary()}")
70
+
71
+ if result.header_changes:
72
+ print("\n Header / settings changes:")
73
+ for c in result.header_changes:
74
+ print(f" {c.field}: {c.old_value!r} → {c.new_value!r}")
75
+
76
+ if result.samples_added:
77
+ print(f"\n Samples added : {result.samples_added}")
78
+
79
+ if result.samples_removed:
80
+ print(f"\n Samples removed : {result.samples_removed}")
81
+
82
+ if result.sample_changes:
83
+ print("\n Per-sample field changes:")
84
+ for sc in result.sample_changes:
85
+ for field, (old_val, new_val) in sc.changes.items():
86
+ print(f" {sc.sample_id} — {field}: {old_val!r} → {new_val!r}")
87
+
88
+
89
+ # ---------------------------------------------------------------------------
90
+ # Scenario 1: Identical sheets
91
+ # ---------------------------------------------------------------------------
92
+
93
+ old = _write_tmp("diff_base.csv", _V1_BASE)
94
+ new = _write_tmp("diff_identical.csv", _V1_BASE)
95
+ _print_diff("Scenario 1: Identical sheets", old, new)
96
+
97
+ # ---------------------------------------------------------------------------
98
+ # Scenario 2: Header change (experiment name updated)
99
+ # ---------------------------------------------------------------------------
100
+
101
+ updated_header = _V1_BASE.replace("Run_001", "Run_002")
102
+ new = _write_tmp("diff_header.csv", updated_header)
103
+ _print_diff("Scenario 2: Header change", old, new)
104
+
105
+ # ---------------------------------------------------------------------------
106
+ # Scenario 3: Sample added
107
+ # ---------------------------------------------------------------------------
108
+
109
+ with_extra = _V1_BASE + "1,SampleC,SampleGamma,GCACAACGTT,CATCTCACAG,ProjectX\n"
110
+ new = _write_tmp("diff_sample_added.csv", with_extra)
111
+ _print_diff("Scenario 3: Sample added", old, new)
112
+
113
+ # ---------------------------------------------------------------------------
114
+ # Scenario 4: Index corrected on SampleB
115
+ # ---------------------------------------------------------------------------
116
+
117
+ corrected = _V1_BASE.replace("TGAACCTGAT", "AACCGTGATC")
118
+ new = _write_tmp("diff_index_fix.csv", corrected)
119
+ _print_diff("Scenario 4: Index corrected", old, new)
120
+
121
+ # ---------------------------------------------------------------------------
122
+ # Scenario 5: Cross-format diff (V1 vs its V2 conversion)
123
+ # ---------------------------------------------------------------------------
124
+
125
+ from samplesheet_parser import SampleSheetConverter # noqa: E402
126
+
127
+ v1_sheet = SHEETS / "v1_dual_index.csv"
128
+ v2_out = Path("/tmp/diff_v2_converted.csv")
129
+ SampleSheetConverter(str(v1_sheet)).to_v2(str(v2_out))
130
+
131
+ _print_diff("Scenario 5: Cross-format diff (V1 vs V2 conversion)", v1_sheet, v2_out)
132
+
133
+ # Clean up
134
+ for f in [
135
+ old,
136
+ new,
137
+ v2_out,
138
+ Path("/tmp/diff_base.csv"),
139
+ Path("/tmp/diff_identical.csv"),
140
+ Path("/tmp/diff_header.csv"),
141
+ Path("/tmp/diff_sample_added.csv"),
142
+ Path("/tmp/diff_index_fix.csv"),
143
+ ]:
144
+ f.unlink(missing_ok=True)
@@ -0,0 +1,123 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ demo_index_utils.py — normalize_index_lengths usage examples.
4
+
5
+ Demonstrates normalizing mixed-length index sequences across a list of sample
6
+ records before merging sheets from different library prep kits.
7
+
8
+ Scenario 1: Trim to shortest — 10 bp + 8 bp kit → all trimmed to 8 bp
9
+ Scenario 2: Pad to longest — 8 bp + 10 bp kit → shorter padded with 'N'
10
+ Scenario 3: Dual-index mixed — both I7 and I5 lengths normalized together
11
+ Scenario 4: Real sheet usage — load a sheet, normalize, inspect the result
12
+
13
+ Run from the repo root::
14
+
15
+ python3 examples/demo_index_utils.py
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import sys
21
+ from pathlib import Path
22
+
23
+ sys.path.insert(0, str(Path(__file__).parent.parent))
24
+
25
+ from samplesheet_parser import SampleSheetFactory, normalize_index_lengths
26
+
27
+ SHEETS = Path(__file__).parent / "sample_sheets"
28
+
29
+
30
+ def _print_samples(samples: list[dict]) -> None: # type: ignore[type-arg]
31
+ for s in samples:
32
+ idx = s.get("index") or s.get("Index") or "—"
33
+ idx2 = s.get("index2") or s.get("Index2") or ""
34
+ idx2_str = f" index2={idx2}" if idx2 else ""
35
+ print(f" {s.get('sample_id') or s.get('Sample_ID'):<12} index={idx}{idx2_str}")
36
+ print()
37
+
38
+
39
+ # ---------------------------------------------------------------------------
40
+ # Scenario 1: Trim to shortest (10-mer + 8-mer → 8-mer)
41
+ # ---------------------------------------------------------------------------
42
+
43
+ print("=" * 60)
44
+ print("Scenario 1: Trim to shortest — mixed 10 bp / 8 bp I7")
45
+ print("=" * 60)
46
+
47
+ samples_mixed = [
48
+ {"sample_id": "SampleA", "index": "CAAGACAGAT"}, # 10 bp
49
+ {"sample_id": "SampleB", "index": "TGAACCTG"}, # 8 bp
50
+ {"sample_id": "SampleC", "index": "GCACAACG"}, # 8 bp
51
+ {"sample_id": "SampleD", "index": "ATCGCCTGTT"}, # 10 bp
52
+ ]
53
+
54
+ print(" Before:")
55
+ _print_samples(samples_mixed)
56
+
57
+ normalized = normalize_index_lengths(samples_mixed, strategy="trim")
58
+ print(" After (strategy='trim' → 8 bp):")
59
+ _print_samples(normalized)
60
+
61
+ # ---------------------------------------------------------------------------
62
+ # Scenario 2: Pad to longest (8-mer → 10-mer with 'NN' suffix)
63
+ # ---------------------------------------------------------------------------
64
+
65
+ print("=" * 60)
66
+ print("Scenario 2: Pad to longest — 8 bp padded to 10 bp")
67
+ print("=" * 60)
68
+
69
+ print(" Before:")
70
+ _print_samples(samples_mixed)
71
+
72
+ normalized = normalize_index_lengths(samples_mixed, strategy="pad")
73
+ print(" After (strategy='pad' → 10 bp, short indexes get 'N' suffix):")
74
+ _print_samples(normalized)
75
+
76
+ # ---------------------------------------------------------------------------
77
+ # Scenario 3: Dual-index — normalize both I7 and I5 together
78
+ # ---------------------------------------------------------------------------
79
+
80
+ print("=" * 60)
81
+ print("Scenario 3: Dual-index — normalize I7 and I5 independently")
82
+ print("=" * 60)
83
+
84
+ dual_mixed = [
85
+ {"sample_id": "SampleA", "index": "CAAGACAGAT", "index2": "ACTATAGCCT"}, # 10+10
86
+ {"sample_id": "SampleB", "index": "TGAACCTG", "index2": "TGATACG"}, # 8+ 7
87
+ {"sample_id": "SampleC", "index": "GCACAACGTT", "index2": "CATCTCAC"}, # 10+ 8
88
+ ]
89
+
90
+ print(" Before:")
91
+ _print_samples(dual_mixed)
92
+
93
+ normalized = normalize_index_lengths(dual_mixed, strategy="trim")
94
+ print(" After (strategy='trim' — I7→8bp, I5→7bp):")
95
+ _print_samples(normalized)
96
+
97
+ # ---------------------------------------------------------------------------
98
+ # Scenario 4: Real sheet — load, normalize, inspect
99
+ # ---------------------------------------------------------------------------
100
+
101
+ print("=" * 60)
102
+ print("Scenario 4: Real sheet — load V1, normalize, inspect")
103
+ print("=" * 60)
104
+
105
+ factory = SampleSheetFactory()
106
+ sheet = factory.create_parser(SHEETS / "v1_dual_index.csv", parse=True)
107
+ samples = sheet.samples()
108
+
109
+ print(f" Loaded : v1_dual_index.csv ({len(samples)} samples)")
110
+ print(" Before normalization:")
111
+ _print_samples(samples)
112
+
113
+ # Simulate a scenario where one index is shorter (trim to 8 bp)
114
+ for s in samples:
115
+ if s.get("sample_id") == "Sample3":
116
+ s["index"] = s["index"][:8] # type: ignore[index]
117
+
118
+ print(" After trimming Sample3 index to 8 bp (simulated mixed kit):")
119
+ _print_samples(samples)
120
+
121
+ normalized = normalize_index_lengths(samples, strategy="trim")
122
+ print(" After normalize_index_lengths(strategy='trim'):")
123
+ _print_samples(normalized)