seqforge 2026.7.1__py3-none-any.whl

seqforge/kb/specs/splitseq/spec.yaml

@@ -0,0 +1,157 @@
+schema_version: 1
+
+# ============================================================================================
+# ORIGINAL SPLiT-seq (Rosenberg et al., Science 2018, doi:10.1126/science.aam8999).
+# Read structure + linker sequences pinned from scg_lib_structs (CC-BY):
+#   https://teichlab.github.io/scg_lib_structs/methods_html/SPLiT-seq.html
+#   https://github.com/Teichlab/scg_lib_structs/issues/13  (the "Published Manuscript" read-2 variant)
+#
+# This entry models the PUBLISHED-MANUSCRIPT SPLiT-seq only. Parse Biosciences Evercode is a separate,
+# updated commercial descendant with different linkers/whitelists and multiple kit versions — it is
+# deliberately OUT OF SCOPE for this pilot and must get its own KB entry, never conflated with this one.
+#
+# Read 2 (94 cycles) reads, 5'->3':
+#   [10 bp UMI][8 bp Round3][30 bp linker1][8 bp Round2][30 bp linker2][8 bp Round1]
+# Read 1 (66 cycles) reads the cDNA. Round1 is the RT/first-round (oligo-dT/randN) barcode; Round3 is
+# nearest the sequencing primer. Whitelists: 96 x 8 bp per round (register the actual barcode files
+# from scg_lib_structs before a real run — the KB declares the registry name, never vendors the list).
+#
+# INDEPENDENTLY RECONSTRUCTED from the paper's own Table S12 oligos (PMC7643870): assembling the RT
+# primer + round-2/round-3 ligation oligos 5'->3' reproduces both linkers base-for-base and lands
+# Read 2 on exactly 10+8+30+8+30+8 = 94 cycles. The structure above is therefore derived from primary
+# oligos, not copied from a diagram. See `backend.params.soloStrand` for the full derivation.
+#
+# THE v1/v2 DISCRIMINATOR (cheap, from Read 2 alone, and the thing most likely to be silently
+# mismatched): this entry is v1 == the Science-2018 original, identified by a 30 bp linker2 with
+# Round1 at offset 86-93. Parse/v2 uses a 22 bp linker2 (ATCCACGTGCTTGAGACTGTGG) with Round1 at
+# 78-85. That single 8 bp shift is why published SPLiT-seq soloCBposition quadruples disagree in the
+# wild (`0_86_0_93` here vs `0_78_0_85` elsewhere) — they are different chemistries, not a typo.
+#
+# NB on demultiplexing (Table S12 footnote): there are 96 Round1 barcodes but only 48 RT WELLS — the
+# oligo-dT and random-hexamer primers in one well carry DIFFERENT barcodes, paired i <-> i+48. A
+# demultiplexer that treats all 96 as distinct doubles the apparent cell count at half the depth.
+# ============================================================================================
+
+identity:
+  id: splitseq
+  version: science-2018                  # the published-manuscript variant (not preprint, not Parse)
+  name: "SPLiT-seq (combinatorial split-pool barcoding, Rosenberg et al. 2018)"
+  aliases: ["SPLiT-seq", "split-pool", "combinatorial indexing", "split-pool ligation"]
+  assay_ontology: ["EFO:0009919"]        # SPLiT-seq — verified against live EFO (EBI OLS), not memory.
+                                         # NB: Parse Evercode has its own terms (EFO:0022600/1/2) — a
+                                         # separate future entry, never this one.
+  modality: rna
+
+reads:
+  - id: cdna
+    seqspec_read_id: R1                  # Read 1 (66 cycles) = cDNA
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 25
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna, start: 0, end: null, seqspec_region_type: cdna}
+  # Read 2 (94 cycles) = UMI + three round barcodes separated by two fixed linkers.
+  - id: bc
+    seqspec_read_id: R2
+    file_hint: "_R2_"
+    strand: pos
+    min_len: 94
+    max_len: 94
+    elements:
+      - {type: umi,     name: UMI, start: 0,  end: 10,                    seqspec_region_type: umi}
+      - {type: barcode, name: bc3, start: 10, end: 18, onlist: round3,    seqspec_region_type: barcode}
+      # linker1 = the Round3->Round2 spacer (Science-2018 sequence, verbatim from scg_lib_structs)
+      - {type: linker,  name: linker1, start: 18, end: 48, seqspec_region_type: linker,
+         sequence: "GTGGCCGATGTTTCGCATCGGCGTACGACT"}
+      - {type: barcode, name: bc2, start: 48, end: 56, onlist: round2,    seqspec_region_type: barcode}
+      # linker2 = the Round2->Round1 spacer (Science-2018 sequence, verbatim from scg_lib_structs)
+      - {type: linker,  name: linker2, start: 56, end: 86, seqspec_region_type: linker,
+         sequence: "ATCCACGTGCTTGAGAGGCCAGAGCATTCG"}
+      - {type: barcode, name: bc1, start: 86, end: 94, onlist: round1,    seqspec_region_type: barcode}
+
+onlists:
+  round1: {registry: splitseq-round1, role: cell_barcode, expected_orientation: forward}   # 96 x 8 bp
+  round2: {registry: splitseq-round2, role: cell_barcode, expected_orientation: forward}
+  round3: {registry: splitseq-round3, role: cell_barcode, expected_orientation: forward}
+  tenx_probe: {registry: 3M-february-2018, role: cell_barcode, expected_orientation: forward}  # exclude only
+
+signature:
+  requires:                              # the two FIXED linkers are the structural signature
+    - {test: read_count, roles: 2}
+    - {test: has_segment, read: bc, start: 18, end: 48, kind: constant}   # linker1
+    - {test: has_segment, read: bc, start: 56, end: 86, kind: constant}   # linker2
+  supports:                              # each round barcode hits its own small whitelist (width-generic 8 bp)
+    - when: {test: onlist_hit_rate, read: bc, element: bc1, onlist: round1, orientation: forward, min: 0.5}
+      weight: 3.0
+    - when: {test: onlist_hit_rate, read: bc, element: bc2, onlist: round2, orientation: forward, min: 0.5}
+      weight: 3.0
+    - when: {test: onlist_hit_rate, read: bc, element: bc3, onlist: round3, orientation: forward, min: 0.5}
+      weight: 3.0
+    - when: {test: distinct_ratio, read: bc, start: 0, end: 10, expect: high}   # UMI ~unique
+      weight: 1.0
+    - when: {test: distinct_ratio, read: cdna, start: 0, end: 20, expect: high} # cDNA role is scored too
+      weight: 1.0
+  excludes:                              # a 16 bp 10x CB at read start => not SPLiT-seq
+    - {test: onlist_hit_rate, read: bc, start: 0, end: 16, onlist: tenx_probe, orientation: forward, min: 0.6}
+
+backend:
+  module: map/starsolo
+  params:
+    soloType: CB_UMI_Complex
+    soloCBwhitelist: ["{onlist:round1}", "{onlist:round2}", "{onlist:round3}"]
+    # soloStrand: DERIVED (FLAG closed). Was the most dangerous value in this file — a wrong strand
+    # leaves most reads unassigned while STARsolo exits 0 and emits a matrix that merely looks like a
+    # thin dataset. Neither gate can catch it: the params gate only proves the value survives compose
+    # intact, and a simulated e2e would test our own assumed orientation against itself (circular).
+    # So it is derived from the primary oligos, then corroborated by the authors' own code.
+    #
+    # DERIVATION (Rosenberg et al., Science 2018, doi:10.1126/science.aam8999; Supp. Table S12 oligos
+    # via PMC7643870 — note the Methods miscite the oligo table as "Table S1"; it is Table S12):
+    #   1. RT primer = /5Phos/AGGCCAGAGCATTCG + [bc1] + dT(15)VN (or N6). It anneals to the mRNA and
+    #      RT extends its 3' end, so first-strand cDNA is ANTISENSE with bc1 at its 5' end. Both
+    #      primer types share that 5' architecture and differ only in the 3' priming tail, which is
+    #      why random hexamer priming does NOT destroy strandedness here (the trap: random-primed
+    #      bulk RNA-seq genuinely is unstranded; this is not that).
+    #   2. Rounds 2/3 ligate onto that same 5' end. Assembling the Table S12 oligos 5'->3' gives
+    #      [PCR handle][UMI10][bc3][linker1][bc2][linker2][bc1][dT15VN]--antisense cDNA--, and the
+    #      ligation junctions reconstruct THIS FILE'S linker1/linker2 base-for-base, with Read2
+    #      landing on 10+8+30+8+30+8 = 94 cycles. The spec below is reproduced from primary oligos.
+    #   3. Read2 therefore reads the first strand = antisense; Read1 is its mate = SENSE to the mRNA.
+    #      STARsolo defines Forward as "read strand same as the original RNA molecule" -> Forward.
+    # CORROBORATION (independent of the derivation):
+    #   - The authors' own pipeline (github.com/Alex-Rosenberg/split-seq-pipeline, processv2.py)
+    #     compares the read strand to the gene's GTF strand with NO flip ("The current implementation
+    #     is stranded and will not return a gene on the opposite strand") == featureCounts -s 1.
+    #   - It finds the TSO (AAGCAGTGGTATCAACGCAGAGTGAATGGG) at the START of read1 and trims it, with
+    #     no reverse-complement on the counting path -> R1 reads sense.
+    #   - scg_lib_structs states it outright and runs --soloStrand Forward on SRR6750042, i.e. on
+    #     GSE110823 itself: "Read 1 comes from the coding strand. Therefore, use Forward".
+    #   - An adversarial search found NO source claiming Reverse. NB salmon's `-l ISR` is NOT a
+    #     Reverse signal: in alevin's convention (-1 barcode, -2 cDNA) ISR is the same library
+    #     STARsolo calls Forward.
+    # HONEST CAVEAT: the field's practice is weaker than its claim. Nobody chose Reverse, but most
+    # pipelines never chose at all — they inherited STARsolo's Forward default. The two affirmative
+    # sources are strong (one is the authors' code); the rest is silence, and silence here means
+    # Forward by accident, not by verification. The remaining non-circular confirmation is rung 6:
+    # run GSE110823 both ways (SRR6750042 is the scg_lib_structs control; SRR6750041 is cheapest at
+    # 77.6M reads) — the correct strand assigns ~an order of magnitude more reads. Bounded.
+    soloStrand: Forward
+    # soloFeatures is NOT here, and that is the point. It says what to COUNT, and 10x 3' v3.1
+    # chemistry is byte-identical for cells and nuclei — what differs is the RNA population, a
+    # property of SAMPLE PREP. Filing it as chemistry cost a measured 40.7% of a nuclear library.
+    # It lives in the processing manifest now, where a user may instruct it.
+    # soloCBposition / soloUMIposition are DERIVED from the element coordinates at compose time
+    # (FLAG-3: never hand-enter a position quadruple from memory — generate it from the element model).
+
+# The combinatorial geometry + onlists separate this from 10x / inDrop. What it does NOT separate
+# itself from is the generic paired-end fallback, which forbids so little that it accepts these two
+# files at rungs 0-2 — the confusion runs in that direction, and the relation is symmetric, so it is
+# declared on both sides. See bulk-rnaseq-pe's note.
+confusable_with:
+  - id: bulk-rnaseq-pe
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      The generic paired-end fallback accepts cdna+bc on geometry alone. Rung 3 decides it: the
+      round1/2/3 whitelists hit, and bulk has no whitelist to hit.

