topolow (version 2.0.1)

create_topolow_map: 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
)

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.

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

See Also

euclidean_embedding() for the replacement function.

Examples

# \donttest{
# 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
)
# }