Remote control

A program on your computer (a script, a notebook, the documentation's screenshot capture) can drive the open ClonoLoom window. Each action is performed in the window, where you see it, and what it changes goes into the project's history like any edit of yours, so it can be undone.

In ClonoLoom 0.9.0, API 2 defaults to read-only. Non-read calls require explicit startup capabilities and a token; edits also require a named proposal accepted in the window. Read Automation permissions before running these examples.

To connect an AI assistant, read AI agents (MCP); both transports share the same policy.

Turn it on

$ clonoloom --remote-control

ClonoLoom then writes remote.json to its library folder (where things are kept): its address and a token. The file is readable by you only, and removed when ClonoLoom stops. Keep a ClonoLoom window open: actions are performed by the window most recently opened.

Send an action

POST {"action": …, "args": {…}, "client": "what your program calls itself"} to /api/remote/action; the answer is {"ok": true|false, "message": …, "data": …}. In Python, with the standard library alone:

import json, pathlib, urllib.request

info = json.loads(pathlib.Path("~/Library/Application Support/ClonoLoom/remote.json").expanduser().read_text())

def act(action, **args):
    request = urllib.request.Request(info["url"] + "/api/remote/action",
        data=json.dumps({"action": action, "args": args, "client": "my notebook"}).encode(),
        headers={"Content-Type": "application/json", "X-ClonoLoom-Token": info["token"]})
    return json.load(urllib.request.urlopen(request))

act("open_example", example="simulated-standard")
act("annotate_samples", samples={"S01-1": {"timepoint": "day 0"}, "S01-2": {"timepoint": "day 0"}})  # replicates
diversity = act("measure_diversity")["data"]
print(act("show_methods")["data"]["text"])

Check a cohort design

check_cohort_design checks an explicit subject-level design. Send spec: {unit: "subject", layout: "independent", groupField: "condition", levels: ["control", "expanded"], exclude: {sample: "reason"}}, plus optional dataset, name and save: true. Use layout: "paired" for within-subject observations. The answer includes sample membership, subject counts, findings and citations; it performs no statistical test. See Cohort study design.

The actions

Action	What it does
`get_state`	The project: its datasets (format, unit, rows, samples, findings, filter, definition, license and citation of public data), the view shown, the example datasets
`new_project`	Starts a new project
`open_data`	Opens files or folders as one dataset; another tool's table through a mapping of its columns (needs the token)
`open_example`	Opens an example dataset, downloading openly licensed data first when asked
`show`	Shows a view, with a dataset in focus
`set_definition`	Chooses a dataset's clonotype definition: a preset by name, or one stated in full
`annotate_samples`	Sets samples' subject, time point, reference role, tissue, cell subset, condition, batch and HLA
`describe_subjects`	Answers each subject's samples in time order, its reference samples and replicates, and the checks' findings
`track_clonotypes`	Follows a reference sample's largest clonotypes, each sample's largest, a list, a test's calls or a class through each subject's time points, and answers each one's frequency with its interval
`class_clonotypes`	Classes each clonotype of each subject across time points against a base, and answers each subject's clonotypes by class
`attribute_samples`	Measures each sample against its subject's reference sample, and answers the shares with their intervals
`test_expansion`	Tests each clonotype between two time points of each subject (the beta-binomial test where replicates allow), and answers the fit and each subject's calls with their p-values
`select_clonotype`	Chooses a clonotype by its rank in the table or its ID
`measure_diversity`	Measures each sample's diversity and answers the main measures with their intervals
`rarefy`	Rarefies and extrapolates each sample and answers each at a chosen level
`gene_usage`	Counts genes, junction lengths and amino acids, and answers the most used genes and commonest lengths
`measure_overlap`	Measures every pair's overlap and answers the most overlapping pairs and the public clonotypes
`show_examples`, `show_methods`, `set_theme`, `close_dialogs`	The Example data dialog; a dataset's methods paragraph with its references; the theme; closing dialogs

Every action's arguments are in the remote control reference; GET /api/remote/tools lists them as JSON Schema.

What is allowed

Only programs on this computer: requests from other computers, and web pages that reach the loopback port under another name, are refused.
Every non-read action needs explicit startup grants and the X-ClonoLoom-Token header with the token in remote.json, so another user of a shared computer cannot make your ClonoLoom read your files.
Data under a provider's terms of use (the immuneACCESS example) are never downloaded by a program: only you can accept their terms, in the window.
One action runs at a time, in the order they come.

Invariant-population annotation

flag_invariant takes species: "human" | "mouse", an optional dataset, and optionally population: "MAIT" | "iNKT" | "GEM". It records the species and shows Clonotypes, returning the first 20 rows plus complete sample totals, matched and evaluable abundance and shares. The published sequence rules do not establish phenotype or specificity.

B-cell sequence evidence

In wave 5, inspect_bcell_inputs opens B cells → Inputs, returning evidence counts and at most 50 rearrangement summaries under the active QC filter. Optional dataset chooses the dataset and select inspects a row on that page, numbered from 1. It does not infer a germline or measure mutation.

Subject feature tables

Use get_state to find saved cohortDesigns and diversity artifacts. Call build_cohort_features with explicit design and diversity IDs from the same dataset. This keeps the saved subject/group observations and their units, missingness and provenance; it performs no group test. See Subject features.

Subject group comparisons

Call compare_cohort with an explicit saved feature-parent ID and options: {features: ["hill1", "shannon"], confidence: 0.95, permutations: 9999, seed: 20261025}. Both tests for each selected feature enter one BH family. The saved design determines independent or paired tests; missing observations never cause silent subject deletion. The response includes the artifact, family size, testable count and method description. See Subject group comparisons for assumptions, effects and interval meanings.

Replicated clonotype counts

Call fit_cohort_counts with a saved feature-parent ID and options: {minCount: 10, minSamples: 12, adjustBatch: true, confidence: 0.95}. The original receptor dataset supplies the initial count snapshot under the saved definition/QC. The response includes the artifact, fitted count, eligible BH family and method. Paired designs add subject blocks; optional batch effects must be estimable. See Replicated clonotype counts for replication limits, relative-abundance estimands and conditional interval interpretation.

Definition robustness

Call audit_definitions with comparison (a saved group-comparison artifact) and one to five alternative definitions. Preserve chain/cell/productivity policies; only junction and V/J resolution may vary. The original receptor source supplies the initial captured abundances under the pinned QC. All subjects, features, tests, confidence and seeds remain fixed. The response includes the artifact, complete BY family, descriptive feature summaries and method. See Definition robustness for the dependent-analysis, interval and interpretation limits.

Motifs and sequence signatures

Call screen_motifs with explicit query and background sample arrays, an optional dataset name/ID, and optional {minK:2,maxK:5,minMembers:3,q:0.05,minFold:2} settings. It captures the current AA definition, QC and subject annotations, then saves overlapping GLIPH2-style sequence groups with exact V/length matching, conditional Fisher scores and full-family BY. The response includes artifact, family, reported count and method. The motif guide documents adaptations, bounds and why these are exploratory sequence hypotheses rather than independent-subject or antigen-specificity evidence.

Subject recurrence and HLA

Call analyze_convergence with a saved motifs ID and selection: {species:"human", samples:[...], subjects:[{id, samples:[...], typing:{A:[call,call]}}], groups:[...], alleles:[...]}. Each sample belongs to one subject; both allele copies are explicit. Empty alleles requests recurrence only. Declare the full subject universe and group/allele panel before viewing HLA outcomes. The response includes artifact, evaluable subjects, family, tested count and method. Saved replay and exports use captured evidence without sources or parent. See Subject recurrence and HLA for missingness, locus universes, BY, marginal intervals and scientific limits.

Contamination evidence

Call screen_contamination with species:"human", unrelated:true, and explicit samples:[{name,subject,batch}]. Optional options:{minCount:2,highFraction:0.01,ratio:20,highPgen:1e-8} controls review heuristics. Optional pgen names a compatible saved human productive NT TRB/V-and-J-gene result under identical QC. The screen uses a fixed nucleotide definition without changing the project’s, preserves all shared matches and returns artifact, pair/match counts and method. Read Contamination evidence for units, missingness, publicness context and the limits of a flag.

Batch QC

screen_batch_qc accepts a dataset, every sample as {name,subject,batch,exclude} and options:{threshold:3.5,minSamples:5}. Use explicit exclusion reasons for repeats or missing assignments. The result includes the artifact ID, included sample and unique-subject counts, and scientific description. See Batch QC for metric denominators, unscored policies and interpretation.

Pseudobulk count evidence

aggregate_pseudobulk accepts explicit saved phenotypes IDs and options containing the supplied annotation column and minCells (default 10). It uses the visible Cells workflow and saves exact raw sums and cell membership. It performs no differential-expression test. See Pseudobulk counts for sample boundaries, missingness and export rules.

Paired pseudobulk expression

compare_pseudobulk accepts a saved pseudobulk count ID and options: exact supplied type, literal timepoint, reference/comparison size bins, optional exclude mapping sample names to reasons, minCount (10), minSamples (25) and confidence (.95). It uses the visible Cells workflow. At least 25 complete subject pairs are required. It returns the saved artifact, subject and family/tested counts and Go-generated description. See paired pseudobulk expression for unmoderated NB assumptions, normalization, conditional uncertainty and complete exports.