SituCraft

Remote control

A program on your computer (a script, a notebook, the screenshots on this site) can drive the open SituCraft window. The window performs each action where you see it, and what an action changes goes into the project's history like any edit, so you can undo it.

Starting it

$ situcraft --remote-control

SituCraft prints where scripts send actions, and writes remote.json to its data folder (where things are kept) with the address and a token. The file is readable by you alone and removed when SituCraft stops.

Sending an action

POST {"action": …, "args": {…}, "client": …} to /api/remote/action; the answer is {"ok": …, "message": …, "data": …}. In Python, with only the standard library:

import json, pathlib, urllib.request

info = json.loads((pathlib.Path.home() / "Library/Application Support/SituCraft/remote.json").read_text())

def act(action, **args):
    request = urllib.request.Request(
        info["url"] + "/api/remote/action",
        data=json.dumps({"action": action, "args": args, "client": "notebook"}).encode(),
        headers={"Content-Type": "application/json", "X-SituCraft-Token": info["token"]},
    )
    answer = json.load(urllib.request.urlopen(request, timeout=3600))
    if not answer["ok"]:
        raise RuntimeError(answer["message"])
    return answer

act("open_example", example="lung")
act("cluster_cells")
act("label_cells", markers="lung")
print(act("methods")["message"])

Actions run one at a time, in the window most recently opened from this run of SituCraft. Most answer within seconds; those that build derived data, download an example or run a long job may take minutes. GET /api/remote/tools lists every action with its arguments as a JSON schema, under an API version that changes only when an action, an argument or a result's field is removed or changes its meaning.

Python and R

The situcraft packages for Python and R make each action a function, with its arguments and help: they find the running SituCraft through its remote.json, give tables as data frames (each column of one type) and pictures as files, and raise SituCraft's reason when it refuses an action. They are generated from the list of actions, so they always have every one.

$ pip install "git+https://github.com/robert-mcdermott/situcraft#subdirectory=clients/python"
import situcraft

sc = situcraft.connect()
sc.open_example("simulated")
sc.cluster_cells()
labels = sc.label_cells(markers="simulated")
cells = sc.query_cells({"labels": labels["id"], "in": ["immune-like"]}, limit=0).frame("rows")
sc.show_tissue(fill="labels", file="tissue.jpg")
remotes::install_github("robert-mcdermott/situcraft", subdir = "clients/r")
library(situcraft)
sc_connect()
sc_open_example("simulated-cohort")
sc_design(unit = "subject", group = "condition", reference = "control", save = "By condition")
sc_cohort_steps(markers = "simulated")
sc_summarize_samples()
compared <- sc_compare_expression(design = "By condition")
tests <- as.data.frame(sc_get_result(compared$data$id, limit = 0))

Two worked examples come with them, a Python notebook on the simulated tissue (its labels against the true types, their neighbors, its recipe) and an R script on the simulated cohort (the gene the simulator changed in one cell type, found between the conditions): clients.

What it can do

Every view's work: projects and data (open bundles and examples, add datasets), seeing the tissue (genes, stains, layers, a cell, any segmentation's fill), regions and reviews, saved views, segmentations (expand, refine, import, compare, decide, export), cell types (cluster, map, label from markers or a reference, import labels, review), post-Xenium images and their alignment, spatial analysis (graphs, every question, an answer made again on another segmentation), quality control (filters, metrics), figures, and the record (the methods paragraph, what made a result). The remote control reference lists each action with its arguments and what it answers.

Security