Visualize transcript isoforms with splice sites and fragment structures
The CSV is a structured description of splicing: splice sites are declared first, then each transcript is described as a path that connects those sites. Internal fragment boundaries (non-first starts and non-last ends) must correspond to declared splice sites, while the outer boundaries (first start, final end) may be arbitrary transcript boundaries.
The file is organized into named sections. Each section begins with a bracketed header like [transcripts], followed by a CSV table with a header row. Three sections are required: [transcripts], [donors], and [acceptors]. The optional [title] section provides a title that appears at the top of the plot.
In [donors] and [acceptors], each row defines one splice site with three fields: name (the label shown below the genome map), position (integer coordinate, marked by a small vertical tick), and colour (optional). When a colour is specified, all fragments touching that splice site inherit that colour. Allowed colours: red, blue, green, orange, purple, cyan, magenta, yellow, pink, brown, lime, navy.
Splice site names must be unique within each category (all donor names must be distinct, and all acceptor names must be distinct). Positions can be any positive integer. If two splice sites at different positions need to be visually grouped, assign them the same colour.
In [transcripts], each row describes one transcript. The required fragments field lists exon-like blocks in start-end format, separated by semicolons (e.g., 1-200; 500-800; 1000-end). The first fragment's start and the last fragment's end are transcript boundaries that can be any positive coordinate within the reference range. However, every internal fragment start must be a declared acceptor site, and every internal fragment end must be a declared donor site. The keyword end is case-insensitive and represents the final position on the reference sequence.
Each fragment can optionally include a colour annotation after the range to set its colour directly, overriding any colour that would be derived from adjacent splice sites. The colour is written in parentheses after the range: 5390-5463 (red), 5390-5463(blue), or 5390-5463( green ). Allowed colours are the same as for splice sites. Explicit fragment colours are especially useful for resolving colour conflicts when a fragment touches two splice sites with different colours.
Three optional fields control how transcripts appear: label, group, and N_observed. The label appears at the right side above the transcript (typically a gene or isoform name). The group field clusters related transcripts visually—transcripts sharing the same group name are drawn as a block, marked by a vertical line on the left edge of the plot. The N_observed appears on the right side of the transcript (commonly used for read counts or sample metadata).
Fragments within a single transcript must not overlap. If fragment A ends at position 500 and fragment B starts at position 500, they will be rejected as overlapping. Fragment B must start at a position after fragment A's end position. Fragments are displayed in the order they appear in the CSV.
When a fragment touches two splice sites with different colours (one at the start, one at the end), the tool will reject the input with a conflict error. Each fragment can have only one colour. To resolve a conflict, you can either remove one of the colours from the splice sites, adjust the fragment boundaries, or add an explicit fragment colour to the conflicting fragment using the 5390-5463(red) syntax. An explicit fragment colour overrides the splice-site colours and bypasses the conflict check.
When multiple consecutive transcripts have the same label, the tool automatically removes duplicate labels to avoid clutter. For example, if three transcripts in a row all have label gag, only the first one will display the label. This behaviour applies only to consecutive transcripts—if a different label appears in between, the repeated label will be shown again.
The group field organizes transcripts into visual blocks. All transcripts with the same group value are drawn together, separated from other groups by spacing. A vertical bar on the left marks each group. Groups appear in the order they first occur in the CSV (preserve the order of first appearance). If a transcript has no group specified (empty or omitted), it's treated as belonging to its own unnamed group.
If an internal fragment boundary uses a position not declared in donors or acceptors, the tool will reject it. Fragment ranges must use integers for both start and end (except for the end keyword). Negative numbers and zero are not allowed. Whitespace around fragment ranges is ignored, so 1-200, 1 - 200, and 1-200 are all equivalent.
The end keyword is internally mapped to the rightmost reference coordinate (the end of the 3'LTR). Section headers are case-insensitive ([transcripts], [TRANSCRIPTS], and [Transcripts] are all equivalent), but duplicate section headers (even with different casing) will be rejected. CSV parsing follows standard rules: fields can be quoted to include commas or newlines.