euclidean_embedding: Main topolow algorithm implementation

In topolow: Force-Directed Euclidean Embedding of Dissimilarity Data

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
)

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.

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.

See Also

create_topolow_map() for the deprecated predecessor function.

Examples

# 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
)

topolow documentation built on Aug. 31, 2025, 1:07 a.m.