samplesheet-parser 0.2.0__tar.gz → 0.2.1__tar.gz

{samplesheet_parser-0.2.0 → samplesheet_parser-0.2.1}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.12"]
 
     steps:
       - uses: actions/checkout@v4

{samplesheet_parser-0.2.0 → samplesheet_parser-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: samplesheet-parser
-Version: 0.2.0
+Version: 0.2.1
 Summary: Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2
 Project-URL: Homepage, https://github.com/chaitanyakasaraneni/samplesheet-parser
 Project-URL: Documentation, https://illumina-samplesheet.readthedocs.io
@@ -33,12 +33,10 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Requires-Dist: loguru>=0.7
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == 'dev'

{samplesheet_parser-0.2.0 → samplesheet_parser-0.2.1}/examples/parse_examples.py

@@ -6,7 +6,8 @@ Run from the repo root:
     python examples/parse_examples.py
 
 Demonstrates auto-detection, samples(), index_type(), UMI extraction,
-and validation for every example sheet in examples/sample_sheets/.
+validation, and custom section parsing for every example sheet in
+examples/sample_sheets/.
 """
 
 from __future__ import annotations
@@ -22,18 +23,23 @@ from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
 SHEETS_DIR = Path(__file__).parent / "sample_sheets"
 
 # Ordered for readability: V1 first, then V2
-EXAMPLE_FILES = [
-    "v1_dual_index.csv",
-    "v1_single_index.csv",
-    "v1_multi_lane.csv",
-    "v2_novaseq_x_dual_index.csv",
-    "v2_with_index_umi.csv",
-    "v2_with_read_umi.csv",
-    "v2_nextseq_single_index.csv",
+# Each entry is (filename, list of custom section names to demo, or [])
+EXAMPLE_FILES: list[tuple[str, list[str]]] = [
+    ("v1_dual_index.csv",            []),
+    ("v1_single_index.csv",          []),
+    ("v1_multi_lane.csv",            []),
+    ("v1_with_manifests.csv",        ["Manifests"]),
+    ("v1_with_lab_qc_settings.csv",  ["Lab_QC_Settings"]),
+    ("v2_novaseq_x_dual_index.csv",  []),
+    ("v2_with_index_umi.csv",        []),
+    ("v2_with_read_umi.csv",         []),
+    ("v2_nextseq_single_index.csv",  []),
+    ("v2_with_cloud_settings.csv",   ["Cloud_Settings"]),
+    ("v2_with_pipeline_settings.csv", ["Pipeline_Settings"]),
 ]
 
 
-def parse_sheet(path: Path) -> None:
+def parse_sheet(path: Path, custom_sections: list[str]) -> None:
     print(f"\n{'='*60}")
     print(f"  {path.name}")
     print(f"{'='*60}")
@@ -70,6 +76,18 @@ def parse_sheet(path: Path) -> None:
         print(f"  UMI location    : {rs.umi_location}")
         print(f"  Read structure  : {rs.read_structure}")
 
+    # Custom sections
+    if custom_sections:
+        print("\n  Custom sections:")
+        for section_name in custom_sections:
+            data = sheet.parse_custom_section(section_name)
+            if data:
+                print(f"    [{section_name}]")
+                for key, value in data.items():
+                    print(f"      {key:<28} {value}")
+            else:
+                print(f"    [{section_name}] — (empty or not present)")
+
     # Samples table
     samples = sheet.samples()
     print(f"\n  Samples ({len(samples)} total):")
@@ -97,14 +115,14 @@ def main() -> None:
     print("samplesheet-parser — Example Sheet Demo")
     print(f"Parsing {len(EXAMPLE_FILES)} example sheets from {SHEETS_DIR}\n")
 
-    missing = [f for f in EXAMPLE_FILES if not (SHEETS_DIR / f).exists()]
+    missing = [f for f, _ in EXAMPLE_FILES if not (SHEETS_DIR / f).exists()]
     if missing:
         print(f"Warning: missing files: {missing}")
 
-    for filename in EXAMPLE_FILES:
+    for filename, custom_sections in EXAMPLE_FILES:
         path = SHEETS_DIR / filename
         if path.exists():
-            parse_sheet(path)
+            parse_sheet(path, custom_sections)
 
     print(f"\n{'='*60}")
     print("Done.")

samplesheet_parser-0.2.1/examples/sample_sheets/README.md

@@ -0,0 +1,195 @@
+# Example Sample Sheets
+
+Reference sample sheets covering the full range of supported formats.
+Each file is a valid, runnable example that can be parsed by `samplesheet-parser`.
+
+---
+
+## V1 — IEM / bcl2fastq format
+
+Used with: NovaSeq 6000, HiSeq, NextSeq 500/550, MiSeq  
+Identified by: `IEMFileVersion` in `[Header]`
+
+| File | Instrument | Indexes | Key feature |
+|---|---|---|---|
+| `v1_dual_index.csv` | NovaSeq 6000 | Dual (10+10 bp) | Multi-lane, TruSeq UD adapters |
+| `v1_single_index.csv` | NextSeq 500 | Single (6 bp) | Small RNA, TruSeq Small RNA adapters |
+| `v1_multi_lane.csv` | NovaSeq 6000 | Dual (10+10 bp) | 4 lanes, 2 projects, mixed assays |
+| `v1_with_manifests.csv` | NovaSeq 6000 | Dual (10+10 bp) | Custom `[Manifests]` section — HyperCapture WES |
+| `v1_with_lab_qc_settings.csv` | NovaSeq 6000 | Dual (10+10 bp) | Custom `[Lab_QC_Settings]` section — QC thresholds |
+
+### V1 `[Settings]` adapter keys
+
+The official IEM spec uses two separate keys — not `AdapterRead1`:
+
+```
+[Settings]
+ReverseComplement,0
+Adapter,AGATCGGAAGAGCACACGTCTGAACTCCAGTCA        ← Read 1
+AdapterRead2,AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT   ← Read 2
+```
+
+`ReverseComplement,1` is only for Nextera Mate Pair libraries.
+`Chemistry,Amplicon` means dual-index. `Chemistry,Default` means no or single index.
+
+---
+
+## V2 — BCLConvert format
+
+Used with: NovaSeq X, NovaSeq X Plus, NextSeq 1000/2000  
+Identified by: `FileFormatVersion` in `[Header]`, or `[BCLConvert_Settings]` / `[BCLConvert_Data]` section names
+
+| File | Instrument | Indexes | UMI | Key feature |
+|---|---|---|---|---|
+| `v2_novaseq_x_dual_index.csv` | NovaSeq X | Dual (10+10 bp) | No | Standard multi-lane |
+| `v2_with_index_umi.csv` | NovaSeq X | Dual (10+10 bp) | Yes — Index1 UMI (9 bp) | cfDNA / liquid biopsy |
+| `v2_with_read_umi.csv` | NovaSeq X | Dual (8+8 bp) | Yes — read-level UMI (5 bp) | Duplex sequencing |
+| `v2_nextseq_single_index.csv` | NextSeq 1000/2000 | Single (8 bp) | No | Amplicon panel, no Lane column |
+| `v2_with_cloud_settings.csv` | NovaSeq X | Dual (10+10 bp) | No | Custom `[Cloud_Settings]` — BaseSpace upload config |
+| `v2_with_pipeline_settings.csv` | NextSeq 1000/2000 | Single (8 bp) | No | Custom `[Pipeline_Settings]` — downstream pipeline config |
+
+### V2 `OverrideCycles` format
+
+```
+Y151;I10;I10;Y151         — 151bp PE, 10bp dual index, no UMI
+Y151;I10U9;I10;Y151       — same, with 9bp UMI appended to Index1
+U5Y146;I8;I8;U5Y146       — 5bp UMI on both reads (read-level UMI)
+Y151;I8;Y151              — single index, no Index2 cycle
+```
+
+Segment order: Read1 ; Index1 ; Index2 ; Read2
+
+---
+
+## Custom sections
+
+Both V1 and V2 sheets support non-standard sections. These are preserved verbatim
+during parsing and accessible via `sheet.parse_custom_section(name)`.
+
+### V1 — `[Manifests]`
+
+Used by Illumina's HyperCapture and other enrichment workflows to specify the
+target capture manifest files the demultiplexer or aligner should load.
+
+```
+[Manifests]
+MFGmanifest,HyperCapture_ExomeV2_manifest.txt
+PoolingManifest,pooling_batch3_v1.txt
+```
+
+### V1 — `[Lab_QC_Settings]`
+
+A lab-defined section for embedding QC thresholds and pipeline metadata
+directly in the sample sheet, so downstream tools can read them without a
+separate config file.
+
+```
+[Lab_QC_Settings]
+MinQ30,85
+TargetCoverage,100x
+MinMappingRate,90
+LibraryKit,TruSeq_Stranded_mRNA
+SequencingCore,GenomicsCoreFacility
+```
+
+### V2 — `[Cloud_Settings]`
+
+Used by Illumina DRAGEN and BaseSpace to configure automated cloud upload
+after demultiplexing. `UploadToBaseSpace,1` triggers the upload; `BaseSpaceProjectId`
+routes the data to the correct project.
+
+```
+[Cloud_Settings]
+GeneratedVersion,3.9.14
+UploadToBaseSpace,1
+BaseSpaceProjectId,bs-proj-240715-wgs
+```
+
+### V2 — `[Pipeline_Settings]`
+
+A lab-defined section for downstream pipeline configuration — reference genome,
+variant caller, output format — bundled with the sample sheet so the compute
+environment has everything it needs in one file.
+
+```
+[Pipeline_Settings]
+PipelineVersion,2.1.0
+ReferenceGenome,hg38
+OutputFormat,CRAM
+VariantCaller,DeepVariant
+MinBaseQuality,20
+MinMappingQuality,30
+```
+
+### Accessing custom sections in code
+
+```python
+from samplesheet_parser import SampleSheetFactory
+
+sheet_with_manifests = SampleSheetFactory().create_parser(
+    "examples/sample_sheets/v1_with_manifests.csv", parse=True
+)
+
+# Returns {} if section is absent (default)
+manifests = sheet_with_manifests.parse_custom_section("Manifests")
+print(manifests)
+# {'MFGmanifest': 'HyperCapture_ExomeV2_manifest.txt',
+#  'PoolingManifest': 'pooling_batch3_v1.txt'}
+
+# Raise if a section your pipeline depends on is missing
+sheet_with_lab_qc_settings = SampleSheetFactory().create_parser(
+    "examples/sample_sheets/v1_with_lab_qc_settings.csv", parse=True
+)
+qc = sheet_with_lab_qc_settings.parse_custom_section("Lab_QC_Settings", required=True)
+
+# Works identically on V2 sheets
+sheet_v2 = SampleSheetFactory().create_parser(
+    "examples/sample_sheets/v2_with_cloud_settings.csv", parse=True
+)
+cloud = sheet_v2.parse_custom_section("Cloud_Settings")
+print(cloud["UploadToBaseSpace"])  # '1'
+```
+
+### Asserting required sections before parsing
+
+```python
+# parse() raises ValueError immediately if a required section is absent
+sheet = SampleSheetFactory().create_parser("SampleSheet.csv", parse=False)
+sheet.parse(required_sections=["Manifests", "Lab_QC_Settings"])
+```
+
+---
+
+## Parsing examples
+
+```python
+from samplesheet_parser import SampleSheetFactory, SampleSheetValidator
+
+# Works for any of the files above — format is auto-detected
+factory = SampleSheetFactory()
+sheet = factory.create_parser("examples/sample_sheets/v2_with_index_umi.csv", parse=True)
+
+print(factory.version)          # SampleSheetVersion.V2
+print(sheet.index_type())       # "dual"
+print(factory.get_umi_length()) # 9
+
+for sample in sheet.samples():
+    print(sample["sample_id"], sample["index"])
+
+result = SampleSheetValidator().validate(sheet)
+print(result.summary())         # PASS — 0 error(s), 0 warning(s)
+```
+
+---
+
+## Notes on column capitalisation (V1)
+
+From the Illumina IEM reference: **capitalisation in the `[Data]` header row matters.**
+
+Standard capitalisation:
+- `Sample_ID`, `Sample_Name`, `Sample_Plate`, `Sample_Well` — Title_Case with underscore
+- `I7_Index_ID`, `I5_Index_ID` — uppercase I, mixed
+- `index`, `index2` — **all lowercase**
+- `Sample_Project`, `Description` — Title_Case
+
+`index` and `index2` being lowercase is deliberate and required by bcl2fastq.

samplesheet_parser-0.2.1/examples/sample_sheets/v1_with_lab_qc_settings.csv

@@ -0,0 +1,35 @@
+[Header]
+IEMFileVersion,5
+Experiment Name,240610_A00123_0112_BHJNMMDRX3
+Date,2024-06-10
+Workflow,GenerateFASTQ
+Application,FASTQ Only
+Instrument Type,NovaSeq 6000
+Assay,TruSeq Stranded mRNA
+Index Adapters,TruSeq RNA UD Indexes (96 Indexes)
+Chemistry,Amplicon
+
+[Reads]
+151
+151
+
+[Settings]
+ReverseComplement,0
+Adapter,AGATCGGAAGAGCACACGTCTGAACTCCAGTCA
+AdapterRead2,AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT
+
+[Lab_QC_Settings]
+MinQ30,85
+TargetCoverage,100x
+MinMappingRate,90
+LibraryKit,TruSeq_Stranded_mRNA
+SequencingCore,GenomicsCoreFacility
+
+[Data]
+Lane,Sample_ID,Sample_Name,Sample_Plate,Sample_Well,I7_Index_ID,index,I5_Index_ID,index2,Sample_Project,Description
+1,RNA_001,Control_Rep1,,A01,UDP0001,CAAGACAGAT,UDP0001,ACTATAGCCT,RNASeq_Project,mRNA_expression
+1,RNA_002,Control_Rep2,,B01,UDP0002,TGAACCTGAT,UDP0002,TGATACGTCC,RNASeq_Project,mRNA_expression
+1,RNA_003,Control_Rep3,,C01,UDP0003,GCACAACGTT,UDP0003,CATCTCACAG,RNASeq_Project,mRNA_expression
+1,RNA_004,Treatment_Rep1,,D01,UDP0004,ATCGCCTGTT,UDP0004,GACTAGCATG,RNASeq_Project,mRNA_expression
+1,RNA_005,Treatment_Rep2,,E01,UDP0005,CTTGTAGCAA,UDP0005,TGCGTCAGCC,RNASeq_Project,mRNA_expression
+1,RNA_006,Treatment_Rep3,,F01,UDP0006,GATCCTAAGT,UDP0006,CATGCGGTTG,RNASeq_Project,mRNA_expression

samplesheet_parser-0.2.1/examples/sample_sheets/v1_with_manifests.csv

@@ -0,0 +1,32 @@
+[Header]
+IEMFileVersion,5
+Experiment Name,240501_A01234_0088_AHJNYGDRX3
+Date,2024-05-01
+Workflow,GenerateFASTQ
+Application,FASTQ Only
+Instrument Type,NovaSeq 6000
+Assay,Nextera DNA Flex for Enrichment
+Index Adapters,IDT for Illumina DNA/RNA UD Indexes (96 Indexes)
+Chemistry,Amplicon
+
+[Reads]
+151
+151
+
+[Settings]
+ReverseComplement,0
+Adapter,CTGTCTCTTATACACATCT
+AdapterRead2,CTGTCTCTTATACACATCT
+
+[Manifests]
+MFGmanifest,HyperCapture_ExomeV2_manifest.txt
+PoolingManifest,pooling_batch3_v1.txt
+
+[Data]
+Lane,Sample_ID,Sample_Name,Sample_Plate,Sample_Well,I7_Index_ID,index,I5_Index_ID,index2,Sample_Project,Description
+1,WES_001,TumorA_WES,,A01,UDP0001,CAAGACAGAT,UDP0001,ACTATAGCCT,WES_Project,tumor_normal_pair
+1,WES_002,NormalA_WES,,B01,UDP0002,TGAACCTGAT,UDP0002,TGATACGTCC,WES_Project,tumor_normal_pair
+1,WES_003,TumorB_WES,,C01,UDP0003,GCACAACGTT,UDP0003,CATCTCACAG,WES_Project,tumor_normal_pair
+1,WES_004,NormalB_WES,,D01,UDP0004,ATCGCCTGTT,UDP0004,GACTAGCATG,WES_Project,tumor_normal_pair
+2,WES_005,TumorC_WES,,E01,UDP0005,CTTGTAGCAA,UDP0005,TGCGTCAGCC,WES_Project,tumor_normal_pair
+2,WES_006,NormalC_WES,,F01,UDP0006,GATCCTAAGT,UDP0006,CATGCGGTTG,WES_Project,tumor_normal_pair

samplesheet_parser-0.2.1/examples/sample_sheets/v2_with_cloud_settings.csv

@@ -0,0 +1,32 @@
+[Header]
+FileFormatVersion,2
+RunName,240715_LH00336_0078_A22TNHKLT3
+InstrumentPlatform,NovaSeqXSeries
+ExperimentName,WGS_CloudUpload_Batch7
+
+[Reads]
+Read1Cycles,151
+Read2Cycles,151
+Index1Cycles,10
+Index2Cycles,10
+
+[BCLConvert_Settings]
+SoftwareVersion,3.9.3
+AdapterRead1,CTGTCTCTTATACACATCT
+AdapterRead2,CTGTCTCTTATACACATCT
+OverrideCycles,Y151;I10;I10;Y151
+BarcodeMismatchesIndex1,1
+BarcodeMismatchesIndex2,1
+
+[BCLConvert_Data]
+Lane,Sample_ID,Sample_Name,Index,Index2,Sample_Project
+1,WGS_001,SampleAlpha,ATTACTCGAT,TATAGCCTGT,WGS_Cloud
+1,WGS_002,SampleBeta,TCCGGAGACC,ATAGAGGCAC,WGS_Cloud
+1,WGS_003,SampleGamma,TAGGCATGCA,CCTATCCTAG,WGS_Cloud
+2,WGS_004,SampleDelta,CTCTCTACGC,GGCTCTGAGA,WGS_Cloud
+2,WGS_005,SampleEpsilon,CGGAGCCTAA,AGGCGAAGAG,WGS_Cloud
+
+[Cloud_Settings]
+GeneratedVersion,3.9.14
+UploadToBaseSpace,1
+BaseSpaceProjectId,bs-proj-240715-wgs

samplesheet_parser-0.2.1/examples/sample_sheets/v2_with_pipeline_settings.csv

@@ -0,0 +1,32 @@
+[Header]
+FileFormatVersion,2
+RunName,240820_VH00123_0041_AACNPJKHV
+InstrumentPlatform,NextSeq1000/2000
+ExperimentName,AmpliSeq_Pipeline_Config_Run
+
+[Reads]
+Read1Cycles,151
+Read2Cycles,151
+Index1Cycles,8
+
+[BCLConvert_Settings]
+SoftwareVersion,3.9.3
+AdapterRead1,CTGTCTCTTATACACATCT
+OverrideCycles,Y151;I8;Y151
+BarcodeMismatchesIndex1,1
+
+[BCLConvert_Data]
+Sample_ID,Sample_Name,Index,Sample_Project
+Panel_001,CancerHotspot_Rep1,ATTACTCG,AmpliconPanel
+Panel_002,CancerHotspot_Rep2,TCCGGAGA,AmpliconPanel
+Panel_003,CancerHotspot_Rep3,TAGGCATG,AmpliconPanel
+Panel_004,NormalControl_Rep1,CTCTCTAC,AmpliconPanel
+Panel_005,NormalControl_Rep2,TAATCTTA,AmpliconPanel
+
+[Pipeline_Settings]
+PipelineVersion,2.1.0
+ReferenceGenome,hg38
+OutputFormat,CRAM
+VariantCaller,DeepVariant
+MinBaseQuality,20
+MinMappingQuality,30

{samplesheet_parser-0.2.0 → samplesheet_parser-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "samplesheet-parser"
-version = "0.2.0"
+version = "0.2.1"
 description = "Format-agnostic parser for Illumina SampleSheet.csv files — supports IEM V1 and BCLConvert V2"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -19,13 +19,11 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Typing :: Typed",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 dependencies = [
     "loguru>=0.7",
 ]
@@ -50,17 +48,17 @@ packages = ["samplesheet_parser"]
 
 [tool.black]
 line-length    = 100
-target-version = ["py310", "py311", "py312"]
+target-version = ["py312"]
 
 [tool.ruff]
 line-length    = 100
-target-version = "py310"
+target-version = "py312"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W", "UP", "B"]
 
 [tool.mypy]
-python_version         = "3.10"
+python_version         = "3.12"
 strict                 = true
 ignore_missing_imports = true
 

{samplesheet_parser-0.2.0 → samplesheet_parser-0.2.1}/samplesheet_parser/enums.py

@@ -2,10 +2,10 @@
 Enumerations for samplesheet-parser.
 """
 
-from enum import Enum
+from enum import StrEnum
 
 
-class SampleSheetVersion(str, Enum):
+class SampleSheetVersion(StrEnum):
     """Illumina sample sheet format version.
 
     V1 — Illumina Experiment Manager (IEM) format, used with bcl2fastq.
@@ -21,7 +21,7 @@ class SampleSheetVersion(str, Enum):
     V2 = "V2"
 
 
-class IndexType(str, Enum):
+class IndexType(StrEnum):
     """Sequencing index configuration.
 
     SINGLE — I7 index only (single-index libraries).
@@ -33,7 +33,7 @@ class IndexType(str, Enum):
     NONE   = "none"
 
 
-class InstrumentPlatform(str, Enum):
+class InstrumentPlatform(StrEnum):
     """Standard Illumina instrument platform identifiers used in V2 sample sheets."""
     NOVASEQ_6000       = "NovaSeq6000"
     NOVASEQ_X_SERIES   = "NovaSeqXSeries"
@@ -43,7 +43,7 @@ class InstrumentPlatform(str, Enum):
     HISEQ_X            = "HiSeqX"
 
 
-class UMILocation(str, Enum):
+class UMILocation(StrEnum):
     """Where the UMI is encoded in the read structure (OverrideCycles string)."""
     READ1  = "read1"
     READ2  = "read2"

{samplesheet_parser-0.2.0 → samplesheet_parser-0.2.1}/samplesheet_parser/factory.py

@@ -37,6 +37,7 @@ Examples
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 
 from loguru import logger
 
@@ -121,7 +122,7 @@ class SampleSheetFactory:
         detected = self._detect_version(path)
 
         self.version = detected
-        kwargs: dict = dict(clean=clean, experiment_id=experiment_id, parse=parse)
+        kwargs: dict[str, Any] = dict(clean=clean, experiment_id=experiment_id, parse=parse)
 
         if detected == SampleSheetVersion.V2:
             logger.info("Detected BCLConvert V2 format — using SampleSheetV2")