Skip to content

Region formats

Every "interval" input in RBrowser is a single string — that's the design behind renderer.region = "...": one string covers DNA, RNA, and CDS coordinate systems alike. This page covers the three formats, the parser rules, and behavioural differences.

Applies to:

  • renderer.region = "..."
  • historyManager.add(region, assembly)
  • favouriteManager.add(region, assembly) / toggle() / remove()
  • URL ↔ region round-tripping

Quick reference

Format Example Parsed as Mode
chr:start-end chr17:7571720-7590868 DNA interval — chromosome + start/end DNA
NAME:up:down NANOG-204:5000:5000 Transcript with 5 kb upstream + 5 kb downstream RNA / CDS
NAME:flank NANOG-204:5000 Transcript with symmetric flank (5 kb each side) RNA / CDS

Every format's accepted character set is defined by a regex in the source — details below.

1. DNA format — chr:start-end

Grammar

<chrom>:<start>-<end>

Regex: /^([\w.]+):(\d+)-(\d+)$/ (from views/main.tsx)

Field Charset Description
chrom [\w.]+ Letters / digits / underscores / dots. E.g. chr17, 17, NC_000017.11
start \d+ Start coordinate (inclusive), bp
end \d+ End coordinate (exclusive), bp

Examples

renderer.region = "chr17:7571720-7590868";
renderer.region = "chrX:1000000-1100000";
renderer.region = "MT:0-16569";

Thousand separators

Commas are stripped before parsing — for human-friendly editing:

renderer.region = "chr17:7,571,720-7,590,868"; // equivalent to comma-free form

Behaviour

  • Immediate — no async catalogue query
  • If the current mode is RNA / CDS, RBrowser switches back to DNA automatically
  • viewRegion reflects the new window on the next frame

2. RNA format (asymmetric) — NAME:up:down

Grammar

<transcript_name>:<upstream>:<downstream>

Regex: /^([\w][\w.-]*):(\d+):(\d+)$/

Field Charset Description
transcript_name [\w][\w.-]* Must start with a letter/digit/underscore; subsequent chars may include . and -. E.g. NANOG-204, ENST00000229307.12, TP53.1
upstream \d+ Upstream flank (bp)
downstream \d+ Downstream flank (bp)

Examples

// Transcript name + 5 kb each side
renderer.region = "NANOG-204:5000:5000";

// Ensembl ID also works
renderer.region = "ENST00000229307.12:8000:2000";

// VAMP3 with 3 kb up, 5 kb down
renderer.region = "VAMP3-201:3000:5000";

Strand and coordinates

  • Flanks are applied with respect to strand:
    • + strand: start = TSS − upstream, end = TES + downstream
    • - strand: start = TES − downstream, end = TSS + upstream
  • The X axis is switched to TSS-relative: TSS shows as 0, downstream positive, upstream negative

Behaviour

  • If the transcript is not yet loaded, RBrowser queries the active reference's catalogue (REST API or SQLite-over-HTTP) asynchronously
  • On success it switches to RNA mode (renderer.isRnaMode === true)
  • On failure the region setter does not throw — the browser simply stays where it was

3. RNA format (symmetric) — NAME:flank

Grammar

<transcript_name>:<flank>

Regex: /^([\w][\w.-]*):(\d+)$/

renderer.region = "NANOG-204:5000";   // same as "NANOG-204:5000:5000"
renderer.region = "VAMP3-201:2000";

Relationship to the asymmetric form

  • A single number → used for both upstream and downstream
  • This is just a shortcut; behaviour is identical to NAME:n:n

4. Parser priority

The commitRegion() function in views/main.tsx tries matches in this order:

1. Strip thousands separators (commas)
2. Try chr:start-end → DNA navigation
3. Try NAME:up:down  → async RNA navigation
4. Try NAME:flank    → async RNA navigation
5. Otherwise — invalid input (no navigation, no error)

No ambiguity exists: chr17:1000-2000 is always DNA, because chr17 is followed by -, not another :.

5. Use in persistent APIs

All these accept the same region grammar:

import { historyManager, favouriteManager } from "@rbrowser/main";

const assembly = renderer.referenceManager.getConfig()?.assembly;
// e.g. { name: "GRCh38" }

// History
historyManager.add("chr17:7571720-7590868", assembly);
historyManager.add("NANOG-204:5000:5000",   assembly);
historyManager.add("VAMP3-201:2000",        assembly);

// Favourites
favouriteManager.add("chr17:7571720-7590868", assembly);
favouriteManager.toggle("NANOG-204:5000:5000", assembly);
favouriteManager.remove("VAMP3-201:2000");

// Highlights — always genomic coords, assembly still recorded
renderer.highlightManager.setRegion(
  "tp53-promoter",
  7575000,
  7580000,
  "#ff6b6b",
  assembly,
);

Why record assembly?

History / Favourites / Highlights persist (in memory or external storage). After switching references, there's otherwise no way to know which assembly an entry belongs to. With assembly:

  • The UI can highlight "entries valid in the current assembly"
  • Reference switches can validate or filter in bulk
  • When you persist to IndexedDB / localStorage, the entries still classify correctly next time

6. Working with getRegionList()

renderer.getRegionList() projects every current highlight into all four coordinate systems. Each entry has structured chr / start / end — to round-trip back into region strings:

const list = renderer.getRegionList();

// Push the DNA projection into history
list.DNA.forEach(r => {
  const region = `${r.chr}:${r.start}-${r.end}`;
  historyManager.add(region, r.assembly);
});

// Push the RNA projection into favourites (using transcript name + flank)
list.RNA
  .filter(r => r.trans_name)            // skip entries without transcript context
  .forEach(r => {
    const up = Math.max(0, -r.start);   // RNA.start may be negative
    const down = Math.max(0, r.end);
    const region = `${r.trans_name}:${up}:${down}`;
    favouriteManager.add(region, r.assembly);
  });

7. Forms that are NOT supported

These are silently ignored (not an error, but no navigation):

Form Why
chr1:100..200 Separator must be -, not ..
chr1:100..200..+ Strand info is not encoded in region strings
100-200 (no chrom) : prefix is required
NANOG-204 A flank value is required
NANOG-204: The flank can't be empty
NANOG-204:5000:5000:200 At most two numbers

To express strand, use the transcript structure carried by navigateByTranscript*() — not the region string.