topolow-package: Algorithm Comparison Helper Functions

In topolow: Force-Directed Euclidean Embedding of Dissimilarity Data

Algorithm Comparison Helper Functions

Description

Helper functions for running RACMACS and Topolow during algorithm comparisons.

The topolow package provides a robust implementation of the Topolow algorithm. It is designed to embed objects into a low-dimensional Euclidean space from a matrix of pairwise dissimilarities, even when the data do not satisfy metric or Euclidean axioms. The package is particularly well-suited for sparse or incomplete datasets and includes methods for handling censored (thresholded) data. The package provides tools for processing antigenic assay data, and visualizing antigenic maps.

Details

The core of the package is a physics-inspired, gradient-free optimization framework. It models objects as particles in a physical system, where observed dissimilarities define spring rest lengths and unobserved pairs exert repulsive forces. Key features include:

• Quantitative reconstruction of metric space from non-metric data.

• Robustness against local optima, especially for sparse data, due to a stochastic pairwise optimization scheme.

• A statistically grounded approach based on maximizing the likelihood under a Laplace error model.

• Tools for parameter optimization, cross-validation, and convergence diagnostics.

• Support for parallel processing

• Cross-validation and error analysis

• A comprehensive suite of visualization functions for network analysis and results.

• Processing and visualization of antigenic maps

Main Functions

• Euclidify: Wizard function to run all steps of the Topolow algorithm automatically

• euclidean_embedding: Core embedding algorithm

• initial_parameter_optimization: Find optimal parameters using Latin Hypercube Sampling.

• run_adaptive_sampling: Refine parameter estimates with adaptive Monte Carlo sampling.

Output Files

Functions that generate output files (like parameter optimization results) will create subdirectories in a user-specified directory (via output_dir parameter)

The following subdirectories may be created:

• model_parameters/: Contains optimization results and parameter evaluations

• init_param_optimization/: Contains files and outputs when using initial_parameter_optimization

Citation

If you use this package, please cite the Bioinformatics paper: Omid Arhami, Pejman Rohani, Topolow: A mapping algorithm for antigenic cross-reactivity and binding affinity assays, Bioinformatics, 2025;, btaf372, https://doi.org/10.1093/bioinformatics/btaf372 \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/bioinformatics/btaf372")}.

bibtex entry: title={Topolow: a mapping algorithm for antigenic cross-reactivity and binding affinity assays}, author={Arhami, Omid and Rohani, Pejman}, journal={Bioinformatics}, volume={41}, number={7}, pages={btaf372}, year={2025}, issn = {1367-4811}, doi = {10.1093/bioinformatics/btaf372}, url = {https://doi.org/10.1093/bioinformatics/btaf372}, eprint = {https://academic.oup.com/bioinformatics/article-pdf/41/7/btaf372/63582086/btaf372.pdf}, publisher={Oxford University Press}

And/or the preprint on mathematical properties: Omid Arhami, Pejman Rohani, Topolow: Force-Directed Euclidean Embedding of Dissimilarity Data with Robustness Against Non-Metricity and Sparsity, arXiv:2508.01733, https://doi.org/10.48550/arXiv.2508.01733 \Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2508.01733")}.

bibtex entry: title={Topolow: Force-Directed Euclidean Embedding of Dissimilarity Data with Robustness Against Non-Metricity and Sparsity}, author={Arhami, Omid and Rohani, Pejman}, year={2025}, doi = {10.48550/arXiv.2508.01733}, url = {https://arxiv.org/abs/2508.01733}, publisher={arXiv}

Author(s)

Maintainer: Omid Arhami [e-mail] (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/omid-arhami/topolow

• Report bugs at https://github.com/omid-arhami/topolow/issues

Useful links:

• https://github.com/omid-arhami/topolow

• Report bugs at https://github.com/omid-arhami/topolow/issues

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