chromosomix 0.19.0

What changed in chromosomix 0.19.0, released on 1 November 2026.

Added

• The site describes itself to AI agents in full (§11). llms.txt now says the four things an agent can do with chromosomix — write a link, run an analysis, embed and drive the viewer, publish data — names every task, and links five reference pages that the app writes about itself, under chromosomix.app/llms/:

  • links.md: every key a link’s fragment takes, with its values, the views, the two forms of a coordinate, the query (embed, config, store), pinned builds, and example links, each of which opens what it says;
  • cli.md: installing the command, writing one, what it writes, its exit statuses, examples, and the usage --help prints;
  • tasks.md: every task, each with what it reads and writes, the shape of its command, and every parameter’s flag, what it takes, its default and what it does — every value a choice takes included, which chromosomix tasks never printed;
  • embed.md: the <iframe>, the six postMessage messages and their rules, a host page’s script, and the Jupyter and R widgets;
  • data.md: the formats and their sidecars, what a host must serve, the built-in stores, and a store file and the smallest workspace a lab can write by hand.

  All of it is written by the site build, from the source it builds, so every deploy of main refreshes it with nothing to remember and nothing generated committed: llms.txt’s lists — the tasks, the stores, the colour maps — and each page are read from what they describe (the task registry, the hash reader’s own keys, the command’s usage, the embed channel, the store shelf), and npm run dev serves them live. llms-full.txt is now the README followed by the five pages, in the order llms.txt links them. The deploy stops before publishing if the build left out llms.txt or a page it links, and after publishing fetches chromosomix.app/llms.txt and its first page as an agent would, failing if they do not answer. llms.txt was a file kept by hand in public/.

• chromosomix tasks --json (§23). The task listing as one JSON document: per task its id, title, what it reads and writes — the files a run leaves as a whole included, such as the map report’s page — the tasks it runs first, and every parameter with its flag as the parser takes it, its default, every value a choice takes, its range and unit; with how a parameter naming a file is given one, and what each kind of result is written as. For a script or an agent writing commands for the installed version.

• TAD annotation: Juicer’s Arrowhead, ported (§18.8, §18.9). A 2D task after the HiC score that calls contact domains from the corners of the squares they make on the map, so they can nest, share an edge, or leave an unstructured stretch uncalled — where insulation’s and the directionality index’s domains tile the sequence. A port of juicer_tools arrowhead as Juicer Tools 1.22.01 runs it: its window (-m, 2,000 bins), its strict pass (variance ≤ 0.2, sign agreement ≥ 0.5), its lenient pass (0.4 down to 0 by 0.1, kept past 60 bins where it crosses no strict edge), the merging of nearby corners and Juicer’s order, every sum in the Java’s order, a contact in a dropped bin NaN as Juicer keeps it, and the lenient blocks tried in the order the jar’s own HashSet gives them — its HighScore.hashCode, read off the bytecode, and HashMap’s buckets down to the red-black trees crowded ones become. The domains open on the map as corners and leave as a BED, and Juicer’s _blocks.bedpe columns — corner score, uVarScore, lVarScore, upSign, loSign — are a table beside them. chromosomix arrowhead runs it from a shell. Its golden is Juicer’s own output over the demo .hic at 2 and 4 kb, raw and KR-balanced, and the port is equal to it to the last bit — 102 domains, every score (npm run fixtures:arrowhead, which needs Java and the jar); and on 4DN’s K562 in situ Hi-C at 10 kb, chromosomes 21 and 22, every one of Juicer’s 177 domains raw and 200 with KR is the port’s, at the same corners with the same scores (notebooks/validation.qmd § 28).

• Map report (§18.8). A 2D task after Pairs QC that runs P(s), Coverage and Cis and trans per sequence as they run on their own, adds the library’s totals — contacts, cis, trans, within a bin, cis by separation, and pairtools stats’ counts where the map was binned from a .pairs — and a resolution ladder: at each bin size, coarsest first, from the file’s finest resolution (opened beside the map when another is on screen) doubled and the file’s own rungs, the mean and median contacts per bin, the count 80 % of bins reach, and the empty and nearly empty shares, a contact counted at both its ends as Juicer’s calculate_map_resolution.sh counts it. Numbers only, no pass or fail. Every figure and table is in the drawer and exports on its own, and HTML report saves the run as one self-contained page: a tab per question (Overview, Library, Resolutions, P(s), Coverage, Cis & trans, About), figures with a hover card and legend chips that hide a series, each saved as SVG or TSV, sortable and filterable tables, light and dark, a phone’s width and a print of every tab — nothing fetched. chromosomix mapreport writes the page too, and four MultiQC custom-content files (*_mqc.tsv, *_mqc.json) a pipeline’s MultiQC collects, one row per library. The ladder is cooler’s own coarsening to the digits written, at every one of the GEO yeast Micro-C file’s ten resolutions, 50 bp to 25.6 kb (notebooks/validation.qmd § 29).

