Match a data-frame column to atlas parcels and return a numeric vector in exact `atlas$ids` order. Matching is strict by default: atlas and data keys must be unique, data keys must all exist in the atlas, and every atlas parcel must be represented unless `allow_partial = TRUE`.
Arguments
- atlas
An atlas object.
- data
A data frame, tibble, or `parcel_data` object containing parcel keys and values.
- value
A numeric value column, supplied as a bare name or string.
- by
Parcel-key specification. Use a shared column name such as `"id"`, or a named character vector to map an atlas metadata column to a differently named data column, for example `c(id = "roi_index")`. Composite keys are supported. When `NULL`, a safe unique key is inferred.
- allow_partial
Logical. If `FALSE` (default), `data` must contain every atlas parcel. If `TRUE`, unmatched atlas parcels receive `NA`. Unknown and duplicate data keys always error.
Details
With `by = NULL`, `id` is preferred, followed by `label_full`. Composite label keys are considered only when they are unique in both the atlas and data. Ambiguous short labels therefore fail instead of being recycled across hemispheres or networks.
Atlas metadata columns supplied in `data` are treated as consistency checks. They are never allowed to overwrite canonical metadata.
Glasser volume and surface IDs number opposite hemispheres first. Any
Glasser join using id (including renamed or composite keys) therefore
requires a matching id_convention column, or a parcel_data
object
with a matching atlas$id_convention. The convention is
"hcp_R_first" for volumes and "surfatlas_L_first" for surfaces.
Only declare a convention
when the source of the IDs is known; missing or conflicting conventions
cause an error. Reload older Glasser atlas objects that lack this metadata.
To move Glasser values between representations, supply only the shared
label_full key and value columns, then use by = "label_full";
alternatively use by = c("area", "hemi"). For example, select
source$parcels[c("label_full", "value")] from a parcel_data
object.
Representation-specific IDs, labels, colours and provenance in a full
source table remain consistency checks and must be omitted for such a join.
A complete parcel_data object remains bound to its source
representation.
Examples
atlas <- structure(
list(
name = "toy",
atlas = array(1:3, c(3, 1, 1)),
ids = 1:3,
labels = c("A", "B", "C"),
orig_labels = c("lh_A", "lh_B", "rh_C"),
hemi = c("left", "left", "right")
),
class = "atlas"
)
results <- data.frame(
roi_index = c(3L, 1L, 2L),
estimate = c(0.3, 0.1, 0.2)
)
align_parcel_values(
atlas,
results,
value = estimate,
by = c(id = "roi_index")
)
#> 1 2 3
#> 0.1 0.2 0.3