R client

Drive the normal research window from R. Preserve original evidence and review proposed project changes before they run.

ClonoLoom 0.9.0. Use R 4.1 or later and a matching host with API 2, catalog 4 and permission policy 1. Package/application version is 0.9.0.

Install from the checkout

Rscript -e 'install.packages(c("curl", "jsonlite"), repos="https://cloud.r-project.org")'
R CMD INSTALL clients/r
clonoloom --remote-control --allow edits,compute,files

Start the host separately and keep its window open. Remote access is read-only without explicit grants. The client never starts a host, expands permissions or accepts proposals. Project edits require a person to accept them in the window and use named History and Undo/Redo. Read Automation permissions.

Query the current repertoire

library(clonoloom)
cl <- cl_connect(client = "Research notebook")
cl_permissions(cl)
# Open a repertoire in the window first.
result <- cl_query_clonotypes(
  where = list(field = "total", op = "gte", value = cl_number("2")),
  limit = 10L, cl = cl)
evidence <- cl_native(result)
rows <- cl_records(result)
frame <- as.data.frame(result)  # list columns preserve tokens

All 61 functions and their help come from the same action catalog as Python and MCP. Generated arguments use snake_case names. Filtering retains current definition, QC, source units and the full-table frequency denominator; displayed ranks reflect selected membership.

Preserve numbers and missingness

Every JSON number retains its original text in a clonoloom_number token. This includes large integers, decimal digits, exponents and negative zero. Use cl_number("9007199254740993") to send an exact number token; host argument bounds still apply. Original response bytes remain in result$raw_json, and cl_native(result) decodes the original native query string.

as.character(token) gives exact text. Arithmetic and comparisons on tokens fail. Explicit as.numeric(token) warns that precision or range may be lost. Already rounded R values cannot recover original digits. List-column frames retain tokens and nulls; missing keys become NULL only in this convenience view. Keep records and raw evidence when that distinction matters.

cl_omit() omits a top-level optional argument; NULL sends explicit JSON null. Generated array parameters preserve empty and singleton vectors. Use cl_array() for nested arrays and cl_object() for an empty object. NA, non-finite values and unsupported R classes are refused rather than silently interpreted as missing evidence.

Connect with explicit permissions

An explicit URL never borrows another library's token. An explicit data_dir selects that library before environment settings. Environment URL/token, environment library and platform-library discovery follow documented precedence. Only loopback HTTP is accepted; proxies and redirects are disabled. Every action checks compatible API/catalog/policy versions before submission.

Typed errors preserve the host code and uncertain completion. No automatic retries occur. The default timeout is 660 seconds per complete HTTP transfer, including review; local decoding is separate. Inspect the project and History after a timeout because worker or file effects may have completed.

Scientific and transport limits

Requests are bounded to 1 MiB, responses to 16 MiB and JSON nesting to 64. Malformed or oversized responses fail instead of returning partial evidence. R cannot represent embedded NUL strings; these are explicitly refused. Exact tokens are an evidence representation, not a new arithmetic or statistical engine.

Existing scientific workers and exact certificate replay remain unchanged. Neither a client object nor a successful automation call establishes biological validity. The shared validation compares original R/Python/HTTP query evidence on a seeded artificial vaccination study and checks review, permissions, cancellation and history.

Read the complete R guide for discovery, errors, bounds and numeric limits, or run the R query example.