# Methodological Notes and Limitations

## Scope

`taxodist` represents each taxon as an ordered lineage from the root of The Taxonomicon classification to the queried node. The resulting distance is a property of that classification hierarchy. It is not an estimate of divergence time, genetic distance, or phylogenetic branch length.

## Definition

Let \(L_A\) and \(L_B\) be two ordered lineages. Let \(h(A,B)\) be the length of their continuous common prefix, equivalent to the depth of their most recent common ancestor (MRCA). The distance is

\[ d(A,B) = \begin{cases} 0, & L_A = L_B, \\ 1/h(A,B), & L_A \ne L_B. \end{cases} \]

If two lineages have no shared root, the package returns an infinite distance. Names repeated after the first divergence are not considered evidence of shared ancestry.

Zero is reserved for the same hierarchy node. Consequently, an ancestor and one of its descendants have positive distance even though they are connected by ancestry. Membership and distance answer different questions: `is_member()` and `taxo_path()` should be used for containment and ancestry queries.

## Ultrametric property

For lineages belonging to one connected hierarchy, the distance is non-negative, symmetric, and satisfies identity of indiscernibles. It also satisfies the strong triangle inequality

\[ d(A,C) \leq \max\{d(A,B), d(B,C)\}. \]

The common prefix of \(A\) and \(C\) must be at least as long as the shorter of the common prefixes of \((A,B)\) and \((B,C)\). Therefore,

\[ h(A,C) \geq \min\{h(A,B),h(B,C)\}. \]

Taking reciprocals gives the strong triangle inequality.

The property can also be checked on the offline reference matrix distributed with the package.

    m <- as.matrix(taxobase$statistical_matrix)
    tolerance <- sqrt(.Machine$double.eps)

    ultrametric_ok <- function(index) {
      i <- index[1]
      j <- index[2]
      k <- index[3]

      d_ij <- m[i, j]
      d_ik <- m[i, k]
      d_jk <- m[j, k]

      d_ij <= max(d_ik, d_jk) + tolerance &&
        d_ik <= max(d_ij, d_jk) + tolerance &&
        d_jk <= max(d_ij, d_ik) + tolerance
    }

    all(combn(seq_len(nrow(m)), 3, FUN = ultrametric_ok))
    #> [1] TRUE

## Dependence on the source classification

The numerical value depends on the number and arrangement of nodes returned by The Taxonomicon. Taxonomic revisions, alternative classifications, and differences in lineage resolution can change both MRCA depth and distance.

Comparisons should therefore use lineages obtained from the same source and, where possible, the same package and data-retrieval version.

## Ambiguous and missing taxa

Some names correspond to more than one valid biological entry. A numeric Taxonomicon identifier can be supplied when a specific taxonomic concept is required.

Missing lineages produce missing pairwise values. Lineages without a common root produce infinite values. These cases should be resolved before applying methods that require a complete finite matrix, including clustering and ordination.

## Interpretation

Smaller values indicate a deeper shared node in the source classification. They should not be interpreted as:

- elapsed evolutionary time;
- genetic or morphological divergence;
- phylogenetic branch length;
- probability of common ancestry.

Hierarchical clustering of these distances produces a taxonomic similarity dendrogram, not an independently inferred phylogenetic tree.

## Recommended reporting

Analyses using `taxodist` should report:

- the package version;
- the lineage retrieval date;
- The Taxonomicon as the source classification;
- the distance definition;
- decisions involving ambiguous or missing taxa;
- any clustering, ordination, or permutation method subsequently applied.

Formatted citations for the package and The Taxonomicon are available through `citation("taxodist")`.