• Example sessions on the landing page (§24.11). Under Just looking? and Pick an example session, in the margin beside the store tiles — under them on a narrow page — four buttons, each opening one tab in the tab it was pressed in, and each with the Analysis column’s ?, whose tip says what the tab holds and where it is from:

  • Human Hi-C data: 4DN’s in situ Hi-C of K562 (Rao et al. 2014, 907 million contacts) at 10 kb over MYC, PVT1 and the blood enhancer cluster on chr8, with no deck; IGV’s hg38 RefSeq genes, sequence and bands above it; 4DN’s insulation, boundaries and E1 and ENCODE’s subcompartments down its left; ENCODE’s CTCF ChIA-PET loops on it; and ENCODE’s ChIP-seq, ATAC-seq and DNase-seq of the same cells under it, as five overlaid pairs — CTCF with RAD21, H3K4me3 with H3K27ac, Pol II with H3K36me3, H3K27me3 with H3K9me3, ATAC with DNase — each track on its own axis. The gene model and the bands are read from IGV’s bucket, whose copy answers a page where UCSC’s does not.
  • Yeast micro-C data and Linear tracks: the lab’s store’s yeast micro-C figure and its yeast landscape in the 1D browser, read from the address the store’s cards read them from.
  • Comparing data: chicken DT40 Hi-C from 4DN (Gibcus et al. 2018), G2 above the diagonal and 60 min into mitosis below it, over 40 Mb of chromosome 1 at 100 kb, with each map’s compartment eigenvector and insulation on the edge beside its own triangle, on one axis per kind.

• The subsample and every normalisation held to cooler and cooltools in CI, run on the day and not read from a golden (§6.4, §6.5, §7.5). The goldens job of .github/workflows/test.yml now installs cooltools beside cooler and, with the other fixtures cooler can write, has them reprocess the demo yeast Micro-C (npm run fixtures:reprocessed, into gitignored fixtures); two new suites compare this app with what they wrote. test/unit/subsample-cooltools.test.ts draws ten million contacts as the contacts box does and holds the draw to cooltools random-sample --exact‘s as two draws from one distribution: the total exact, every pair of sequences and every bin’s coverage within the noise two draws leave, every pixel spread as a draw without replacement spreads it, as many pixels holding each count, and the file’s weights times √(T/N) to cooler balance over cooltools’ draw — the median ratio 1.0004. test/unit/normalise-cooler.test.ts holds balanced to cooler’s matrix(balance=True) on a copy cooler balance rewrote, VC and VC √ to one round of cooler balance with every filter off, and ICE to cooltools’ iterative correction, over three chromosomes at 1 kb and, after cooler coarsen, the whole genome and a block between two chromosomes at 16 kb: every cell to Float32’s precision, and in fact within the half unit its own rounding costs. Made to fail on purpose, it does — a draw with replacement, ICE stopped early, VC averaged over empty bins.

Changed

• Compartments by cooltools’ method are cooltools’, to the digits they are written in (§18.8). E1 agreed with cooltools.eigs_cis at r = 0.9985 to 0.99993 chromosome by chromosome on the mouse map at 100 kb, the A/B call differed in up to 1.1% of a chromosome’s bins, and on chr4 and chr15 one tool’s third component was the other’s fourth. The difference was the expectation: eigs_cis does not divide by expected_cis but by one it takes from each chromosome’s square — each diagonal’s mean up to about the thirty-fifth and, beyond it, the mean of a group of diagonals at most 3% wide — where the app divided every cell by its own diagonal’s mean, which left the far cells on a sawtooth of a percent or two against cooltools’. It now divides by cooltools’, with that expectation’s two small rules: the near diagonal pooled as the ones cooltools sets it to, and a group with no contacts left undivided. On the mouse map (§ 3 of the validation notebook) and on the zoo’s P. aeruginosa, C. necator and E. coli maps at 8 kb, every component is cooltools’ to within 3·10⁻¹² in r and 5·10⁻⁶ in any bin — the six significant digits a track is written to — the eigenvalues to the table’s three decimals, the A/B call the same in every bin, and E2 and E3 the same components on every chromosome. The saddle and the Lieberman-Aiden method still divide by each diagonal’s own mean, as cooltools.saddle does by expected_cis, and the correlation’s eigenvectors, A/B call and saddle are what they were; the of contacts share is measured over cooltools’ matrix under both methods, which moves the correlation’s in the third decimal. Version 4 of the task. The second observed/expected it makes of each chromosome costs a twentieth of the run: over the mouse map, 16.7 s of CPU where it was 16.0, against 28.2 s for cooltools.

