Standalone Codecs

library(fmrilatent)

The primary package workflow is spec_*() plus encode(), which returns latent neuroimaging representations such as LatentNeuroVec and transport-backed latents.

Standalone codecs are different. They work on ordinary matrices, own their own encode/decode payloads, and are not dispatched through encode(). BOLDZip-SR is currently the only standalone codec in fmrilatent. For a full encode/decode/evaluate workflow, see vignette("boldzip").

What sets a standalone codec apart?

BOLDZip-SR is currently the only standalone codec in fmrilatent, and it makes the category concrete. Three properties distinguish it from a spec_*() encoder:

  • Matrix in, matrix out. It expects voxels (or grayordinates) in rows and time in columns — intentionally the transpose of the encode() convention, which uses time by voxels.
  • Owns its payload. The encoder returns a BoldZipSR object, not a LatentNeuroVec, and it carries its own decode logic.
  • Not in the encode-spec registry. You call it directly; it is never dispatched through encode().

A minimal fit shows all three at once:

set.seed(9)
n_voxels <- 10L
n_time <- 24L
carrier <- sin(seq(0, 2 * pi, length.out = n_time))
texture <- seq(-1, 1, length.out = n_voxels)
X <- outer(texture, carrier)               # voxels x time
X <- X + matrix(rnorm(n_voxels * n_time, sd = 0.01), nrow = n_voxels)

fit <- boldzip_sr_encode(X, k_carriers = 1L, q_texture = 1L,
                         temporal_k = 6L)

inherits(fit, "BoldZipSR")    # a codec object, not a LatentNeuroVec
#> [1] TRUE
inherits(fit, "LatentNeuroVec")
#> [1] FALSE

That is the whole distinction. For the full encode → evaluate → decode → budget-tuning workflow (including the as_implicit_latent() bridge back into the package’s decoder contract), see vignette("boldzip"). For the lower-level shared-structure contracts BOLDZip-SR can share with other representations, see vignette("shared-structure-boldzip").