Install ClonoLoom

ClonoLoom is one executable. The browser application is inside it, so nothing else needs to be installed; example data are downloaded only when you ask. One command downloads the release for your computer, checks it and installs it.

$ curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/robert-mcdermott/clonoloom/main/install.sh | sh

Installs the latest release as ~/.local/bin/clonoloom. No sudo, and your PATH is left as it is; if ~/.local/bin is not on it, the installer prints the full path to run.

PS> irm https://raw.githubusercontent.com/robert-mcdermott/clonoloom/main/install.ps1 | iex

Run in PowerShell. Installs to %LocalAppData%\Programs\ClonoLoom and adds it to your user PATH. No administrator rights and no change to the execution policy needed.

Start it

$ clonoloom

ClonoLoom starts a local server on http://127.0.0.1:8860 (or the next free port up to 8879) and opens its window. If Chrome, Edge, Brave or Chromium is installed, the window is a desktop app window with its own profile; otherwise your default browser is used. Closing the window stops the program. On Windows, open a new terminal after installing so that it sees the updated PATH.

Files and folders named on the command line (AIRR tables, Cell Ranger output folders, immunoSEQ exports, MiXCR clone tables, OAS and OTS units, tcrdist3 clone tables, or folders of them) open directly as one dataset, and running clonoloom <paths> again while it is open hands them to the open window:

$ clonoloom /path/to/airr_rearrangement.tsv

Then continue with Getting started.

Requirements

Operating system	Architecture	Release file
macOS	Apple silicon (ARM64)	`clonoloom-darwin-arm64`
macOS	Intel (x64)	`clonoloom-darwin-amd64`
Linux	x64	`clonoloom-linux-amd64`
Linux	ARM64	`clonoloom-linux-arm64`
Windows	x64	`clonoloom-windows-amd64.exe`
Windows	ARM64	`clonoloom-windows-arm64.exe`

The window is a page in a current browser; ClonoLoom is tested in Chrome and the browsers built on Chromium. Each release has SHA256SUMS, the checksum of every file; the installers require exactly one matching checksum and run the downloaded program's --version before moving it into place, so a failed download never replaces a working copy.

Memory follows the data: a million rearrangements take about 130 MB once read (58 bytes a row and their junctions), and a cohort's tables are kept in a cache on disk so that it reopens in a fraction of a second.

Options

To install a particular release, or somewhere else:

$ curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/robert-mcdermott/clonoloom/main/install.sh | CLONOLOOM_VERSION=v0.9.0 CLONOLOOM_INSTALL_DIR="$HOME/bin" sh

In PowerShell, set $env:CLONOLOOM_VERSION and $env:CLONOLOOM_INSTALL_DIR before the same command. To read an installer before running it, download it first; INSTALLING.md describes every option, and how to install by hand.

The program's own options:

Flag	Default	What it does
`--port`	8860	Preferred port; the next free one up to 8879 is used if it is taken
`--window`	`app`	`app` (a desktop window), `browser` (the default browser) or `none`
`--keep-running`	off	Keep serving after the window is closed
`--data-dir`	your configuration folder's `ClonoLoom`	Where the project library is kept
`--examples-dir`	`<data dir>/examples`	Where example data are downloaded, when you ask
`--cache-dir`	your cache folder's `clonoloom`	Where tables read once are kept, to reopen datasets quickly; can be deleted at any time
`--cache-limit`	`10GB`	The size the cache is kept within, removing what was used least recently (`0` for no limit)
`--offline`	off	Download nothing: ClonoLoom then reaches no other computer
`--remote-control`	off	Let programs on this computer drive the window (remote control)
`--host`	127.0.0.1	Interface to bind
`--version`		Print `clonoloom X.Y.Z` and exit

Upgrading and uninstalling

Run the installer again to upgrade; it replaces the program only after every check passes. On Windows, stop ClonoLoom first. To go back, install the release you want by its tag. Each release opens the projects earlier releases saved.

To uninstall, delete the program (~/.local/bin/clonoloom, or %LocalAppData%\Programs\ClonoLoom and its PATH entry). Your projects and the cache stay where they are (where things are kept) until you delete them.

Building from source

With Go (the version in go.mod or newer), and nothing else:

$ git clone https://github.com/robert-mcdermott/clonoloom.git
$ cd clonoloom
$ go build -o clonoloom .