topolow

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.

Examples that run

87%

Documented parameters

94%

Return-value docs

97%

References docs

0%

6Stars

3Forks

0Open issues

0Open PRs

11Releases

252Commits

3Contributors

4 development-tooling and community-health practices detected across 4 families in the upstream repository

Checks run against github.com/omid-arhami/topolow on 2026-08-23.

Nothing depends on this yet.

3 releases. Pick two to compare their code metrics. R releases are shown for context.

First published

2025-07-11

Total releases

3 / 1 yrs

License

BSD_3_clause + file LICENSE OSI

Minimum R

≥ 4.1.0

Bundled data

333 KB / 5 files

Download size

1.5 MB

Installed size

not tracked yet

With dependencies

not tracked yet

Cite this package

Run in R for the authors' preferred citation:

The authors publish a JOSS paper, so they have said how they want this cited. Run citation() and use what it gives you.

Cite the R Observatory

For a number measured here: a download total, a coverage figure, an archival date.

From data release v2026-08-23, which the citation names so these numbers can be found later. More on citing and the projects behind them.