Save IGV hosted genomes by ID in sessions by jrobinso · Pull Request #1875 · igvteam/igv

jrobinso · 2026-09-17T06:16:46Z

Sessions on an IGV hosted genome now record just the genome ID instead of an expanded reference object.

A frozen copy of a hosted genome definition goes stale as the server gains annotations or corrects URLs; the ID is smaller and always resolves to the current definition.

"genome": "hg38"

replaces the reference block (which was already written minus its tracks). Anything not on the genome server — GenArk, hubs, local files, user genomes — still writes the expanded reference exactly as before, and both forms are read.

Not loading the genome's tracks twice

A session lists every track, the genome's default annotations included, so when a session names a genome by ID those annotations are not loaded again with the genome: GenomeManager.loadGenomeById / loadGenome / setCurrentGenome / restoreGenomeTracks take a loadAnnotationTracks flag, and the session's track list is the sole authority. The sequence track and the legacy .genome/.gbk gene track are still restored.

A hand-written session that names a genome by ID and expects its default annotations without listing them can set "loadGenomeTracks": true, which merges the genome's tracks with the session's, matched on url. Default false. The reference branch is untouched and still merges inline reference.tracks.

Fixes found along the way

The by-ID branch skipped its session reset when the requested genome was already current. Harmless while IGV never wrote "genome" itself; once it does, loading a second session on the same genome leaks ROIs, sample attributes and frames from the first.
loadGenomeById's return value was discarded, so a genome that failed to resolve left the session's tracks loaded against whatever genome was still current — a session that looks loaded but is plotted on the wrong assembly. It now fails.
Genbank genomes could not be loaded from the genome chooser — a regression against 2.19.x. The dialog assumed every entry had a json or hub definition to rename, choose annotations from and download; .gbk has neither, and is now loaded directly.
Genbank genomes are identified by the versioned accession (NC_012920.1) from the VERSION line, matching the hosted genome list. Previously the unversioned ACCESSION was used, so a session on the mitochondrial genome wrote a reference carrying no sequence at all — GenomeConfig.toJSON serializes only URL fields, and a genbank genome's sequence lives in the file.
GenArk records were keyed by the assembly column — names like Loxafr3.0 that nothing else uses — and that list has no url column, so all 52,777 had a null path and could not be loaded by ID at all. They are now keyed by accession, with the path derived via HubGenomeLoader.convertToHubURL.
The genome chooser's legacy .genome cleanup was passed the accession, so it looked for a filename that never exists.

Keeping the genome list cheap

Answering "is this ID hosted?" used to download the 5.8 MB UCSC GenArk list along with the 4 KB IGV list, from the EDT, the autosave timer thread and the JVM shutdown hook. The two lists are now loaded independently: the session writer and ID resolution touch only the small one, and GenArk loads solely for the genome chooser or an ID that is not ours. The IGV list is also cached in the genome directory — fetched live every session, with the local copy used only when the server cannot be reached, so an outage does not silently cost sessions their genome IDs.

Test sessions

test/sessions/json/*.json converted to the ID form. The webapp-* sessions were written by igv.js and are left alone, as is blat-session.json, whose genome is GenArk rather than IGV hosted.

The matching igv.js change is not part of this PR.

🤖 Generated with Claude Code