% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/parse_files.R
\name{NexusTokensToInteger}
\alias{NexusTokensToInteger}
\title{Convert Nexus token matrix to integer}
\usage{
NexusTokensToInteger(tokens, polymorphism = c("?", "first", "last"))
}
\arguments{
\item{tokens}{Character matrix as returned by \code{\link[=ReadCharacters]{ReadCharacters()}}, a
character vector as returned by \code{\link[=NexusTokens]{NexusTokens()}}, or a \code{phyDat} object.}

\item{polymorphism}{Character string specifying how to handle polymorphic
tokens such as \code{"(01)"} or \code{"{12}"}:
\describe{
\item{\code{"?"} (default)}{Treat as the NEXUS missing-data token: map to
\code{NA_integer_}.}
\item{\code{"first"}}{Use the first state digit inside the brackets.}
\item{\code{"last"}}{Use the last state digit inside the brackets.}
}
Tokens \code{"?"} and \code{"-"} always map to \code{NA_integer_} regardless of
\code{polymorphism}.}
}
\value{
An integer matrix (or vector) with the same dimensions and
\code{dimnames} as \code{tokens}.
}
\description{
\code{NexusTokensToInteger()} converts the character matrix returned by
\code{\link[=ReadCharacters]{ReadCharacters()}} to an integer matrix, mapping polymorphic,
ambiguous (\verb{?}), and inapplicable (\code{-}) tokens to \code{NA_integer_} or to the
first/last state listed in the polymorphism, depending on \code{polymorphism}.
}
\details{
Only digit states \code{0}..\code{9} are recognised; non-digit symbols (and any
token whose interior contains no digits) become \code{NA_integer_}.
Polymorphism extraction (\code{polymorphism = "first"}/\code{"last"}) likewise
considers digits only.

If \code{tokens} is a \code{phyDat} object it is first converted via
\code{\link[=PhyDatToMatrix]{PhyDatToMatrix()}} with \verb{ambigNA = TRUE, inappNA = TRUE}, so that
fully-ambiguous and inapplicable rows become \code{NA_integer_} and only
true partial polymorphisms are subject to the \code{polymorphism} rule.
}
\examples{
tokens <- matrix(c("0", "(12)", "1", "?", "-"),
                 nrow = 1,
                 dimnames = list("Taxon_A", paste0("C", 1:5)))
NexusTokensToInteger(tokens)
NexusTokensToInteger(tokens, polymorphism = "first")

}
\seealso{
Other phylogenetic matrix conversion functions:
\code{\link[=Decompose]{Decompose()}},
\code{\link[=MatrixToPhyDat]{MatrixToPhyDat()}},
\code{\link[=Reweight]{Reweight()}},
\code{\link[=StringToPhyDat]{StringToPhyDat()}}
}
\author{
\href{https://orcid.org/0000-0001-5660-1727}{Martin R. Smith}
(\href{mailto:martin.smith@durham.ac.uk}{martin.smith@durham.ac.uk})
}
\concept{phylogenetic matrix conversion functions}
