TopoLow (Topological Optimization for Low-Dimensional Mapping) optimizes point positions in n-dimensional space to match a target distance matrix. The algorithm uses a physics-inspired approach with spring and repulsive forces to find optimal point configurations while handling missing and thresholded measurements.
create_topolow_map(
distance_matrix,
ndim,
mapping_max_iter,
k0,
cooling_rate,
c_repulsion,
relative_epsilon = 1e-04,
convergence_counter = 5,
initial_positions = NULL,
write_positions_to_csv = FALSE,
output_dir,
verbose = FALSE
)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 distances 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.
Matrix. Square, symmetric distance matrix. Can contain NA values for missing measurements and character strings with < or > prefixes for thresholded measurements.
Integer. Number of dimensions for the embedding space.
Integer. Maximum number of map optimization iterations.
Numeric. Initial spring constant controlling spring forces.
Numeric. Rate of spring constant decay per iteration (0 < cooling_rate < 1).
Numeric. Repulsion constant controlling repulsive forces.
Numeric. Convergence threshold for relative change in error. Default is 1e-4.
Integer. Number of iterations below threshold before declaring convergence. Default is 5.
Matrix or NULL. Optional starting coordinates. If NULL, random initialization is used. Matrix should have nrow = nrow(distance_matrix) and ncol = ndim.
Logical. Whether to save point positions to CSV file. Default is FALSE
Character. Directory to save CSV file. Required if write_positions_to_csv is TRUE.
Logical. Whether to print progress messages. Default is TRUE.
The algorithm iteratively updates point positions using:
Spring forces between points with measured distances
Repulsive forces between points without measurements
Modified forces for thresholded measurements (< or >)
Adaptive spring constant that decays over iterations
Convergence monitoring based on relative error change
Valid parameter ranges and constraints:
ndim: Positive integer, typically 2-20.
k0: Initial spring constant, positive numeric > 0. Typical range: 0.1-30 Controls initial force strength
cooling_rate: Spring and repulsion decay rate, numeric between 0 and 1. Typical range: 0.0001-0.1 Controls how quickly spring forces weaken
c_repulsion: Repulsion constant, positive numeric > 0. Typical range: 0.00001-0.1 Controls strength of repulsive forces
relative_epsilon: Positive numeric, typically 1e-9 to 1e-3 Smaller values require more iterations but give higher precision
convergence_counter: Positive integer, typically 5-20 Higher values do not necessarily lead to a better convergence
# Create a simple distance matrix
dist_mat <- matrix(c(0, 2, 3, 2, 0, 4, 3, 4, 0), nrow=3)
# Run TopoLow in 2D without writing to a file
result <- create_topolow_map(dist_mat, ndim=2, mapping_max_iter=100,
k0=1.0, cooling_rate=0.001, c_repulsion=0.01, verbose=FALSE)
# results
head(result$positions)
Run the code above in your browser using DataLab