Convert Similarity Table to RDM

Converts a similarity lookup table to a Representational Dissimilarity Matrix (RDM) for use in RSA analyses. The function maps label pairs through the similarity table and creates a complete RDM, using default values for missing pairs.

Usage

table_to_rdm(
  similarity_table,
  labels,
  label1_col = "label1",
  label2_col = "label2",
  similarity_col = "similarity",
  default_similarity = 0,
  symmetric = TRUE,
  self_similarity = 1,
  as_dist = TRUE
)

Arguments

similarity_table

A data frame containing pairwise similarity values with columns for label1, label2, and similarity values

labels

A character vector of labels for which to create the RDM. The output RDM will have these labels in this order

label1_col

Character string specifying the column name for the first label (default: "label1")

label2_col

Character string specifying the column name for the second label (default: "label2")

similarity_col

Character string specifying the column name for similarity values (default: "similarity"). Values should be between 0 and 1, where 1 = identical

default_similarity

Numeric value to use for label pairs not found in the table (default: 0, meaning maximum dissimilarity)

symmetric

Logical indicating whether the similarity table should be treated as symmetric (default: TRUE). If TRUE, (A,B) = (B,A)

self_similarity

Numeric value for diagonal elements (self-similarity). Default is 1 (perfect similarity). Set to NA to look up in table

as_dist

Logical; if TRUE return a dist object, otherwise return matrix (default: TRUE)

Value

A dist object or symmetric matrix representing dissimilarities (RDM). Values are computed as 1 - similarity, so that 0 = identical and 1 = maximally different

Details

This function is useful for hypothesis-driven RSA where you have theoretical predictions about the similarity structure between conditions. The similarity table can be sparse (not all pairs need to be specified), and missing pairs will use the default similarity value.

The function converts similarities to dissimilarities using the formula: dissimilarity = 1 - similarity

Examples

# Create a similarity table based on theoretical predictions
sim_table <- data.frame(
  label1 = c("cat", "cat", "dog", "car"),
  label2 = c("dog", "bird", "bird", "plane"),
  similarity = c(0.7, 0.5, 0.6, 0.8)
)

# Create RDM for specific conditions
conditions <- c("cat", "dog", "bird", "car", "plane", "boat")
rdm <- table_to_rdm(sim_table, conditions)

# Get as matrix instead of dist
rdm_matrix <- table_to_rdm(sim_table, conditions, as_dist = FALSE)

# Use in RSA design
if (FALSE) { # \dontrun{
rsa_des <- rsa_design(~ theoretical_rdm,
                     data = list(theoretical_rdm = rdm))
} # }