euclidean_embedding: Main topolow algorithm implementation

Description

topolow (topological stochastic pairwise reconstruction for Euclidean embedding) optimizes point positions in an N-dimensional space to match a target dissimilarity matrix. The algorithm uses a physics-inspired approach with spring and repulsive forces to find optimal point configurations while handling missing and thresholded measurements.

Usage

euclidean_embedding(
  dissimilarity_matrix,
  ndim,
  mapping_max_iter = 1000,
  k0,
  cooling_rate,
  c_repulsion,
  relative_epsilon = 1e-04,
  convergence_counter = 5,
  initial_positions = NULL,
  write_positions_to_csv = FALSE,
  output_dir,
  verbose = FALSE
)

Value

A list object of class topolow. This list contains the results of the optimization and includes the following components:

positions: A matrix of the optimized point coordinates in the N-dimensional space.
est_distances: A matrix of the Euclidean distances between points in the final optimized configuration.
mae: The final Mean Absolute Error between the target dissimilarities and the estimated distances.
iter: The total number of iterations performed before the algorithm terminated.
parameters: A list containing the input parameters used for the optimization run.
convergence: A list containing the final convergence status, including a logical achieved flag and the final error value.

Arguments

dissimilarity_matrix: Matrix. A square, symmetric dissimilarity matrix. Can contain NA values for missing measurements and character strings with < or > prefixes for thresholded measurements.
ndim: Integer. Number of dimensions for the embedding space.
mapping_max_iter: Integer. Maximum number of map optimization iterations.
k0: Numeric. Initial spring constant controlling spring forces.
cooling_rate: Numeric. Rate of spring constant decay per iteration (0 < cooling_rate < 1).
c_repulsion: Numeric. Repulsion constant controlling repulsive forces.
relative_epsilon: Numeric. Convergence threshold for relative change in error. Default is 1e-4.
convergence_counter: Integer. Number of iterations below threshold before declaring convergence. Default is 5.
initial_positions: Matrix or NULL. Optional starting coordinates. If NULL, random initialization is used. Matrix should have nrow = nrow(dissimilarity_matrix) and ncol = ndim.
write_positions_to_csv: Logical. Whether to save point positions to a CSV file. Default is FALSE.
output_dir: Character. Directory to save the CSV file. Required if write_positions_to_csv is TRUE.
verbose: Logical. Whether to print progress messages. Default is FALSE.

Details

The algorithm iteratively updates point positions using:

Spring forces between points with measured dissimilarities.
Repulsive forces between points without measurements.
Conditional forces for thresholded measurements (< or >).
An adaptive spring constant that decays over iterations.
Convergence monitoring based on relative error change.
Automatic matrix reordering to optimize convergence. Consider if downstream analyses depend on specific point ordering: The order of points in the output is adjusted to put high-dissimilarity points in the opposing ends.

This function replaces the deprecated create_topolow_map(). The core algorithm is identical, but includes performance improvements and enhanced validation.

Examples

Run this code

# Create a simple dissimilarity matrix
dist_mat <- matrix(c(0, 2, 3, 2, 0, 4, 3, 4, 0), nrow=3)

# Run topolow in 2D
result <- euclidean_embedding(
  dissimilarity_matrix = dist_mat,
  ndim = 2,
  mapping_max_iter = 100,
  k0 = 1.0,
  cooling_rate = 0.001,
  c_repulsion = 0.01,
  verbose = FALSE
)

# View results
head(result$positions)
print(result$mae)

# Example with thresholded measurements
thresh_mat <- matrix(c(0, ">2", 3, ">2", 0, "<5", 3, "<5", 0), nrow=3)
result_thresh <- euclidean_embedding(
  dissimilarity_matrix = thresh_mat,
  ndim = 2,
  mapping_max_iter = 50,
  k0 = 0.5,
  cooling_rate = 0.01,
  c_repulsion = 0.001
)