topolow-package

Helper functions for running RACMACS and Topolow during algorithm comparisons.
The <code>topolow</code> 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.

internal

A robust implementation of Topolow algorithm. It embeds 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, incomplete, and censored (thresholded) datasets such as antigenic relationships. The core is a physics-inspired, gradient-free optimization framework that models objects as particles in a physical system, where observed dissimilarities define spring rest lengths and unobserved pairs exert repulsive forces. The package also provides functions specific to antigenic mapping to transform cross-reactivity and binding affinity measurements into accurate spatial representations in a phenotype space.
Key features include:
* Robust Embedding from Sparse Data: Effectively creates complete and consistent maps (in optimal dimensions) even with high proportions of missing data (e.g., >95%).
* Physics-Inspired Optimization: Models objects (e.g., antigens, landmarks) as particles connected by springs (for measured dissimilarities) and subject to repulsive forces (for missing dissimilarities), and simulates the physical system using laws of mechanics, reducing the need for complex gradient computations.
* Automatic Dimensionality Detection: Employs a likelihood-based approach to determine the optimal number of dimensions for the embedding/map, avoiding distortions common in methods with fixed low dimensions.
* Noise and Bias Reduction: Naturally mitigates experimental noise and bias through its network-based, error-dampening mechanism.
* Antigenic Velocity Calculation (for antigenic data): Introduces and quantifies "antigenic velocity," a vector that describes the rate and direction of antigenic drift for each pathogen isolate. This can help identify cluster transitions and potential lineage replacements.
* Broad Applicability: Analyzes data from various objects that their dissimilarity may be of interest, ranging from complex biological measurements such as continuous and relational phenotypes, antibody-antigen interactions, and protein folding to abstract concepts, such as customer perception of different brands.
Methods are described in the context of bioinformatics applications in Arhami and Rohani (2025a) <doi:10.1093/bioinformatics/btaf372>, and mathematical proofs and Euclidean embedding details are in Arhami and Rohani (2025b) <doi:10.48550/arXiv.2508.01733>.

Omid Arhami

topolow

Force-Directed Euclidean Embedding of Dissimilarity Data

topolow-package function

<ul>
<li><code>Euclidify</code>: Wizard function to run all steps of the Topolow algorithm automatically</li>
<li><code>euclidean_embedding</code>: Core embedding algorithm</li>
<li><code>initial_parameter_optimization</code>: Find optimal parameters using Latin Hypercube Sampling.</li>
<li><code>run_adaptive_sampling</code>: Refine parameter estimates with adaptive Monte Carlo sampling.</li>
</ul>

Main Functions

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:<ul>
<li>model_parameters/: Contains optimization results and parameter evaluations</li>
<li>init_param_optimization/: Contains files and outputs when using initial_parameter_optimization</li>
</ul>

Output Files

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
tools:::Rd_expr_doi("10.1093/bioinformatics/btaf372").
<code>bibtex</code> 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
tools:::Rd_expr_doi("10.48550/arXiv.2508.01733").
<code>bibtex</code> 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}

Citation

Maintainer: Omid Arhami <a href="/link/omid.arhami%40uga.edu?package=topolow&version=2.0.1" data-mini-rdoc="topolow::omid.arhami@uga.edu">omid.arhami@uga.edu</a> (<a href="https://orcid.org/0009-0005-2681-6598">ORCID</a>) [copyright holder]

Author

Algorithm Comparison Helper Functions — topolow-package

<ul>
<li><code>Euclidify</code>: Wizard function to run all steps of the Topolow algorithm automatically</li>
<li><code>euclidean_embedding</code>: Core embedding algorithm</li>
<li><code>initial_parameter_optimization</code>: Find optimal parameters using Latin Hypercube Sampling.</li>
<li><code>run_adaptive_sampling</code>: Refine parameter estimates with adaptive Monte Carlo sampling.</li>
</ul>

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:<ul>
<li>model_parameters/: Contains optimization results and parameter evaluations</li>
<li>init_param_optimization/: Contains files and outputs when using initial_parameter_optimization</li>
</ul>

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
tools:::Rd_expr_doi("10.1093/bioinformatics/btaf372").
<code>bibtex</code> 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
tools:::Rd_expr_doi("10.48550/arXiv.2508.01733").
<code>bibtex</code> 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}

Maintainer: Omid Arhami <a href='mailto:omid.arhami@uga.edu'>omid.arhami@uga.edu</a> (<a href='https://orcid.org/0009-0005-2681-6598'>ORCID</a>) [copyright holder]

topolow-package: Algorithm Comparison Helper Functions

Description

Arguments

Main Functions

Output Files

Citation

Author

Details

See Also