map_or_consensus.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tzara.R
\name{map_or_consensus}
\alias{map_or_consensus}
\title{Assign consensus sequences to unmapped reads}
\usage{
map_or_consensus(
  asvs,
  raw,
  maxdist = 10,
  allow_map = TRUE,
  allow_consensus = TRUE,
  allow_raw = FALSE,
  ...
)
}
\arguments{
\item{asvs}{(\code{character} vector) ASV sequences mapped to a set of reads.
Should be \code{\link{NA_character_}} for reads which did not map to an
ASV.}

\item{raw}{(\code{character} vector) Raw read sequences for the same set of
reads as \code{asvs}.  May be \code{\link{NA_character_}}}

\item{maxdist}{(\code{numeric} scalar) Maximum Levenshtein distance between
a raw read and an ASV for the read to be mapped to the ASV.}

\item{allow_map}{(\code{logical} scalar) If \code{TRUE} and if \code{asvs}
contains non-missing values, attempt to map each raw read without a
corresponding ASV to the nearest ASV.}

\item{allow_consensus}{(\code{logical} scalar) If \code{TRUE} and if
\code{allow_map} is \code{FALSE} or there are no non-missing values in
\code{asvs}, then attempt to make a consensus of all raw reads.}

\item{allow_raw}{(\code{logical} scalar) If \code{TRUE}, then after mapping
and/or consensus building, remaining raw reads are taken as they are. If
\code{FALSE}, the corresponding results will be \code{NA}.}

\item{...}{passed to \code{\link{cluster_consensus.character}}}
}
\value{
a \code{character} vector the same length as \code{asvs}, which has
   the closest ASV for each read if any ASVs are non-missing, or the cluster
   consensus values for raw reads which were non-missing and not outliers.
}
\description{
This function is intended to be run on reads from a single sub-region/domain,
which have been clustered using a linked sub-region/domain; for instance,
ITS1 reads clustered based on identity/similarity of the linked ITS2 reads.
}
\details{
If some of the target reads have been mapped to ASVs, then
\code{map_or_consensus} attempts to map additional raw reads to the same
ASVs using a (potentially) more relaxed criteria than
\code{\link[dada2]{dada}}. This is implemented in
\code{\link{map_to_best_asv}}.

If, on the other hand, none of the input sequences have been assigned to an
ASV, then the entire group is taken to represent one cluster, and a consensus
sequence for the cluster is determined using \code{\link{cluster_consensus}}.
This process will remove outliers (generally chimeric in origin) and assign
\code{NA_character_} to the associated reads, as well as any reads which are
already \code{NA} due to quality filtering, failed region extraction, etc.
}