IAN graphs: setup and interpreting results

IAN starts with a Gabriel graph, estimates local neighborhood scales, and prunes edges. create.ian.graph() preserves connectivity by default by retaining proposed edges whose removal would disconnect the current graph. It also retains the initial Gabriel graph and useful numerical and pruning diagnostics.

Build the optional backend once

The initial supported target is macOS arm64. Setup needs Python 3, Apple’s C++ compiler/SDK, and native arm64 Cargo/Rust (Rust at least 1.77). The package installs pinned backend sources; its ordinary installation does not build Rust or download a toolchain. These setup commands run explicitly:

library(dgraphs)
backend <- build.ian.backend("ian-build")

Use a new build directory. Logs and source identities remain there. Save the returned module path for later sessions, and rebuild after changing the R runtime or backend sources. The graph function uses this module directly; it does not launch a separate solver process. With cached dependencies, offline=TRUE avoids Cargo network access. If the default toolchain targets Intel Mac, specify matching native cargo and rustc executable paths. See help("build.ian.backend").

Construct and inspect a graph

X <- rbind(c(0, 0), c(1, 0), c(2, 0), c(0, 0))
fit <- create.ian.graph(X, backend = backend,
    specimen.ids = c("alpha", "beta", "gamma", "delta"),
    participant.ids = c("p1", "p1", "p2", "p3"))
if (!fit$complete) stop(fit$error$message)
graph.edges(fit$initial_graph)
graph.edges(fit$final_graph)
fit$mapping$member_to_profile
fit$scales
fit$affinity
fit$diagnostics$connectivity$protected.edges
fit$diagnostics$connectivity$history

Input rows are specimens. Exact duplicate feature rows become one graph vertex; the example has four specimens and three vertices, in first-occurrence order. Repeated participant IDs remain labels and do not cause profile merging. Mapping indices and graph vertices are one-based. Full raw traces retain explicitly labeled zero-based native indices.

When distances are omitted, the function uses Euclidean distances computed by R. An optional distances matrix or dist object supplies unsquared distances in the same row order as X. Duplicate feature profiles must have identical distance rows. Coordinates remain required for duplicate identification. Named supplied distances must match the specimen IDs. Feature transformation and distance choice are part of the user’s scientific model; no microbiome-specific preprocessing is automatically selected.

Graph edge lengths retain input distance units. The affinity matrix contains similarities and is returned separately; it is not a matrix of metric edge lengths. The protected-edge table contains encountered bridges whose pruning conditions were deliberately not tested. It is neither a list of every bridge nor a claim that those edges would otherwise have passed pruning criteria.

Numerical behavior and incomplete results

The default numerical.policy="IAN evaluated-LP retry-power 0.1" permits one fresh normalized retry after an eligible rejected solver return. That retry must pass strict solver success and the unchanged original-unit numerical checks. Both attempts remain in diagnostics$solver_history.

To select the earlier strict numerical and reference pruning behavior:

reference <- create.ian.graph(X, backend = backend,
    numerical.policy = "IAN evaluated-LP 1.0",
    preserve.connectivity = FALSE)

Reference pruning can disconnect a graph. Numerical policy and connectivity are independent options; these defaults select already-qualified implementations. They do not establish that retained connections improve biological interpretation or prediction.

Invalid arguments or an unavailable module raise an R error. Numerical refusal, solve-budget exhaustion or interruption at an engine event return complete=FALSE, a structured error, no final_graph, and whatever initial or last-valid graph and diagnostics are available. A last-valid graph is partial, not an accepted final output. Always check complete before proceeding. Interrupts do not preempt a running solver or every initialization loop. Memory exhaustion or operating-system termination need not return a recoverable result. R restart is not provided by this interface.

Resources and qualification

There is no fixed experimental row cap. One dense n-by-n double matrix uses 8*n*n bytes before overhead; several arrays and conversion copies coexist. Original specimen count matters because distances precede duplicate collapse. Gabriel construction has cubic worst-case work. diagnostics="summary" is the default; full traces retain additional dense solve data and can be much larger.

Accepted preceding qualification covers seven 1,000-profile geometries in both pruning modes and two 2,000-profile connected examples through native/R paths on Mac arm64 R-devel. The conditional 5,000-profile run was not executed because its prospective memory gate failed. These sizes describe tested examples, not a universal capacity promise. Public-interface qualification is documented in the project’s versioned records; support on other operating systems is not established.