• Signal by group compares one value per entry by default (§18.8). Its bin size is 0 unless one is typed, where it was the open map’s resolution: each run of a name, merged where its features overlap or touch, each stretch of the rest between two, and each run of bins in one group of a track is one value, and an entry across a circular sequence’s origin is one entry. The tests count their values as independent, and the bins of one compartment are not — over P. aeruginosa‘s 782 8-kb bins in 110 compartments, A against B in GC had a P of 2·10⁻²⁰ in 8 kb bins and 3·10⁻² in 128 kb ones, its effect the same at both. A bin size gives the stretches of at most a bin it gave before, number for number, and a chromosomix groupsignal line with no --resolution is now one value per entry; the task’s version is 2. Over § 3’s compartments on chr19, § 23 of the validation notebook holds both ways to pyBigWig and SciPy to the digits written, P and q to their four places above 10⁻⁴ where an exponent does not write them, and by entry the run takes 0.64 s against the 10 kb stretches’ 1.2 s.

• The laptop notebook runs each of its 23 analyses in the app, in Chromium, Firefox and WebKit, as well as on the command line (§18.10). What a genome-wide analysis costs was measured on the command line alone, where a reader runs most of them in the browser. Each is now run again in each of the three browser engines Playwright drives headless — Chromium, which Chrome and Edge are built on; Firefox; and WebKit, Safari’s engine — as a reader runs it (notebooks/scripts/laptop.mjs): the files the command names dropped on the landing page, a map framed on its whole genome at the command’s resolution, the task opened from the Analysis panel, every flag of the command set in its form, and run pressed once the map is drawn, its circles measured and the browser idle — a browser of its own for each, so nothing an earlier run held is counted. Its time is the app’s own, dispatch to result; its CPU time and peak memory are the page’s, sampled five times a second as the operating system counts them, the same way in the three, with all of the browser’s processes kept beside them. Every file a command names is read through before each run, so the first venue to read an 8.3 GB map does not pay alone for reading it from disk. LAPTOP_BROWSERS names the browsers, all three unless it says. The table under the results is one row a run; the page shows the time, the CPU time and the memory with a column for each venue, each browser against the command line and against Chromium, how many finished in each, the five analyses at two depths and the figure, and the line each browser’s console wrote for each run is held to the command it ran, flag by flag, and to the others’. The memory table’s column for a browser is what the run added to what the page already held, and a sentence gives the geometric means of each browser’s CPU time and peak memory over the command line’s. Its findings are written by the page itself, where they were inline expressions that a Quarto before 1.4 printed as code. The runner’s render installs Playwright’s three browsers and may take close to six hours.

• ICE balances to Float32’s precision (§7.5). It went on until every bin’s marginal was within 1e-5 of their mean, which left its cells up to 3·10⁻⁵ from cooltools’ iterative correction; it now goes on to 1e-9 while the cell budget allows, and its cells are cooltools’ to the half unit in the last place their own rounding costs. That is some thirty rounds more — chromosome IV of the yeast Micro-C at 1 kb takes 0.6 s where it took 0.35 — and nothing a colormap can show, so a block is still called balanced at 1e-5: no caption that said balanced now says it stopped before convergence.

Removed

• Telemetry, all of it (§1, §11, §13, §18.10; §31 is gone). The site sends nothing on its own behalf any more: no visit, no format opened, no task, error, install or allow access counted, and no request to Umami. About’s Telemetry section and its switch go, and so does the landing page’s clause about it, whose privacy note says again that there is no upload, no account and no server; so do src/telemetry.ts, the TELEMETRY_ENDPOINT and TELEMETRY_WEBSITE build variables and the deploy’s use of them. C1 is again no server-side component of any kind. forget everything keeps no key back: a chromosomix:telemetry left by an earlier version is swept with the rest, and nothing reads it. The gallery script is now scripts/ui-allow.mjs, and drives allow access alone.

Fixed

• llms.txt, a mistyped address and every other file beside the app open as themselves in a browser that has visited the site (§11). The service worker answered every page load on chromosomix.app with the app, except a list of known addresses, so chromosomix.app/llms.txt typed into the address bar showed the landing page — as did robots.txt, sitemap.xml, the licences linked from About, and an address that does not exist, which should be a 404. A hard reload or a private window showed the file, since neither goes through the worker, and agents, which run no worker, always saw it. The worker now answers only the app’s own address — the root and index.html, with any query and hash — and leaves everything else to the network. A browser already holding the old worker takes the fix when it accepts the bar offering the new version.

• A task’s required steps keep a balancing the task answered for them, from the shell as in the app (§18.2). chromosomix re-derived every required step’s use balancing weights from the file even where the task had answered it, which AnalysisRunner.plan never did; no task answered one before the map report, whose cis and trans are of the raw counts in both.

• A FASTA dropped with its .fai and nothing else opens by range (§8.8). The two were paired, and the index went to the sequence track — but not to the question asked first, which sequences the genome has, so the FASTA was read whole for it, and one past 300 MB, mm10.fa beside its mm10.fa.fai, was refused for want of an index. Dropped with a track or a feature file it opened, since that file named the genome instead.