chromosomix 0.15.0 → 0.16.0

package/README.md

@@ -6,7 +6,7 @@
 [![npm](https://img.shields.io/npm/v/chromosomix?logo=npm)](https://www.npmjs.com/package/chromosomix)
 [![Release](https://img.shields.io/github/v/release/js2264/chromosomix?logo=github)](https://github.com/js2264/chromosomix/releases)
 [![Validation](https://img.shields.io/badge/validation-vs%20reference%20tools-2ea44f)](https://chromosomix.app/validation/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)](LICENSE)
 
 **A unified genome browser for multi-dimensional genomic data.** Chromatin contact maps, genome tracks and 3D models, side by side, straight from your files.
 
@@ -21,7 +21,7 @@ chromosomix launches in about a second and reads your data where it lives, on yo
 - Support for all genomic data types: 
   - Supports 1D genomic formats: bigWig, bigBed, BED, bedGraph, wig, GTF/GFF3, FASTA (+`.fai`), `.2bit`, BAM, VCF, barChart/bigBarChart, genePred/refFlat/bigGenePred, bedMethyl/bigMethyl, chrom.sizes, ...
   - Supports 2D genomic formats: `.*cool`, `.hic`, HiC-Pro, `pairs(.gz)`, ..., at every resolution the file stores. Also supports interaction formats: BEDPE, and UCSC's `interact`/`bigInteract` and `longrange`/longTabix — drawn as arcs over the contact map and as their own lane in the 1D browser.
-  - Supports 3D genomic formats: WashU's g3d (text or binary), `.3dg`, and `bed3d`, drawn in 3D and synchronized with the maps and tracks view. 
+  - Supports 3D genomic formats: WashU's g3d (text or binary), `.3dg`, and `bed3d`, drawn in 3D and synchronized with the maps and tracks view. Every model also leaves as a PDB for PyMOL, ChimeraX and the other molecular viewers, a chain per chromosome and bonds along the fibre, and reads back here. 
 
 - Perform analyses directly in the browser:
   - 1D analysis tasks: peak calling from a coverage track (yapc, with IDR between replicates), motif search, base composition and GC skew, the origin and terminus of replication, metaplots, track correlation, FRiP over a feature set, signal by group, interval overlap with a shuffle null, ...
@@ -30,8 +30,6 @@ chromosomix launches in about a second and reads your data where it lives, on yo
 
 - Serverless browser & CLI-based: there is no upload, no required preprocessing step and no backend of any kind — the viewer is static files that read standard genome-wide formats directly. Every analysis can be run **interactively**, in the browser, or **programmatically**, with the `chromosomix` command line in a script or a pipeline: the same tasks, with the same parameters, producing the same results. A bottom Console panel in the browser records every run and reports the `chromosomix` command that repeats it.
 
-- Side by side: contact maps, 1D browsers and 3D models open as the cells of a deck, panned and zoomed together, and several sessions stay open at once, one tab each.
-
 - Dedicated browser panels, four around the picture:
   - General panel: the file itself — its attributes, its chromosomes (or a metagenome's genomes and contigs), a minimap of the genome and the metadata it stores.
   - Aesthetics panel: to customize scales, color map, normalization, track layout, grouping, ...
@@ -42,13 +40,15 @@ chromosomix launches in about a second and reads your data where it lives, on yo
   - Cloud-based file access: Open files directly from any object store that serves byte ranges with CORS (e.g. S3, Cloudflare R2, Google Cloud Storage, or any HTTP server that supports range requests), from Dropbox and Google Drive share links, and private Google Drive folder or Dropbox.
   - Stores: several pre-configured remote data stores are available — the lab's own figures, IGV's genomes, 4DN open data, ENCODE, DNA Zoo and Roadmap — and so is any UCSC track hub with a `hub.txt` file. The user can also setup their own store by providing a structured JSON file describing the store and its data.
 
+- Side by side: contact maps, 1D browsers and 3D models open as the cells of a deck, panned and zoomed together, and several sessions stay open at once, one tab each.
+
 ## Philosophy
 
 1. **No backend or install of any kind.** No tile server, no specific process on a host, no accounts. The viewer is static files; the data are objects on a bucket, or a file on your disk. This is what makes the app free to run and free to archive.
 
-1. **Nothing is uploaded.** A local file is handed to an air-gapped worker by reference and read in place through the Emscripten filesystem. Nothing crosses the network, which is why there is no account system, no storage, no hosting cost and nothing to review for GDPR. You can open unpublished patient-derived genomic data on a laptop with the network cable out.
+2. **Nothing is uploaded.** A local file is handed to an air-gapped worker by reference and read in place through the Emscripten filesystem. Nothing crosses the network, which is why there is no account system, no storage, no hosting cost and nothing to review for GDPR. You can open unpublished patient-derived genomic data on a laptop with the network cable out.
 
-1. **No pre-parsing of genomic files is required.** Contact maps and 1D genomic files are read in bounded reads, and the rest is pure canvas transforms with **zero** further I/O. That is the central difference from HiGlass, which needs a tile server, a tile cache and a tile compositor to stream contact maps. 
+3. **No pre-parsing of genomic files is required.** Contact maps and 1D genomic files are read in bounded reads, and the rest is pure canvas transforms with **zero** further I/O. That is the central difference from HiGlass, which needs a tile server, a tile cache and a tile compositor to stream contact maps. 
 
 ## Using chromosomix
 
@@ -96,17 +96,9 @@ A minimal version of the viewer can be added to any HTML page as an `<iframe>`.
 
 Paste it into a page and it works (not rendered here though because GitHub does not allow `<iframe>`). The `src` URL is the same as the one you would use to open the viewer in a browser, with the addition of `?embed=1` to tell it to hide the header and tab strip. 
 
-The text below is a live version of the above `<iframe>` (it will not work on GitHub, but it would work on any HTML page):
-
-<iframe
-  src="https://chromosomix.app/?embed=1#uri=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_microC_G2M_1kb.cool&view=region&region=IV:1000000-1400000&transform=log10&balance=true"
-  width="100%"
-  height="640"
-></iframe>
-
 ## Using the chromosomix analysis CLI
 
-Thirty-one analysis tasks can be executed programatically through the CLI, with the same parameters and producing the same results as the Analysis panel interactively. This can be used in a pipeline or a script.
+Over thirty analysis tasks can be executed programatically through the CLI, with the same parameters and producing the same results as the Analysis panel interactively. This can be used in a pipeline or a script.
 
 ### Installing the CLI
 
@@ -165,6 +157,14 @@ chromosomix tasks
 ##       --matrix (default true)  draw the square
 ##       --no-balance  read the raw counts (balanced by default where the file carries weights)
 ## 
+## cellqc
+##     Per-cell contact QC
+##       --cells (default "all")  cells
+##       --nearFrom (default 23000)  near band, from
+##       --nearTo (default 2000000)  near band, to
+##       --mitoticTo (default 12000000)  mitotic band, to
+##       --no-balance  read the raw counts (balanced by default where the file carries weights)
+## 
 ## expected
 ##     Contact probability P(s)
 ##       --scope (default "contig")  scope
@@ -251,6 +251,18 @@ chromosomix tasks
 ##       --armWindow (default 50)  window along the arms
 ##       --no-balance  read the raw counts (balanced by default where the file carries weights)
 ## 
+## loops
+##     Loop calling
+##       --sequences  sequences
+##       --outer (default 5)  outer half-width
+##       --inner (default 2)  inner half-width
+##       --maxSeparation (default 1000)  furthest from the diagonal
+##       --fdr (default 0.1)  false discovery rate
+##       --lambdaBins (default 40)  λ-chunks
+##       --clusteringRadius (default 2)  clustering radius
+##       --filter (default true)  enrichment filter
+##       --no-balance  read the raw counts (balanced by default where the file carries weights)
+## 
 ## chromosight
 ##     Pattern detection
 ##       --pattern (default "loops")  pattern
@@ -267,6 +279,14 @@ chromosomix tasks
 ##       --maxQvalue (default 1)  report down to a q-value of
 ##       --no-balance  read the raw counts (balanced by default where the file carries weights)
 ## 
+## hicrep
+##     Reproducibility
+##       --against <file>  The other maps to compare with; repeat per map
+##       --sequences  sequences
+##       --maxDistance (default 500)  furthest separation compared
+##       --smooth (default 1)  smoothing half-width
+##       --no-balance  read the raw counts (balanced by default where the file carries weights)
+## 
 ## apa
 ##     Aggregate peak analysis
 ##       --anchors (default "pairs")  anchors
@@ -457,7 +477,8 @@ chromosomix tasks
 
 Each analysis is held to the package it reproduces — cooltools, coolpuppy, chromosight, deepTools,
 bedtools and a dozen others — on public data, command for command, in a notebook rendered with every
-release: <https://chromosomix.app/validation/>, and how long each command takes beside its
+release: <https://chromosomix.app/validation/>, with every number its figures draw in one table beside
+it, <https://chromosomix.app/validation/validation.txt>; and how long each command takes beside its
 reference, <https://chromosomix.app/timings/>.
 
 Every task writes its results where `--out` points, each named after the file it came from up to
@@ -534,7 +555,8 @@ chromosomix circular ecoli.mcool::/resolutions/5000
 chromosomix interarm ecoli.mcool::/resolutions/5000 --circular NC_000913.3 \
   --origin NC_000913.3:3925744 --out results/
 
-# A 3D model built from the map, written as a bed3d the viewer opens beside it.
+# A 3D model built from the map, written as a bed3d the viewer opens beside it,
+# and as a PDB for PyMOL.
 chromosomix reconstruct3d ecoli.mcool::/resolutions/20000 --out results/
 
 # What the session set from the picture, as flags: the score column a
@@ -558,15 +580,25 @@ The log is kept in your own browser for seven days or five hundred lines, whiche
 
 ## Licence
 
-chromosomix is released under the MIT licence (`LICENSE`).
+Copyright © 2026 Jacques Serizay.
+
+chromosomix is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License, in [`LICENSE`](LICENSE), for more details.
+
+It is under the GPL because its peak calling is ported from yapc (GPL-3.0) and the IDR test it runs across replicates from IDR (GPL-2.0 or later), and a translation of GPL code can only be distributed under the GPL.
+
+Every build also carries the work of other projects, each under its own licence, and the app names them in **About → Licences**:
+
+- **Libraries compiled into the bundles:** three.js (MIT); echarts (Apache-2.0) with zrender (BSD-3-Clause) and tslib (0BSD); h5wasm (NIST's notice, with the BSD-style licence of the HDF5 library inside it); and `@gmod/bbi` with its dependencies `generic-filehandle2`, `@gmod/abortable-promise-cache` and `@jbrowse/quick-lru` (all MIT).
+- **Code ported from reference implementations**, where an analysis follows its reference function for function so that it gives the same numbers: yapc (GPL-3.0) and IDR (GPL-2.0 or later) for peak calling; cooltools (MIT) for loop calling and insulation's peak prominence; cooler (BSD-3-Clause) for region strings; chromosight (MIT) for pattern detection; SciPy (BSD-3-Clause) with the cephes functions its `xsf` carries for the Poisson tail and `fminbound`; NumPy (BSD-3-Clause, and NCSA or BSD-3-Clause for `numpy.random`) for its pairwise sums and its binomial and hypergeometric samplers; scikit-learn (BSD-3-Clause) for BIRCH; Boost-HiC (MIT); and fdlibm (Sun Microsystems' notice) for the error function.
+- **Material copied into the source by a generator:** Lucide (ISC), Simple Icons (CC0), chromosight's kernels (MIT), matplotlib's colour tables (the Matplotlib licence) and ColorBrewer's schemes (Apache-2.0).
 
-Every build also carries the work of other projects, each under its own licence. The libraries compiled into the bundles are echarts (Apache-2.0), zrender (BSD-3-Clause), three.js (MIT), h5wasm (NIST's notice, with the BSD-style licence of the HDF5 library inside it), and `@gmod/bbi` with its dependencies (MIT). The source also holds material copied from Lucide (ISC), Simple Icons (CC0), chromosight (MIT), matplotlib (the Matplotlib licence) and ColorBrewer (Apache-2.0). Each build lists what it carries and reproduces every one of those licences in full in `THIRD-PARTY-NOTICES.txt`, beside its `index.html`:
+All of them are compatible with version 3 of the GPL. Each build lists what it carries and reproduces every one of those licences in full, after chromosomix's own, in `THIRD-PARTY-NOTICES.txt`, beside its `index.html`:
 
 - the web app: <https://chromosomix.app/THIRD-PARTY-NOTICES.txt>;
 - the npm package: `dist/` for the viewer, `dist-cli/` for the command;
-- the desktop app: inside the application;
+- the desktop app: inside the application, beside the licences of Electron and Chromium that every installer ships;
 - the standalone HTML page: in a comment at the end of the file.
 
-The upstream texts that are not in an npm package are kept under [`licenses/`](licenses/).
+The upstream texts that are not in an npm package are kept under [`licenses/`](licenses/), and so is the MIT licence `generic-filehandle2` declares but does not ship.
 
 **Trademarks.** The logos on the data store tiles (IGV, 4DN, ENCODE, DNA Zoo, UCSC and Roadmap Epigenomics) are those projects' own published marks, and the GitHub, Google Drive and Dropbox marks in the interface are their owners' trademarks. Each is shown only to name the store or service it stands for. None of them is covered by chromosomix's licence or by the notices above, and their use implies no endorsement of chromosomix by their owners.