% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Sequence.R
\name{collapseDuplicates}
\alias{collapseDuplicates}
\title{Remove duplicate DNA sequences and combine annotations}
\usage{
collapseDuplicates(
  data,
  id = "sequence_id",
  seq = "sequence_alignment",
  text_fields = NULL,
  num_fields = NULL,
  seq_fields = NULL,
  add_count = FALSE,
  ignore = c("N", "-", ".", "?"),
  sep = ",",
  dry = FALSE,
  verbose = FALSE
)
}
\arguments{
\item{data}{data.frame containing Change-O columns. The data.frame 
must contain, at a minimum, a unique identifier column 
and a column containing a character vector of DNA sequences.}

\item{id}{name of the column containing sequence identifiers.}

\item{seq}{name of the column containing DNA sequences.}

\item{text_fields}{character vector of textual columns to collapse. The textual 
annotations of duplicate sequences will be merged into a single 
string with each unique value alphabetized and delimited by 
\code{sep}.}

\item{num_fields}{vector of numeric columns to collapse. The numeric annotations
of duplicate sequences will be summed.}

\item{seq_fields}{vector of nucleotide sequence columns to collapse. The sequence 
with the fewest number of non-informative characters will be 
retained. Where a non-informative character is one of 
\code{c("N", "-", ".", "?")}. Note, this is distinct from the 
\code{seq} parameter which is used to determine duplicates.}

\item{add_count}{if \code{TRUE} add the column \code{collpase_count} that 
indicates the number of sequences that were collapsed to build 
each unique entry.}

\item{ignore}{vector of characters to ignore when testing for equality.}

\item{sep}{character to use for delimiting collapsed annotations in the 
\code{text_fields} columns. Defines both the input and output 
delimiter.}

\item{dry}{if \code{TRUE} perform dry run. Only labels the sequences without 
collapsing them.}

\item{verbose}{if \code{TRUE} report the number input, discarded and output 
sequences; if \code{FALSE} process sequences silently.}
}
\value{
A modified \code{data} data.frame with duplicate sequences removed and 
          annotation fields collapsed if \code{dry=FALSE}. If \code{dry=TRUE}, 
          sequences will be labeled with the collapse action, but the input will be
          otherwise unmodified (see Details).
}
\description{
\code{collapseDuplicates} identifies duplicate DNA sequences, allowing for ambiguous 
characters, removes the duplicate entries, and combines any associated annotations.
}
\details{
\code{collapseDuplicates} identifies duplicate sequences in the \code{seq} column by
testing for character identity, with consideration of IUPAC ambiguous nucleotide codes. 
A cluster of sequences are considered duplicates if they are all equivalent, and no 
member of the cluster is equivalent to a sequence in a different cluster. 

Textual annotations, specified by \code{text_fields}, are collapsed by taking the unique
set of values within in each duplicate cluster and delimiting those values by \code{sep}.
Numeric annotations, specified by \code{num_fields}, are collapsed by summing all values 
in the duplicate cluster. Sequence annotations, specified by \code{seq_fields}, are 
collapsed by retaining the first sequence with the fewest number of N characters.

Columns that are not specified in either \code{text_fields}, \code{num_fields}, or 
\code{seq_fields} will be retained, but the value will be chosen from a random entry 
amongst all sequences in a cluster of duplicates.

An ambiguous sequence is one that can be assigned to two different clusters, wherein
the ambiguous sequence is equivalent to two sequences which are themselves 
non-equivalent. Ambiguous sequences arise due to ambiguous characters at positions that
vary across sequences, and are discarded along with their annotations when \code{dry=FALSE}. 
Thus, ambiguous sequences are removed as duplicates of some sequence, but do not create a potential
false-positive annotation merger. Ambiguous sequences are not included in the 
\code{collapse_count} annotation that is added when \code{add_count=TRUE}.

If \code{dry=TRUE} sequences will not be removed from the input. Instead, the following columns
will be appended to the input defining the collapse action that would have been performed in the
\code{dry=FALSE} case.

\itemize{
  \item  \code{collapse_id}:     an identifier for the group of identical sequences.
  \item  \code{collapse_class}:  string defining how the sequence matches to the other in the set.
                                 one of \code{"duplicated"} (has duplicates),
                                 \code{"unique"} (no duplicates), \code{"ambiguous_duplicate"} 
                                 (no duplicates after ambiguous sequences are removed), 
                                 or \code{"ambiguous"} (matches multiple non-duplicate sequences).
  \item  \code{collapse_pass}:   \code{TRUE} for the sequences that would be retained.
}
}
\examples{
# Example data.frame
db <- data.frame(sequence_id=LETTERS[1:4],
                 sequence_alignment=c("CCCCTGGG", "CCCCTGGN", "NAACTGGN", "NNNCTGNN"),
                 c_call=c("IGHM", "IGHG", "IGHG", "IGHA"),
                 sample_id=c("S1", "S1", "S2", "S2"),
                 duplicate_count=1:4,
                 stringsAsFactors=FALSE)

# Annotations are not parsed if neither text_fields nor num_fields is specified
# The retained sequence annotations will be random
collapseDuplicates(db, verbose=TRUE)

# Unique text_fields annotations are combined into a single string with ","
# num_fields annotations are summed
# Ambiguous duplicates are discarded
collapseDuplicates(db, text_fields=c("c_call", "sample_id"), num_fields="duplicate_count", 
                   verbose=TRUE)

# Use alternate delimiter for collapsing textual annotations
collapseDuplicates(db, text_fields=c("c_call", "sample_id"), num_fields="duplicate_count", 
                   sep="/", verbose=TRUE)

# Add count of duplicates
collapseDuplicates(db, text_fields=c("c_call", "sample_id"), num_fields="duplicate_count", 
                   add_count=TRUE, verbose=TRUE)

# Masking ragged ends may impact duplicate removal
db$sequence_alignment <- maskSeqEnds(db$sequence_alignment)
collapseDuplicates(db, text_fields=c("c_call", "sample_id"), num_fields="duplicate_count", 
                   add_count=TRUE, verbose=TRUE)

}
\seealso{
Equality is tested with \link{seqEqual} and \link{pairwiseEqual}. 
          For IUPAC ambiguous character codes see \link{IUPAC_DNA}.
}
