MicroTrace: SNP Clustering for Outbreaks

• MicroTrace is an open-source R tool for SNP-based hierarchical clustering of pathogen genomes, transforming SNP distance matrices into candidate transmission clusters.
• It employs a default 10th-percentile threshold suggestion and integrates metadata such as collection date, ward, and patient ID to support actionable outbreak investigations.
• The tool generates publication-ready dendrograms, tables, and customizable HTML reports, bridging upstream genomic analyses with real-time public health interpretation.

Searching arXiv for the specified paper and closely related trace/pathogen-clustering context. MicroTrace is an open-source R tool for SNP-based hierarchical clustering of pathogen whole-genome sequencing data to identify potential transmission clusters in outbreak investigations (Lai, 10 Jul 2025). It is designed for epidemiologists, microbiologists, and genomic surveillance teams, and addresses the practical step between upstream genomics pipelines and downstream public health interpretation: turning pairwise SNP distance matrices into candidate outbreak clusters, dendrograms, metadata-aware tables, and a customizable HTML report. The tool is presented as lightweight, scriptable, and reproducible, with minimal setup and a workflow suited to both routine genomic surveillance and retrospective outbreak review (Lai, 10 Jul 2025).

1. Purpose and epidemiological role

MicroTrace targets the operational problem of converting genomic relatedness into actionable outbreak summaries. In hospital and surveillance practice, users may already have genome-derived pairwise SNP distances, yet still need to determine which isolates form genetically tight groups, what SNP cutoff should define a likely cluster, how those clusters align with collection date, ward, or patient ID, and how to communicate the results rapidly and reproducibly (Lai, 10 Jul 2025).

The tool is framed around the common genomic epidemiology premise that closely related isolates tend to have low pairwise SNP distances, and that these distances can be used to group isolates into candidate outbreak or transmission clusters (Lai, 10 Jul 2025). MicroTrace therefore focuses not on read mapping, variant calling, or SNP discovery, but on downstream clustering and interpretation. It is explicitly positioned for clinical microbiology and public health settings where a simple, real-time analytic workflow is needed, while remaining equally applicable to retrospective analysis because it operates from existing SNP distance matrices and optional metadata (Lai, 10 Jul 2025).

The paper characterizes the tool as filling a niche between upstream variant pipelines and visualization utilities. Tools such as Snippy are identified with variant calling, and GrapeTree with phylogenetic visualization, whereas MicroTrace is presented as a lightweight R-based tool for direct clustering from SNP matrices (Lai, 10 Jul 2025). Its contribution is therefore primarily workflow-oriented rather than theoretical: a compact implementation of SNP-threshold-based hierarchical clustering for outbreak detection.

2. Inputs, assumptions, and computational workflow

MicroTrace begins from a pairwise SNP distance matrix derived from pathogen whole-genome sequencing. The accepted input explicitly described is a pairwise SNP distance matrix loaded from CSV, with optional metadata (Lai, 10 Jul 2025). The metadata fields explicitly mentioned are collection date, ward, and patient ID. The paper does not mention direct FASTA, VCF, BAM, or FASTQ input, nor database connectivity or alternative matrix formats (Lai, 10 Jul 2025).

The workflow consists of six automated stages: loading the SNP distance matrix, suggesting a threshold based on the distance distribution, performing hierarchical clustering, cutting the dendrogram into clusters at a chosen SNP cutoff, merging metadata, and generating figures, tables, and an HTML report (Lai, 10 Jul 2025). MicroTrace does not itself perform read mapping, variant calling, or SNP matrix generation; those steps are assumed to have been completed upstream (Lai, 10 Jul 2025).

The named software components described in the paper are concise and modular.

Component	Role
distance_loader()	Loads a pairwise SNP distance matrix from CSV
auto_threshold_suggestion()	Suggests a clustering threshold and generates a histogram and density plot
run_microtrace_clustering()	Performs UPGMA hierarchical clustering, cuts the tree, and generates outputs
MicroTrace_Report.Rmd	Produces a customizable HTML report

The implementation is deliberately lightweight. The paper attributes this to a small set of modular R functions, use of a simple CSV SNP distance matrix rather than a full variant-calling pipeline, minimal setup, automatic production of standard outputs, metadata integration, a Markdown-based HTML report template, and unit tests for core functions (Lai, 10 Jul 2025).

