Reference Manager v1.0.60¶

Manages the "reference genome list", including default loading, runtime addition, switching, and searching transcripts by name. Every renderer instance has its own:

const rm = renderer.referenceManager;

See Type definitions for the full IReferenceConfig definition.

Method¶

getAll¶

method

rm.getAll(): IReferenceConfig[]

getConfig¶

method

rm.getConfig(): IReferenceConfig | undefined

Returns the currently active reference. Commonly used to "get the current assembly":

const assembly = renderer.referenceManager.getConfig()?.assembly;
// assembly?.name === "GRCh38"

// Note: history / favourite store the full ILocus (not a string + assembly):
historyManager.add(renderer.locusManager.getLocus());

getActiveIndex¶

method

rm.getActiveIndex(): number

get¶

method

rm.get(index: number): IReferenceConfig | undefined

add¶

method

rm.add(ref: IReferenceConfig): number

Appends a reference. Returns the index of the inserted position.

update¶

method

rm.update(index: number, ref: IReferenceConfig): void

remove¶

method

rm.remove(index: number): void

Removes a reference. If the removed one is currently active, it falls back to index 0.

replaceAll¶

method

rm.replaceAll(refs: IReferenceConfig[]): void

switchTo¶

method

rm.switchTo(index: number): IReferenceConfig | undefined

Switches the active reference and synchronously returns the switched-to IReferenceConfig (returns undefined for an invalid index). Fires the "switch" event and internally calls renderer.applyReference().

Async synchronization via lastSyncPromise

switchTo() itself is synchronous; the channel re-sync triggered by the reference switch is asynchronous, and its Promise is exposed via lastSyncPromise. To wait until the switch has truly settled, await rm.lastSyncPromise.

switchByName¶

method

rm.switchByName(name: string): IReferenceConfig | undefined

Switches by assembly.name (case-insensitive).

labelFor¶

method

rm.labelFor(index: number): string

Returns a human-readable label, e.g. "Human · GRCh38 · GENCODE v44".

syncChannels¶

method

async rm.syncChannels(): Promise<void>

Syncs the pinned channels bound to the reference (such as the built-in Transcript / Sequence tracks). switchTo() calls this automatically.

resolveDefaultLocus¶

method

async rm.resolveDefaultLocus(): Promise<DefaultLocusPlan | undefined>

Reads the current reference's defaultLocus and decides how to navigate there (based on the catalog type, RNA-API / GFF / DNA). Returns DefaultLocusPlan.

searchTranscripts¶

method

async rm.searchTranscripts(query: string, limit = 20): Promise<ITrans[]>

Searches genes / transcripts by name. The backend is either a REST API or SQLite-over-HTTP, depending on the current reference's configuration. limit defaults to 20. Returns [] when query is shorter than 2 characters or on error. For terminal-facing search, prefer renderer.searchManager directly.

const list = await rm.searchTranscripts("nanog", 10);
// list[0] = { trans_id: "ENST00000229307.12", trans_name: "NANOG-204",
//             trans_type: "protein_coding", level: "transcript" }

count / active / activeIndex / activeTooltip / lastSyncPromise¶

getter

rm.count: number
rm.active: IReferenceConfig | undefined  // @deprecated use getConfig()
rm.activeIndex: number
rm.activeTooltip: string
rm.lastSyncPromise: Promise<void> | undefined

on¶

method

rm.on(listener: ReferenceManagerListener): () => void

Event¶

event

Event	Trigger	`detail`
`"add"`	after `add()`	`{ index, ref }`
`"remove"`	after `remove()`	`{ index, ref }` (ref = removed item)
`"update"`	after `update()` (if the active item changed, a `"switch"` is emitted afterwards)	`{ index, ref }`
`"switch"`	after switching the active reference	`{ index, ref, activeIndex }`
`"replace"`	after `replaceAll()` (if the list is non-empty, a `"switch"` is emitted afterwards)	`{ refs, activeIndex }`

ReferenceManagerEvent / ReferenceManagerListener¶

type

type ReferenceManagerEvent = "add" | "remove" | "update" | "switch" | "replace";

type ReferenceManagerListener = (
  event: ReferenceManagerEvent,
  detail?: {
    index?: number;
    ref?: IReferenceConfig;
    refs?: IReferenceConfig[];
    activeIndex?: number;
  },
) => void;

Types¶

ITrans¶

type

A gene / transcript search hit. The same shape is shared by SearchManager and the toolbar autocomplete.

interface ITrans {
  /** Ensembl transcript / gene ID (e.g. `ENST00000054666.11`). */
  trans_id: string;
  /** Display name (e.g. `VAMP3-201` or `VAMP3`). */
  trans_name: string;
  /** biotype / feature_type (e.g. `protein_coding`, `lncRNA`, `gene`). */
  trans_type: string;
  /** Whether the row points to a gene-level alias or a specific transcript. */
  level: "gene" | "transcript";
}

DefaultLocusPlan¶

type

The return value of resolveDefaultLocus() — decides the navigation strategy based on the reference's catalog type. Note that the locus field is an IDefaultLocus (the config-shaped partial Locus), not an ILocus.

type DefaultLocusPlan =
  | { kind: "rna-name";       locus: IDefaultLocus }   // use NAME:up:down annotation (REST / .rba/.sqlite searchable catalog)
  | { kind: "rna-annotation"; locus: IDefaultLocus }   // resolve transcripts from the reference GFF (scoped by locus.dna) (.rbi catalog)
  | { kind: "dna";            locus: IDefaultLocus };  // direct genomic coordinates

IDefaultLocus¶

type

The initial locus written into the reference / browser config (a partial shape of ILocus): id / time / isFavorite are derived at runtime, and assembly is derived from the active reference, so the config author only needs to provide the identity (transcript / gene name) and / or coordinates.

interface IDefaultLocus {
  mode?: ViewMode;            // "dna" | "rna" | "cds"
  rna?: Partial<ILocusRna>;
  dna?: Partial<ILocusDna>;
}