tcfinder

A lightweight tool to find clusters of samples from a list of identifiers within a phylogeny in phylo4 format (see phylobase), regarding a minimum cluster size and a minimum proportion of targets in the cluster.

Installation

This tool is available through the bioconda conda channel. Check out the package recipe for more information. Run the following command to install it in the current conda environment.

shell conda install -c bioconda tcfinder

The most recent release can be retrieved through the Releases section (see latest release). As a Rust project, it can be built and tested using cargo.

Usage

Quick reference

```txt Usage: tcfinder [OPTIONS] --tree --targets --output

Options: -i, --tree Input tree in phylo4 format (mandatory CSV columns are 'label', 'node', 'ancestor' and 'nodetype') -t, --targets Input list of target labels plain text (one tip label per line) -o, --output

Output CSV file with clustering result -s, --minimum-size Minimum cluster size [default: 2] -p, --minimum-prop Minimum proportion of targets in cluster [default: 0.9] -v, --verbose Prints debug messages -h, --help Print help -V, --version Print version ```

For example, the following command will analyze the test data using the default thresholds.

shell tcfinder -i test/rtree.csv -t test/targets.txt -o test/clusters.csv

Building a phylo4 tree

Trees can easily be converted to phylo4 format using the phylobase R package. As an example, the following code was used for generating the test tree. A similar approach may be used to convert an existing tree after reading it from disk (for instance, Newick files can be read using the read.tree function from the ape package).

```R library(ape) # v5.6-2 library(phylobase) # v0.8.10

Generate random tree with 100 tips

tree <- rtree(100)

Convert to phylo4

tree.p4 <- as(tree, "phylo4")

Convert to dataframe and set undotted column names

tree.p4.df <- as(tree.p4, "data.frame") names(tree.p4.df) <- c("label", "node", "ancestor", "edgelength", "nodetype") ```

Note that column names are key. The input tree file must contain the following columns:

• label: a node label string (often found only for tip nodes).
• node: an integer indicating the node index, starting from 1.
• ancestor: an integer indicating the node index of the ancestor of the node. In a tree, a node can only have a single ancestor. A value of 0 indicates that the node has no ancestors (i.e. it is the tree root).
• nodetype: a string, either "tip", "internal" or "root". It is only used for checking if the node is a tip.

Branch lengths are not considered in the current implementation. Users can take this variable into consideration by collapsing nodes beforehand.

Clade stats

Threshold clade stats are provided via the command line. Qualifying clades must meet both criteria.

• --minimum-size: an integer indicating the minimum cluster size, i.e. the minimum number of target tips (or leaves) in a qualifying clade.
• --minimum-prop: a floating point number in [0,1] indicating the minimum proportion of target tips in a qualifying clade.

The following figure shows the stats of two clades, the first of whic qualifies under the default thresholds (✓), while the second does not (✗).

Citation

This tool was originally developed to support this work:

Álvarez-Herrera M, Ruiz-Rodriguez P, Navarro-Domínguez B, Zulaica J, Grau B, Bracho MA, Guerreiro M, Aguilar-Gallardo C, González-Candelas F, Comas I, Geller R & Coscollá M (2025). Genome data artifacts and functional studies of deletion repair in the BA.1 SARS-CoV-2 spike protein. Virus Evolution, 11(1), veaf015. https://doi.org/10.1093/ve/veaf015

If you find the tool helpful, please feel free to cite the above (see also CITATION.cff).