# anishl135/twintrondetect architecture

> Architecture diagram of the GitHub repository anishl135/twintrondetect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anishl135/twintrondetect
- Repository: https://github.com/anishl135/twintrondetect

## Overview

Twintron Detector is a command-line RNA-seq analysis tool that finds candidate splice junctions nested inside annotated U12 introns, compares their usage between two conditions, and emits tables, reports, and genome-browser tracks. The main workflow validates inputs, discovers nested junctions using junction BED and BAM evidence, then classifies candidates, annotates known-junction status, scores evidence, calculates differential usage, and writes results. README capabilities guide the map; sampled excerpts confirm key detection, classification, annotation, validation, scoring, and reporting details, but not every orchestration call.

Main entry points: [`src/twintron/cli.py`](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/cli.py) (CLI orchestration), [`src/twintron/detection/nested_junctions.py`](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/nested_junctions.py) (Nested discovery), [`src/twintron/io/references.py`](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/references.py) (Reference access), [`src/twintron/reporting/html.py`](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/html.py) (HTML report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and access"]
  node_cli["CLI orchestration<br/>[cli.py]"]
  node_bam_io["BAM access<br/>[bam.py]"]
  node_junction_io["Junction indexing<br/>[junctions.py]"]
  node_reference_io["Reference access<br/>[references.py]"]
end

subgraph group_detection["Candidate detection"]
  node_outer["Outer introns<br/>[outer_introns.py]"]
  node_nested["Nested discovery"]
  node_candidate["Candidate handling<br/>[candidate.py]"]
  node_clustering["Junction clustering<br/>[clustering.py]"]
  node_bam_validation["BAM support<br/>[bam_support.py]"]
  node_junction_validation["Junction validation"]
  node_replicate["Replicate support"]
  node_mappability["Mappability scoring<br/>[mappability.py]"]
end

subgraph group_interpretation["Candidate interpretation"]
  node_structural["Structural classes<br/>[structural.py]"]
  node_annotation["Known status<br/>[gencode.py]"]
  node_evidence["Evidence score<br/>[evidence.py]"]
  node_motif["Splice motifs<br/>[motif.py]"]
  node_confidence["Confidence tier<br/>[confidence.py]"]
  node_differential["Usage comparison<br/>[differential.py]"]
end

subgraph group_outputs["Results and reporting"]
  node_writers["CSV and BED12<br/>[writers.py]"]
  node_tables["Report tables<br/>[tables.py]"]
  node_figures["Report figures<br/>[figures.py]"]
  node_html["HTML report<br/>[html.py]"]
end

node_researcher(("Researcher"))
node_bam["RNA-seq BAMs"]
node_junction_bed["Junction BEDs"]
node_u12_bed["U12 reference"]
node_genome["Genome FASTA"]
node_known_bed["Known junctions"]
node_map_track["Mappability track"]
node_results["Candidate outputs"]

node_researcher -->|"runs detection"| node_cli
node_cli -->|"opens alignments"| node_bam_io
node_bam -->|"read by"| node_bam_io
node_cli -->|"loads junctions"| node_junction_io
node_junction_bed -->|"indexed from"| node_junction_io
node_cli -->|"loads references"| node_reference_io
node_u12_bed -->|"read by"| node_reference_io
node_genome -->|"read by"| node_reference_io
node_map_track -.->|"optional input"| node_reference_io
node_cli -->|"starts scan"| node_outer
node_outer -->|"supplies loci"| node_nested
node_nested -->|"checks calls"| node_junction_validation
node_junction_validation -->|"queries index"| node_junction_io
node_nested -->|"checks reads"| node_bam_validation
node_bam_validation -->|"counts alignments"| node_bam_io
node_nested -->|"clusters junctions"| node_clustering
node_nested -->|"checks recurrence"| node_replicate
node_nested -->|"forms candidates"| node_candidate
node_cli -->|"classifies candidates"| node_structural
node_cli -->|"labels status"| node_annotation
node_annotation -->|"parses coordinates"| node_junction_io
node_known_bed -->|"compared against"| node_annotation
node_cli -->|"scores support"| node_evidence
node_evidence -->|"uses motif strength"| node_motif
node_motif -->|"reads sequence"| node_reference_io
node_cli -->|"assesses uniqueness"| node_mappability
node_mappability -->|"uses reference data"| node_reference_io
node_cli -->|"assigns tier"| node_confidence
node_cli -->|"compares usage"| node_differential
node_cli -->|"writes candidate data"| node_writers
node_cli -->|"prepares summaries"| node_tables
node_cli -->|"prepares figures"| node_figures
node_cli -->|"generates report"| node_html
node_writers -->|"emits CSV and BED12"| node_results
node_html -->|"emits HTML"| node_results
node_tables -->|"supplies summaries"| node_html
node_figures -->|"supplies figures"| node_html

click node_cli "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/cli.py"
click node_bam_io "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/bam.py"
click node_junction_io "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/junctions.py"
click node_reference_io "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/references.py"
click node_outer "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/outer_introns.py"
click node_nested "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/nested_junctions.py"
click node_candidate "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/candidate.py"
click node_clustering "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/clustering.py"
click node_bam_validation "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/bam_support.py"
click node_junction_validation "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/junction_validation.py"
click node_replicate "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/replicate_support.py"
click node_mappability "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/mappability.py"
click node_structural "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/classification/structural.py"
click node_annotation "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/annotation/gencode.py"
click node_evidence "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/scoring/evidence.py"
click node_motif "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/scoring/motif.py"
click node_confidence "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/scoring/confidence.py"
click node_differential "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/statistics/differential.py"
click node_writers "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/writers.py"
click node_tables "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/tables.py"
click node_figures "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/figures.py"
click node_html "https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/html.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_bam_io,node_junction_io,node_reference_io toneBlue
class node_outer,node_nested,node_candidate,node_clustering,node_bam_validation,node_junction_validation,node_replicate,node_mappability toneAmber
class node_structural,node_annotation,node_evidence,node_motif,node_confidence,node_differential toneMint
class node_writers,node_tables,node_figures,node_html toneRose
class node_researcher,node_bam,node_junction_bed,node_u12_bed,node_genome,node_known_bed,node_map_track,node_results toneIndigo
```

## Components

### Inputs and access

- [CLI orchestration](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/cli.py): `src/twintron/cli.py`
- [BAM access](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/bam.py): `src/twintron/io/bam.py`
- [Junction indexing](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/junctions.py): `src/twintron/io/junctions.py`
- [Reference access](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/references.py): `src/twintron/io/references.py`

### Candidate detection

- [Outer introns](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/outer_introns.py): `src/twintron/detection/outer_introns.py`
- [Nested discovery](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/nested_junctions.py): `src/twintron/detection/nested_junctions.py`
- [Candidate handling](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/candidate.py): `src/twintron/detection/candidate.py`
- [Junction clustering](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/detection/clustering.py): `src/twintron/detection/clustering.py`
- [BAM support](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/bam_support.py): `src/twintron/validation/bam_support.py`
- [Junction validation](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/junction_validation.py): `src/twintron/validation/junction_validation.py`
- [Replicate support](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/replicate_support.py): `src/twintron/validation/replicate_support.py`
- [Mappability scoring](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/validation/mappability.py): `src/twintron/validation/mappability.py`

### Candidate interpretation

- [Structural classes](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/classification/structural.py): `src/twintron/classification/structural.py`
- [Known status](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/annotation/gencode.py): `src/twintron/annotation/gencode.py`
- [Evidence score](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/scoring/evidence.py): `src/twintron/scoring/evidence.py`
- [Splice motifs](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/scoring/motif.py): `src/twintron/scoring/motif.py`
- [Confidence tier](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/scoring/confidence.py): `src/twintron/scoring/confidence.py`
- [Usage comparison](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/statistics/differential.py): `src/twintron/statistics/differential.py`

### Results and reporting

- [CSV and BED12](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/io/writers.py): `src/twintron/io/writers.py`
- [Report tables](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/tables.py): `src/twintron/reporting/tables.py`
- [Report figures](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/figures.py): `src/twintron/reporting/figures.py`
- [HTML report](https://github.com/anishl135/twintrondetect/blob/main/src/twintron/reporting/html.py): `src/twintron/reporting/html.py`

### Other components

- **Researcher**
- **RNA-seq BAMs**
- **Junction BEDs**
- **U12 reference**
- **Genome FASTA**
- **Known junctions**
- **Mappability track**
- **Candidate outputs**

## Connections

- Researcher → CLI orchestration: runs detection
- CLI orchestration → BAM access: opens alignments
- RNA-seq BAMs → BAM access: read by
- CLI orchestration → Junction indexing: loads junctions
- Junction BEDs → Junction indexing: indexed from
- CLI orchestration → Reference access: loads references
- U12 reference → Reference access: read by
- Genome FASTA → Reference access: read by
- Mappability track → Reference access: optional input
- CLI orchestration → Outer introns: starts scan
- Outer introns → Nested discovery: supplies loci
- Nested discovery → Junction validation: checks calls
- Junction validation → Junction indexing: queries index
- Nested discovery → BAM support: checks reads
- BAM support → BAM access: counts alignments
- Nested discovery → Junction clustering: clusters junctions
- Nested discovery → Replicate support: checks recurrence
- Nested discovery → Candidate handling: forms candidates
- CLI orchestration → Structural classes: classifies candidates
- CLI orchestration → Known status: labels status
- Known status → Junction indexing: parses coordinates
- Known junctions → Known status: compared against
- CLI orchestration → Evidence score: scores support
- Evidence score → Splice motifs: uses motif strength
- Splice motifs → Reference access: reads sequence
- CLI orchestration → Mappability scoring: assesses uniqueness
- Mappability scoring → Reference access: uses reference data
- CLI orchestration → Confidence tier: assigns tier
- CLI orchestration → Usage comparison: compares usage
- CLI orchestration → CSV and BED12: writes candidate data
- CLI orchestration → Report tables: prepares summaries
- CLI orchestration → Report figures: prepares figures
- CLI orchestration → HTML report: generates report
- CSV and BED12 → Candidate outputs: emits CSV and BED12
- HTML report → Candidate outputs: emits HTML
- Report tables → HTML report: supplies summaries
- Report figures → HTML report: supplies figures