seqforge/manifest/__init__.py

@@ -0,0 +1,61 @@
+"""``manifest`` — assemble, validate, and hash the two artifacts.
+
+Operations live here; the *schemas* are :mod:`seqforge.models.dataset` (the IR: what the data is) and
+:mod:`seqforge.models.processing` (the flags: what to do with it). ``fill`` assembles a Decision into
+a dataset manifest — each section keeping its own authority — and ``fill_processing`` builds one of
+the many processing manifests a dataset may be paired with. ``validate`` is the refusal contract
+(structured ``Blocker``s + a nonzero exit), and ``hash`` gives each artifact a content-addressed
+identity plus the ``run_id`` that records their pairing.
+"""
+
+from __future__ import annotations
+
+from .fill import (
+    ExperimentInputs,
+    FillError,
+    ProcessingInputs,
+    dataset_uris,
+    experiment_from_metadata,
+    fill_manifest,
+    fill_processing,
+)
+from .hash import dataset_content_hash, processing_content_hash, run_id
+from .instruct import INSTRUCTABLE_FIELDS, Instruction, instructions_from_assertions
+from .policy import (
+    DEFAULT_SOLO_FEATURES,
+    PolicyError,
+    ProcessingDefaults,
+    ProcessingOverrides,
+    prep_type_from_assertions,
+    processing_defaults,
+    resolve_features,
+    resolve_processing,
+)
+from .validate import exit_code_for_report, validate_manifest, validate_processing
+
+__all__ = [
+    "dataset_uris",
+    "fill_manifest",
+    "fill_processing",
+    "ExperimentInputs",
+    "experiment_from_metadata",
+    "ProcessingInputs",
+    "FillError",
+    "validate_manifest",
+    "validate_processing",
+    "exit_code_for_report",
+    "dataset_content_hash",
+    "processing_content_hash",
+    "run_id",
+    "processing_defaults",
+    "ProcessingDefaults",
+    "ProcessingOverrides",
+    "resolve_processing",
+    "resolve_features",
+    "prep_type_from_assertions",
+    "DEFAULT_SOLO_FEATURES",
+    "PolicyError",
+    "Instruction",
+    "INSTRUCTABLE_FIELDS",
+    "instructions_from_assertions",
+]