chromosomix 0.21.0

What changed in chromosomix 0.21.0, released on 5 November 2026.

Added

• The files a contributor looks for, and a page on adding a reader or a task. CONTRIBUTING.md, CODE_OF_CONDUCT.md (the Contributor Covenant 2.1), SECURITY.md, issue forms for a bug and a feature request, and a pull request template whose checks are this repository’s rules. The documentation’s Contributing group gains Adding a reader or a task: how a file is read and a task runs, and where a track format, a contact-map format or a task goes, with what each must come with. The README has a Contributing section.
• The Python widget carries its licence. A wheel built from widgets/python/ held no licence text; widgets/python/LICENSE, the root’s GPL-3.0 word for word, is now in it as its License-File, and test/unit/licences.test.ts holds the copy to the original.
• The notebooks render every week, unpublished (§18.10). .github/workflows/notebooks.yml also runs on Sundays at 02:37 UTC, on main’s newest commit with every input at its default, and publishes nothing — no push to the notebooks branch, no release assets, no deploy: its artifacts and its summary are what it leaves, and a page it rendered says it was rendered on that schedule. It has a concurrency group of its own, so it can neither cancel a release’s run waiting behind another nor hold one back.
• The deep human map on five sides (§18.10). notebooks/laptop.qmd times its six analyses over the IMR-90 map on the command line as before, and now in Chromium too — the map opened once, each task run in turn in the same page, the pileup over the loops the first called there, the map moved to 250 kb for the compartments and back — the cooltools and coolpuppy script on one process as well as on one a core, and cooltools’ and coolpuppy’s own commands one after another, as chromosomix’s run, each set to the API’s defaults the script uses where the command’s differ. The virtual 4C reads the whole genome on every side, as the validation’s § 10 does, where it read chr8 alone. coolpup.py needs PyTables, setuptools 81.0.0 (the last with pkg_resources) and, on a Mac, multiprocessing-logging 0.3.4: notebooks/environment-laptop.yml adds them, and the page checks for them first. notebooks/scripts/laptop.mjs runs a plan with steps in one page, weighing the browser throughout and timing the opening, each move to another rung and each run apart; the page lays the browser’s stretches end to end, as the commands are, leaving out what the driver does between them. pipeline.tsv, the page’s table, its figure and its summary have a side for each, and notebooks/scripts/timing.plot.R‘s panel c a row for each — chromosomix’s command line and Chromium, then the reference’s commands, its script on several processes and on one — the panel as wide as the page and growing with its rows, each side’s end and peak written just past where it finished. Its caption is three bullets — b’s comparisons, every comparison the timings notebook makes, and the deep map whole, the command line against cooltools’ and coolpup.py’s commands and Chromium against the script — each in CPU time, wall clock and peak memory.

Changed

• The Notebooks workflow publishes without waiting for the laptop (§18.10). Its publish job needs the parity, the validation and the viewers alone, since the runner’s render of the laptop is published nowhere; a laptop render that stalled had held the pages back for hours. The laptop job writes its own section of the run’s summary (pages.py summary laptop), and is never the run’s failure: its render stops at 330 minutes, short of the job’s limit, a render that fails or overruns is a notice, and the job continues on error.
• notebooks/viewers.qmd draws each viewer the way it draws best without a GPU (§18.10). All three viewers were timed in a Chromium told to draw WebGL with SwiftShader, for HiGlass’s sake, and that browser composites every page on the emulated GPU, which no reader’s browser does: chromosomix’s pictures of the yeast map from disk took 0.54–0.82 s there, and take 0.21–0.33 s in a Chromium launched without the flags, compositing in software, where chromosomix and juicebox.js are now timed. HiGlass, which draws nothing without WebGL, keeps its browser: one browser for all three that draws WebGL with SwiftShader and composites in software reads its every frame back off the emulated GPU, and its pictures took 1.17–1.32 s there against 0.34–0.37 s. The table’s new graphics column says which drew each run.
• Every workflow’s actions run on Node 24. GitHub runs Node 20 actions on Node 24 with a deprecation warning, and will stop: checkout v7, upload-artifact v7, download-artifact v8, setup-node v7, setup-python v7, setup-java v6, github-script v9, cache v6, upload-pages-artifact v5, deploy-pages v5 and action-gh-release v3, each the newest major, every input the workflows pass still one it takes. r-lib/actions v2 already ran on Node 24. The Node the app is built and tested with is unchanged.
• The notebooks’ runners are described as they are (§18.10). notebooks.yml and SPECS said a standard runner has 2 cores and 8 GB, a private repository’s; the repository is public, and every page of 0.20.0 ran on 4 cores and 15.6 GB. The memory shutdowns they record happened on the private runner.
• npm test passes on a fresh clone, and leaves the dev features’ tests to npm run test:dev (§29.6). It failed 491 tests in 13 suites there, every one for want of a fixture npm run fixtures builds with metacooler, a private repository. Those suites now say // @fixtures metacooler in their header and are left out while none of the fixtures is on disk. The 39 files that test a dev feature — the reference editor, the dot plot and the multi-genome format — say // @dev-feature <name> and are left out unless the run asks: npm run test:dev, vitest --mode dev or CHROMOSOMIX_DEV_TESTS=1. A run says at its top what it left out and the command that runs it. CI’s every vitest run, and npm version’s check, ask for the dev features, so nothing goes untested on a push; test/unit/dev-tests.test.ts fails the default run on a marker that names a feature the registry no longer has, or that sits where it is not read.

