# chromosomix

[![Web app](https://img.shields.io/badge/web%20app-chromosomix.app-1f6feb)](https://chromosomix.app/)
[![Documentation](https://img.shields.io/badge/docs-doc.chromosomix.app-1f6feb)](https://doc.chromosomix.app/)
[![Tests](https://github.com/js2264/chromosomix/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/js2264/chromosomix/actions/workflows/test.yml)
[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fchromosomix.app%2Fcoverage%2Fbadge.json)](https://chromosomix.app/coverage/)
[![Deploy](https://github.com/js2264/chromosomix/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/js2264/chromosomix/actions/workflows/deploy.yml)
[![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: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)](https://github.com/js2264/chromosomix/blob/main/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.

chromosomix launches in about a second and reads your data where it lives, on your own disk or in the cloud. No server, no preprocessing, no installation, no account, and it works offline. Most formats open as they are: `.*cool`, `.hic`, HiC-Pro, `.pairs`, bigWig, BED, BAM, FASTA/`.2bit`, 3D structures and more.

<p align="center">
  <img src="https://raw.githubusercontent.com/js2264/chromosomix/main/docs/screenshot.png" alt="chromosomix: a yeast micro-C contact map with its loop calls, beside sequence, gene, ATAC and Pol II tracks" width="100%">
</p>

## Main features 

- 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. A `.pairs` is binned on import, and the same pass counts what `pairtools stats` counts — mapped, duplicates, cis and trans, pair types, strand convergence, library size — shown in the General panel and saved as a `.stats` file MultiQC reads. 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. 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, ...
  - 2D analysis tasks: a QC map report (one HTML page, and MultiQC sections from the CLI), P(s) (and its four pair orientations), scalogram, diamond insulation, directionality index, HiC score, TAD annotation (Juicer's Arrowhead), coverage, cis/trans per chromosome, virtual 4C, compartments annotation and saddle plot, the alignment of a bacterial chromosome's two arms, loops and borders detection, APA, loop ranking, ...
  - 3D analysis tasks: build a 3D model from the contact map (pastis-NB or ShRec3D), compare a 3D model with the contact map, and turn a 3D model into tracks.

- 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.

- 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, ...
  - Annotations panel, supporting linear tracks, 1D and 2D manual annotations, bookmarks and synthetic annotations.
  - Analysis panel: runs the analyses above on what is on screen, with exportable results.

- Virtual file system: The browser runs entirely in the client, with no server-side processing or data upload. It uses a virtual file system to access local files, remote files, and cloud storage: 
  - 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.

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.

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

### Use it from a web browser

Go to [`chromosomix.app`](https://chromosomix.app/) to open the viewer in a web browser. The app runs entirely in the browser, with no server-side processing or data upload.

### Install as a PWA (Progressive Web App)

Go to [`chromosomix.app`](https://chromosomix.app/) and: 

- On **Chrome** or **Edge**: click on the **Install** in the URL bar (far right button). 
- On **Safari**: click on **Share → Add to Dock**.
- On **Firefox**: support to be added soon. 

The app is then available offline as a desktop app as a PWA (Progressive Web App).

### Install as a desktop app

To install the app as a desktop app, you can fetch the latest release from [https://github.com/js2264/chromosomix/releases](https://github.com/js2264/chromosomix/releases). Builds are available for macOS (`.dmg`, Intel and Apple silicon) and Linux (`AppImage`, `.deb`); the Windows installer is temporarily not built, and on Windows the static HTML page below needs no installer at all. The app is then available offline as a desktop app.

### From a static HTML file

Every release produces a single `index.html` (about 14 MB). It has
no server and no install: put it on a USB stick, email it, open it by
double-clicking and you end up with a fully functional genome browser.

It is attached to every [release](https://github.com/js2264/chromosomix/releases)
as `chromosomix-<tag>.html`, and `npm run build:standalone` builds it from a clone.

### For AI agents

The site describes itself to language models at <https://chromosomix.app/llms.txt>, in the shape
[llmstxt.org](https://llmstxt.org/) gives one, with reference pages generated from the app itself:
how to write a link to a view, every analysis task with every parameter, the embed protocol, and the
file, store and workspace formats. <https://chromosomix.app/llms-full.txt> is all of it, and this
README, in one file.

## Embedding chromosomix in a page

A minimal version of the viewer can be added to any HTML page as an `<iframe>`. Nothing needs to be installed. There is no extra package dependency and no modifications to make to the page's header, just drop the `<iframe>` in. The `src` attribute is the URL of the viewer, with a query string that tells it what to show.

```html
<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"
  loading="lazy"
  style="border: 0"
  title="Mitotic micro-C of synthetic yeast, IV:1.0–1.4 Mb"
></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 page holding the frame can drive it too: `postMessage` moves the view, adds tracks beside the map, and is told where the reader has taken it (SPECS §21.4).

## In a Jupyter notebook

The same viewer is a Jupyter widget: the app itself in a cell, driven from Python and telling Python where the reader has taken it. It works in JupyterLab, Notebook 7, VS Code, Colab and marimo.

```bash
pip install "git+https://github.com/js2264/chromosomix#subdirectory=widgets/python"
```

It is not on PyPI: pip installs it from this repository (git must be on the machine), and from a clone
`pip install -e widgets/python` does.

```python
from chromosomix import Chromosomix

view = Chromosomix(
    'sample.mcool::/resolutions/5000',      # a path on the kernel's disk, or any address the app opens
    region='chr2:10000000-14000000',
    tracks=['ATAC.bw', 'genes.gtf.gz'],
    transform='log10',
)
view                                        # the map, its tracks, its side panels

view.goto('chr2:11000000-12000000')         # frame a region (or a locus, in the 1D browser)
view.navigate(transform='log2', oe=True)    # any key the address bar carries
view.add('model.g3d.gz')                    # the header's +: a track, a map, a 3D model beside the map
view.observe(lambda change: print(change['new']['region']), names='state')
```

Files on the kernel's disk are served to the viewer by byte range from a server on `127.0.0.1`, with their sidecars beside them; nothing is uploaded. [`widgets/python/demo.ipynb`](https://github.com/js2264/chromosomix/blob/main/widgets/python/demo.ipynb) walks through it on the yeast demo, and [`widgets/python/README.md`](https://github.com/js2264/chromosomix/blob/main/widgets/python/README.md) says which viewer build the frame holds and how to pin one.

## In R: R Markdown, Quarto, RStudio and Shiny

The same viewer is an htmlwidget, in the R package under [`widgets/r`](https://github.com/js2264/chromosomix/blob/main/widgets/r/README.md):

```r
remotes::install_github("js2264/chromosomix", subdir = "widgets/r")
# or, from a clone: install.packages("widgets/r", repos = NULL, type = "source")

library(chromosomix)
chromosomix("sample.mcool::/resolutions/5000", region = "chr2:10000000-14000000",
            tracks = c("ATAC.bw", "genes.gtf.gz"), transform = "log10") |>
  chromosomix_goto("chr2:11000000-12000000") |>
  chromosomix_navigate(oe = TRUE) |>
  chromosomix_add("model.g3d.gz")
```

In Shiny, `chromosomixOutput()`, `renderChromosomix()` and `chromosomixProxy()` drive a view on screen,
and `input$<id>_state` follows the reader. `system.file("examples", package = "chromosomix")` holds an
R Markdown page of the yeast demo and a Shiny app driving it.

## Using the chromosomix analysis CLI

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

The CLI is published to npm with every release. It needs Node 22.12 or later on the machine:

```bash
node --version
```

Then install the `chromosomix` command globally, at the latest release:

```bash
npm install -g chromosomix
```

To pin a release instead, which is what a pipeline or a methods section should do, name its version; `npx` runs a given version without installing anything:

```bash
npm install -g chromosomix@<version>
npx chromosomix@<version> insulation sample.cool --window 10 --out results/
```

`chromosomix --version` prints the version on its first line, then the Node it runs on and the versions of the two libraries that read every map and track, `h5wasm` and `@gmod/bbi`, as they are installed.

To run the CLI from a clone instead, for example to try a change before it is released:

```bash
git clone https://github.com/js2264/chromosomix
cd chromosomix
npm install
npm run build:cli && npm link
```

### Running tasks

Once it is installed, run the following command to see the available tasks and their parameters
(`chromosomix tasks --json` prints the same as one JSON document, with every value a choice takes,
for a script or an agent):

```bash
chromosomix tasks

## coverage
##     Coverage and marginals
##       --total (default true)  total coverage
##       --fraction (default false)  cis fraction
##       --cis (default false)  cis coverage
##       --trans (default false)  trans coverage
##       --balance (default false)  use balancing weights
## 
## cistrans
##     Cis and trans per sequence
##       --sequences  sequences
##       --bars (default "cis")  bars per sequence
##       --normalise (default "enrichment")  off-diagonal value
##       --minContacts (default 10)  least contact worth listing
##       --maxEdges (default 500)  pairs to list
##       --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
##       --sequences  sequences
##       --quantity (default "density")  quantity
##       --factor (default 1.1)  log bins per step
##       --minSeparation (default 2)  minimum separation
##       --derivative (default true)  log-log slope
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## pairsqc
##     Pairs QC
##       --pairs  .pairs file
##       --reference  reference
##       --enzyme (default "none")  enzyme
##       --sites (default "")  sites
## 
## mapreport
##     Map report
##       --base (default "finest")  ladder from
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## scalogram
##     Scalogram
##       --quantiles (default "standard")  quantiles
##       --reach (default 0)  look out to
##       --sequences  sequences
##       --ignoreDiags (default 1)  diagonals to ignore
##       --minValid (default 0.5)  minimum coverage of the distribution
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## fourc
##     4C profile from an anchor
##       --anchor  anchor
##       --normalise (default "none")  normalisation
##       --cis (default true)  cis only
##       --excludeAnchor (default false)  exclude anchor region
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## insulation
##     Diamond insulation
##       --window (default 10)  window
##       --scales (default 1)  scales
##       --sequences  sequences
##       --ignoreDiags (default 2)  diagonals to ignore
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
##       --call (default true)  call boundaries
##       --prominence (default 0.2)  minimum prominence
##       --minValid (default 0.5)  diamond coverage to call
##       --spacing (default 0)  minimum spacing
##       --domains (default true)  domains between them
## 
## di
##     Directionality index
##       --window (default 50)  window
##       --sequences  sequences
##       --ignoreDiags (default 0)  diagonals to ignore
##       --minValid (default 0.5)  minimum coverage of each side
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
##       --call (default true)  call borders
##       --prominence (default 10)  minimum prominence
##       --spacing (default 0)  minimum spacing
##       --domains (default true)  domains between them
## 
## hicscore
##     HiC score
##       --diagonals (default 3)  diagonals
##       --sequences  sequences
##       --ignoreDiags (default 0)  diagonals to ignore
##       --minValid (default 0.5)  minimum coverage of the line
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## arrowhead
##     TAD annotation
##       --sequences  sequences
##       --matrixSize (default 2000)  window
##       --minBlockSize (default 60)  smallest lenient domain
##       --varThreshold (default 0.2)  variance at most
##       --highSignThreshold (default 0.5)  sign agreement at least
##       --maxLowSignThreshold (default 0.4)  sign agreement from
##       --minLowSignThreshold (default 0)  down to
##       --decrementLowSignThreshold (default 0.1)  in steps of
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## compartments
##     Compartments
##       --sequences  sequences
##       --contacts (default "cis")  contacts
##       --ignoreDiags (default 2)  diagonals to ignore
##       --expected (default "distance")  expected
##       --armWindow (default 50)  window along the arms
##       --method (default "cooltools")  method
##       --components (default 1)  components
##       --phaseFeatures  phase by gene density
##       --phaseTrack  phase by a track
##       --phaseSequence  phase by GC content
##       --minR (default 0.1)  least convincing correlation
##       --saddle (default true)  draw the saddle
##       --quantiles (default 50)  quantile groups
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## interarm
##     Inter-arm alignment
##       --sequences  sequences
##       --band (default 2)  band
##       --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
##       --sequences  sequences
##       --thresholds (default "preset")  thresholds
##       --pearson (default 0.3)  score threshold
##       --minDist (default 10)  nearest to the diagonal
##       --maxDist (default 1000)  furthest from the diagonal
##       --minSeparation (default 3)  nearest two calls may be
##       --iterations (default 1)  refinement passes
##       --maxPercUndetected (default 50)  most undetectable pixels a window may hold
##       --maxPercZero (default 10)  most empty pixels a window may hold
##       --nMads (default 5)  detectability cut
##       --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
##       --pairs  pairs
##       --features  features
##       --mode (default "fixed")  mode
##       --at (default "centre")  anchor on
##       --window (default 21)  half-width
##       --grid (default 51)  grid
##       --flankFraction (default 0.5)  flank
##       --minDiag (default 2)  diagonals left out
##       --norm (default "oe")  normalisation
##       --csPattern (default "loops")  template
##       --controls (default 5)  controls per pair
##       --minShift (default 50)  smallest shift
##       --maxShift (default 500)  largest shift
##       --minShiftScale (default 1)  smallest shift
##       --maxShiftScale (default 3)  largest shift
##       --seed (default 1)  seed
##       --minDist (default 5)  nearest loop
##       --minSep (default 2)  nearest two features may be
##       --maxSep (default 200)  furthest two features may be
##       --byDistance (default 0)  split by separation into
##       --rankBy  rank by
##       --subset (default "all")  then
##       --count (default 500)  N
##       --groups (default 4)  groups
##       --tracks  track aggregates
##       --symmetric (default true)  same profile both sides
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## reconstruct3d
##     Model from the map
##       --method (default "nb")  method
##       --region  sequences
##       --alpha (default 3)  exponent α
##       --weights (default "contacts")  weight pairs by
##       --seed (default 0)  seed
##       --iterations (default 150)  refinement steps
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## structuremap
##     Model versus map
##       --structure  structure
##       --region  sequences
##       --alpha (default 3)  exponent α
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
## 
## spatialtracks
##     Spatial tracks
##       --structure  structure
##       --locus  distance to
##       --window (default 5)  compaction window
## 
## motif
##     Find a motif
##       --sequence  reference
##       --sequences  sequences
##       --pattern  motif
##       --bothStrands (default true)  both strands
##       --mismatches (default 0)  mismatches
##       --limit (default 500000)  most sites
## 
## restriction
##     Restriction sites
##       --sequence  reference
##       --sequences  sequences
##       --enzyme (default "none")  enzyme
##       --sites (default "")  sites
## 
## peaks
##     Peak calling
##       --signal  track
##       --replicate  replicate
##       --idr (default "0.05")  IDR threshold
##       --sequences  sequences
##       --perPeak (default false)  list every peak
##       --width (default 150)  smoothing window
##       --times (default 3)  smoothing passes
##       --minWidth (default 75)  narrowest peak
##       --halfWidth (default 0)  fixed half-width
##       --truncate (default 100000)  keep the strongest
## 
## composition
##     Base composition
##       --sequence  reference
##       --resolution (default 10000)  bin size
##       --window (default 0)  window
##       --gc (default true)  GC content
##       --gcSkew (default true)  GC skew
##       --atSkew (default true)  AT skew
##       --cumulative (default true)  cumulative GC skew
## 
## oriter
##     Origin and terminus
##       --sequence  reference
##       --sequences  sequences
##       --coverage  coverage
##       --window (default 5000)  skew window
##       --step (default 1000)  skew step
##       --parS (default "TGTTNCACGTGNAACA")  parS motif
##       --parSMismatches (default 1)  parS mismatches
##       --matS (default "GTGACRNYGTCAC")  matS motif
##       --matSMismatches (default 0)  matS mismatches
##       --knots (default 10)  spline knots
## 
## metaplot
##     Metaplot over a feature set
##       --tracks  tracks
##       --features  features
##       --mode (default "reference")  mode
##       --at (default "start")  anchor on
##       --flank (default 2000)  flank
##       --step (default 50)  resolution
##       --body (default 100)  body columns
##       --stranded (default true)  respect strand
##       --rankBy  rank by
##       --subset (default "all")  then
##       --count (default 500)  N
##       --groups (default 4)  groups
##       --zscore (default false)  z-score tracks first
##       --average (default "mean")  average
##       --band (default "bootstrap")  band
##       --iterations (default 200)  bootstrap draws
##       --seed (default 1)  seed
##       --heatmap (default true)  per-feature heatmap
## 
## trackcorr
##     Track correlation
##       --tracks  tracks
##       --over (default "bins")  compare over
##       --binsize (default 100)  window
##       --features  features
##       --method (default "spearman")  method
## 
## frip
##     Fraction of signal in features
##       --tracks  tracks
##       --features  features
##       --resolution (default 0)  read features at
##       --perFeature (default false)  score every feature
## 
## groupsignal
##     Signal by group
##       --tracks  tracks
##       --groupBy (default "features")  groups from
##       --features  features
##       --split (default "name")  split the set by
##       --outside (default true)  the rest as a group
##       --groupTrack  grouping track
##       --cut (default "sign")  cut it by
##       --quantiles (default 4)  quantiles
##       --resolution (default 0)  bin size
##       --perFeature (default false)  score every feature
## 
## overlap
##     Interval set overlap
##       --a  first set
##       --b  second set
##       --minFraction (default 0.000001)  least of a feature covered
##       --shuffle (default false)  shuffled null
##       --shuffleWhich (default "a")  set that moves
##       --iterations (default 1000)  shuffles
##       --seed (default 1)  seed
## 
## dotplot
##     Two sequences against each other
##       --x  along x
##       --y  along y
##       --streaks (default "one to one")  streaks
##       --cells (default 400)  cells
## 
## magqc
##     MAG contact QC
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
##       --network (default true)  inter-MAG matrix
## 
## magnetwork
##     Inter-MAG network
##       --normalise (default "coverage")  edge weight
##       --minWeight (default 0)  least edge worth listing
##       --maxEdges (default 500)  edges to list
## 
## magpurity
##     MAG purity and contamination
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
##       --minContacts (default 10)  least contact before judging a contig
##       --flagAbove (default 0.5)  flag above this outside fraction
## 
## magsplit
##     Split-MAG detection
##       --no-balance  read the raw counts (balanced by default where the file carries weights)
##       --minContigs (default 4)  least contigs before judging a MAG
##       --flagBelow (default 0.1)  flag below this cross-block ratio
```

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/>, 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/>; and how long a map and a track take to draw beside
juicebox.js and HiGlass, on the same files, <https://chromosomix.app/viewers/>. A fourth notebook holds
the app to this command: ten
tasks run in the app, in headless Chromium, Firefox and WebKit, then from the line its console wrote
for each, and every file the two wrote compared, <https://chromosomix.app/parity/>. And what the commands cost on a machine
like yours — the time and the peak memory of 23 analyses run genome-wide, up to a 1.08-billion-contact
human map — is <https://chromosomix.app/laptop/>, rendered on a laptop and committed as
`notebooks/laptop.html`; render `notebooks/laptop.qmd` from a clone to measure your own —
`micromamba run -n open2c quarto render notebooks/laptop.qmd`, in the environment
`notebooks/environment-laptop.yml` makes — and it downloads the data, runs each analysis once and
tabulates them. The app lists all five in
**About → Notebooks**, each with the one line of what it found.

Every task writes its results where `--out` points, each named after the file it came from up to
its first dot — `sample.coverage.coverage-total.tsv`. Two files of one command that would share a
name keep more of theirs (`HCT116.rep1`, `HCT116.rep2`), then their directories (`dirA_sample`,
`dirB_sample`), and nothing one command writes is written over by it. A map is read balanced
wherever the file carries balancing weights, as the app reads it; `--no-balance` reads the raw
counts. A locus — `--window`, or a task's own, such as 4C's `--anchor` — is written as the app
writes one: 1-based and inclusive, digits grouped or not. A parameter that is on or off takes no
value after it: `--stranded` turns it on, `--stranded=false` or `--no-stranded` off. A choice that
is none of its values is refused before any file is opened, with exit 2 and the values there are,
and so is a number that is not one.

Files are read from disk or from where they are published. A map named by an http or https address —
a cooler, an `.mcool` rung, a `.hic`, an `.scool` or a `.pairs`, as the positional or after
`--against` — and a bigWig, a `.2bit` or an indexed FASTA after `--tracks` or `--sequence` is read
**by range**, as the app reads it: one rung of a seven-gigabyte `.mcool` costs that rung, and nothing
is written to disk; a bedGraph or a wig after `--tracks` is read in one request. What is read whole
from a copy — a `--features` or `--pairs` set, a HiC-Pro matrix, a workspace — and any file whose host
will not serve a range is downloaded into `$TMPDIR` instead, with its progress on stderr, and removed
when the command ends.

```bash
chromosomix insulation *.mcool --sequences II --out results/
chromosomix chromosight sample.cool --pattern borders --out results/
chromosomix apa sample.cool --pairs loops.bedpe --norm chromosight

# A 4C profile from an anchor, written as the breadcrumb or IGV writes a locus:
# 1-based and inclusive, so the window you copied is the window that is read.
chromosomix fourc sample.cool --anchor IV:1,200,001-1,210,000 --out results/

# The domain pileup: a set of TADs — the span from one insulation boundary to
# the next — every one of them stretched to the same width, with half a domain
# of padding each side, over its distance-matched control rather than over the
# expected. The control is shifted by a multiple of the window, so it never
# overlaps the domain it is the denominator of.
chromosomix apa sample.cool --features domains.bed --anchors features \
  --mode scaled --grid 48 --flankFraction 0.5 --norm matched --out results/

# Two of the tasks that run beside the tracks rather than on the map. A motif
# search reads the reference `--sequence` names and writes both halves: the
# sites as a BED-shaped table, and their density on the open map's bin grid.
chromosomix motif sample.cool --sequence ref.fa.gz --pattern GGTCANNNTGACC --mismatches 1 --out results/
chromosomix overlap sample.cool --features peaks.bed --features boundaries.bed --a peaks.bed --b boundaries.bed

# A library's quality from its contact list: the pairtools counts as figures,
# the four orientations' P(s), and — with a reference and an enzyme — pair
# classes, distance to the cut, fragments seen and coverage against sites.
# Restriction sites alone digests the reference into a lane of cuts.
chromosomix pairsqc sample.pairs.gz --bin-size 10000 --sequence ref.fa.gz --enzyme DpnII --out qc/
chromosomix restriction sample.cool --sequence ref.fa.gz --enzyme Arima --out results/

# The tasks that read tracks take them as --tracks: a bigWig, a bedGraph, a
# wig, or a FASTA read as GC content. Repeat the flag or separate with commas.
chromosomix metaplot sample.cool --tracks ATAC.bw --features peaks.narrowPeak --flank 2000 --out results/
chromosomix frip sample.cool --tracks ATAC.bw,MNase.bw --features peaks.narrowPeak
chromosomix trackcorr sample.cool --tracks ATAC.bw --tracks MNase.bw --over features --features peaks.bed

# ...and with no contact map at all, over the assembly the tracks declare —
# what a 1D browser session runs. Peak calling names its track --signal (and a
# second one --replicate, for IDR); base composition reads a reference.
chromosomix metaplot --tracks ATAC.bw --features peaks.narrowPeak --out results/
chromosomix peaks --signal ChIP.bw --out results/
chromosomix composition --sequence ref.fa.gz --out results/

# Compartments phased by GC content read the reference under --sequence.
chromosomix compartments sample.cool --sequence ref.fa.gz --phaseSequence ref.fa.gz

# Maps drawn to one number of contacts before the task reads them: an exact
# subsample below the file's own total, Boost-HiC above it, with the app's seed.
chromosomix insulation rep1.cool --contacts 10M --out results/
# The map that oversample draws each chromosome's new contacts from, written as
# Boost-HiC's own main.py writes it: one square TSV per sequence.
chromosomix boost rep1.mcool::/resolutions/100000 --sequences chr19 --out results/

# A resolution the file does not store, as the app reads one you added (3 kb*):
# the 1 kb bins summed three at a time, counts exactly, weights by their
# harmonic mean.
chromosomix insulation sample.mcool::resolutions/1000 --coarsen 3000 --out results/

# A bacterial chromosome: which sequences join their own ends (the test the app
# runs on a first open), then the alignment of its two arms about its origin.
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,
# 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
# .metacool is drawn from and the sequences declared circular. The console
# writes them whenever they differ from the defaults (count, none).
chromosomix insulation sample.metacool --value balanced_by_depth --circular pCEN,p2u

# A .pairs is binned first, at a resolution you name — the shell's answer to
# the browser's dialog. `--pairs` above is a BEDPE of features; the contact
# list is the positional argument.
chromosomix coverage Hum53.pairs.gz --bin-size 5000 --rungs 4

chromosomix replay workspace.chromosomix.json --over data/*.hic

# What `pairtools stats` writes for a contact list, counted by the pass the
# app's import makes, in pairtools' own format — for MultiQC.
chromosomix stats sample.pairs.gz --out qc/
```

### Recovering the commands you ran

You do not have to write those lines from memory. The browser app has a **console** and every analysis run lands in it as the `chromosomix` command that repeats it, written the moment the run happens rather than when you look at the result. 

The log is kept in your own browser for seven days or five hundred lines, whichever comes first. Nothing is uploaded; it is listed under *What this browser is remembering* (in the command palette, `Ctrl+P` → Help) with everything else this app keeps, and *forget everything* drops it.

## Contributing

Bug reports, fixes, file formats and analyses are welcome: [`CONTRIBUTING.md`](https://github.com/js2264/chromosomix/blob/main/CONTRIBUTING.md) says how to
build and test it and what a pull request carries, and
[Adding a reader or a task](https://doc.chromosomix.app/contributing/readers-and-tasks/) where a new
format or analysis goes. Taking part follows the [code of conduct](https://github.com/js2264/chromosomix/blob/main/CODE_OF_CONDUCT.md); a security problem
is reported privately, as [`SECURITY.md`](https://github.com/js2264/chromosomix/blob/main/SECURITY.md) says.

## Licence

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`](https://github.com/js2264/chromosomix/blob/main/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).

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, 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/`](https://github.com/js2264/chromosomix/blob/main/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.

---

# chromosomix links: a view as a URL

> Every view in chromosomix is a URL, and a link is the simplest way to show somebody a file at a place: no install, no upload, no account at either end. This page is the grammar — the keys of the fragment and the values each takes, the two forms of a coordinate, and the query parameters that mount the app differently. A link written to it opens in the web app, in a pinned release, in an embed and in the notebook widgets alike.

## The shape

```
https://chromosomix.app/[?<query>]#<key>=<value>&<key>=<value>…
```

- The view is in the fragment, after `#`: `key=value` pairs joined by `&`. Each value is percent-encoded as `encodeURIComponent` does it; `/`, `:`, `,` and `|` may be left as they are, `&` and `=` may not.
- `uri` is required. A fragment without one is ignored and the app opens on its landing page.
- Keys are case-sensitive, and the app drops what it cannot read rather than refusing the link: a `view` it does not know opens the file’s table, and a `transform`, a `smooth` or a `vmin` it cannot read is left out. A misspelt key therefore does nothing at all — check each against the table below.
- The fragment is never sent to a server. The reader’s browser reads the file, from where it is, by HTTP range requests; nothing is uploaded.
- A link can only name a file the reader can reach: a public address, or one their own browser holds credentials for. A file on the sender’s disk cannot be linked to.

## Coordinates

A locus has two written forms, and the keys do not share one:

- **Machine form**, for `region`, `region2` and `focus`: cooler’s, 0-based and half-open, with no separators — `IV:1000000-1400000` is shown in the app as `IV:1,000,001-1,400,000`. A sequence name alone is the whole sequence.
- **Display form**, for `locus`: 1-based and inclusive, as the app, IGV and UCSC print it — `IV:1,000,001-1,400,000`, digits grouped or not.
- Write a sequence name as the file spells it: `chr4` for a file that says `chr4`, `4` for one that says `4`.

The command line takes the display form everywhere (`--window`, `--anchor`): see the [command line](https://chromosomix.app/llms/cli.md).

## The keys of the fragment

| Key | Values | What it does |
|---|---|---|
| `uri` | an address | **Required.** The file: a contact map (`.cool`, `.mcool`, `.hic`, `.scool`), or a reference or track (a FASTA, a `.2bit`, a bigWig…), which opens the 1D browser over its assembly. `https://`, `s3://`, `gs://` and Dropbox or Google Drive share links all work. For one resolution of a multi-resolution file, append `::/resolutions/<bin size>`: `sample.mcool::/resolutions/10000`. |
| `uri2` | an address | A second map on the same bins, drawn in the lower triangle of the same square. `op` says how the two are put together. |
| `maps` | addresses joined by `\|` | More cells beside the first map, as a deck panned and zoomed together. A member is a map’s address, `3d` for the session’s 3D model, `tracks` for its tracks on their own, or `~` for a local file that a link cannot carry. |
| `view` | `contigs`, `whole`, `region`, `selection`, `browser` or `cells` | What is shown (see the table below). A value it does not know opens the file’s table. |
| `region` | `<sequence>` or `<sequence>:<start>-<end>`, machine form | The block a `region` view reads: its rows, and its columns too unless `region2` is given. |
| `region2` | as `region` | The columns of an off-diagonal block: the contacts between `region` and this. |
| `focus` | `<sequence>:<start>-<end>`, machine form | A window inside `region` that the map opens zoomed to, with the rest of the block still there to pan into. Applied once, on opening; it does not follow the reader. |
| `regions` | sequence names joined by `,` | The sequences of a `selection` view. |
| `cells` | cell names joined by `,`, or `*` | The cells of an `.scool` summed into the map, in file order; `*` is every cell, the default. |
| `contacts` | a whole number | Every map drawn to this many contacts before it is shown or analysed: an exact subsample below the file’s own total, an oversample through Boost-HiC above it, with a fixed seed. |
| `locus` | `<sequence>:<start>-<end>`, display form | The window of the 1D browser (`view=browser`). Absent is the whole genome. |
| `level` | `bin` or `contig` | What one row of the matrix is: a bin (the default), or a whole sequence summed into one cell. |
| `coarsen` | a bin size in bp | A resolution the file does not store, a whole multiple of the one `uri` names: the stored bins are summed as they are read. A value the file cannot reach is ignored. |
| `transform` | `log1p`, `log10`, `log2` or `none` | How values are mapped to colour. |
| `colormap` | `default`, `afmhot_r`, `afmhot`, `Reds`, `cividis`, `viridis`, `magma`, `RdBu_r`, `BuWtRd` or `seismic` | `RdBu_r`, `BuWtRd` and `seismic` are diverging, for a ratio or an observed over expected. |
| `vmin` | a number | The bottom of the colour scale, in transformed units (`-1` under `log10` is 0.1). Absent is automatic. Not applied to a ratio — `oe`, or `op=ratio` or `difference` — whose scale opens centred on no change. |
| `vmax` | a number | The top of the colour scale, in transformed units. Absent is automatic; the two are independent. |
| `balance` | `true` or `false` | Balanced values, with the weights the file carries, or raw counts. |
| `score` | `count`, `balanced`, `vc`, `vcsqrt`, `ice`, `baseline` or `correlation`, or a column of the file | What each cell is drawn from: the raw counts, the balanced counts, a normalisation computed on the fly (VC, square-root VC, ICE), the expected count at that distance, the Pearson correlation of the observed over expected (on a balanced file), or another column of the file’s pixel table. Overrides `balance`. A value the file cannot answer falls back to the counts. |
| `oe` | `true` or `false` | Observed over expected: each cell divided by what its distance from the diagonal predicts. |
| `arms` | a whole number of bins, `0` for all | With `oe=true`, on a circular bacterial chromosome whose origin is set: the expected is read along both arms, within this many bins, rather than along the diagonal alone. |
| `smooth` | `0`, `1`, `2`, `3` or `a50` | Despeckling: `0` is off, a number is a fixed radius (`1` is 3 × 3), `a50` grows a window per cell until it holds enough contacts. |
| `op` | `split`, `ratio` or `difference` | With `uri2`: the two files on either side of the diagonal (`split`), or one derived map over the whole square, their `ratio` or their `difference`. |
| `flip` | `true` or `false` | Turn a map of one sequence 45°: position along the bottom, distance from the diagonal up the side. |
| `lower` | `true` or `false` | Draw the lower triangle in a reading of its own, set by the six keys below; ignored with `uri2` or `maps`. |
| `score2` | as `score` | The lower triangle’s `score`. |
| `oe2` | as `oe` | The lower triangle’s `oe`. |
| `smooth2` | as `smooth` | The lower triangle’s `smooth`. |
| `transform2` | as `transform` | The lower triangle’s `transform`. |
| `colormap2` | as `colormap` | The lower triangle’s `colormap`. |
| `vmin2` | a number | The lower triangle’s `vmin`. |
| `vmax2` | a number | The lower triangle’s `vmax`. |

### Views

| `view` | What it opens |
|---|---|
| `contigs` | the table of the file’s sequences, with their lengths and contacts |
| `whole` | the whole matrix, every sequence against every other. It reads the whole file, so it opens on a button that says what that costs, and draws once the reader presses it |
| `region` | a block of the map, named by `region` (and `region2` for an off-diagonal one) |
| `selection` | several sequences side by side, named by `regions` |
| `browser` | the 1D genome browser over the file’s assembly, at `locus` |
| `cells` | the table of an `.scool`’s cells, to pick the ones summed into the map |

## Examples

Micro-C of synthetic yeast chromosome IV, and its tracks, from the public demo bucket:

A window of chromosome IV, balanced, on a log scale:

    https://chromosomix.app/#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

The same window as observed over expected, on a diverging colour map:

    https://chromosomix.app/#uri=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_microC_G2M_1kb.cool&view=region&region=IV:1000000-1400000&balance=true&oe=true&transform=log2&colormap=RdBu_r

The same window, its colour scale clipped to 10⁻³–10⁻¹·⁵:

    https://chromosomix.app/#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&vmin=-3&vmax=-1.5

All of chromosome IV read, opened zoomed to 100 kb of it:

    https://chromosomix.app/#uri=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_microC_G2M_1kb.cool&view=region&region=IV&focus=IV:1150000-1250000&transform=log10&balance=true

The whole genome, every chromosome against every other — once the reader agrees to read it all:

    https://chromosomix.app/#uri=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_microC_G2M_1kb.cool&view=whole&transform=log10&balance=true

The contacts between two chromosomes:

    https://chromosomix.app/#uri=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_microC_G2M_1kb.cool&view=region&region=IV&region2=XII&transform=log10&balance=true

The 1D browser over an ATAC-seq bigWig, at a locus:

    https://chromosomix.app/#uri=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_ATAC.bw&view=browser&locus=IV:1,150,001-1,250,000

## The query: how the app is mounted

The query string, before the `#`, changes what the page around the view is rather than what it shows:

| Parameter | What it does |
|---|---|
| `embed=1` | The bare view, for an `<iframe>`: no header, no tabs, the side panels folded. See [embedding](https://chromosomix.app/llms/embed.md). |
| `config=<URL>` | Opens a saved workspace — a `.chromosomix.json`, every tab with its tracks, colours and marks — instead of one file. Names inside it resolve against its own URL. See [files and workspaces](https://chromosomix.app/llms/data.md). |
| `store=<id or URL>` | Opens a data store’s catalogue over the page: a built-in one by its id, or a store file or a UCSC `hub.txt` by its address. `q=<text>` searches it, `<column>=<value>` ticks a facet, and `view=matrix&axes=<a>,<b>` shows it as a matrix of two columns. |
| `panels=open` | With `embed=1`: the frame opens with its Annotations and Aesthetics panels unfolded rather than folded. `panels=annotations` or `panels=aesthetics` opens one. |

Examples:

    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
    https://chromosomix.app/?config=https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/store/yeast/Yeast_microC.chromosomix.json
    https://chromosomix.app/?store=4dn&q=HCT116

## A link that never changes

The root, https://chromosomix.app/, is the newest build, and changes with it. Every release is also kept for good at its own address, `https://chromosomix.app/v/<tag>/` — `https://chromosomix.app/v/v0.13.0/`, say — which takes the same query and fragment. A link in a paper, a figure legend or a notebook that must draw the same picture in five years should name one.

## Writing a link from code

Build the fragment from an object, encoding each value; this is what the app itself does:

```js
const view = { uri: "https://example.org/sample.mcool::/resolutions/10000",
               view: "region", region: "chr2:10000000-14000000", transform: "log10", balance: true }
const hash = Object.entries(view)
  .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`)
  .join("&")
const link = "https://chromosomix.app/#" + hash
```

---

# chromosomix command line

> `chromosomix` runs the analyses of the app’s Analysis panel from a shell — insulation, compartments, loops, APA, P(s), virtual 4C, peaks, metaplots and two dozen more — with the same parameters and the same results as a run in the browser, for scripts and pipelines. It reads `.cool`, `.mcool`, `.hic`, `.scool`, HiC-Pro and `.pairs` maps, and bigWig, BED-like and FASTA files, from disk or by address, and writes TSV, BED, bedGraph and bigWig.

## Install

```sh
node --version                 # 22.12 or later
npm install -g chromosomix     # the latest release
npx chromosomix@<version> …    # a pinned release, with nothing installed
chromosomix --version          # the build on its first line, then Node, h5wasm and @gmod/bbi
```

A pipeline or a methods section should pin a version. From a clone: `npm install`, then `npm run build:cli && npm link`.

## Finding a task and its parameters

```sh
chromosomix tasks          # every task, its flags and their defaults
chromosomix tasks --json   # the same, with every value a choice takes, every range and unit
chromosomix --help         # the usage below
```

Every task, with every parameter, is also on [the task page](https://chromosomix.app/llms/tasks.md). The shape of a command:

```sh
chromosomix <task> <map> [<map> …] [--<parameter> <value> …] --out <dir>
```

- **One task, one or more maps.** Each map is run on its own and its outputs are named after it, up to its first dot: `sample.coverage.coverage-total.tsv`. Two that would share a name keep more of theirs, and nothing one command writes is written over by it.
- **A map** is a path or an `http(s)` address. An `.mcool` names one resolution — `sample.mcool::/resolutions/10000` — and one named bare is refused with the list of the resolutions it has. A `.pairs` is binned first and needs `--bin-size <bp>`.
- **Balanced by default.** A map is read balanced wherever the file carries weights, as the app reads it; `--no-balance` reads the raw counts.
- **A locus is the display form**: 1-based and inclusive, digits grouped or not — `--window IV:1,000,001-1,400,000` — as the app, IGV and samtools write one.
- **Remote files are read by range** where they can be: one rung of a 7 GB `.mcool` costs that rung. What has to be read whole — a feature file, a workspace, a host that serves no ranges — is fetched into `$TMPDIR` and removed when the command ends.
- **Every output records its provenance**: each TSV opens with `#` lines naming the build, the file and every parameter, so `head` says how a number was made.

## Exit status

- `0`: every file ran.
- `1`: at least one file failed; the others still ran, and stderr says which and why.
- `2`: the command was refused before any file was opened — an unknown task or flag, a choice that is none of its values, a number that is not one, a missing input. The sentence on stderr names what the flag takes. Fix the command and run it again.

Progress and notes go to stderr; `--quiet` silences progress.

## Examples

```sh
# Insulation and its boundaries, on one resolution of an .mcool
chromosomix insulation sample.mcool::/resolutions/10000 --window 10 --out results/

# P(s) and its slope; compartments phased by GC content
chromosomix expected sample.cool --out results/
chromosomix compartments sample.cool --sequence ref.fa.gz --phaseSequence ref.fa.gz --out results/

# Loops and borders by pattern, then a pileup at a loop set
chromosomix chromosight sample.cool --pattern borders --out results/
chromosomix apa sample.cool --pairs loops.bedpe --norm chromosight --out results/

# A 4C profile from an anchor, written as the app writes a locus
chromosomix fourc sample.cool --anchor IV:1,200,001-1,210,000 --out results/

# Tasks over tracks, with or without a map
chromosomix metaplot --tracks ATAC.bw --features peaks.narrowPeak --flank 2000 --out results/
chromosomix frip sample.cool --tracks ATAC.bw,MNase.bw --features peaks.narrowPeak
chromosomix peaks --signal ChIP.bw --out results/
chromosomix overlap sample.cool --features peaks.bed --a peaks.bed --features tads.bed --b tads.bed

# Two libraries drawn to one depth before they are compared
chromosomix insulation rep1.cool rep2.cool --contacts 10M --out results/

# A map read by range from where it is published
chromosomix insulation https://example.org/sample.mcool::/resolutions/10000 --out results/

# A 3D model from the map, as a bed3d and a PDB
chromosomix reconstruct3d ecoli.mcool::/resolutions/20000 --out results/

# What `pairtools stats` writes, for MultiQC
chromosomix stats sample.pairs.gz --out qc/
```

## From the app to a script

Every run in the app is written to its console as the `chromosomix` command that repeats it, so a reader can tune a run on screen and copy the line. A saved workspace runs again over other files, every analysis it recorded with the parameters it recorded:

```sh
chromosomix replay workspace.chromosomix.json --over data/*.hic --out results/
```

## The usage, as `chromosomix --help` prints it

```
chromosomix — the Analysis panel, from a shell

  chromosomix tasks [--json]
      Every task, its id, and the parameters it takes. With --json, the same
      as one JSON document: every value a choice takes, every range and unit,
      what each input reads and what each task writes.

  chromosomix <task> <file.cool|file.mcool|file.hic|file.pairs.gz> [...]
      Run one task over one or more files. Each file's outputs are named after
      it, up to its first dot: sample.coverage.coverage-total.tsv. Two files
      that would share a name keep more of theirs — HCT116.rep1 and
      HCT116.rep2, then dirA_sample and dirB_sample — and nothing one command
      writes is written over by it.

      --out <dir>          where to write (default: .)
      --window <chr:a-b>   a window rather than the whole file, 1-based and
                           inclusive as the app, IGV and samtools write it,
                           digits grouped or not: chrIV:1,000,001-1,400,000
      --no-balance         read the raw counts. A map is read balanced wherever
                           the file carries weights, as the app reads it
      --features <file>    a feature or loop file a task needs, read as the app
                           reads it: BED, narrowPeak, GTF, genePred, VCF,
                           cytoBand, barChart, junctions, bedpe, interact,
                           longrange
      --sequence <ref.fa>  a reference, for a task that reads residues (motif,
                           restriction, and pairsqc's digest) or phases by GC
                           content (compartments). Gzipped or not; read by
                           range where its .fai is beside it, or a .2bit
      --pairs <file>       a BEDPE, interact or longrange, for an off-diagonal
                           pileup. Note this is a *feature* table and not a
                           contact list — a .pairs file to bin is a positional
                           argument, and takes --bin-size below. pairsqc's own
                           --pairs is the exception: the contact list a matrix
                           was made from, read for its records
      --against <file>     another contact map, for a task that compares two
                           (hicrep). Repeat it for a third
      --value <column>     the score column to read, for a file that carries
                           more than the count (default: count)
      --origin <name:pos>  where a sequence's replication origin is, 1-based,
                           as the Origin and terminus task reports it; repeat
                           or separate with commas
      --circular <name>    a sequence to read as a circle (a plasmid); repeat
                           or separate with commas
      --cell <name>        a cell of an .scool to sum into the map; repeat or
                           separate with commas. Default: every cell
      --contacts <n>       draw the map to n contacts before the task reads it:
                           below the file's own total, an exact subsample
                           (cooltools random-sample --count n --exact); above
                           it, an oversample through Boost-HiC. Takes 10M,
                           23,000,000 or 2.5e7; --against maps are drawn to it
                           too. The same seed as the app, so the same pixels
      --coarsen <bp>       read the map at this bin size, a whole number of the
                           file's own bins summed along each sequence — what
                           the app does at a resolution you added (3 kb*).
                           Counts sum exactly; a bin's weight is the harmonic
                           mean of its bins' weights. --against maps are summed
                           to it too
      --bin-size <bp>      required for a .pairs input, which states no
                           resolution of its own; ignored for every other format
      --rungs <n>          how many ladder resolutions to build from it
                           (1-2-5 series from the base). Default 1
      --threads <n>        threads for a task that shares its work —
                           pastis-NB's MDS start and likelihood in
                           reconstruct3d. Default 1, so a time is one core's;
                           the results are the same bits on any number
      --quiet              no progress on stderr
      --<param> <value>    any parameter the task takes; see `tasks`. A choice
                           is one of its values and a number is a number: any
                           other is refused before a file is opened, with the
                           values it takes. A locus (fourc's --anchor, the 3D
                           tasks' --region and --locus) is read as --window is.
                           A task that reads tracks (metaplot, trackcorr, frip,
                           groupsignal) takes them as --tracks <file.bw>,
                           repeated or comma-separated: a bigWig, a bedGraph, a
                           wig, or a FASTA read as GC content
      --<switch>           a parameter that is on or off, which takes no value
                           after it: --derivative turns one on, and
                           --derivative=false or --no-derivative turns it off

  chromosomix <task> --tracks <file.bw> --features <file.bed> [...]
      A task that reads tracks and no matrix (metaplot, trackcorr, frip,
      groupsignal, overlap, motif, composition, oriter), run with no contact map
      at all — what a 1D browser session runs. The assembly is what the tracks
      and references declare.

  chromosomix circular <file.mcool::/resolutions/<bp>> [...]
      Which sequences join their own ends: the junction test the app runs when
      a map is first opened, as a table on stdout — sequence, length, score,
      and yes or no where it could be decided: a sequence needs 50 bins at the
      resolution read. The names to hand every other run as --circular.

  chromosomix boost <file.mcool::/resolutions/<bp>> [...]
      The boosted map of each sequence: what an oversample (--contacts above
      the file's own total) draws the sequence's new contacts from — the bins
      the outlier filter keeps, and the boosted map over them in SCN units.
      One square TSV per sequence, rows and columns named by each kept bin's
      start, into --out.
      --sequences <a,b>    the sequences to boost. Default: every one; a
                           sequence past 3,000 bins is refused by name
      --alpha <a>          the exponent of the distances, 1/SCN^a.
                           Default: 0.2

  chromosomix stats <file.pairs.gz> [...]
      What `pairtools stats` writes for a .pairs file, counted by the pass the
      app's import makes: records mapped on both sides, on one and on neither,
      duplicates, cis and trans and cis past 1 to 40 kb, every pair type, the
      four orientations by separation and where they converge, and the
      library's size. One <name>.stats per file into --out, in pairtools' own
      format, which MultiQC and `pairtools stats --merge` read; to stdout
      without --out.

  chromosomix replay <workspace.chromosomix.json> --over <file> [...]
      Re-run every analysis recorded in a saved workspace, with the parameters
      it recorded, over the files named by --over and after the workspace —
      --over data/*.hic as a shell expands it. The workspace is what the
      app's Save button produces: every open tab in one file. A locus it
      recorded is read as --window is, as the app's form showed it; a value
      it recorded that this build cannot run is refused, before any file is.
      --tab <n>            which tab to replay, 1-based. Default: the one that
                           was in front when the workspace was saved.
      --track <file.bw>    the file behind a track the workspace recorded by
                           the app's own id. Repeat it per track
      --against <file>     the other maps a recorded hicrep compared against

  chromosomix --version
      Which build this is: chromosomix, its version and the commit it was
      built from, on the first line, as every file it writes opens with them.
      Then what the version does not fix — the Node it runs on, and the
      h5wasm and @gmod/bbi installed beside it, which read every map and track.

A file may be an http or https address — a map, or what --against,
--sequence, --tracks, --features or --pairs names. A map, a bigWig, a .2bit
and an indexed FASTA are read by range, as the app reads them, and nothing of
them is written to disk. What is read whole — a feature file, a HiC-Pro
matrix, a workspace, or any file whose host serves no range — is fetched into
$TMPDIR, with its progress on stderr, and removed when the command ends.

Every task, what it reads and writes, and how to read a result:
https://doc.chromosomix.app/
```

---

# chromosomix analysis tasks

> Every analysis chromosomix runs — 31 tasks, in the app’s Analysis panel and from the `chromosomix` command line, with the same parameters and the same results — with what each reads, what it writes, and every parameter: its flag, what it takes, its default and what it does. Generated from the app’s own task registry, so it is exactly what this release accepts.

## Reading this page

- A task is run as its section’s command shows; installing the command and its shared flags (`--window`, `--no-balance`, `--contacts`, `--coarsen`…) are on the [command line page](https://chromosomix.app/llms/cli.md).
- A parameter’s flag is its key: `--window 20`. A switch takes no value — `--call` turns it on, `--no-call` or `--call=false` off. A list is the flag repeated or one comma-separated value.
- A choice is one of the values listed, exactly, and a number is a number: anything else is refused before a file is opened, with exit status 2 and a sentence naming what the flag takes.
- A locus is written as the app displays it: 1-based and inclusive, digits grouped or not, `IV:1,000,001-1,400,000`.
- A map is read balanced wherever the file carries balancing weights; `--no-balance` reads the raw counts. An `.mcool` names one resolution: `sample.mcool::/resolutions/10000`.
- A task that reads tracks rather than a matrix runs with no map at all, over the assembly its files declare — but then needs a track (`--tracks`, or `--track <file.bw>`) or a reference (`--sequence`) among them; with interval files alone, name a map.
- *Read only under other settings* marks a parameter the app’s form hides at the task’s defaults: it takes effect once another parameter is set to what it belongs to.
- `chromosomix tasks --json` prints all of this as one JSON document, for the installed version.

### Inputs that are files

| A parameter that takes | Formats, and how a command names one |
|---|---|
| a feature set | BED, narrowPeak, GTF/GFF3, genePred, VCF, cytoBand, barChart or splice junctions. Load the file with `--features <file>` and name it in the parameter by its file name; where the parameter is itself called `features`, that one flag does both. |
| a set of pairs | BEDPE, interact or longrange. Load the file with `--pairs <file>` (or `--features <file>`) and name it in the parameter by its file name; where the parameter is itself called `pairs`, that one flag does both. |
| a signal track | bigWig, bedGraph or wig, or a FASTA read as its GC content, by path or address. The file the parameter names is the file loaded. |
| a reference sequence | FASTA, gzipped or not (read by range where its `.fai` is beside it), or `.2bit`. Load it with `--sequence <file>` and give the parameter the same path; where the parameter is itself called `sequence`, that one flag does both. |

### What a task writes

Every result goes into `--out` (default `.`) as `<file stem>.<task>.<output>.<ext>`, and each TSV opens with `#` lines naming the build, the file and every parameter that produced it.

| Result | Files |
|---|---|
| `profile` | a value per bin: TSV, bedGraph and bigWig |
| `curve` | a curve: TSV |
| `matrix` | a matrix, a pileup or a heatmap: TSV |
| `table` | a table: TSV |
| `intervals` | a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model) |

## Index

| Task | Command | Kind | What it does |
|---|---|---|---|
| Coverage and marginals | `coverage` | 2D tasks | How much contact each bin carries, and how much of it stays at home. |
| Cis and trans per sequence | `cistrans` | 2D tasks | How much of each sequence’s contact stays on it, and which pairs touch. |
| Per-cell contact QC | `cellqc` | 2D tasks | What each cell’s contacts look like, and where in the cycle that puts it. |
| Contact probability P(s) | `expected` | 2D tasks | How contact frequency falls with genomic separation. |
| Pairs QC | `pairsqc` | 2D tasks | A library’s records: pairtools stats, P(s) by orientation, and restriction fragments. |
| Map report | `mapreport` | 2D tasks | A library’s QC on one page: its contacts, their decay and coverage, and the resolutions it can bear. |
| Scalogram | `scalogram` | 2D tasks | How far each bin’s contacts reach, as nested quantile bands. |
| 4C profile from an anchor | `fourc` | 2D tasks | What one locus touches, as a track you can export. |
| Diamond insulation | `insulation` | 2D tasks | How much contact crosses each bin, and where the boundaries are. |
| Directionality index | `di` | 2D tasks | Which way each bin looks, and the domains the sign flips call. |
| HiC score | `hicscore` | 2D tasks | The mean contact a bin makes with its near neighbourhood. |
| TAD annotation | `arrowhead` | 2D tasks | Contact domains by Juicer’s Arrowhead: nested where they nest, and none where there are none. |
| Compartments | `compartments` | 2D tasks | Observed/expected, correlated or taken as it is, and its leading components. |
| Inter-arm alignment | `interarm` | 2D tasks | How strongly the two arms of a bacterial chromosome touch, from origin to terminus. |
| Loop calling | `loops` | 2D tasks | Call loops as pixels enriched over their local background. |
| Pattern detection | `chromosight` | 2D tasks | Find loops, borders, hairpins, centromeres or stripes by template matching. |
| Reproducibility | `hicrep` | 2D tasks | How much the maps on screen agree, stratum by stratum and pooled. |
| Aggregate peak analysis | `apa` | 2D tasks | Pile up the matrix at a set of loops or features, against a control. |
| Model from the map | `reconstruct3d` | 3D tasks | A 3D model of what is loaded: contacts read as distances, beads placed to honour them. |
| Model versus map | `structuremap` | 3D tasks | How well a 3D model’s distances agree with the contacts the map counted. |
| Spatial tracks | `spatialtracks` | 3D tasks | The model as tracks: radial position, distance to a locus, local compaction. |
| Find a motif | `motif` | 1D tasks | Every place a motif occurs, as sites and as a density track. |
| Restriction sites | `restriction` | 1D tasks | Where an enzyme cuts the reference, as sites and as a density track. |
| Peak calling | `peaks` | 1D tasks | Narrow peaks from a coverage track, where its smoothed signal curves down (yapc). |
| Base composition | `composition` | 1D tasks | GC content, GC skew and AT skew per bin, as tracks. |
| Origin and terminus | `oriter` | 1D tasks | Where replication starts and ends, from the GC skew, parS, matS and coverage. |
| Metaplot over a feature set | `metaplot` | 1D tasks | Average track signal at a set of places, with a band and a heatmap. |
| Track correlation | `trackcorr` | 1D tasks | How much every pair of loaded tracks agrees. |
| Fraction of signal in features | `frip` | 1D tasks | How much of each track sits inside a feature set, against how much of the genome it is. |
| Signal by group | `groupsignal` | 1D tasks | A track’s values in each group of the genome — A against B — compared and tested. |
| Interval set overlap | `overlap` | 1D tasks | Jaccard, shared bases, how many features touch — and whether that is more than chance. |

## 2D tasks

### Coverage and marginals — `coverage`

How much contact each bin carries, and how much of it stays at home.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** depth, marginal, balancing, weights.

```sh
chromosomix coverage <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--total / --no-total` | on or off | on | Total coverage: Every contact touching the bin, and flat on a correctly balanced file. |
| `--fraction / --no-fraction` | on or off | off | Cis fraction: Of the contacts a bin has, how many stay on its own sequence. |
| `--cis / --no-cis` | on or off | off | Cis coverage. |
| `--trans / --no-trans` | on or off | off | Trans coverage. |
| `--balance / --balance=false` | on or off | off | Use balancing weights: Worth turning on to check the balancing itself: a balanced file should have a flat total, so one that is not is a file whose weights do not fit it. |

### Cis and trans per sequence — `cistrans`

How much of each sequence’s contact stays on it, and which pairs touch.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a table: TSV; a curve: TSV; a matrix, a pileup or a heatmap: TSV.
- **Also known as:** interchromosomal, trans ratio, karyotype, cis/trans.

```sh
chromosomix cistrans <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--bars <value>` | `cis`, `trans` or `both` | `cis` | Bars per sequence: Fractions of each sequence’s own contact, so a deep sequence and a shallow one compare. `both` — the two sum to one, so every bar is full and the split is the cis fraction. |
| `--normalise <value>` | `enrichment`, `raw` or `bins` | `enrichment` | Off-diagonal value. `enrichment` — contacts over what the two sequences’ own trans coverage predicts. 1 is what any two sequences of that depth would give; a fusion is far above it; `raw` — raw contacts; `bins` — divided by the two sequences’ bin counts. |
| `--minContacts <n>` | a whole number, at least 0 | `10` | Least contact worth listing: Raw contacts, before any normalisation, which keeps one stray read out of the table’s top. |
| `--maxEdges <n>` | a whole number, at least 10 | `500` | Pairs to list. |
| `--matrix / --no-matrix` | on or off | on | Draw the square: Skipped above 512 sequences, where it is not a picture. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Per-cell contact QC — `cellqc`

What each cell’s contacts look like, and where in the cycle that puts it.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a table: TSV; a curve: TSV.
- **Also known as:** single cell, scool, cell cycle, quality.

```sh
chromosomix cellqc <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--cells <value>` | `all` or `selected` | `all` | Cells. `all` — what the choice is made from, so this is the answer that helps make it; `selected` — the ticked ones only. |
| `--nearFrom <n>` | a whole number, at least 0, in bp | `23000` | *Bands.* Near band, from: Below this a contact is mostly self-ligation and unligated ends rather than structure. |
| `--nearTo <n>` | a whole number, at least 1, in bp | `2000000` | *Bands.* Near band, to. |
| `--mitoticTo <n>` | a whole number, at least 1, in bp | `12000000` | *Bands.* Mitotic band, to: The near band’s upper edge is this band’s lower one; beyond it is the far band. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Contact probability P(s) — `expected`

How contact frequency falls with genomic separation.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a curve: TSV.
- **Also known as:** P(s), Ps, decay, distance, scaling, expected, slope.

```sh
chromosomix expected <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--scope <value>` | `contig` or `file` | `contig` | Scope. `contig` — one curve per sequence; `file` — every sequence pooled into one curve. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--quantity <value>` | `density` or `expected` | `density` | Quantity. `density` — share of all cis contacts, per base pair. HiContacts' norm_p; `expected` — mean contact per pair of bins that far apart. What cooltools expected-cis reports. |
| `--factor <n>` | a number, 1.01 to 2 | `1.1` | Log bins per step: Each separation bin is this many times wider than the last. |
| `--minSeparation <n>` | a whole number, at least 0, in bins | `2` | Minimum separation: Drops the near-diagonal, where unligated fragments dominate. |
| `--derivative / --no-derivative` | on or off | on | Log-log slope: The shoulder and the plateau are visible there and not on the curve. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Pairs QC — `pairsqc`

A library’s records: pairtools stats, P(s) by orientation, and restriction fragments.

- **Reads:** a contact map, named as the positional argument.
- **Runs first:** `restriction`, at its defaults, and reads its result.
- **Writes:** a curve: TSV; a table: TSV.
- **Also known as:** pairtools, stats, QC, orientation, strand, convergence, restriction, enzyme, fragment, dangling, self-circle, duplicates, pair types.

```sh
chromosomix pairsqc <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--pairs <file>` | a file or address: `.pairs` or `.pairs.gz` | — | *From the .pairs file.* .pairs file: Read for its records alone: nothing is binned and no map changes. *Not asked of a file that answers it itself.* |
| `--reference <file>` | a file: a reference sequence; optional | not used | *Restriction enzyme.* Reference: The FASTA or .2bit the reads were mapped to, where the enzyme’s sites are found. |
| `--enzyme <value>` | `none`, `DpnII`, `HindIII`, `NcoI`, `EcoRI`, `BglII`, `HinfI`, `DdeI`, `MseI`, `NlaIII`, `CviQI`, `AluI`, `Arima` or `custom` | `none` | *Restriction enzyme.* Enzyme: The enzyme the library was cut with, or a kit that cuts with several. `none` — no enzyme: a library cut with a nuclease, as Micro-C and Omni-C are; `DpnII` — dpnII (^GATC); `HindIII` — hindIII (A^AGCTT); `NcoI` — ncoI (C^CATGG); `EcoRI` — ecoRI (G^AATTC); `BglII` — bglII (A^GATCT); `HinfI` — hinfI (G^ANTC); `DdeI` — ddeI (C^TNAG); `MseI` — mseI (T^TAA); `NlaIII` — nlaIII (CATG^); `CviQI` — cviQI (G^TAC); `AluI` — aluI (AG^CT); `Arima` — arima (DpnII + HinfI); `custom` — enzymes by name, aliases such as MboI included, or sites typed with a ^ where they cut. |
| `--sites <text>` | text | empty | *Restriction enzyme.* Sites: Enzyme names or IUPAC sites with a ^ where the top strand is cut, separated by commas. *Read only under other settings of this task.* |

### Map report — `mapreport`

A library’s QC on one page: its contacts, their decay and coverage, and the resolutions it can bear.

- **Reads:** a contact map, named as the positional argument.
- **Runs first:** `expected`, `coverage` and `cistrans`, at their defaults, and reads their results.
- **Writes:** a table: TSV; a curve: TSV.
- **And, for the run as a whole:** HTML report, `<file stem>.mapreport.report.html`; MultiQC summary, `<file stem>.mapreport.summary_mqc.tsv` (command line only); MultiQC resolutions, `<file stem>.mapreport.resolutions_mqc.tsv` (command line only); MultiQC contacts per bin, `<file stem>.mapreport.resolution_mqc.json` (command line only); MultiQC P(s), `<file stem>.mapreport.ps_mqc.json` (command line only).
- **Also known as:** QC, quality, report, map resolution, MultiQC, summary, depth.

```sh
chromosomix mapreport <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--base <value>` | `finest` or `map` | `finest` | Ladder from: The resolution the library is counted at and the ladder climbs from. `finest` — where the file stores more than one, its finest is read for the ladder, whatever is on screen; `map` — this map’s resolution. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Scalogram — `scalogram`

How far each bin’s contacts reach, as nested quantile bands.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** reach, distance, quantiles.

```sh
chromosomix scalogram <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--quantiles <value>` | `standard`, `quartiles` or `deciles` | `standard` | Quantiles: One band per quantile, nested in a single lane. `standard` — lioy et al.’s bands, and what HiContacts draws; `quartiles` — the quartiles alone; `deciles` — a finer picture; nine lanes of ink. |
| `--reach <n>` | a whole number, at least 0, in bins | `0` | Look out to: 0 is the whole sequence; a cut makes every quantile a quantile of what is within it, and the lane says so. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--ignoreDiags <n>` | a whole number, at least 0 | `1` | *Quality.* Diagonals to ignore: 1 drops the bin’s contact with itself, which is not a contact at a distance. |
| `--minValid <n>` | a number, 0 to 1 | `0.5` | *Quality.* Minimum coverage of the distribution: Below this fraction of usable separations the bin gets no bands at all. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### 4C profile from an anchor — `fourc`

What one locus touches, as a track you can export.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** virtual 4C, v4C, viewpoint, anchor.

```sh
chromosomix fourc <map> --anchor <locus> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--anchor <locus>` | a locus, display form | None. | Anchor. |
| `--normalise <value>` | `none`, `coverage`, `ps` or `ps+coverage` | `none` | Normalisation. `none` — contacts as they were counted; `coverage` — each bin divided by how much it is seen at all, so a dead bin is not a dip; `ps` — observed over expected at that separation, from this sequence’s own decay; `ps+coverage` — both divisions: the decay out of the shape, the depth out of each bin. |
| `--cis / --no-cis` | on or off | on | Cis only: On, this reads one sequence and costs a handful of requests; off, it walks the pixel table for the contacts leaving that sequence. |
| `--excludeAnchor / --no-excludeAnchor` | on or off | off | Exclude anchor region: Leave the anchor and one bin either side empty, so its contact with itself does not set the scale. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Diamond insulation — `insulation`

How much contact crosses each bin, and where the boundaries are.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig; a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model).
- **Also known as:** TAD, domains, boundaries, insulation score.

```sh
chromosomix insulation <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--window <n>` | a whole number, at least 1, in bins | `10` | Window: The diamond is a square this many bins on a side, cornered on the bin it scores. |
| `--scales <n>` | a whole number, 1 to 4 | `1` | Scales: One track per scale, each twice the width of the last. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--ignoreDiags <n>` | a whole number, at least 0 | `2` | *Quality.* Diagonals to ignore: 0 counts every cell; 2 leaves out the corner of the diamond on the diagonal. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |
| `--call / --no-call` | on or off | on | *Boundaries.* Call boundaries: Adds the calls as a set of their own, a 1D track under the score to begin with. |
| `--prominence <n>` | a number, 0 to 3 | `0.2` | *Boundaries.* Minimum prominence: How far the track must climb from a minimum before it falls lower, in log2 units. |
| `--minValid <n>` | a number, 0 to 1 | `0.5` | *Boundaries.* Diamond coverage to call: Bins whose diamond holds less than this share of the fullest one’s cells are not called. |
| `--spacing <n>` | a whole number, at least 0, in bins | `0` | *Boundaries.* Minimum spacing: Two calls closer than this many bins keep only the stronger. |
| `--domains / --no-domains` | on or off | on | *Boundaries.* Domains between them: A second set, the span from each call to the next, drawn as corners along the diagonal to begin with. |

### Directionality index — `di`

Which way each bin looks, and the domains the sign flips call.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig; a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model).
- **Also known as:** DI, TAD, domains, boundaries.

```sh
chromosomix di <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--window <n>` | a whole number, at least 1, in bins | `50` | Window: Contacts are summed this many bins each way of every bin, 50 being Dixon et al.’s 2 Mb at the 40 kb they worked at. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--ignoreDiags <n>` | a whole number, at least 0 | `0` | *Quality.* Diagonals to ignore: 0 counts every cell; the bin’s contact with itself is never in either sum. |
| `--minValid <n>` | a number, 0 to 1 | `0.5` | *Quality.* Minimum coverage of each side: Below this fraction of usable cells — on either side — the bin gets no score. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |
| `--call / --no-call` | on or off | on | *Borders.* Call borders: Adds the borders as a set of their own, a 1D track under the index to begin with. |
| `--prominence <n>` | a number, 0 to 200 | `10` | *Borders.* Minimum prominence: How many bins of steady bias the track must carry on both sides of a flip. |
| `--spacing <n>` | a whole number, at least 0, in bins | `0` | *Borders.* Minimum spacing: Two calls closer than this many bins keep only the stronger. |
| `--domains / --no-domains` | on or off | on | *Borders.* Domains between them: A second set, the span from each border to the next, drawn as corners along the diagonal to begin with. |

### HiC score — `hicscore`

The mean contact a bin makes with its near neighbourhood.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** contact density, local contacts.

```sh
chromosomix hicscore <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--diagonals <n>` | a whole number, at least 1 | `3` | Diagonals: How many diagonals the bin’s line crosses, counting the main one — at 3 that is five cells, reaching two bins each way. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--ignoreDiags <n>` | a whole number, at least 0 | `0` | *Quality.* Diagonals to ignore: 0 counts every cell, including the bin’s contact with itself, which at three diagonals is most of the score and is where self-ligation lands. |
| `--minValid <n>` | a number, 0 to 1 | `0.5` | *Quality.* Minimum coverage of the line: Below this fraction of usable cells the bin gets no score at all. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### TAD annotation — `arrowhead`

Contact domains by Juicer’s Arrowhead: nested where they nest, and none where there are none.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a table: TSV.
- **Also known as:** TAD, Arrowhead, Juicer, contact domains, domains, corner score.

```sh
chromosomix arrowhead <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--matrixSize <n>` | a whole number, 30 to 4000, in bins | `2000` | Window: Juicer’s -m: each sequence is read as squares this many bins wide, half of one overlapping the next, and a domain wider than a square is not found. |
| `--minBlockSize <n>` | a whole number, at least 0, in bins | `60` | Smallest lenient domain: A domain found only by the lenient pass is kept when it is wider than this. |
| `--varThreshold <n>` | a number, at least 0 | `0.2` | *Strict pass.* Variance at most: The two triangles’ variances summed; a corner above it is not kept by the strict pass. |
| `--highSignThreshold <n>` | a number, -1 to 1 | `0.5` | *Strict pass.* Sign agreement at least: How consistently each triangle points the way a domain’s does, from −1 to 1. |
| `--maxLowSignThreshold <n>` | a number, -1 to 1 | `0.4` | *Lenient pass.* Sign agreement from: The lenient pass asks this much of both triangles and no variance, and asks less, a step at a time, until a sequence has a domain. |
| `--minLowSignThreshold <n>` | a number, -1 to 1 | `0` | *Lenient pass.* Down to. |
| `--decrementLowSignThreshold <n>` | a number, 0.01 to 1 | `0.1` | *Lenient pass.* In steps of. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Compartments — `compartments`

Observed/expected, correlated or taken as it is, and its leading components.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig; a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a matrix, a pileup or a heatmap: TSV; a table: TSV.
- **Also known as:** A/B, eigenvector, E1, PCA, saddle, correlation.

```sh
chromosomix compartments <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences: One correlation per sequence under “cis only”, and one over all of them under “cis and trans” or “trans only”. |
| `--contacts <value>` | `cis`, `both` or `trans` | `cis` | Contacts. `cis` — one correlation per sequence, over its own contacts. The cheapest, and per chromosome; `both` — one correlation over everything ticked. Each half keeps its own expectation; `trans` — between sequences alone, so no distance decay enters the answer. Needs two or more. |
| `--ignoreDiags <n>` | a whole number, at least 0 | `2` | Diagonals to ignore: 0 keeps every cell; 1 drops the main diagonal; 2 drops it and the two beside it. |
| `--expected <value>` | `distance` or `arms` | `distance` | Expected. `distance` — the mean of each diagonal: the ordinary observed/expected; `arms` — also removes the secondary diagonal of a bacterial chromosome whose arms are aligned, reading the arms from the origin on the Chromosomes table — the first base unless set. |
| `--armWindow <n>` | a whole number, at least 0, in bins | `50` | Window along the arms: Each cell is compared within this far along the arms; 0 is the whole chromosome. *Read only under other settings of this task.* |
| `--method <value>` | `cooltools` or `correlation` | `cooltools` | Method. `cooltools` — observed/expected itself, clipped at its 99.9th percentile and less one, decomposed; `correlation` — the Pearson correlation of observed/expected’s rows, decomposed. |
| `--components <n>` | a whole number, 1 to 3 | `1` | Components: E1 is the compartment track; E2 and E3 occasionally say something. |
| `--phaseFeatures <file>` | a file: a feature set; optional | not used | *Phasing.* Phase by gene density: Positive is made to mean the compartment these features are dense in. |
| `--phaseTrack <file>` | a file: a signal track; optional | not used | *Phasing.* Phase by a track: Positive is made to follow this track, when no gene model is chosen. |
| `--phaseSequence <file>` | a file: a reference sequence; optional | not used | *Phasing.* Phase by GC content: Used when neither a gene model nor a track is chosen. |
| `--minR <n>` | a number, 0 to 1 | `0.1` | *Phasing.* Least convincing correlation: Below this the sign is left alone and the drawer says the phasing was ambiguous. |
| `--saddle / --no-saddle` | on or off | on | *Saddle.* Draw the saddle: The compartment claim in one square, with AA, BB and AB under it. |
| `--quantiles <n>` | a whole number, 5 to 100 | `50` | *Saddle.* Quantile groups. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Inter-arm alignment — `interarm`

How strongly the two arms of a bacterial chromosome touch, from origin to terminus.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a curve: TSV; a value per bin: TSV, bedGraph and bigWig; a table: TSV.
- **Also known as:** arms, secondary diagonal, bacteria, SMC, ParB.

```sh
chromosomix interarm <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--band <n>` | a whole number, 0 to 50, in bins | `2` | Band: Cells this close to the secondary diagonal are averaged; 0 is the diagonal alone. |
| `--armWindow <n>` | a whole number, at least 0, in bins | `50` | Window along the arms: For the enrichment after detrend: each cell is compared within this far along the arms, as the map’s arms and Compartments do; 0 is the whole chromosome. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Loop calling — `loops`

Call loops as pixels enriched over their local background.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a curve: TSV; a table: TSV.
- **Also known as:** loops, dots, call loops, hiccups, peaks, cooltools dots.

```sh
chromosomix loops <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--outer <n>` | a whole number, 1 to 50, in bins | Worked out from the map's bin size when left out; 5 where there is no map. | Outer half-width: w: how far the donut and the other three neighbourhoods reach from a pixel. |
| `--inner <n>` | a whole number, 0 to 49, in bins | Worked out from the map's bin size when left out; 2 where there is no map. | Inner half-width: p: the square about a pixel none of the four counts, a loop’s own size. |
| `--maxSeparation <n>` | a whole number, at least 1, in bins | Worked out from the map's bin size when left out; 1000 where there is no map. | Furthest from the diagonal: Loops whose anchors are farther apart are not looked for; 10 Mb unless changed. |
| `--fdr <n>` | a number, 0.001 to 0.5 | `0.1` | *Statistics.* False discovery rate: Benjamini–Hochberg, within each λ-chunk of pixels of a like local expected. |
| `--lambdaBins <n>` | a whole number, 40 to 50 | `40` | *Statistics.* Λ-chunks: Log-spaced chunks of local expected, each corrected on its own; 40 to 50 of them. |
| `--clusteringRadius <n>` | a number, at least 0, in bins | Worked out from the map's bin size when left out; 2 where there is no map. | *Clusters.* Clustering radius: Enriched pixels this close are one loop, at its brightest; 0 keeps every pixel, unfiltered. |
| `--filter / --no-filter` | on or off | on | *Clusters.* Enrichment filter: 1.5–2× over the four neighbourhoods, and a lone pixel only at q ≤ 0.02 summed over them. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Pattern detection — `chromosight`

Find loops, borders, hairpins, centromeres or stripes by template matching.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a matrix, a pileup or a heatmap: TSV; a curve: TSV; a table: TSV.
- **Also known as:** template, borders, stripes, hairpins, centromeres.

```sh
chromosomix chromosight <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--pattern <value>` | `loops`, `loops_small`, `borders`, `hairpins`, `centromeres`, `stripes_left` or `stripes_right` | `loops` | Pattern: Every threshold below follows the template: they were tuned together. `loops` — focal contacts between two anchors — the classic dot off the diagonal; `loops_small` — the same, at a tighter 7×7 template, for short-range dots; `borders` — domain boundaries: the corner where one self-interacting block ends and the next begins; `hairpins` — the fold-back signal of a hairpin, on the diagonal; `centromeres` — the large-scale depletion around a centromere; `stripes_left` — an architectural stripe running left from an anchor; `stripes_right` — an architectural stripe running right from an anchor. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--thresholds <value>` | `preset` or `custom` | `preset` | *Scan.* Thresholds. `preset` — the template’s own numbers, tuned for it and published with it; `custom` — the boxes start at the loops preset; check them against the pattern you picked. |
| `--pearson <n>` | a number, 0 to 1 | `0.3` | *Scan.* Score threshold: The correlation a pixel must reach to be a candidate; lower finds more, and more of it is noise. *Read only under other settings of this task.* |
| `--minDist <n>` | a whole number, at least 0, in bins | `10` | *Scan.* Nearest to the diagonal. *Read only under other settings of this task.* |
| `--maxDist <n>` | a whole number, at least 0, in bins | `1000` | *Scan.* Furthest from the diagonal: The scan band: widening it costs time in proportion, and zero puts the pattern on the diagonal. *Read only under other settings of this task.* |
| `--minSeparation <n>` | a whole number, at least 0, in bins | `3` | *Scan.* Nearest two calls may be: Closer than this on both axes and only the higher-scoring one is kept. *Read only under other settings of this task.* |
| `--iterations <n>` | a whole number, 1 to 5 | `1` | *Scan.* Refinement passes: Each pass re-scans with the pileup of what the last one found as its template. |
| `--maxPercUndetected <n>` | a number, 0 to 100, in % | `50` | *Quality.* Most undetectable pixels a window may hold. *Read only under other settings of this task.* |
| `--maxPercZero <n>` | a number, 0 to 100, in % | `10` | *Quality.* Most empty pixels a window may hold. *Read only under other settings of this task.* |
| `--nMads <n>` | a number, 1 to 20 | `5` | *Quality.* Detectability cut: Median absolute deviations below the median coverage, and only read where the file has no weights. |
| `--maxQvalue <n>` | a number, 0 to 1 | `1` | *Quality.* Report down to a q-value of: Benjamini-Hochberg over every call; 1 keeps them all and still reports the number. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Reproducibility — `hicrep`

How much the maps on screen agree, stratum by stratum and pooled.

- **Reads:** a contact map, named as the positional argument, and the maps it is compared with, by `--against`.
- **Writes:** a table: TSV; a matrix, a pileup or a heatmap: TSV; a curve: TSV.
- **Also known as:** HiCRep, SCC, replicates, similarity, correlation.

```sh
chromosomix hicrep <map> --against <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--against <file>` | a file or address: | — | Other maps: The other contact maps to compare with; repeat the flag for each. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences: Each is scored on its own as well as pooled. |
| `--maxDistance <n>` | a whole number, 1 to 500, in bins | `500` | Furthest separation compared: Every stratum out to here counts, weighted by the positions it compares — so this moves the answer, as hicrep’s dBPMax does: 5 Mb is 50 strata at 100 kb. |
| `--smooth <n>` | a whole number, 0 to 20, in bins | `1` | Smoothing half-width: The 2D mean filter HiCRep applies before correlating; 0 measures depth as much as structure on any sparse pair of maps. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Aggregate peak analysis — `apa`

Pile up the matrix at a set of loops or features, against a control.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a matrix, a pileup or a heatmap: TSV; a table: TSV; a curve: TSV.
- **Also known as:** APA, pileup, aggregate, loops, coolpup.

```sh
chromosomix apa <map> --pairs <pairs.bedpe> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--anchors <value>` | `pairs`, `features`, `allpairs` or `consecutive` | `pairs` | Anchors. `pairs` — off the diagonal, between two anchors; `features` — on the diagonal, at each feature; `allpairs` — off the diagonal, between every two features within a separation range — the test of whether a set of places contacts itself; `consecutive` — off the diagonal, between each feature and the next one along its sequence — the pairs of neighbouring sites, such as consecutive CTCF peaks. |
| `--pairs <file>` | a file: a set of pairs | — | Pairs. |
| `--features <file>` | a file: a feature set | — | Features. *Read only under other settings of this task.* |
| `--mode <value>` | `fixed` or `scaled` | `fixed` | Mode. `fixed` — centre plus or minus a number of bins; `scaled` — flank, the feature, flank — every window on one grid. Over a set of domains this is the domain pileup: the TAD in the middle and its two boundaries as the cross through it. |
| `--at <value>` | `centre`, `start` or `end` | `centre` | Anchor on. `centre` — half way along the feature; `start` — its 5′ end — a TSS, on a gene model; `end` — its 3′ end. *Read only under other settings of this task.* |
| `--window <n>` | a whole number, 1 to 200, in bins | `21` | Half-width. |
| `--grid <n>` | a whole number, 11 to 201 | `51` | Grid: Every window resampled to this many cells a side; a multiple of four puts the feature’s two ends on axis ticks. *Read only under other settings of this task.* |
| `--flankFraction <n>` | a number, 0 to 2 | `0.5` | Flank: As a fraction of the feature’s own length each side: at 0.5 the feature is the middle half of the picture, at 1 the middle third. *Read only under other settings of this task.* |
| `--minDiag <n>` | a whole number, 0 to 50 | `2` | Diagonals left out: The main diagonal and the ones beside it, left out of every window; 0 keeps every one. |
| `--norm <value>` | `matched`, `oe`, `none` or `chromosight` | `oe` | Normalisation. `matched` — against shifted anchors at the same separations. Controls for local background too; `oe` — each window over its sequence’s own P(s). Controls for the distance decay only; `none` — the raw pileup; `chromosight` — the map detrended by its own distance law, then averaged — and every anchor scored against the template. |
| `--csPattern <value>` | `loops`, `loops_small`, `borders`, `hairpins`, `centromeres`, `stripes_left` or `stripes_right` | `loops` | Template: What each window is scored against, and how wide it is. `loops` — focal contacts between two anchors — the classic dot off the diagonal; `loops_small` — the same, at a tighter 7×7 template, for short-range dots; `borders` — domain boundaries: the corner where one self-interacting block ends and the next begins; `hairpins` — the fold-back signal of a hairpin, on the diagonal; `centromeres` — the large-scale depletion around a centromere; `stripes_left` — an architectural stripe running left from an anchor; `stripes_right` — an architectural stripe running right from an anchor. *Read only under other settings of this task.* |
| `--controls <n>` | a whole number, 1 to 25 | `5` | *Control.* Controls per pair. *Read only under other settings of this task.* |
| `--minShift <n>` | a whole number, at least 0, in bins | `50` | *Control.* Smallest shift: A control nearer than the window’s own width overlaps the anchors it stands in for. *Read only under other settings of this task.* |
| `--maxShift <n>` | a whole number, at least 1, in bins | `500` | *Control.* Largest shift. *Read only under other settings of this task.* |
| `--minShiftScale <n>` | a number, 0 to 20 | `1` | *Control.* Smallest shift: As a multiple of the window’s own width; below 1 a control overlaps the feature. *Read only under other settings of this task.* |
| `--maxShiftScale <n>` | a number, 0.5 to 50 | `3` | *Control.* Largest shift. *Read only under other settings of this task.* |
| `--seed <n>` | a seed, a whole number | `1` | *Control.* Seed: The same seed gives the same control twice. *Read only under other settings of this task.* |
| `--minDist <n>` | a whole number, at least 0, in bins | `5` | *Separation.* Nearest loop: Loops nearer the diagonal than this are left out, 0 keeping every one; from twice the half-width and two, no window reaches the first two diagonals. |
| `--minSep <n>` | a whole number, at least 0, in bins | `2` | *Separation.* Nearest two features may be: Below this a pair is mostly the diagonal it sits on rather than a contact between two places. *Read only under other settings of this task.* |
| `--maxSep <n>` | a whole number, at least 1, in bins | `200` | *Separation.* Furthest two features may be. *Read only under other settings of this task.* |
| `--byDistance <n>` | a whole number, 0 to 6 | `0` | *Separation.* Split by separation into: Log-spaced bands, each piled up on its own with its own control; one band averages a 30 kb contact and a 2 Mb one into a picture of neither. |
| `--rankBy <column>` | a numeric column of the set `--features` names; optional | not used | *Ranking.* Rank by. *Read only under other settings of this task.* |
| `--subset <value>` | `all`, `top` or `groups` | `all` | *Ranking.* Then. `all` — one pileup; `top` — top N; `groups` — k groups. *Read only under other settings of this task.* |
| `--count <n>` | a whole number, at least 1 | `500` | *Ranking.* N. *Read only under other settings of this task.* |
| `--groups <n>` | a whole number, 2 to 6 | `4` | *Ranking.* Groups. *Read only under other settings of this task.* |
| `--tracks <file,…>` | files: a signal track; optional | not used | *Tracks.* Track aggregates: Each is averaged over the same windows the pileup is taken from and drawn along its two edges — the aggregate signal above and beside the aggregate map. |
| `--symmetric / --no-symmetric` | on or off | on | *Tracks.* Same profile both sides: One aggregate over every anchor, drawn identically above and beside. Untick to keep each pair’s two anchors apart — the second along the top, the first down the right. *Read only under other settings of this task.* |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

## 3D tasks

### Model from the map — `reconstruct3d`

A 3D model of what is loaded: contacts read as distances, beads placed to honour them.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a table: TSV.
- **Also known as:** 3D, structure, reconstruction, ShRec3D, negative binomial.

```sh
chromosomix reconstruct3d <map> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--method <value>` | `nb` or `shrec3d` | `nb` | Method: The two published readings of a contact count, which give different models of the same map. `nb` — fits the model the counts are likeliest under, so a pair counted zero times is evidence rather than a distance to invent; `shrec3d` — faster, and what most published models were made with, but it has to invent a distance for every pair the map never counted. |
| `--region <locus,…>` | loci, comma-separated, display form | Every sequence of the file when left out. | Sequences: A locus or comma-separated sequences, empty for the whole file, one bead per bin. |
| `--alpha <n>` | a number, 0.5 to 6 | `3` | Exponent α: How steeply contacts fall off with distance: 3 is the fractal-globule value, 1 flattens the near diagonal, 6 stretches it. |
| `--weights <value>` | `contacts`, `sqrt` or `equal` | `contacts` | Weight pairs by: How strongly a pair’s count holds its beads at the distance it implies. `contacts` — a pair seen a thousand times is a thousand times as sure as one seen once; `sqrt` — a weak pair is still heard on a deep map; `equal` — one vote each, which lets the far, weak pairs outvote the near diagonal. *Read only under other settings of this task.* |
| `--seed <n>` | a seed, a whole number | `0` | Seed: Where pastis’ MDS places the beads before the fit; another seed can settle in another optimum. |
| `--iterations <n>` | a whole number, 0 to 2000 | `150` | Refinement steps: How many steps refine the beads after the start, stopping earlier once a step stops buying anything. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Model versus map — `structuremap`

How well a 3D model’s distances agree with the contacts the map counted.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a matrix, a pileup or a heatmap: TSV; a curve: TSV; a table: TSV.
- **Also known as:** 3D, structure, distances.

```sh
chromosomix structuremap <map> --features <structure.bed3d> --structure <structure.bed3d> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--structure <file>` | a file: a feature set | — | Structure: The model to read: a row of the Structures card. |
| `--region <locus,…>` | loci, comma-separated, display form | Every sequence of the file when left out. | Sequences: The matrices are drawn for the first named; the table covers them all. |
| `--alpha <n>` | a number, 0.5 to 6 | `3` | Exponent α: Contacts fall as 1/dᵅ in the predicted map; only the picture depends on it. |
| `--no-balance` | a switch | On wherever the file carries balancing weights; --no-balance reads the raw counts. | Use balancing weights. |

### Spatial tracks — `spatialtracks`

The model as tracks: radial position, distance to a locus, local compaction.

- **Reads:** a contact map, named as the positional argument.
- **Writes:** a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** 3D, structure, radial position, compaction.

```sh
chromosomix spatialtracks <map> --features <structure.bed3d> --structure <structure.bed3d> --locus <locus> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--structure <file>` | a file: a feature set | — | Structure: The model to read: a row of the Structures card. |
| `--locus <locus>` | a locus, display form | None. | Distance to: A locus to measure every bead’s distance from — the spatial virtual 4C — and empty leaves the other two tracks alone. |
| `--window <n>` | a whole number, 1 to 100 | `5` | Compaction window: How many beads either side a bead is compared with, for the local compaction track. |

## 1D tasks

### Find a motif — `motif`

Every place a motif occurs, as sites and as a density track.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** sequence, pattern, sites, GATC, restriction.

```sh
chromosomix motif [<map>] --sequence <sequence.fa> --pattern <pattern> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequence <file>` | a file: a reference sequence | — | Reference: The FASTA or .2bit to search — its own sequences, in its own order. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--pattern <text>` | text | None. | Motif: IUPAC — A C G T U and the ambiguity codes R Y S W K M B D H V N — with spaces and case ignored and every overlapping match counted. |
| `--bothStrands / --no-bothStrands` | on or off | on | Both strands: A palindrome is still reported once, not twice. |
| `--mismatches <n>` | a whole number, 0 to 4 | `0` | Mismatches: Positions a site may differ from the motif by; N in the motif is always free. |
| `--limit <n>` | a whole number, 1 to 500000 | `500000` | Most sites: A backstop against a pattern like N: up to 500,000, and the run says so when it bites. |

### Restriction sites — `restriction`

Where an enzyme cuts the reference, as sites and as a density track.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** enzyme, digest, fragments, cut sites, DpnII, MboI, HindIII, Arima.

```sh
chromosomix restriction [<map>] --sequence <sequence.fa> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequence <file>` | a file: a reference sequence | — | Reference: The FASTA or .2bit to cut, with its own sequences in its own order. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--enzyme <value>` | `none`, `DpnII`, `HindIII`, `NcoI`, `EcoRI`, `BglII`, `HinfI`, `DdeI`, `MseI`, `NlaIII`, `CviQI`, `AluI`, `Arima` or `custom` | `none` | Enzyme: The enzyme the library was cut with, or a kit that cuts with several. `none` — no enzyme: a library cut with a nuclease, as Micro-C and Omni-C are; `DpnII` — dpnII (^GATC); `HindIII` — hindIII (A^AGCTT); `NcoI` — ncoI (C^CATGG); `EcoRI` — ecoRI (G^AATTC); `BglII` — bglII (A^GATCT); `HinfI` — hinfI (G^ANTC); `DdeI` — ddeI (C^TNAG); `MseI` — mseI (T^TAA); `NlaIII` — nlaIII (CATG^); `CviQI` — cviQI (G^TAC); `AluI` — aluI (AG^CT); `Arima` — arima (DpnII + HinfI); `custom` — enzymes by name, aliases such as MboI included, or sites typed with a ^ where they cut. |
| `--sites <text>` | text | empty | Sites: Enzyme names or IUPAC sites with a ^ where the top strand is cut, separated by commas. *Read only under other settings of this task.* |

### Peak calling — `peaks`

Narrow peaks from a coverage track, where its smoothed signal curves down (yapc).

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a table: TSV; a curve: TSV.
- **Also known as:** peaks, yapc, narrowPeak, ChIP, ATAC.

```sh
chromosomix peaks [<map>] --signal <signal.bw> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--signal <file>` | a file: a signal track | — | Track: The coverage to call on, as normalised; a bigWig, a bedGraph or a wig. |
| `--replicate <file>` | a file: a signal track; optional | not used | Replicate: A second replicate of the same experiment; with one, IDR tests every peak. |
| `--idr <value>` | `0.001`, `0.005`, `0.01`, `0.05`, `0.1` or `0.2` | `0.05` | IDR threshold: Keep peaks whose global IDR is at most this. *Read only under other settings of this task.* |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--perPeak / --no-perPeak` | on or off | off | List every peak: One row per peak, with its summit, its scores and its IDR; long on a large genome. |
| `--width <n>` | a whole number, 1 to 2000, in bp | `150` | *Smoothing.* Smoothing window: yapc’s default; 75 to 200 bp suits most narrow peaks. |
| `--times <n>` | a whole number, 0 to 10 | `3` | *Smoothing.* Smoothing passes: Rolling means applied to the second derivative. |
| `--minWidth <n>` | a whole number, at least 1, in bp | `75` | *Peaks.* Narrowest peak: Concave stretches narrower than this are dropped. |
| `--halfWidth <n>` | a whole number, at least 0, in bp | `0` | *Peaks.* Fixed half-width: 0 keeps each peak’s concave bounds; otherwise this many bases each side of its summit. |
| `--truncate <n>` | a whole number, at least 1 | `100000` | *Peaks.* Keep the strongest: By each track’s curvature rank, before IDR; with one track, the only cut. |

### Base composition — `composition`

GC content, GC skew and AT skew per bin, as tracks.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** GC, GC skew, AT skew.

```sh
chromosomix composition [<map>] --sequence <sequence.fa> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequence <file>` | a file: a reference sequence | — | Reference: The FASTA to read, under the names of the sequences open. |
| `--resolution <n>` | a whole number, at least 1, in bp | Worked out from the map's bin size when left out; 10000 where there is no map. | Bin size: The open map’s resolution unless changed, and 10 kb with no map open. |
| `--window <n>` | a whole number, at least 0, in bp | `0` | Window: 0 reads each bin alone; wider reads that many bases centred on it. |
| `--gc / --no-gc` | on or off | on | *Tracks.* GC content. |
| `--gcSkew / --no-gcSkew` | on or off | on | *Tracks.* GC skew: (G − C) / (G + C), which changes sign at the origin and the terminus. |
| `--atSkew / --no-atSkew` | on or off | on | *Tracks.* AT skew: (A − T) / (A + T). |
| `--cumulative / --no-cumulative` | on or off | on | *Tracks.* Cumulative GC skew: Its minimum is the origin and its maximum the terminus. |

### Origin and terminus — `oriter`

Where replication starts and ends, from the GC skew, parS, matS and coverage.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model); a table: TSV; a value per bin: TSV, bedGraph and bigWig.
- **Also known as:** ori, ter, replication, GC skew, dif.

```sh
chromosomix oriter [<map>] --sequence <sequence.fa> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--sequence <file>` | a file: a reference sequence | — | Reference: The FASTA to read the skew and the sites from. |
| `--sequences <name,…>` | sequence names, comma-separated | Every sequence of the file when left out. | Sequences. |
| `--coverage <file>` | a file: a signal track; optional | not used | Coverage: Raw Hi-C coverage: breaks a tie, and gives the ori/ter ratio. |
| `--window <n>` | a whole number, at least 100, in bp | `5000` | *GC skew.* Skew window. |
| `--step <n>` | a whole number, at least 10, in bp | `1000` | *GC skew.* Skew step. |
| `--parS <text>` | text | `TGTTNCACGTGNAACA` | *Sites.* ParS motif: Sites cluster round the origin; empty skips them. |
| `--parSMismatches <n>` | a whole number, 0 to 4 | `1` | *Sites.* ParS mismatches. |
| `--matS <text>` | text | `GTGACRNYGTCAC` | *Sites.* MatS motif: Ten or more sites place the terminus; empty skips them. |
| `--matSMismatches <n>` | a whole number, 0 to 4 | `0` | *Sites.* MatS mismatches. |
| `--knots <n>` | a whole number, 4 to 40 | `10` | *Coverage.* Spline knots: Of the cubic spline the coverage is smoothed with. *Read only under other settings of this task.* |

### Metaplot over a feature set — `metaplot`

Average track signal at a set of places, with a band and a heatmap.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a curve: TSV; a matrix, a pileup or a heatmap: TSV.
- **Also known as:** profile, aggregate, average, TSS, deeptools.

```sh
chromosomix metaplot [<map>] --tracks <tracks.bw> --features <features.bed> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--tracks <file,…>` | files: a signal track | — | Tracks. |
| `--features <file>` | a file: a feature set | — | Features. |
| `--mode <value>` | `reference` or `scaled` | `reference` | Mode. `reference` — a fixed flank around one point; `scaled` — every feature body resampled to one width. |
| `--at <value>` | `start`, `centre` or `end` | `start` | Anchor on. |
| `--flank <n>` | a number, at least 0, in bp | `2000` | Flank: Read this far either side of the anchor. |
| `--step <n>` | a number, at least 1, in bp | `50` | Resolution: One column of the plot per this many base pairs. |
| `--body <n>` | a whole number, at least 10 | `100` | Body columns. *Read only under other settings of this task.* |
| `--stranded / --no-stranded` | on or off | on | Respect strand: A minus-strand feature is read right to left, or an asymmetric signal cancels itself. |
| `--rankBy <column>` | a numeric column of the set `--features` names; optional | not used | *Ranking.* Rank by. |
| `--subset <value>` | `all`, `top`, `bottom` or `groups` | `all` | *Ranking.* Then. `all` — rank only; still one average; `top` — top N; `bottom` — bottom N; `groups` — one line per equal-sized group. *Read only under other settings of this task.* |
| `--count <n>` | a whole number, at least 1 | `500` | *Ranking.* N. *Read only under other settings of this task.* |
| `--groups <n>` | a whole number, 2 to 10 | `4` | *Ranking.* Groups. *Read only under other settings of this task.* |
| `--zscore / --no-zscore` | on or off | off | *Summary.* Z-score tracks first: Centre and scale each track by its own mean and SD over this run’s windows, so tracks in different units share one axis. |
| `--average <value>` | `mean`, `median` or `trimmed` | `mean` | *Summary.* Average. |
| `--band <value>` | `bootstrap`, `sd` or `none` | `bootstrap` | *Summary.* Band. `bootstrap` — bootstrap CI; `sd` — SD. |
| `--iterations <n>` | a whole number, 20 to 2000 | `200` | *Summary.* Bootstrap draws. |
| `--seed <n>` | a seed, a whole number | `1` | *Summary.* Seed: The same seed gives the same band twice. |
| `--heatmap / --no-heatmap` | on or off | on | *Summary.* Per-feature heatmap: The mean of a bimodal set is a line that describes nothing. |

### Track correlation — `trackcorr`

How much every pair of loaded tracks agrees.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a matrix, a pileup or a heatmap: TSV; a table: TSV.
- **Also known as:** Pearson, Spearman, compare tracks.

```sh
chromosomix trackcorr [<map>] --tracks <tracks.bw> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--tracks <file,…>` | files: a signal track | — | Tracks. |
| `--over <value>` | `bins` or `features` | `bins` | Compare over. `bins` — everywhere, including the empty majority; `features` — only where something is happening. |
| `--binsize <n>` | a whole number, at least 1, in bp | `100` | Window. |
| `--features <file>` | a file: a feature set | — | Features. *Read only under other settings of this task.* |
| `--method <value>` | `spearman` or `pearson` | `spearman` | Method. `spearman` — rank-based; robust to one very deep locus; `pearson` — pearson. |

### Fraction of signal in features — `frip`

How much of each track sits inside a feature set, against how much of the genome it is.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a table: TSV.
- **Also known as:** FRiP, reads in peaks, enrichment.

```sh
chromosomix frip [<map>] --tracks <tracks.bw> --features <features.bed> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--tracks <file,…>` | files: a signal track | — | Tracks. |
| `--features <file>` | a file: a feature set | — | Features. |
| `--resolution <n>` | a whole number, at least 0, in bp | `0` | Read features at: 0 is auto: about 50 samples across a feature of the set’s median width. |
| `--perFeature / --no-perFeature` | on or off | off | Score every feature: One row per feature, so a FRiP carried by a handful of them can be seen to be. |

### Signal by group — `groupsignal`

A track’s values in each group of the genome — A against B — compared and tested.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a curve: TSV; a table: TSV; a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model).
- **Also known as:** A versus B, compartment signal, box plot, test.

```sh
chromosomix groupsignal [<map>] --tracks <tracks.bw> --features <features.bed> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--tracks <file,…>` | files: a signal track | — | Tracks: The values compared between the groups. |
| `--groupBy <value>` | `features` or `track` | `features` | Groups from. `features` — its intervals, split by what is written on them: A and B on a compartment call; `track` — its bins, cut by sign or into quantiles: an eigenvector’s two compartments. |
| `--features <file>` | a file: a feature set | — | Features. |
| `--split <value>` | `name`, `strand`, `score` or `none` | `name` | Split the set by. `name` — one group per name the features carry; `score` — score, in quantiles; `none` — nothing: one group. |
| `--outside / --no-outside` | on or off | on | The rest as a group: Every base the set does not cover, as one more group. |
| `--groupTrack <file>` | a file: a signal track; optional | not used | Grouping track. *Read only under other settings of this task.* |
| `--cut <value>` | `sign` or `quantiles` | `sign` | Cut it by. `sign` — above zero and below it; `quantiles` — equal numbers of bins, lowest to highest. *Read only under other settings of this task.* |
| `--quantiles <n>` | a whole number, 2 to 10 | `4` | Quantiles. *Read only under other settings of this task.* |
| `--resolution <n>` | a whole number, at least 0, in bp | `0` | Bin size: 0 compares one value per entry — a run of features, the stretch between two, a run of bins in one group — and any other size compares stretches of at most that many bases. |
| `--perFeature / --no-perFeature` | on or off | off | Score every feature: A row per feature of the set, its mean on every track. |

### Interval set overlap — `overlap`

Jaccard, shared bases, how many features touch — and whether that is more than chance.

- **Reads:** tracks and interval files, with or without a contact map.
- **Writes:** a table: TSV.
- **Also known as:** intersect, Jaccard, bedtools.

```sh
chromosomix overlap <map> --features <a.bed> --a <a.bed> --features <b.bed> --b <b.bed> [--<parameter> <value> …] --out <dir>
```

| Flag | Takes | Default | What it is |
|---|---|---|---|
| `--a <file>` | a file: a feature set | — | First set. |
| `--b <file>` | a file: a feature set | — | Second set. |
| `--minFraction <n>` | a number, 0 to 1 | `0.000001` | Least of a feature covered: A feature counts as hit when this fraction of it is inside the other set. |
| `--shuffle / --no-shuffle` | on or off | off | Shuffled null: Relocates one set at random within the sequences it already occupies, keeping its count and its lengths, and reports the observed overlap against that null. |
| `--shuffleWhich <value>` | `a` or `b` | `a` | Set that moves. `a` — “Are the first set’s features on the second’s?”; `b` — the second. *Read only under other settings of this task.* |
| `--iterations <n>` | a whole number, 20 to 100000 | `1000` | Shuffles: The smallest p a run can report is one over this, plus one. *Read only under other settings of this task.* |
| `--seed <n>` | a seed, a whole number | `1` | Seed: The same seed gives the same null twice. *Read only under other settings of this task.* |

---

# Embedding and driving chromosomix

> The viewer goes inside any web page as an `<iframe>`, with nothing to install and no script to load: the `src` is a link to the view, with `?embed=1`. The page around it can then drive it by `postMessage` — move it, add tracks to it, and be told where the reader has taken it. The Jupyter widget and the R htmlwidget are this same frame, driven from Python and R.

## An iframe

```html
<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" loading="lazy" style="border: 0"
  title="Micro-C of yeast chromosome IV"></iframe>
```

- The `src` is a link to a view, as [the links page](https://chromosomix.app/llms/links.md) writes one, with `?embed=1` before the `#`. Or `?embed=1&config=<URL>` for a saved workspace — several tabs, their tracks, colours and marks.
- The frame is the view alone: no header, no tab strip, no status bar. The Annotations and Aesthetics panels are there, folded, because they are controls over the picture; the Files, General and Analysis panels are not. Add `&panels=open` to the query to open them both (`panels=annotations` or `panels=aesthetics` for one). A reader can still drop a file of their own on it.
- The view fills the frame and follows its size, so a frame the reader can resize is a box away: see *A frame the reader can resize*, below.
- For a figure that must not change, pin a release: `https://chromosomix.app/v/<tag>/?embed=1#…`. The root is the newest build, and changes with it.
- Nothing is needed of the page around it — no `Cross-Origin-Opener-Policy`, no `Cross-Origin-Embedder-Policy` — and nothing of the data host beyond what any link needs: the frame’s requests come from the viewer’s origin, so a bucket whose CORS admits the viewer admits every page that embeds it.
- An embed writes nothing to the reader’s storage and adds nothing to their back button: it shows what its `src` says, every time it loads.

## A frame the reader can resize

Put the frame in a box the browser lets the reader resize by its corner. The padding keeps the corner’s grip clear of the frame, which would cover it, and the script lets the pointer through the frame while the box is dragged, without which the drag stalls as soon as it shrinks the box under the hand:

```html
<div class="chromosomix-frame"
  style="resize: both; overflow: hidden; width: 100%; height: 640px; padding-bottom: 14px; box-sizing: border-box">
  <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"
    style="display: block; width: 100%; height: 100%; border: 0" loading="lazy"
    title="Micro-C of yeast chromosome IV"></iframe>
</div>
<script>
  for (const box of document.querySelectorAll('.chromosomix-frame')) {
    box.addEventListener('pointerdown', (event) => {
      if (event.target === box) box.querySelector('iframe').style.pointerEvents = 'none'
    })
  }
  addEventListener('pointerup', () => {
    for (const frame of document.querySelectorAll('.chromosomix-frame iframe')) frame.style.pointerEvents = ''
  })
</script>
```

## The channel

Six messages, each an object with a `type`. Protocol version 1; a message is added without changing the number, so a host reads which messages a frame takes from its `ready`.

| Message | Direction | Fields | What it is |
|---|---|---|---|
| `chromosomix:ready` | frame → page | `protocol`, `version`, `commit`, `accepts` | Sent once, when the frame is listening. `accepts` lists the messages it takes. It carries nothing about what is on screen. |
| `chromosomix:where` | page → frame | — | Where is the view? Answered with `chromosomix:state`. |
| `chromosomix:navigate` | page → frame | `state` | Go here. `state` is a **patch** laid over the view on screen: any key a link carries, so `{ locus: "IV:1,000,001-1,100,000" }` moves a 1D browser and `{ transform: "log2", oe: true }` re-colours a map. A key given `null` is removed; `state: null` is the landing page. Answered with `chromosomix:state`, saying where the view actually went. |
| `chromosomix:add` | page → frame | `files` | Put these addresses in the tab, in order, as the app’s `+` does: a track among the tracks, a map or a 3D model beside the map; on an empty tab the first is its file. `http(s)` only, at most 64. Waits for the first picture, and is answered with `chromosomix:state` once every file is in. Builds before 0.17.0 do not take it. |
| `chromosomix:state` | frame → page | `state` | The view: an object of the keys a link carries (`uri`, `view`, `region`, `locus`…), or `null` for the landing page. Sent in answer, and on every move once the page has spoken. |
| `chromosomix:rendered` | frame → page | `report` | A picture is finished: `report.status` is `drawn`, `gated` (waiting for the reader to agree to a large read) or `error`, with `report.maps` (each map’s `title`, `binsize`, `resolution`, `rows`, `cols`), `report.lanes` and `report.state`, the view as a hash string. What to take a screenshot on. |

- **The page speaks first.** The frame answers only the window that framed it, and only once that window has sent it something; `chromosomix:ready` is the one message it sends unasked. Listen before the frame loads — put the script ahead of the `<iframe>`, or set its `src` from the script — so as not to miss it.
- **Replies go to the origin the page spoke from**, never to `*`: the reader may open their own file in the frame, and only the page that asked is told.
- **Messages are carried out in the order they came.** A `navigate` sent after an `add` waits for the files to open, and is laid over the view they opened.
- **A patch is read as a link is**: a key the frame does not know is dropped, a value it cannot read is ignored. Read the answer to know where the view went.

### A host page

```js
const frame = document.querySelector("iframe")
const viewer = new URL(frame.src).origin
const send = (message) => frame.contentWindow.postMessage(message, viewer)

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow) return
  const message = event.data
  if (message?.type === "chromosomix:ready") {
    if (message.accepts?.includes("chromosomix:add")) {
      send({ type: "chromosomix:add", files: ["https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/yeast/Yeast_ATAC.bw"] })
    }
    send({ type: "chromosomix:navigate", state: { region: "IV:1100000-1300000" } })
  }
  if (message?.type === "chromosomix:state") console.log("the view is at", message.state)
  if (message?.type === "chromosomix:rendered") console.log("drawn:", message.report.status)
})
```

## In a Jupyter notebook

The same frame as an anywidget, in JupyterLab, Notebook 7, VS Code, Colab and marimo. A file is an address or a path on the kernel’s disk, which the kernel serves to the frame by byte range from `127.0.0.1`, sidecars and all; nothing is uploaded.

```python
# pip install "git+https://github.com/js2264/chromosomix#subdirectory=widgets/python"   (not on PyPI)
from chromosomix import Chromosomix
view = Chromosomix("sample.mcool::/resolutions/5000", region="chr2:10000000-14000000",
                   tracks=["ATAC.bw", "genes.gtf.gz"], transform="log10")
view                                        # the map, its tracks, its side panels
view.goto("chr2:11000000-12000000")         # a region, or a locus in the 1D browser
view.navigate(transform="log2", oe=True)    # any key a link carries; None removes one
view.add("model.g3d.gz")                    # a track, a map or a 3D model beside the map
view.state                                  # where the reader is: a traitlet to observe
view.rendered                               # the last finished picture
```

`viewer="0.17.0"` pins the build in the frame to a release; `chromosomix.install_viewer()` fetches one to serve beside the data, which is what makes local files work behind JupyterHub and offline.

## In R: R Markdown, Quarto and Shiny

```r
remotes::install_github("js2264/chromosomix", subdir = "widgets/r")

library(chromosomix)
chromosomix("sample.mcool::/resolutions/5000", region = "chr2:10000000-14000000",
            tracks = c("ATAC.bw", "genes.gtf.gz"), transform = "log10") |>
  chromosomix_goto("chr2:11000000-12000000") |>
  chromosomix_navigate(oe = TRUE) |>
  chromosomix_add("model.g3d.gz")
```

In Shiny, `chromosomixOutput()`, `renderChromosomix()` and `chromosomixProxy()` drive a view on screen, and `input$<id>_state` follows the reader. A page knitted for others names its files by address: a local file is served only while the R session that rendered the page runs.

Both widgets are documented in the repository: [Python](https://github.com/js2264/chromosomix/blob/main/widgets/python/README.md), [R](https://github.com/js2264/chromosomix/blob/main/widgets/r/README.md).

---

# chromosomix files, hosting, stores and workspaces

> What chromosomix opens, and how: files are read where they are — on the reader’s disk, never uploaded, or from any host that serves byte ranges with CORS — in their own formats, with no preprocessing. This page lists the formats and the sidecars they read, what a host must serve, the built-in data stores, and the two JSON files a lab writes to publish its data: a store, which is a catalogue, and a workspace, which is a composed view.

## Formats

| What | Formats |
|---|---|
| Contact maps | `.cool`, `.mcool` (every resolution), `.hic` (versions 7 to 9, every resolution), `.scool` (cells summed), HiC-Pro maps (the `.matrix` with its `_abs.bed`, gzipped or not), `.pairs` and `.pairs.gz` (binned on opening, at a resolution the reader picks) |
| Signal | bigWig, bedGraph, wig, bedMethyl and bigMethyl, barChart and bigBarChart |
| Intervals and annotations | BED, narrowPeak and broadPeak, bigBed, GTF and GFF3, genePred, refFlat and bigGenePred, VCF, cytoBand, splice junctions (STAR’s `SJ.out.tab`, junctions BED) |
| Interactions | BEDPE, `interact` and `bigInteract`, `longrange` |
| Reads | BAM, with its `.bai` beside it |
| Sequence | FASTA (read by range with its `.fai` beside it), `.2bit`, `chrom.sizes` |
| 3D models | g3d (text or binary), `.3dg`, bed3d, PDB |
| Collections | a UCSC track hub (`hub.txt`), a store, a workspace (`.chromosomix.json`) |

- A bgzipped text file with its tabix index (`.tbi`) beside it is read by range; one without is read whole.
- A file is told by its name first and its bytes second, so a `.txt` or `.tsv` of a known format opens too.
- A container’s group follows `::`: `sample.mcool::/resolutions/10000`, `sample.hic::/resolutions/5000`.
- A map opens as a map; any other file opens as a track over it, or — with no map — as a 1D genome browser over the assembly it declares.

## Where files can be read from

- **The reader’s own disk**: dropped on the window, picked, or in a connected folder. Read in place by the browser; nothing leaves the machine. A link cannot name such a file, since only the reader has it.
- **Any `https://` address** whose host serves byte ranges with CORS: S3, Google Cloud Storage, Cloudflare R2, Azure, and most static web servers. `s3://bucket/key` and `gs://bucket/key` are read as the public addresses they stand for.
- **Dropbox and Google Drive share links**, and a private Drive or Dropbox the reader signs in to.
- **A private bucket**, with a key the reader enters, kept in their browser.
- **Not GEO or SRA**: their downloads serve no ranges and no CORS. Deposit there, and serve a copy from a bucket for viewing.

### What a host must serve

| Requirement | Why |
|---|---|
| `Accept-Ranges: bytes` | Every read is a byte range; without them a 4 kB lookup downloads the file. |
| CORS allowing `GET` and `HEAD` and the `Range` request header, and exposing `Content-Length` and `Content-Range` | The app runs on another origin than the data. The exposed headers are what is most often forgotten. |
| No `Content-Encoding` | A range of a compressed response is a range of the compressed bytes. Serve `.gz` files as they are. |
| `Content-Type: application/octet-stream` | Keeps a CDN from sniffing and transforming the body. |

An S3-compatible bucket’s CORS rule:

```json
[
  {
    "AllowedOrigins": ["https://chromosomix.app"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["Range", "If-Match", "If-None-Match"],
    "ExposeHeaders": ["Content-Length", "Content-Range", "ETag", "Accept-Ranges"],
    "MaxAgeSeconds": 86400
  }
]
```

`["*"]` as the origin suits released data and lets every copy of the viewer read it. A presigned URL opens and works until it expires, so it is for sharing today, not for a paper.

## Data stores

A store is a searchable catalogue of files, opened over the app from the landing page or by `https://chromosomix.app/?store=<id>`, with `&q=<text>` to search it and `&<column>=<value>` to tick a facet. The built-in ones:

| `?store=` | Store | What it holds |
|---|---|---|
| `rsg` | [RSG lab data](https://research.pasteur.fr/fr/team/spatial-regulation-of-genomes/) | Demos of the viewer and the figures of the lab’s papers, over yeast, human, chicken, mouse and bacterial data, one click each. |
| `igv` | [IGV genomes](https://igv.org/doc/desktop/#FileFormats/Genomes) | IGV’s reference genomes, each with the tracks it ships, ready for the 1D browser. |
| `4dn` | [4DN open data](https://data.4dnucleome.org/) | Every file on the 4DN open-data bucket, by cell line, assay, lab and experiment set. |
| `encode` | [ENCODE](https://www.encodeproject.org/matrix/?type=Experiment) | ENCODE’s released signal, peaks and alignments, one file per experiment, by assembly. |
| `dnazoo` | [DNA Zoo](https://www.dnazoo.org/) | Chromosome-length genome assemblies and the Hi-C maps behind them, a directory a species. |
| `roadmap` | [Roadmap (UCSC hub)](https://egg2.wustl.edu/roadmap/web_portal/) | The Roadmap Epigenomics integrative tracks, as the hub WashU publishes them. |

Any UCSC track hub is a store too: `https://chromosomix.app/?store=<address of hub.txt>` opens its genomes and tracks. So is a store file of a lab’s own, by its address.

### A store file

A JSON file, on any host that serves CORS, listing files with enough about each to choose one without opening it. A `uri` resolves against `base`, or against the store’s own address when there is no `base`, so a store beside its data can be copied anywhere with it. An entry’s `kind` is `map`, `genome` (a track or reference) or `workspace`, and is read from the file name when left out; `tracks` are offered beside a map once it is open. Unknown keys are ignored. The repository’s `scripts/make_store.py bucket <address>` writes one from a bucket’s listing, and `make_store.py check <store.json>` validates one.

```json
{
  "kind": "chromosomix.store",
  "version": 1,
  "name": "My lab’s maps",
  "description": "Micro-C and ATAC-seq of yeast, by condition.",
  "base": "https://example.org/data/",
  "columns": [
    { "key": "assay", "label": "Assay" },
    { "key": "condition", "label": "Condition" }
  ],
  "entries": [
    {
      "label": "Micro-C, G2/M",
      "uri": "microC_G2M.mcool",
      "kind": "map",
      "size": 1250000000,
      "fields": { "assay": "Micro-C", "condition": "G2/M" },
      "note": "GEO GSE000000",
      "tracks": [
        { "label": "ATAC-seq", "url": "ATAC_G2M.bw" }
      ]
    },
    {
      "label": "Micro-C with its tracks, as in the paper",
      "uri": "figure2.chromosomix.json",
      "kind": "workspace",
      "fields": { "assay": "Micro-C", "condition": "G2/M" }
    }
  ]
}
```

## Workspaces

A workspace is every tab of a window in one file, `<name>.chromosomix.json`: each tab’s view, as the keys of a link, and everything a link cannot carry — its tracks with their colours, heights and groups, marks and bookmarks, the deck beside the map, the analyses it ran and their parameters. The app’s save button writes one. It opens by being dropped on the window, by `https://chromosomix.app/?config=<address>`, or as a store entry, and `chromosomix replay` runs its analyses again over other files.

- A relative name inside one resolves against the workspace’s own address, so a workspace published beside its data is self-contained.
- `state` takes the keys of a link (see the [links page](https://chromosomix.app/llms/links.md)), as JSON values.
- Only `kind`, and a `state.uri` in each tab, are required; a missing field is a default, and a tab that cannot be read is dropped while the others open.
- A track is best recorded by the app: open the files, arrange them, and save. To write one by script, start from a saved workspace — the yeast demo’s is https://rsglab-data.s3.eu-west-3.amazonaws.com/demo/store/yeast/Yeast_microC.chromosomix.json — and change its addresses.
- In an embed or a widget, `chromosomix:add` puts tracks beside a view without a workspace (see [embedding](https://chromosomix.app/llms/embed.md)).

The smallest workspace, which opens one tab on chromosome IV of a map beside it:

```json
{
  "kind": "chromosomix.workspace",
  "version": 1,
  "active": 0,
  "tabs": [
    {
      "name": "Chromosome IV",
      "state": {
        "uri": "Yeast_microC_G2M_1kb.cool",
        "view": "region",
        "region": "IV:1000000-1400000",
        "transform": "log10",
        "balance": true
      }
    }
  ]
}
```