create_topolow_map {topolow}R Documentation

Main TopoLow algorithm implementation

Description

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.

Usage

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
)

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

Details

The algorithm iteratively updates point positions using:

Valid parameter ranges and constraints:

Value

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

Examples

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


[Package topolow version 1.0.0 Index]