The preprocessing assumptions are correspondingly limited. Pathogen whole-genome sequencing must already have been performed, pairwise SNP distances must already have been computed, and the resulting matrix must be suitable for outbreak analysis (Lai, 10 Jul 2025). No detailed quality-control protocol is specified, and the paper gives no thresholds for genome coverage, read depth, contamination, missing data, recombinant region masking, or SNP-calling quality (Lai, 10 Jul 2025). This suggests that MicroTrace assumes a valid SNP distance matrix prepared by an upstream workflow, but does not formalize QC requirements itself.

3. Thresholding, clustering, and cluster definition

MicroTrace uses threshold-based hierarchical clustering. The clustering algorithm is UPGMA, that is, average-linkage hierarchical clustering, and the final clusters are obtained by cutting the resulting dendrogram at a selected SNP threshold (Lai, 10 Jul 2025). Because the linkage is average-based, the inferred groups are shaped by the average pairwise SNP distance between candidate clusters rather than by single-linkage chaining or complete-linkage maximal within-cluster distance criteria (Lai, 10 Jul 2025).

A central feature is the default threshold suggestion. The paper states that exploratory analyses showed closely related isolates often had SNP distances in the lowest decile of all pairwise comparisons, and on that basis MicroTrace uses the 10th percentile of pairwise SNP distances as a conservative default threshold for outbreak definition, with the stated goal of prioritizing sensitivity in early cluster detection (Lai, 10 Jul 2025). The threshold remains configurable for local epidemiologic context.

A precise rendering of the described default rule is: $t_{\text{default}} = Q_{0.10}(D),$ where $D$ denotes the collection of all pairwise SNP distances and $Q_{0.10}$ the 10th percentile. This notation is a formal rendering of the rule described in prose rather than a formula explicitly printed in the paper (Lai, 10 Jul 2025).

Likewise, the cluster cut step can be rendered as: $C = \operatorname{cutree}(T, h=t),$ where $T$ is the UPGMA dendrogram and $t$ is the selected SNP threshold. This again is a precise mathematical expression of the described procedure rather than notation explicitly printed in the paper (Lai, 10 Jul 2025).

Threshold selection is supported visually by auto_threshold_suggestion(), which generates both a histogram and a density plot of pairwise SNP distances (Lai, 10 Jul 2025). In practical terms, the paper notes that a lower threshold generally yields smaller, tighter clusters and may miss some related isolates, whereas a higher threshold generally yields larger, broader clusters and may join isolates that are less closely related (Lai, 10 Jul 2025). The default is therefore conservative but not normative; pathogen, setting, and surveillance objective remain important determinants of the final cutoff.

The paper consistently refers to the output groups as potential transmission clusters rather than confirmed transmission events (Lai, 10 Jul 2025). That wording is significant. It indicates that genomic clustering is treated as evidence of genetic relatedness sufficient to warrant epidemiologic follow-up, not as a definitive reconstruction of person-to-person transmission.

4. Outputs, metadata integration, and reproducibility features

MicroTrace produces several output artifacts intended for both analysis and communication. It generates dendrograms representing the hierarchical clustering of isolates, and these are also available as publication-ready PNG files (Lai, 10 Jul 2025). It outputs cluster tables listing cluster assignments for isolates, with optional metadata joined in so that clusters can be interpreted in spatiotemporal context (Lai, 10 Jul 2025).

The tool also computes intra-cluster SNP summary statistics, specifically mean, standard deviation, and range (Lai, 10 Jul 2025). These provide a compact description of the genetic tightness of each inferred cluster. In addition, threshold exploration outputs include the SNP distance histogram and density plot produced by auto_threshold_suggestion() (Lai, 10 Jul 2025).

A separate reporting template, MicroTrace_Report.Rmd, produces a Markdown-based HTML report summarizing clustering results, the SNP distance histogram, the SNP distance density plot, the dendrogram, and metadata-aware statistics (Lai, 10 Jul 2025). The paper emphasizes the utility of this report for communication with infection control and public health teams (Lai, 10 Jul 2025).

Metadata integration is central to interpretation rather than a peripheral feature. The explicitly named metadata fields are collection date, ward, and patient ID (Lai, 10 Jul 2025). These fields are merged into the output tables so that genetic clusters can be examined alongside time, place, and patient linkage. No formal metadata schema is given, but the intended use is clear: align genetic relatedness with hospital or public health context (Lai, 10 Jul 2025).

