Install SituCraft

SituCraft 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/situcraft/main/install.sh | sh

Installs the latest release as ~/.local/bin/situcraft. 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/situcraft/main/install.ps1 | iex

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

Start it

$ situcraft

SituCraft starts a local server on http://127.0.0.1:8840 (or the next free port) 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.

Bundles named on the command line (their folder, their .zip or their experiment.xenium, or folders of them) open directly, and running situcraft <paths> again while it is open hands them to the open window:

$ situcraft /path/to/Xenium_output_bundle

Then continue with Getting started.

Requirements

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

The window is a page in a current browser with WebGL2; SituCraft 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

16 GB is recommended for whole sections; 8 GB is enough for the examples and smaller sections. What takes memory, as measured:

Work	Memory at its peak
Opening, viewing and checking the examples (2 fields of view)	under 1 GB
Refining a segmentation	about 100 bytes a transcript: under 0.3 GB for an example, 5 to 7.4 GB for 55 million transcripts
Clustering, mapping and labeling 380,000 cells	4.3 GB
Spatial analyses of a million cells	under 2 GB; nearest distances and Ripley's K 3 to 4 GB

Before a refinement starts, the segmentation studio estimates its memory, disk and time against the computer's, and refuses a run that would not fit.

Options

To install a particular release, or somewhere else:

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

In PowerShell, set $env:SITUCRAFT_VERSION and $env:SITUCRAFT_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 are in Troubleshooting.

Upgrading and uninstalling

Run the installer again to upgrade; it replaces the program only after every check passes. On Windows, stop SituCraft 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/situcraft, or %LocalAppData%\Programs\SituCraft 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/situcraft.git
$ cd situcraft
$ go build -o situcraft .