Fixed

• A remote .hic’s whole genome is drawn four times sooner (§3.6). The walk across its chromosome pairs keeps six reads in flight, and in Chromium they went out one at a time: the browser’s HTTP cache lets one request per URL at its entry at once, holds the rest until it has, and every read of a walk is of one URL. Its reads now go past the cache (cache: 'no-store'), as nothing kept them anyway. From 4DN’s bucket, the chicken map’s whole genome at 2.5 Mb is 12–14 s where it was 60 s, the mouse map’s at 5 Mb 17 s where it was 75 s, and the yeast map’s from the demo store 4 s where it was 15 s, for the same requests and bytes. The census of §6.5 reads through the same call, and goes past the cache too.
• A .hic’s walk across its chromosome pairs reads through gaps of 256 KiB, not 64 (§3.6) — the whole-genome picture and the census, from a bucket and from disk. Fewer requests for more bytes, now that the walk’s requests are in flight together: from the buckets, in Chromium, the yeast map’s whole genome is 1.7 s where it was 3.6 (8 requests and 11.9 MB, where 74 and 3.4 MB), the chicken map’s 8.9 s where it was 12.4 (273 and 52.8 MB, where 432 and 29.9 MB), the mouse map’s 14.2 s where it was 17.0 (374 and 35.9 MB, where 458 and 21.1 MB); from disk, the yeast map’s 208 ms where it was 251 and the chicken map’s 438 where it was 497. On a link slower than about 7 MB/s, the chicken map’s extra 23 MB give back part of the gain.
• A .hic opens reading its footer’s framing, not the whole of it (§3.6). The footer is nearly all expected values the viewer never uses — 9.8 of the 4DN chicken map’s 9.9 MB — and it was read whole to reach the normalisation index past them. It is now walked: each section’s few bytes of framing are read and the values stepped over. On the chicken map from disk, in Chromium, the chromosome, region and locus pictures are 254, 283 and 251 ms where they were 311, 323 and 292; from 4DN’s bucket every open reads 13.6 MB where it read 18.9. The two indexes it finds are the ones a whole read found, on the yeast, chicken and mouse maps of notebooks/viewers.qmd.
• The Python widget’s install line names where it is (§21.5). The README, the widget’s README, the documentation’s In a Jupyter notebook and Ways to use it, llms.txt and SPECS said pip install chromosomix, and the package is not on PyPI. They now say pip install "git+https://github.com/js2264/chromosomix#subdirectory=widgets/python", which installs it from the repository, with @<tag> to pin a release and pip install -e widgets/python from a clone. The README’s R section, which gave only the line for a clone, now gives remotes::install_github("js2264/chromosomix", subdir = "widgets/r") first, as the R widget’s README and the documentation do.
• The laptop’s deep human map runs on a Mac (§18.10). notebooks/scripts/cooltools_pipeline.py stopped at coolpuppy’s pileup on macOS: there Python spawns its workers rather than forking them, and coolpuppy’s pool logs through multiprocessing_logging, which refuses any start method but fork. The script asks for fork, as Linux gives it, and notebooks/laptop.qmd gets past the map.