Package 'fmridataset'

Description

Construct a strictly aligned assay set

Usage

aligned_assay_set(assays, observations, features)

Arguments

Value

An aligned_assay_set.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
obs <- axis_frame(data.frame(.obs_id = sprintf("vol-%d", 1:4)), axis = "observation")
feat <- feature_axis(feature_data(sp), space = sp)
bold <- matrix(rnorm(4 * n_features(sp)), nrow = 4)
aligned_assay_set(list(bold = bold), obs, feat)

Description

Append immutable source shards

Usage

append_source_shards(x, sources, shard_ids = NULL, shard_data = NULL)

Arguments

Value

A new row_sharded_source; x and its child descriptors are not modified.

Examples

src <- row_sharded_source(list(memory_source(matrix(1:4, nrow = 2))))
grown <- append_source_shards(src, list(memory_source(matrix(5:8, nrow = 2))))
source_shape(grown)

Description

Apply one validity relation lazily to frame assays

Usage

apply_feature_validity(x, name = NULL, assays = NULL)

Arguments

Value

A new frame with lazy NA masking and derivation provenance.

Examples

space <- index_space(4, ids = paste0("f", 1:4), namespace = "validity-ex")
subjects <- entity_frame(
  data.frame(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
validity <- entity_feature_validity(
  entity = "subject", entity_ids = c("sub-1", "sub-2"),
  masks = rbind(
    c(TRUE, TRUE, FALSE, TRUE),
    c(TRUE, FALSE, FALSE, TRUE)
  ),
  space = space
)
frame <- fmri_frame(
  assays = list(signal = matrix(1:8, nrow = 2)),
  observations = data.frame(.obs_id = c("o1", "o2"), subject_id = c("sub-1", "sub-2")),
  space = space,
  entities = list(subject = subjects),
  relations = list(
    observation_subject = key_relation("subject_id"),
    subject_feature_validity = validity
  )
)
masked_frame <- apply_feature_validity(frame)
collect_assay(masked_frame)

Description

The estimate distinguishes source storage from the R object returned by a read. Numeric source dtypes, including float16 and float32, are realized as R doubles. The conservative peak estimate adds selection, conversion, and compressed-input buffers to the retained output. It covers numerical payloads; fixed R object headers and selector metadata are outside the estimate.

Usage

as_array_source(x, ...)

source_shape(x, ...)

source_dtype(x, ...)

source_chunks(x, ...)

source_capabilities(x, ...)

source_fingerprint(x, ...)

source_open(x, ...)

source_read(x, observations = NULL, features = NULL, ...)

source_read_native(x, observations = NULL, ...)

source_close(x, ...)

source_realization_cost(x, observations = NULL, features = NULL)

Arguments

Details

Fingerprint policy. source_fingerprint() returns the revision fingerprint of a descriptor: one SHA-256 string over the serializable descriptor and the physical revision evidence a backend can observe without reading values (file sizes and modification times, store metadata, or a per-object identity token for in-memory sources), combined with selectors and shard composition for wrappers. It never hashes array values, it is computed once at construction and cached in the descriptor, and it survives serialization. Equal fingerprints mean "the same descriptor of the same revision"; they never mean equal values, and different fingerprints never mean different values. Two independently constructed memory_source() objects with equal payloads have different fingerprints by design.

Value identity is a separate, explicit, O(n) operation: content_hash(). File-backed sources compare their captured revision evidence with the physical state before every open and read and raise fmridataset_error_source_stale when it differs; genuine backend failures raise fmridataset_error_backend_io. The policy is recorded in inst/architecture/ADR-009-source-fingerprints-and-content-hashes.md.

Value

A source_realization_cost list containing storage and realized dtypes, storage and output bytes, temporary buffer components, and the estimated peak bytes.

Examples

src <- memory_source(matrix(seq_len(6), nrow = 2))
source_shape(src)
source_dtype(src)
handle <- source_open(src)
source_read(handle, observations = 1)
source_close(handle)

Description

as_delarr() wraps a serializable array source as a delarr provider so that bounded, chunk-aware execution can be delegated to delarr without materializing the assay. The realization budget bounds each provider pull, not the whole source, so a lazy array may describe more data than the budget allows; every pull is checked before it reads.

Usage

as_delarr(x, memory_budget = Inf, ...)

## Default S3 method:
as_delarr(x, memory_budget = Inf, ...)

Arguments

Value

A delarr lazy array whose pulls route through source_read().

See Also

array-source for the source protocol.

Examples

src <- memory_source(matrix(seq_len(6), nrow = 2))
lazy <- as_delarr(src)
dim(lazy)

Description

Companion packages implement methods for legacy or domain-specific objects. The generic is owned by fmridataset so conversions have one canonical destination and do not introduce competing frame classes.

Usage

as_fmri_frame(x, ...)

Arguments

Value

An fmri_frame.

Examples

src <- memory_source(matrix(seq_len(6), nrow = 2))
obs <- tibble::tibble(.obs_id = c("o1", "o2"))
fr <- fmri_frame(list(beta = src), obs)
identical(as_fmri_frame(fr), fr)

Description

Construct a typed auxiliary table

Usage

auxiliary_table(data, key = NULL, role = "auxiliary", metadata = list())

Arguments

Value

An fmri_auxiliary_table.

Examples

at <- auxiliary_table(
  data.frame(contrast = c("A-B", "B-A"), stat = c(2.1, -2.1)),
  key = "contrast", role = "contrasts"
)
table_data(at)

Description

Validate and inspect a typed auxiliary table

Usage

validate_auxiliary_table(x)

table_data(x)

table_key(x)

table_role(x)

Arguments

Value

validate_auxiliary_table() returns x invisibly; other functions return table data, key, or role.

Examples

at <- auxiliary_table(
  data.frame(contrast = c("A-B", "B-A"), stat = c(2.1, -2.1)),
  key = "contrast", role = "contrasts"
)
validate_auxiliary_table(at)
table_key(at)
table_role(at)

Description

A block is two-dimensional: rows are the elements of the owning axis and columns are named components. Arrays with more than two dimensions are rejected because a trailing axis without typed metadata would be an anonymous semantic dimension; represent higher-order structure as named components, as several blocks, or as an assay.

Usage

axis_block(
  data,
  components = NULL,
  role = "continuous",
  units = NULL,
  metadata = list()
)

axis_block_data(x)

block_components(x)

block_component_ids(x)

Arguments

Value

An axis_block.

Examples

b <- axis_block(
  matrix(1:6, 3, 2),
  components = data.frame(.component_id = c("x", "y")),
  role = "continuous"
)
dim(axis_block_data(b))
block_component_ids(b)

Description

Construct an annotated axis

Usage

axis_frame(
  data,
  blocks = list(),
  id = NULL,
  axis = c("observation", "feature", "entity", "component"),
  id_col = NULL,
  metadata = list(),
  id_policy = c("require", "deterministic", "ephemeral"),
  id_keys = NULL,
  id_namespace = NULL
)

axis_data(x)

axis_blocks(x)

axis_ids(x)

Arguments

Value

An axis_frame.

Examples

x <- axis_frame(data.frame(value = 1:3), id_policy = "ephemeral")
axis_ids(x)
axis_data(x)

Description

A basis_space is a representational feature axis linked to one parent spatial space. Its encoder maps parent features to component coefficients; its optional decoder maps coefficients back to the parent. Fitting and model-specific offsets remain the responsibility of packages such as fmrilatent.

Usage

basis_space(
  parent,
  component_ids,
  encoder,
  decoder = NULL,
  data = NULL,
  basis_type = "linear_basis",
  provenance = list(),
  tolerance = 1e-08,
  metadata = list()
)

Arguments

Value

A basis_space.

Examples

parent <- volume_space(c(2, 1, 1), support = 1:2)
x <- basis_space(parent, c("c1", "c2"), diag(2), diag(2))
n_features(x)

Description

Computes the exact unregularized least-squares encoder ⁠(D' D)^{-1} D'⁠ for a full-column-rank decoder D.

Usage

basis_space_from_decoder(
  parent,
  component_ids,
  decoder,
  data = NULL,
  basis_type = "linear_basis",
  provenance = list(),
  tolerance = 1e-08,
  metadata = list(),
  encoder = c("least_squares", "none")
)

Arguments

Value

A basis_space.

Examples

parent <- volume_space(c(2, 1, 1), support = 1:2)
x <- basis_space_from_decoder(parent, c("c1", "c2"), diag(2))
basis_synthesis(x)

Description

fmrilatent remains the owner of latent fitting, temporal scores, handles, and offsets. This adapter extracts only its spatial synthesis dictionary and constructs the corresponding least-squares feature-space algebra.

Usage

basis_space_from_fmrilatent(
  x,
  parent,
  component_ids = NULL,
  data = NULL,
  provenance = list(),
  tolerance = 1e-08
)

Arguments

Value

A basis_space.

Examples

# Loading fmrilatent itself takes several seconds, so this full
# integration example is wrapped in \donttest{}.
if (requireNamespace("fmrilatent", quietly = TRUE)) {
  parent <- volume_space(c(2, 2, 1), support = 1:4, template = "toy-native")
  decoder <- Matrix::Matrix(
    matrix(c(1, 0, 0, 1, 1, 1, 2, -1), nrow = 4, byrow = TRUE),
    sparse = TRUE
  )
  scores <- Matrix::Matrix(matrix(c(1, 0, 0, 1, 2, -1), nrow = 3, byrow = TRUE))
  mask <- neuroim2::LogicalNeuroVol(
    array(TRUE, dim = c(2, 2, 1)), neuroim2::NeuroSpace(c(2, 2, 1))
  )
  latent <- fmrilatent::LatentNeuroVec(
    basis = scores, loadings = decoder,
    space = neuroim2::NeuroSpace(c(2, 2, 1, 3)), mask = mask,
    offset = rep(10, 4), meta = list(family = "toy_pca")
  )
  x <- basis_space_from_fmrilatent(latent, parent = parent)
  basis_projection_info(x)
}

Description

Inspect basis-space operators

Usage

basis_analysis(x)

basis_synthesis(x)

basis_projection_info(x)

Arguments

Value

basis_analysis() returns the parent-to-component analysis operator; basis_synthesis() returns the optional component-to-parent synthesis operator; basis_projection_info() returns validation metadata. These names deliberately avoid colliding with fmrilatent::basis_decoder(), which constructs model-level decoders.

Examples

parent <- volume_space(c(2, 1, 1), support = 1:2)
x <- basis_space(parent, c("c1", "c2"), diag(2), diag(2))
basis_analysis(x)
basis_synthesis(x)
basis_projection_info(x)

Description

Bind frames along observations

Usage

bind_observations(
  ...,
  metadata_policy = c("identical", "merge"),
  active_assay = NULL
)

Arguments

Value

A lazily row-bound fmri_frame.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
make <- function(prefix) {
  fmri_frame(
    assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
    observations = data.frame(.obs_id = sprintf("%s-%d", prefix, 1:4)),
    space = sp
  )
}
bound <- bind_observations(make("a"), make("b"))
dim(bound)

Description

Apply a function to bounded feature blocks

Usage

block_apply(x, FUN, block_size = 4096L, assay = active_assay(x), ...)

Arguments

Value

A list of block results.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
block_apply(frame, function(mat, ids) colMeans(mat), block_size = 4L)

Description

Inspect a frame block plan

Usage

block_manifest(plan)

Arguments

Value

A data frame containing logical block bounds and byte estimates.

Examples

frame <- fmri_frame(
  assays = list(signal = memory_source(matrix(seq_len(20), 5, 4))),
  observations = data.frame(.obs_id = sprintf("obs-%d", 1:5)),
  active_assay = "signal"
)
plan <- plan_blocks(frame, memory_budget = 10 * 1024^2)
block_manifest(plan)

Description

Canonicalization version 1 normalizes semantic R values and writes a tagged, length-prefixed package binary format. It is an explicitly R-only format. Named lists and attributes use lexicographic field order; unnamed list order is preserved. Strings are UTF-8 NFC, sparse matrix storage layouts are normalized, and NaN payloads use one R value while remaining distinct from NA_real_. Negative zero remains distinct from zero.

Usage

canonical_bytes(x)

canonical_sha256(x)

Arguments

Value

canonical_bytes() returns a raw vector. canonical_sha256() returns its lowercase SHA-256 hexadecimal digest.

Examples

canonical_bytes(list(b = 2, a = 1))
canonical_sha256(list(b = 2, a = 1))

Description

Canonicalization version 1 hashes normalized R objects with SHA-256 over a package-owned tagged binary encoding. It is stable for supported package operations and round trips, but is deliberately R-only rather than a cross-language wire encoding.

Usage

canonicalization_contract()

Value

A serializable canonicalization descriptor.

Examples

contract <- canonicalization_contract()
contract$algorithm

Description

Collect one frame assay under an explicit memory budget

Usage

collect_assay(
  x,
  assay = active_assay(x),
  memory_budget = getOption("fmridataset.collect_budget", 2 * 1024^3),
  force = FALSE
)

Arguments

Value

A dense matrix.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
collect_assay(frame)

Description

Collect spatial maps through native or reconstructed reads

Usage

collect_spatial_maps(
  x,
  observations = NULL,
  assay = active_assay(x),
  path = c("auto", "native", "reconstruct"),
  memory_budget = getOption("fmridataset.spatial_budget", 512 * 1024^2)
)

Arguments

Value

A named list with one native spatial object per observation.

Examples

sp <- volume_space(dim = c(2L, 2L, 1L), affine = diag(4), support = 1:4)
frame <- fmri_frame(
  assays = list(signal = memory_source(matrix(seq_len(12), 3, 4))),
  observations = data.frame(.obs_id = sprintf("obs-%d", 1:3)),
  space = sp,
  active_assay = "signal"
)
maps <- collect_spatial_maps(frame, observations = c(1L, 2L))
names(maps)

Description

Compute a deterministic collection digest

Usage

collection_digest(x)

Arguments

Value

A SHA-256 digest computed without reading numerical arrays.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
collection <- fmri_collection(list(sub01 = frame, sub02 = frame))
collection_digest(collection)

Description

Access frames in an fMRI collection

Usage

collection_frames(x)

collection_frame(x, id)

collection_ids(x)

Arguments

Value

The named frame list, one frame, or the stable frame IDs.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
collection <- fmri_collection(list(sub01 = frame, sub02 = frame))
collection_ids(collection)
collection_frame(collection, "sub01")

Description

Summarize collection feature spaces

Usage

collection_space_data(x)

collection_common_space(x)

Arguments

Value

collection_space_data() returns one metadata row per frame; collection_common_space() returns whether every feature space is exactly compatible with the first.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
collection <- fmri_collection(list(sub01 = frame, sub02 = frame))
collection_space_data(collection)
collection_common_space(collection)

Description

The target of first must be the source of second, and their addressed axes must agree. Explicit ID maps are joined through the intermediate IDs. Feature operators are composed as second %*% first without changing link direction.

Usage

compose_frame_links(first, second, type = NULL, metadata = list())

Arguments

Value

A canonical source-to-target frame_link.

Examples

first <- frame_link("bold", "beta", type = "derivation")
second <- frame_link("beta", "summary", type = "derivation")
composed <- compose_frame_links(first, second)
composed$source
composed$target

Description

A composite_space forms one feature axis from heterogeneous child spaces, such as left cortex, right cortex, and subcortical volume. It owns only the ordered routing between that axis and its named parts; each child remains the authority for spatial identity, vectorization, and reconstruction.

Usage

composite_space(
  parts,
  composite_type = "composite",
  metadata = list(),
  route = NULL
)

Arguments

Value

A composite_space.

Examples

parts <- list(
  left = index_space(2, ids = c("l1", "l2")),
  right = index_space(2, ids = c("r1", "r2"))
)
x <- composite_space(parts, composite_type = "bilateral")
feature_ids(x)

Description

Inspect composite feature-space parts

Usage

composite_parts(x)

composite_part_names(x)

composite_part(x, name)

Arguments

Value

composite_parts() returns the ordered named child spaces; composite_part_names() returns their names; and composite_part() returns one child space.

Examples

parts <- list(
  left = index_space(2, ids = c("l1", "l2")),
  right = index_space(2, ids = c("r1", "r2"))
)
x <- composite_space(parts)
composite_part_names(x)
composite_part(x, "left")

Description

content_hash() is the one operation in the package that identifies an array by its values. It is the content domain of the identity contract (see identity_descriptor()) and it is always explicit: nothing in the package computes it for you. Ordinary construction, inspection, fingerprinting, planning, and persistence never call it.

Usage

content_hash(x, ...)

## Default S3 method:
content_hash(x, ...)

## S3 method for class 'array_source'
content_hash(
  x,
  ...,
  block_bytes = getOption("fmridataset.target_block_bytes", 4 * 1024^2)
)

## S3 method for class 'memory_source'
content_hash(
  x,
  ...,
  block_bytes = getOption("fmridataset.target_block_bytes", 4 * 1024^2)
)

## S3 method for class 'source_view'
content_hash(
  x,
  ...,
  block_bytes = getOption("fmridataset.target_block_bytes", 4 * 1024^2)
)

## S3 method for class 'row_sharded_source'
content_hash(
  x,
  ...,
  block_bytes = getOption("fmridataset.target_block_bytes", 4 * 1024^2)
)

Arguments

Details

The digest is O(n) in the number of values. The default method streams: it opens one handle, reads bounded row blocks through the source protocol aligned to the source chunk grid, and hashes each block into a running state, so no source is materialized whole. block_bytes bounds the realized size of one read and affects only I/O; every block size produces the same digest. Blocks cover whole rows when a row fits the bound and consecutive feature ranges of one row otherwise.

Two sources hash equal exactly when they have the same shape, realize to the same R mode (double, logical, or complex), and hold equal values. Storage dtype, chunking, wrappers, views, and shard composition do not enter the digest, so an in-memory copy and a row-bound composition of the same values agree. NaN payloads and NA are normalized to one representation each and remain distinct; negative zero stays distinct from zero.

The digest describes the values at the moment they were read. It is a receipt, not a live property: a later in-memory mutation of a memory source's payload is not detected by source_fingerprint() and shows only when a fresh content_hash() is compared with the earlier one.

Value

One lowercase SHA-256 hexadecimal string.

See Also

source_fingerprint() for the cheap revision identity of a descriptor, identity_descriptor() for typed identity domains, and inst/architecture/ADR-009-source-fingerprints-and-content-hashes.md for the policy.

Examples

a <- memory_source(matrix(1:6, 2, 3))
b <- memory_source(matrix(as.double(1:6), 2, 3), chunks = c(1, 1))
identical(source_fingerprint(a), source_fingerprint(b))
identical(content_hash(a), content_hash(b))

Description

Content hashing version 1 is a chained SHA-256 over fixed-size leaves of the realized values in row-major order. The digest depends on the shape, the realized R mode, and every value, and on nothing else: not on the storage dtype, the chunk grid, the read block size, or the composition of sources that produced the values.

Usage

content_hash_contract()

Value

A serializable content-hash contract descriptor.

Examples

content_hash_contract()

Description

counting_source() records numerical reads without placing a mutable environment inside the source descriptor. It is exported for backend and downstream conformance suites, not as an application data source.

Usage

counting_source(source)

source_counts(x)

reset_source_counts(x)

Arguments

Details

This is developer-only test instrumentation. The counter registry is process-local, is not persisted with the descriptor, and must not be used as provenance or as an execution receipt.

Value

A serializable instrumented source.

Examples

src <- counting_source(memory_source(matrix(seq_len(6), nrow = 2)))
source_read(src, observations = 1)
source_counts(src)$reads

Description

Describe compressed entity-by-feature validity

Usage

entity_feature_validity(entity, entity_ids, masks, space, metadata = list())

Arguments

Value

An entity_feature_validity relation descriptor.

Examples

space <- index_space(4, ids = paste0("f", 1:4), namespace = "validity-ex")
validity <- entity_feature_validity(
  entity = "subject", entity_ids = c("sub-1", "sub-2"),
  masks = rbind(
    c(TRUE, TRUE, FALSE, TRUE),
    c(TRUE, FALSE, FALSE, TRUE)
  ),
  space = space
)
validity_entity(validity)

Description

An entity frame stores one row per subject, session, run, stimulus, item, or other study entity. Scalar annotations live in data; multivariate values live in named, first-axis-aligned axis_block objects.

Usage

entity_frame(data, key, blocks = list(), entity_type = NULL, metadata = list())

Arguments

Value

An entity_frame, also implementing the axis_frame contract.

Examples

x <- entity_frame(
  data = tibble::tibble(
    stimulus_id = c("stim-1", "stim-2", "stim-3"),
    category = c("face", "scene", "object")
  ),
  key = "stimulus_id"
)
entity_ids(x)

Description

Construct and validate an entity registry

Usage

entity_registry(entities = list(), ...)

validate_entity_registry(x)

Arguments

Value

A named entity_registry.

Examples

subjects <- entity_frame(
  data = tibble::tibble(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
registry <- entity_registry(subject = subjects)
entity_names(registry)

Description

Compute a stable entity-registry digest

Usage

entity_registry_digest(x)

Arguments

Value

A hexadecimal digest over the normalized registry.

Examples

subjects <- entity_frame(
  data = tibble::tibble(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
registry <- entity_registry(subject = subjects)
entity_registry_digest(registry)

Description

Access entities from a frame or registry

Usage

entities(x, ...)

entity(x, name, ...)

entity_names(x)

Arguments

Value

entities() returns the registry; entity() returns one entity_frame; entity_names() returns registry names.

Examples

subjects <- entity_frame(
  data = tibble::tibble(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
registry <- entity_registry(subject = subjects)
entities(registry)
entity(registry, "subject")
entity_names(registry)

Description

Entity-frame accessors

Usage

entity_key(x)

entity_ids(x)

entity_data(x)

entity_blocks(x)

Arguments

Value

The stable key name, entity IDs, scalar data, or aligned blocks.

Examples

embedding <- axis_block(matrix(as.double(1:8), 2, 4), role = "embedding")
x <- entity_frame(
  data = tibble::tibble(stimulus_id = c("stim-1", "stim-2")),
  key = "stimulus_id",
  blocks = list(semantic = embedding)
)
entity_key(x)
entity_ids(x)
entity_data(x)
entity_blocks(x)

Description

Event rows retain their natural cardinality and are not expanded to acquired volumes. Entity-key columns are validated against a study when attached.

Usage

event_table(data, key = "event_id", metadata = list())

Arguments

Value

An fmri_event_table.

Examples

et <- event_table(
  data.frame(event_id = c("e1", "e2"), onset = c(0, 10), duration = c(2, 2)),
  key = "event_id"
)
event_data(et)
event_key(et)

Description

Event-table accessors

Usage

event_data(x)

event_key(x)

Arguments

Value

Event scalar data or the stable key name.

Examples

et <- event_table(
  data.frame(event_id = c("e1", "e2"), onset = c(0, 10)),
  key = "event_id"
)
event_data(et)
event_key(et)

Description

Execute a bounded frame block plan

Usage

execute_block_plan(x, plan, FUN, ..., assay = plan$assay)

Arguments

Value

A list containing one result per planned block.

Examples

frame <- fmri_frame(
  assays = list(signal = memory_source(matrix(seq_len(20), 5, 4))),
  observations = data.frame(.obs_id = sprintf("obs-%d", 1:5)),
  active_assay = "signal"
)
plan <- plan_blocks(frame, memory_budget = 10 * 1024^2)
execute_block_plan(frame, plan, function(values, observation_ids, feature_ids, block) {
  sum(values)
})

Description

Unlike collect_spatial_maps(), execute_spatial() holds only one input map at a time. The callback result is retained, so callers remain responsible for keeping returned values appropriately small.

Usage

execute_spatial(
  x,
  observations = NULL,
  FUN,
  ...,
  assay = active_assay(x),
  path = c("auto", "native", "reconstruct"),
  memory_budget = getOption("fmridataset.spatial_budget", 512 * 1024^2)
)

Arguments

Value

A list of callback results in requested observation order.

Examples

sp <- volume_space(dim = c(2L, 2L, 1L), affine = diag(4), support = 1:4)
frame <- fmri_frame(
  assays = list(signal = memory_source(matrix(seq_len(12), 3, 4))),
  observations = data.frame(.obs_id = sprintf("obs-%d", 1:3)),
  space = sp,
  active_assay = "signal"
)
execute_spatial(frame, c(1L, 2L), function(map, observation_id) observation_id)

Description

Matrix operations always use bounded observation-by-feature blocks. Spatial operations use a source's native-image capability only when the frame view retains the complete feature domain; otherwise they reconstruct maps from packed assay values through the frame's feature space.

Usage

execution_path(
  x,
  operation = c("matrix", "spatial"),
  assay = active_assay(x),
  path = c("auto", "native", "reconstruct")
)

Arguments

Value

One of "matrix", "native", or "reconstruct".

Examples

sp <- volume_space(dim = c(2L, 2L, 1L), affine = diag(4), support = 1:4)
frame <- fmri_frame(
  assays = list(signal = memory_source(matrix(seq_len(12), 3, 4))),
  observations = data.frame(.obs_id = sprintf("obs-%d", 1:3)),
  space = sp,
  active_assay = "signal"
)
execution_path(frame, operation = "matrix")
execution_path(frame, operation = "spatial")

Description

explain() returns a bounded, serializable summary of the visible frame. Axis IDs are sampled by default so inspecting a large study does not create another large object. Set ids = "complete" only when every visible ID is required.

Usage

explain(x, ids = c("sample", "none", "complete"), sample_size = 3L)

Arguments

Details

The schema digest describes column, block, assay, relation, entity, table, and space contracts. The semantic digest covers the complete source-free FDS manifest. Physical source fingerprints are reported separately.

Value

A bounded serializable execution summary. No assay or aligned-block values are read. ids_durable reports whether the observation axis and the feature space carry durable IDs; when it is FALSE the semantic digest is NULL because ephemeral IDs cannot enter an FDS manifest.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
summary <- explain(frame)
summary$shape

Description

This source is exported solely for deterministic backend, codec, cleanup, and recovery conformance tests.

Usage

fault_source(
  source,
  stage = c("read", "open", "native_read", "close"),
  message = NULL
)

Arguments

Details

This is developer-only test instrumentation. Never persist a fault_source as study data or use one in an analysis plan.

Value

A serializable fault-injecting source.

Examples

src <- fault_source(memory_source(matrix(seq_len(6), nrow = 2)), stage = "read")
tryCatch(source_read(src), error = function(e) conditionMessage(e))

Description

Storage codecs use this helper to pair each source-free FDS array declaration with its current physical or in-memory array_source.

Usage

fds_frame_bindings(x)

Arguments

Value

A named list of array_source descriptors keyed exactly like the manifest arrays registry.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
bindings <- fds_frame_bindings(frame)
names(bindings)

Description

The manifest owns semantic alignment but deliberately excludes physical source descriptors. Storage packages bind assay names to physical array locations separately and reconstruct frames with frame_from_fds_manifest().

Usage

fds_frame_manifest(x)

validate_fds_manifest(manifest)

Arguments

Value

A serializable backend-neutral manifest.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
manifest <- fds_frame_manifest(frame)
manifest$shape
validate_fds_manifest(manifest)

Description

Compute a canonical FDS manifest digest

Usage

fds_manifest_digest(manifest)

Arguments

Value

A stable hexadecimal digest over semantic manifest content.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
manifest <- fds_frame_manifest(frame)
fds_manifest_digest(manifest)

Description

FDS version 1 is the backend-neutral semantic contract for persisted fmri_frame objects. Physical codecs may add locations, chunks, compression, and checksums outside this manifest, but cannot change its field meanings.

Usage

fds_schema()

fds_schema_version()

Value

fds_schema() returns the immutable schema identity; fds_schema_version() returns its integer major version.

Examples

fds_schema()
fds_schema_version()

Description

Extract shared study-level physical bindings

Usage

fds_study_bindings(x)

Arguments

Value

A named list of shared entity-block payloads. Representation arrays remain owned by their individual frame bindings.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
study <- fmri_study(list(main = frame))
fds_study_bindings(study)

Description

Study manifests retain shared entities, typed links, relational tables, and the semantic manifests of every frame or collection member. Numerical sources remain separate bindings so physical storage packages do not own or reinterpret study semantics.

Usage

fds_study_manifest(x)

validate_fds_study_manifest(manifest)

Arguments

Value

fds_study_manifest() returns a serializable source-free manifest; validate_fds_study_manifest() returns manifest invisibly.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
study <- fmri_study(list(main = frame))
manifest <- fds_study_manifest(study)
names(manifest$representations)

Description

Compute a canonical FDS study-manifest digest

Usage

fds_study_manifest_digest(manifest)

Arguments

Value

A stable hexadecimal digest over source-free study semantics.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
study <- fmri_study(list(main = frame))
manifest <- fds_study_manifest(study)
fds_study_manifest_digest(manifest)

Description

Extract canonical study representations for persistence

Usage

fds_study_representations(x)

Arguments

Value

Named frames and collections matching fds_study_manifest(x).

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
study <- fmri_study(list(main = frame))
names(fds_study_representations(study))

Description

Construct a spatial feature axis

Usage

feature_axis(data, space = NULL, blocks = list(), metadata = list(), ...)

Arguments

Value

A feature axis_frame carrying its space.

Examples

sp <- index_space(3, ids = sprintf("f%d", 1:3), namespace = "ex")
fx <- feature_axis(data.frame(.feature_id = sprintf("f%d", 1:3)), space = sp)
axis_ids(fx)

Description

A feature map owns a target-by-source linear operator and the complete spatial identity of both axes. Equal dimensions are never treated as evidence of spatial compatibility. Statistical execution plans and covariance models remain the responsibility of packages such as fmrigds.

Usage

feature_map(
  from,
  to,
  operator,
  map_type = "linear",
  traits = list(linear = TRUE),
  provenance = list(),
  metadata = list()
)

Arguments

Value

A serializable feature_map descriptor.

Examples

src <- index_space(4, ids = paste0("v", 1:4), namespace = "map-source")
tgt <- index_space(2, ids = paste0("p", 1:2), namespace = "map-target")
op <- matrix(c(0.5, 0.5, 0, 0, 0, 0, 0.5, 0.5), nrow = 2, byrow = TRUE)
m <- feature_map(src, tgt, op, map_type = "toy_aggregation")
feature_map_operator(m)

Description

Parcel spaces contribute their aggregation operator and basis spaces their analysis operator. Other transformations require an explicit feature_map().

Usage

feature_map_from_target(target)

Arguments

Value

A feature_map from parent_space(target) to target.

Examples

parent <- volume_space(c(2, 2, 1), support = 1:4, template = "toy")
membership <- Matrix::sparseMatrix(
  i = 1:4, j = c(1L, 1L, 2L, 2L), x = 1, dims = c(4L, 2L)
)
target <- parcel_space(parent, c("left", "right"), membership, atlas = "toy")
m <- feature_map_from_target(target)
feature_map_target_space(m)

Description

Construct a lazy source transformed through a feature map

Usage

feature_mapped_source(source, map, rule = c("linear", "independent_variance"))

Arguments

Value

A serializable feature_mapped_source.

Examples

src <- index_space(4, ids = paste0("v", 1:4), namespace = "map-source")
tgt <- index_space(2, ids = paste0("p", 1:2), namespace = "map-target")
op <- matrix(c(0.5, 0.5, 0, 0, 0, 0, 0.5, 0.5), nrow = 2, byrow = TRUE)
m <- feature_map(src, tgt, op, map_type = "toy_aggregation")
fs <- feature_mapped_source(memory_source(matrix(1:12, nrow = 3)), m)
dim(source_read(fs))

Description

Validate and inspect feature maps

Usage

validate_feature_map(x)

feature_map_source_space(x)

feature_map_target_space(x)

feature_map_operator(x)

feature_map_digest(x)

Arguments

Value

validate_feature_map() returns x invisibly. The accessors return the source space, target space, linear operator, or deterministic digest.

Examples

src <- index_space(4, ids = paste0("v", 1:4), namespace = "map-source")
tgt <- index_space(2, ids = paste0("p", 1:2), namespace = "map-target")
op <- matrix(c(0.5, 0.5, 0, 0, 0, 0, 0.5, 0.5), nrow = 2, byrow = TRUE)
m <- feature_map(src, tgt, op, map_type = "toy_aggregation")
feature_map_source_space(m)
feature_map_target_space(m)
feature_map_digest(m)

Description

Every feature-space class (such as volume_space(), surface_space(), parcel_space(), basis_space(), composite_space(), and index_space()) implements this shared generic contract for feature count, stable identity, restriction, vectorization, and reconstruction.

Usage

n_features(x, ...)

feature_ids(x, ...)

native_shape(x, ...)

feature_data(x, ...)

space_digest(x, ...)

restrict_space(x, index, ...)

vectorize_space(x, spatial_object, ...)

reconstruct_space(x, vector, ...)

adjacency(x, ...)

same_space(x, y, ...)

assert_same_space(x, y, ...)

## S3 method for class 'surface_space'
reconstruct_space(x, vector, format = c("surface_map", "neurosurf"), ...)

Arguments

Value

n_features() returns a single integer; feature_ids() returns a character vector of stable feature identifiers; native_shape() returns the class-specific native dimensions; feature_data() returns a tibble of per-feature metadata; space_digest() returns a content digest string; restrict_space() and reconstruct_space() return an object of the same feature-space class; vectorize_space() returns a numeric vector; adjacency() returns a sparse adjacency matrix or NULL; same_space() returns a space_comparison list whose same field is TRUE only when class, digest, and ordered feature IDs all agree; assert_same_space() returns that report invisibly and signals an fmridataset_error_space_mismatch error otherwise.

Examples

x <- index_space(3, ids = c("a", "b", "c"))
n_features(x)
feature_ids(x)
y <- restrict_space(x, 1:2)
same_space(x, x)$same

Description

Validate and inspect entity-feature validity

Usage

validate_entity_feature_validity(x)

validity_entity(x, name = NULL)

validity_entity_ids(x, name = NULL)

validity_mask_bank(x, name = NULL)

validity_space(x, name = NULL)

validity_matrix(x, name = NULL)

Arguments

Value

The validated descriptor, entity name/IDs, mask bank, feature space, or expanded entity-by-feature logical matrix.

Examples

space <- index_space(4, ids = paste0("f", 1:4), namespace = "validity-ex")
validity <- entity_feature_validity(
  entity = "subject", entity_ids = c("sub-1", "sub-2"),
  masks = rbind(
    c(TRUE, TRUE, FALSE, TRUE),
    c(TRUE, FALSE, FALSE, TRUE)
  ),
  space = space
)
validity_entity_ids(validity)
validity_matrix(validity)

Description

Dropping entity records cascades: child entities whose key relation references a dropped record are dropped too, observations reaching a dropped record are removed, and sparse edges, validity rows, link maps, and table rows are restricted to the surviving IDs. Table rows without a key value are kept.

Usage

filter_entities(x, entity, predicate)

Arguments

Value

A self-contained fmri_study whose numerical sources remain lazy.

Examples

subject_entity <- entity_frame(
  data.frame(subject_id = c("s1", "s2"), age = c(20, 60)),
  key = "subject_id"
)
obs <- data.frame(
  .obs_id = paste0("o", 1:4),
  subject_id = c("s1", "s1", "s2", "s2")
)
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(16), nrow = 4)),
  observations = obs,
  space = index_space(4, ids = paste0("f", 1:4)),
  entities = list(subject = subject_entity),
  relations = list(
    observation_subject = key_relation("subject_id", target = "subject")
  )
)
study <- fmri_study(list(main = frame), entities = list(subject = subject_entity))
older <- filter_entities(study, subject, age > 30)
observation_ids(study_frame(older, "main"))

Description

Filter frame observations using scalar metadata

Usage

filter_obs(x, predicate, resolve = TRUE)

Arguments

Value

An fmri_view.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(
    .obs_id = sprintf("vol-%d", 1:4),
    run_id = rep(c("run-1", "run-2"), each = 2)
  ),
  space = sp
)
filter_obs(frame, run_id == "run-1")

Description

A collection keeps frames separate when they share an observational and assay contract but cannot share a feature axis, as with participant-native volume or surface spaces. Equal feature dimensions or IDs are not required; feature-space type and annotation semantics are validated explicitly.

Usage

fmri_collection(frames, metadata = list(), provenance = NULL)

Arguments

Value

An fmri_collection.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
collection <- fmri_collection(list(sub01 = frame, sub02 = frame))
collection_ids(collection)

Description

Construct a spatially typed annotated matrix

Usage

fmri_frame(
  assays,
  observations,
  features = NULL,
  space = NULL,
  entities = list(),
  relations = list(),
  tables = list(),
  active_assay = NULL,
  metadata = list(),
  provenance = NULL
)

Arguments

Value

An fmri_frame.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
frame

Description

Construct a linked fMRI study

Usage

fmri_study(
  frames,
  entities = list(),
  links = list(),
  tables = list(),
  metadata = list(),
  provenance = NULL
)

Arguments

Value

An fmri_study.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
study <- fmri_study(list(main = frame))
study_ids(study)

Description

Reconstruct a frame from an FDS manifest and physical sources

Usage

frame_from_fds_manifest(manifest, bindings)

Arguments

Value

An fmri_frame whose semantic state comes from manifest and whose lazy arrays come from bindings.

Examples

voxels <- volume_space(dim = c(2, 2, 1), affine = diag(4), template = "toy")
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(3 * n_features(voxels)), nrow = 3)),
  observations = data.frame(.obs_id = paste0("vol-", 1:3)),
  space = voxels
)
manifest <- fds_frame_manifest(frame)
bindings <- fds_frame_bindings(frame)
rebuilt <- frame_from_fds_manifest(manifest, bindings)
identical(feature_ids(rebuilt), feature_ids(frame))

Description

Describe a typed link between study representations

Usage

frame_link(
  source,
  target,
  type = c("derivation", "mapping", "correspondence", "alignment"),
  map = NULL,
  source_axis = c("observation", "feature"),
  target_axis = c("observation", "feature"),
  metadata = list(),
  operator = NULL
)

Arguments

Value

A frame_link descriptor.

Examples

link <- frame_link("bold", "surface", type = "derivation")
link$source
link$target

Description

The schema describes aligned assay annotations, scalar column types and factor levels, multivariate block trailing axes and components, spatial identity, entities, relations, auxiliary tables, and active-assay policy. It inspects descriptors and metadata only and never reads numerical values.

Usage

frame_schema(x)

Arguments

Value

A serializable fmri_frame_schema.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
schema <- frame_schema(frame)
schema$active_assay

Description

Generic accessors for the components of an fmri_frame or fmri_view: its assays, active assay, observation and feature axes and IDs, block registries, and dimensions.

Usage

assays(x, ...)

assay(x, name = active_assay(x), ...)

active_assay(x, ...)

observation_axis(x, ...)

observations(x, resolve = FALSE, ...)

features(x, ...)

observation_ids(x, ...)

obs_blocks(x, resolve = FALSE, ...)

feature_blocks(x, ...)

## S3 method for class 'fmri_frame'
dim(x)

## S3 method for class 'fmri_view'
dim(x)

Arguments

Value

assays() returns a named aligned_assay_set list and assay() one aligned_assay from it. active_assay() returns a single assay name. observation_axis() returns an axis_frame; observations() and features() return a data frame of the corresponding metadata. observation_ids() and feature_ids() return character vectors of stable IDs. obs_blocks() and feature_blocks() return named lists of axis_blocks. dim() returns a length-2 integer vector, and nrow() and ncol() return single integers.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
names(assays(frame))
active_assay(frame)
dim(frame)

Description

Validate and compare canonical frame schemas

Usage

validate_frame_schema(schema)

compare_frame_schema(x, reference, mode = c("same", "collection", "bind"))

validate_against_schema(x, reference, mode = c("same", "collection", "bind"))

frame_schema_digest(x)

Arguments

Details

compare_frame_schema() treats named records, such as column descriptors and the assay, entity, relation, and table registries, as unordered: column order and assay registry order are not semantic. This matches frame_schema_digest(), whose canonical encoding sorts record fields by name. Unnamed sequences such as feature and component IDs remain order-sensitive. validate_frame_schema() checks the shape of every section and rejects missing or unknown top-level fields.

Value

Validators return their input invisibly. compare_frame_schema() returns a structured frame_schema_compatibility report. frame_schema_digest() returns a single hex digest string.

Examples

sp <- volume_space(dim = c(2, 2, 2), affine = diag(4))
frame <- fmri_frame(
  assays = list(bold = matrix(rnorm(4 * n_features(sp)), nrow = 4)),
  observations = data.frame(.obs_id = sprintf("vol-%d", 1:4)),
  space = sp
)
schema <- frame_schema(frame)
validate_frame_schema(schema)
compare_frame_schema(frame, frame)$compatible
frame_schema_digest(frame)

Description

Compute the deterministic digest of a hierarchy index

Usage

hierarchy_digest(x)

Arguments

Value

A SHA-256 digest.

Examples

subject <- entity_frame(
  data = tibble::tibble(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
observations <- tibble::tibble(
  .obs_id = paste0("obs-", 1:4),
  subject_id = c("sub-1", "sub-1", "sub-2", "sub-2")
)
frame <- fmri_frame(
  assays = list(beta = memory_source(matrix(as.double(1:12), 4, 3))),
  observations = observations,
  entities = list(subject = subject),
  relations = list(
    observation_subject = key_relation("subject_id", target = "subject")
  )
)
idx <- hierarchy_index(frame, levels = "subject")
hierarchy_digest(idx)

Description

A hierarchy index is an immutable, assay-free cache derived from validated key relations. levels are supplied root-to-leaf. Each adjacent edge must form a strict chain from observations to the deepest entity and then through its parents. Crossed relations are therefore never mistaken for containment.

Usage

hierarchy_index(x, levels, relations = NULL)

Arguments

Details

Integer group codes use entity-registry order, so they remain stable when a frame is filtered or reordered.

Value

An fmri_hierarchy_index.

Examples

subject <- entity_frame(
  data = tibble::tibble(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
observations <- tibble::tibble(
  .obs_id = paste0("obs-", 1:4),
  subject_id = c("sub-1", "sub-1", "sub-2", "sub-2")
)
frame <- fmri_frame(
  assays = list(beta = memory_source(matrix(as.double(1:12), 4, 3))),
  observations = observations,
  entities = list(subject = subject),
  relations = list(
    observation_subject = key_relation("subject_id", target = "subject")
  )
)
idx <- hierarchy_index(frame, levels = "subject")
hierarchy_ids(idx)

Description

Access derived hierarchy index data

Usage

hierarchy_ids(x)

hierarchy_groups(x)

hierarchy_levels(x)

hierarchy_relations(x)

hierarchy_complete(x)

Arguments

Value

hierarchy_ids() returns stable entity IDs; hierarchy_groups() returns stable integer grouping codes; hierarchy_levels() and hierarchy_relations() return named character vectors; hierarchy_complete() returns a logical vector.

Examples

subject <- entity_frame(
  data = tibble::tibble(subject_id = c("sub-1", "sub-2")),
  key = "subject_id"
)
observations <- tibble::tibble(
  .obs_id = paste0("obs-", 1:4),
  subject_id = c("sub-1", "sub-1", "sub-2", "sub-2")
)
frame <- fmri_frame(
  assays = list(beta = memory_source(matrix(as.double(1:12), 4, 3))),
  observations = observations,
  entities = list(subject = subject),
  relations = list(
    observation_subject = key_relation("subject_id", target = "subject")
  )
)
idx <- hierarchy_index(frame, levels = "subject")
hierarchy_ids(idx)
hierarchy_groups(idx)
hierarchy_levels(idx)
hierarchy_relations(idx)
hierarchy_complete(idx)

Description

Inspect axis ID durability

Usage

axis_id_policy(x)

ids_are_durable(x)

Arguments

Value

axis_id_policy() returns the versioned ID-policy descriptor; ids_are_durable() returns one logical value.

Examples

x <- axis_frame(data.frame(value = 1:3), id_policy = "ephemeral")
axis_id_policy(x)
ids_are_durable(x)

Description

Semantic and schema identities are independent of physical locations. Source fingerprints identify descriptors and selectors, not array contents. Content digests are optional receipts computed explicitly by content_hash() or supplied by a backend; this function never reads data to infer one, so the content domain always requires content_digest.

Usage

identity_descriptor(
  x,
  domain = c("auto", "semantic", "schema", "space", "source", "provenance", "content"),
  content_digest = NULL
)

Arguments

Value

A serializable typed identity descriptor.

Examples

src <- memory_source(matrix(seq_len(6), nrow = 2))
identity_descriptor(src)$domain

Description

Construct a generic indexed feature space

Usage

index_space(
  n,
  ids = NULL,
  namespace = NULL,
  data = NULL,
  id_policy = c("require", "deterministic", "ephemeral")
)

Arguments

Value

An index_space.

Examples

index_space(3, ids = c("a", "b", "c"))
index_space(2, namespace = "roi", id_policy = "deterministic")

Description

A key relation does not duplicate a mapping. It declares that one scalar column on an observation, feature, or entity table references the stable IDs of one entity frame.

Usage

key_relation(
  key,
  target = NULL,
  source = "observation",
  allow_missing = FALSE,
  metadata = list()
)

Arguments

Value

A serializable key_relation descriptor.

Examples

rel <- key_relation("stimulus_id", target = "stimulus", source = "observation")
rel$key