create_topolow_map: Main TopoLow algorithm implementation (DEPRECATED)

In topolow: Force-Directed Euclidean Embedding of Dissimilarity Data

Main TopoLow algorithm implementation (DEPRECATED)

Description

create_topolow_map() was deprecated in version 2.0.0 and will be removed in a future version. Please use euclidean_embedding() instead, which provides the same functionality with improved performance and additional features.

Usage

create_topolow_map(
  distance_matrix,
  ndim,
  mapping_max_iter = 1000,
  k0,
  cooling_rate,
  c_repulsion,
  relative_epsilon = 1e-04,
  convergence_counter = 3,
  initial_positions = NULL,
  write_positions_to_csv = FALSE,
  output_dir,
  verbose = FALSE
)

Arguments

distance_matrix	Matrix. Square, symmetric distance 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(distance_matrix) and ncol = ndim.
write_positions_to_csv	Logical. Whether to save point positions to CSV file. Default is FALSE.
output_dir	Character. Directory to save CSV file. Required if write_positions_to_csv is TRUE.
verbose	Logical. Whether to print progress messages. Default is FALSE.

Details

This function has been superseded by euclidean_embedding(), which offers:

• Enhanced matrix reordering for better optimization

• Improved parameter validation with informative warnings

• Consistent naming convention (dissimilarity vs distance)

• Better documentation and examples

The core algorithm remains identical, ensuring your results will be equivalent. The main changes are:

• Parameter name: distance_matrix –> dissimilarity_matrix

• Function name: create_topolow_map() –> euclidean_embedding()

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 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.

See Also

euclidean_embedding() for the replacement function.

Examples

# Simple example (deprecated - use euclidean_embedding() instead)
dist_mat <- matrix(c(0, 2, 3, 2, 0, 4, 3, 4, 0), nrow=3)

# This will generate a deprecation warning
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
)

# Recommended approach with new function:
result_new <- 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
)

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