The \eslmod{distance} module implements routines for inferring mutational distances between pairs of aligned sequences, and for constructing distance matrices from multiple sequence alignments. The API for the \eslmod{distance} module is summarized in Table~\ref{tbl:distance_api}. \begin{table}[hbp] \begin{center} {\small \begin{tabular}{|ll|}\hline \apisubhead{Pairwise distances for aligned text sequences}\\ \hyperlink{func:esl_dst_CPairId()}{\ccode{esl\_dst\_CPairId()}} & Pairwise identity of two aligned text strings.\\ \hyperlink{func:esl_dst_CJukesCantor()}{\ccode{esl\_dst\_CJukesCantor()}} & Jukes-Cantor distance for two aligned strings.\\ \apisubhead{Pairwise distances for aligned digital seqs}\\ \hyperlink{func:esl_dst_XPairId()}{\ccode{esl\_dst\_XPairId()}} & Pairwise identity of two aligned digital seqs.\\ \hyperlink{func:esl_dst_XJukesCantor()}{\ccode{esl\_dst\_XJukesCantor()}} & Jukes-Cantor distance for two aligned digitized seqs.\\ \apisubhead{Distance matrices for aligned text sequences}\\ \hyperlink{func:esl_dst_CPairIdMx()}{\ccode{esl\_dst\_CPairIdMx()}} & NxN identity matrix for N aligned text sequences. \\ \hyperlink{func:esl_dst_CDiffMx()}{\ccode{esl\_dst\_CDiffMx()}} & NxN difference matrix for N aligned text sequences.\\ \hyperlink{func:esl_dst_CJukesCantorMx()}{\ccode{esl\_dst\_CJukesCantorMx()}} & NxN Jukes/Cantor distance matrix for N aligned text seqs.\\ \apisubhead{Distance matrices for aligned digital sequences}\\ \hyperlink{func:esl_dst_XPairIdMx()}{\ccode{esl\_dst\_XPairIdMx()}} & NxN identity matrix for N aligned digital seqs.\\ \hyperlink{func:esl_dst_XDiffMx()}{\ccode{esl\_dst\_XDiffMx()}} & NxN difference matrix for N aligned digital seqs.\\ \hyperlink{func:esl_dst_XJukesCantorMx()}{\ccode{esl\_dst\_XJukesCantorMx()}} & NxN Jukes/Cantor distance matrix for N aligned digital seqs.\\ \hline \end{tabular} } \end{center} \caption{The \eslmod{distance} API.} \label{tbl:distance_api} \end{table} \subsection{Example of using the distance API} The example code below opens a multiple sequence alignment file and reads an alignment from it, then uses one of the routines from the \eslmod{distance} module to calculate a fractional identity matrix from it. The example then finds the average, minimum, and maximum of the values in the identity matrix. \input{cexcerpts/distance_example} \subsection{Definition of pairwise identity and pairwise difference} Given a pairwise sequence alignment of length $L$, between two sequences of $n_1$ and $n_2$ residues ($n_1 \leq L$, $n_2 \leq L$), where the $L$ aligned symbol pairs are classified and counted as $c_{\mbox{ident}}$ identities, $c_{\mbox{mismat}}$ mismatches, and $c_{\mbox{indel}}$ pairs that have a gap symbol in either or both sequences ($c_{\mbox{ident}} + c_{\mbox{mismat}} + c_{\mbox{indel}} = L$), \esldef{pairwise sequence identity} is defined as: $\mbox{pid} = \frac{c_{\mbox{ident}}}{\mbox{MIN}(n_1, n_2)},$ and \esldef{pairwise sequence difference} is defined as $\mbox{diff} = 1 - \mbox{pid} = \frac{\mbox{MIN}(n_1,n_2) - c_{\mbox{ident}}}{\mbox{MIN}(n_1, n_2)}.$ Both pid and diff range from 0 to 1. In the unusual case where $\mbox{MIN}(n_1,n_2)=0$ -- that is, one of the aligned sequences consists entirely of gaps -- the percent identity $0/0$ is defined as 0. The calculation is robust against length 0 sequences, which do arise in real applications. (Not just in bad input, either. For example, this arises when dealing with subsets of the columns of a multiple alignment.) There are many ways that pairwise identity might be calculated, because there are a variety of choices for the denominator. In Easel, identity calculations are used primarily in \emph{ad hoc} sequence weight calculations for multiple sequence alignments, as part of profile HMM or profile SCFG construction. Multiple alignments will often contain short sequence fragments. We want to deal robustly with cases where two short fragments may have little overlap, or none at all. The most obvious calculation of pairwise identity, $c_{\mbox{ident}} / c_{\mbox{ident}} + c_{\mbox{mismat}}$, is not robust, because alignments with few aligned residues (either because they are highly gappy, or they are partially overlapping fragments) may receive artifactually high identities. Other definitions, $c_{\mbox{ident}} / L$ or $c_{\mbox{ident}} / \mbox{MEAN}(n_1, n_2)$ or $c_{\mbox{ident}} / \mbox{MAX}(n_1, n_2)$ are also not robust, sharing the disadvantage that good alignments of fragments to longer sequences would be scored as artifactually low identities. \subsection{Generalized Jukes-Cantor distances} The Jukes-Cantor model of DNA sequence evolution assumes that all substitutions occur at the same rate $\alpha$ \citep{JukesCantor69}. It is a reversible, multiplicative evolutionary model. It implies equiprobable stationary probabilities. The \esldef{Jukes/Cantor distance} is the maximum likelihood estimate of the number of substitutions per site that have occurred between the two sequences, correcting for multiple substitutions that may have occurred the same site. Given an ungapped pairwise alignment of length $L$ consisting of $c_{\mbox{ident}}$ identities and $c_{\mbox{mismat}}$ mismatches (observed substitutions) ($c_{\mbox{ident}} + c_{\mbox{mismat}} = L$, the fractional observed difference $D$ is defined as $D = \frac{c_{\mbox{mismat}}}{c_{\mbox{ident}} + c_{\mbox{mismat}}},$ and the Jukes-Cantor distance $d$ is defined in terms of $D$ as: $d = -\frac{3}{4} \log \left( 1 - \frac{4}{3} D \right)$ The Jukes/Cantor model does not allow insertions or deletions. When calculating Jukes/Cantor distances'' for gapped alignments, gap symbols are simply ignored, and the same calculations above are applied. The Jukes-Cantor model readily generalizes from the four-letter DNA alphabet to any alphabet size $K$, using the same definition of observed fractional difference $D$. A \esldef{generalized Jukes-Cantor distance} is: $d = -\frac{K-1}{K} \log \left( 1 - \frac{K}{K-1} D \right).$ The large-sample variance of this estimate $d$ is: $\sigma^2 = e^\frac{2Kd}{K-1} \frac{D(1-D)}{L'}$ where $L'$ is the total number of columns counted, exclusive of gaps, $L' = c_{\mbox{ident}} + c_{\mbox{mismat}}$. If the observed $D \geq \frac{K-1}{K}$, the maximum likelihood Jukes-Cantor distance is infinity, as is the variance. In this case, both $d$ and $V$ are returned as \ccode{HUGE\_VAL}.