[jmschrei]

This pull request was written with Claude Code.

Following #1896, this adds figwig (.fw) files to IGV desktop. A figwig file holds the
per-base signal of many tracks over one genome in one file (an assay's experiments, both strands,
model predictions, one track per cell), with a JSON record of attributes per track. Format:
https://figwig.readthedocs.io/en/latest/format.html. The attached NOTES.md has the design, the checks
and every timing.

What it adds

• org.igv.figwig, a new package with no new dependency: the reader (FigWigFile, with
  FigWigChunks, FigWigPool and FigWigSummaryIndex), a DataSource, and a track chooser.
• 49 lines elsewhere: the fw format in TrackLoader, the magic FIGW in FileFormatUtils,
  and IGV.isRestoringSession().
• 24 JUnit tests with 13 small test files (691 KB) written by the figwig package.

A .fw loads as one DataSourceTrack per figwig track, named by the track, with its attributes as
IGV attributes. A file of more than 50 tracks opens the existing TrackChooser first; sessions and
batch scripts load without asking. Zoomed out, tracks draw from the file's summaries and zoom levels
(mean; the window functions offered are mean and none). Local files, http(s), s3 and gs paths are
read with range requests through IGV's own streams.

Speed

IGV headless, every track of a view loaded on 5 threads, data caches cleared before each view, one
pinned 8-core CPU complex, all formats on this branch's build. ms per screen update:

	1 Mb	10 Mb
24 tracks over HTTP (20 ms/request): 24 bigWigs / one TDF / 24 TDFs / figwig	612 / 3,645 / 2,047 / 22	357 / 144 / 713 / 27
3 of 1,000 cells over HTTP (20 ms/request): 3 TDFs / figwig	155 / 24	143 / 31
fold change, local: bigWig / TDF / figwig	0.56 / 6.4 / 2.5	1.1 / 0.40 / 15.6
fold change over HTTP (20 ms/request): bigWig / TDF / figwig	32 / 500 / 26	22 / 143 / 59

• Up to 100 kb, one track takes 0.06-1.3 ms locally (bigWig 0.34-1.1, TDF 0.05-3.6) and one
  round trip over HTTP.
• At 10 Mb one figwig track is slower than bigWig and TDF, locally (1.1-15.6 against 0.25-1.2 ms)
  and on slow links, because its finest summary is the 16 kb tile, so it decodes raw data there.
• Against the reader shown in the issue, 10 Mb views are 1.5-5.4x faster locally and 2.8-23x
  faster over HTTP.

Testing

• Against the figwig package: every base and every summary and zoom bin of the test files. These
  cover every chunk kind and element type, the types' extreme values, both orders and codecs, files
  where some groups keep no summary, and a regional summary index (current and stale).
• Against IGV's own code: summaries match AbstractDataSource score object for score object
  under every window function.
• Edge cases: chromosome aliases, ranges past a chromosome's ends, reads racing the file's closing,
  and corrupted files, which fail with an exception and never hang.
• Remote files: over HTTP from an in-JVM server, through redirects and short responses.
• IGV's full suite: 697 tests, main's 673 and these 24. The one failure,
  UCSCBackupHostTest.testFileNotFoundDoesNotSwitchHosts, connects to UCSC's server. It also failed
  in 1 of 2 full runs on main, and passed alone on both.

Outside the unit tests, IGV draws from figwig files the values it draws from the source bigWigs
wherever both read raw data. Remote reads equal local reads over HTTP and HTTPS, including a 2.3 GB
file.

🤖 Generated with Claude Code

[jmschrei]

Hello! Here is the PR adding figwig integration to IGV. I asked Claude to write a summary of all of our timing experiments and that is attached here. It is quite verbose so I imagine you'll probaby just skim it to find numbers interesting to you.

The numbers are better than the ones in the issue because we did a second round of improvements and changed the zoom/summary details a bit to improve performance on large reads. But also note that many comparisons involve a figwig with a single track vs a bigwig, and it's unclear to me if thats a setting where we'd expect figwigs to be much better.

Let me know if there's anything else I can provide or any crucial issues I've overlooked, and thanks for your time.

NOTES.md