isodyad

Pair-anchored isoform-switch annotation for single-cell long-read RNA-seq.

This monorepo contains:

Path	What
pipelines/isodyad-nf/	Nextflow DSL2 pipeline (Stage 1): ONT FASTQ → Sicelore → IsoQuant → SQANTI3 → functional annotation → SUPPA → interface TSVs
packages/isodyad/	R package (Stage 2 core): layered structural attribution (.ioe → exon-chain → coord) + estimator-consistency + pair consequences
analysis/	Manuscript figure glue (not part of the package)
containers/	Dockerfiles for five runtime images
docs/guide.md	Design guide (pair-anchored structure + consequence)
docs/ANNOTATION_SCHEMA.md	Column contract for the tables Stage 2 reads
legacy/	Original two-stage scripts: stage1_preprocessing/ (shell) and stage2_downstream/ (R)

Two stages, with your Seurat object in between

Stage 1                          (between)                    Stage 2
pipelines/isodyad-nf             you build this yourself      packages/isodyad
(+ legacy/stage1_preprocessing)  ─────────────────────        (+ legacy/stage2_downstream)
──────────────────────────       integration, clustering,     per-cell-type switch
reads → transcript models        cell-type annotation         detection, structure
→ QC → functional annotation     → multi-modal Seurat         and consequence
one run per dataset              object with an isoform
                                 ("trx") assay

Stage 1 annotates transcript models and knows nothing about cell types. Stage 2 needs cell-type, donor, and condition labels, which only exist once you have finished integration and annotation. The bridge tables are isoform_annotation.tsv, isoform_celltype_props.tsv, and isoform_celltype_donor_counts.tsv — see docs/ANNOTATION_SCHEMA.md for columns, and legacy/stage2_downstream/ for the prepare scripts that build the first two from a Seurat object.

The idea

Per-isoform functional annotation (Pfam, DeepTMHMM, NMD) is static, so a switch's consequence is the difference between two isoforms' labels. Splicing-event annotation is usually event-level ("this exon is skipped somewhere in this gene"), which does not difference the same way. isodyad resolves events per isoform pair, so structure and consequence share a unit and compose into statements like "this splicing event produces this protein change".

See docs/guide.md.

Quick start

Pipeline

cd pipelines/isodyad-nf
nextflow run main.nf \
  -profile docker,slurm \
  --input samplesheet.csv \
  --genome_fasta ref/genome.fa \
  --genome_gtf  ref/genes.gtf \
  --sicelore_jars /path/to/sicelore/Jar \
  --outdir results

Samplesheet columns: sample,condition,donor,replicate,fastq_dir (see assets/samplesheet_schema.json).

Sicelore JARs, DeepTMHMM, and InterProScan are bring-your-own — see containers/README.md for setup and docs/licences.md for which of them are licence-restricted. SignalP6 is not run; has_signal_peptide is derived from DeepTMHMM S labels (optional --signalp6_results override).

R package

# install.packages("devtools")
devtools::install("packages/isodyad")

library(isodyad)
cfg <- isodyad_config(
  gtf       = "interface/corrected.gtf",
  ioe_dir   = "interface/suppa_events",
  iso_annot = "interface/isoform_annotation.tsv",
  donor_cnt = "interface/isoform_celltype_donor_counts.tsv"
)
struct <- pair_structure(cfg)
sw <- compute_switch_dpsi(read.delim(cfg$donor_cnt))  # or pooled counts df
sw <- annotate_switch_pair(sw, read.delim(cfg$iso_annot))
check_panel_consistency(sw[, c("gene_symbol","cell_type")], counts_df = ...)

Related work

• nf-core/scnanoseq overlaps barcode correction / IsoQuant quantification. isodyad uses Sicelore consensus molecules and adds SQANTI3, confidence tiers, CPAT, InterProScan, DeepTMHMM, PolyASite APA, master annotation, and SUPPA — none of which scnanoseq provides.
• IsoformSwitchAnalyzeR (v2) covers statistical switch calling and many consequence types. isodyad is positioned as a companion for pair-resolved structural attribution (str_source-tracked .ioe / exon-chain / coord layers) and pooled-vs-per-donor estimator consistency. Thin adapters: as_switchAnalyzeRlist() / from_switchAnalyzeRlist().

Licence

MIT for pipeline scripts, R package, and containers. Third-party tools retain their own licences — Sicelore is MIT, DeepTMHMM is academic-use only, and InterProScan bundles member analyses with separate terms. See docs/licences.md.