Reproducibility is emphasized through a scripted R workflow, the Markdown-based HTML report, a tests/ directory, and automated unit tests using testthat (Lai, 10 Jul 2025). The paper specifies that test coverage includes distance matrix loading, threshold estimation, cluster output generation, and output dimensions and object class checks (Lai, 10 Jul 2025). These features support reproducibility and continuous integration, although no specific CI platform is named.

MicroTrace is explicitly described as open source, with source code freely available on GitHub at https://github.com/biosciences/MicroTrace (Lai, 10 Jul 2025). No software license is specified in the provided excerpt (Lai, 10 Jul 2025).

5. Demonstration and practical interpretation

The paper includes a simulated dataset example with 10 samples (Lai, 10 Jul 2025). In that demonstration, isolates from Ward A have pairwise SNP distances of 0--3, isolates from Ward B have pairwise SNP distances of 7--10, and using a 5-SNP threshold MicroTrace correctly identifies two distinct groups (Lai, 10 Jul 2025). This example illustrates three practical points: the clustering workflow can recover genetically distinct groups, metadata integration helps align clusters with ward information, and the method is useful for localized outbreak tracking in hospitals or communities (Lai, 10 Jul 2025).

The paper also outlines a practical use pattern in public health or hospital laboratories. A team would generate or receive a pairwise SNP distance matrix from WGS-derived analyses, load the matrix in R with distance_loader(), inspect the SNP distance distribution with auto_threshold_suggestion(), use the 10th percentile as a default starting threshold or choose another based on local epidemiology, run UPGMA clustering with run_microtrace_clustering(), cut the dendrogram at the chosen threshold to define candidate clusters, merge metadata such as collection date, ward, and patient ID, review the dendrogram, cluster table, and intra-cluster statistics, and optionally generate the HTML report for communication with infection control or public health teams (Lai, 10 Jul 2025).

Interpretively, the paper supports a cautious use of clusters. Because the output is framed as potential transmission clusters, genomic similarity should inform outbreak investigation rather than replace epidemiologic inference (Lai, 10 Jul 2025). Metadata integration is intended to support exactly that synthesis: genetic proximity alone does not resolve direct transmission, whereas combined genomic and spatiotemporal evidence can prioritize follow-up.

6. Position in the software landscape, strengths, and limitations

MicroTrace is presented as a pragmatic downstream clustering utility rather than an end-to-end genomics platform. Its strengths, as identified in the paper, include lightweight and minimal setup, direct use of SNP distance matrices, automated hierarchical clustering, configurable thresholding with a default recommendation, metadata integration, publication-ready visualization, HTML report generation, reproducibility through testing and scripted use, and practical suitability for real-time response in hospital and public health settings (Lai, 10 Jul 2025).

The paper does not include a formal limitations section, but several limits are explicit from scope and omissions. MicroTrace does not perform upstream SNP calling or genome QC, provides no explicit pathogen-specific threshold calibration beyond the 10th-percentile heuristic, reports no runtime benchmarks, memory usage, or scalability testing, and presents no extensive real-world outbreak validation in the paper (Lai, 10 Jul 2025). No head-to-head quantitative comparison against Snippy, GrapeTree, or manual workflows is given; the comparisons remain conceptual (Lai, 10 Jul 2025).

These omissions matter for interpretation. The absence of QC guidance means that results depend on the validity of the supplied distance matrix. The absence of pathogen-specific threshold calibration means that the 10th-percentile heuristic should not be treated as universally optimal. The lack of runtime and scalability evaluation leaves large-surveillance performance unspecified. The framing of clusters as potential transmission clusters also implicitly cautions against overinterpreting genetic clustering as direct transmission evidence (Lai, 10 Jul 2025).

Taken together, MicroTrace is best understood as a lightweight, reproducible R implementation for transforming WGS-derived SNP distance matrices into candidate outbreak clusters, metadata-linked tables, visual summaries, and reports (Lai, 10 Jul 2025). Its value lies in operationalizing a common outbreak-analysis workflow with minimal setup and explicit support for interpretation and communication, rather than in proposing a new clustering theory or an end-to-end genomics stack.