Bayesian Multidimensional Scaling (BMDS)

This function performs Bayesian Multidimensional Scaling (BMDS) using a specified distance matrix and predefined positions for stimuli. It uses the JAGS (Just Another Gibbs Sampler) framework to estimate the positions of stimuli in a lower-dimensional space.

Usage

BMDS(data, posStims, negStims, z, fname = NULL, n.sample = 2500, ...)

Arguments

data: A numeric matrix representing the observed distance matrix. The matrix should be symmetric with non-negative entries.
posStims: A numeric vector of length 2 specifying the indices of the stimuli that should be constrained to have positive coordinates on the first and second dimensions, respectively.
negStims: A numeric vector of length 2 specifying the indices of the stimuli that should be constrained to have negative coordinates on the first and second dimensions, respectively.
z: A numeric matrix with the initial positions for the stimuli. Missing values (NA) indicate positions to be estimated.
fname: A character string specifying the file name to which the JAGS model code should be written. This argument is required.
n.sample: An integer specifying the number of MCMC samples to draw. The default is 2500.
...: Additional arguments passed to the JAGS model, such as n.chains and n.adapt.

Value

An invisible list with two components:

zhat: An object containing the MCMC samples for the estimated positions.
zhat.ci: A data frame containing the summary statistics (mean, standard deviation, and credible intervals) for the estimated positions.

Details

This function requires the rjags package and JAGS software to run. It constructs a JAGS model that imposes constraints on the positions of certain stimuli (specified by posStims and negStims) and estimates the remaining positions using MCMC sampling. The model is written to a file specified by fname, and the function then runs the JAGS model using the specified number of samples.

Examples

if (FALSE) { # \dontrun{
# Load the nations dataset (assuming it's already loaded in your environment)
# If not, load or create a similar dataset with distance values.
data(nations)
# Initialize the z matrix with NA values and set specific starting points
z <- matrix(NA, nrow = nrow(nations), ncol = 2)
z[10, ] <- 0        # Fix both dimensions of the 10th stimulus to 0
z[11, 2] <- 0       # Fix the second dimension of the 11th stimulus to 0

# Perform Bayesian Multidimensional Scaling (BMDS)
nations.bmds <- BMDS(nations, 
                     posStims = c(7, 2),  # Stimuli to constrain to positive coordinates
                     negStims = c(9, 8),  # Stimuli to constrain to negative coordinates
                     z = z,               # Initial positions matrix
                     fname = "nations_jags.txt",  # File to write the JAGS model
                     n.sample = 10000,     # Number of MCMC samples
                     n.adapt = 10000)      # Number of adaptation steps

# Inspect the result
print(nations.bmds$zhat.ci)  # Print the summary statistics for the estimated positions
} # }