% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/MutationProfiling.R
\name{observedMutations}
\alias{observedMutations}
\title{Calculate observed numbers of mutations}
\usage{
observedMutations(
  db,
  sequenceColumn = "sequence_alignment",
  germlineColumn = "germline_alignment_d_mask",
  regionDefinition = NULL,
  mutationDefinition = NULL,
  ambiguousMode = c("eitherOr", "and"),
  frequency = FALSE,
  combine = FALSE,
  nproc = 1,
  cloneColumn = "clone_id",
  juncLengthColumn = "junction_length"
)
}
\arguments{
\item{db}{\code{data.frame} containing sequence data.}

\item{sequenceColumn}{\code{character} name of the column containing input 
sequences. IUPAC ambiguous characters for DNA are 
supported.}

\item{germlineColumn}{\code{character} name of the column containing 
the germline or reference sequence. IUPAC ambiguous 
characters for DNA are supported.}

\item{regionDefinition}{\link{RegionDefinition} object defining the regions
and boundaries of the Ig sequences. If NULL, mutations 
are counted for entire sequence. To use regions definitions,
sequences in \code{sequenceColumn} and \code{germlineColumn}
must be aligned, following the IMGT schema.}

\item{mutationDefinition}{\link{MutationDefinition} object defining replacement
and silent mutation criteria. If \code{NULL} then 
replacement and silent are determined by exact 
amino acid identity.}

\item{ambiguousMode}{whether to consider ambiguous characters as 
\code{"either or"} or \code{"and"} when determining and 
counting the type(s) of mutations. Applicable only if
\code{sequenceColumn} and/or \code{germlineColumn} 
contain(s) ambiguous characters. One of 
\code{c("eitherOr", "and")}. Default is \code{"eitherOr"}.}

\item{frequency}{\code{logical} indicating whether or not to calculate
mutation frequencies. Default is \code{FALSE}.}

\item{combine}{\code{logical} indicating whether for each sequence should
the mutation counts for the different regions (CDR, FWR) and 
mutation types be combined and return one value of 
count/frequency per sequence instead of 
multiple values. Default is \code{FALSE}.}

\item{nproc}{number of cores to distribute the operation over. If the 
cluster has already been set the call function with 
\code{nproc} = 0 to not reset or reinitialize. Default is 
\code{nproc} = 1.}

\item{cloneColumn}{clone id column name in \code{db}}

\item{juncLengthColumn}{junction length column name in \code{db}}
}
\value{
A modified \code{db} \code{data.frame} with observed mutation counts for each 
          sequence listed. The columns names are dynamically created based on the
          regions in the \code{regionDefinition}. For example, when using the
          \link{IMGT_V} definition, which defines positions for CDR and
          FWR, the following columns are added:
          \itemize{
            \item  \code{mu_count_cdr_r}:  number of replacement mutations in CDR1 and 
                                           CDR2 of the V-segment.
            \item  \code{mu_count_cdr_s}:  number of silent mutations in CDR1 and CDR2 
                                           of the V-segment.
            \item  \code{mu_count_fwr_r}:  number of replacement mutations in FWR1, 
                                           FWR2 and FWR3 of the V-segment.
            \item  \code{mu_count_fwr_s}:  number of silent mutations in FWR1, FWR2 and
                                           FWR3 of the V-segment.
          }
          If \code{frequency=TRUE}, R and S mutation frequencies are
          calculated over the number of non-N positions in the specified regions.
          \itemize{
            \item  \code{mu_freq_cdr_r}:  frequency of replacement mutations in CDR1 and 
                                           CDR2 of the V-segment.
            \item  \code{mu_freq_cdr_s}:  frequency of silent mutations in CDR1 and CDR2 
                                           of the V-segment.
            \item  \code{mu_freq_fwr_r}:  frequency of replacement mutations in FWR1, 
                                           FWR2 and FWR3 of the V-segment.
            \item  \code{mu_freq_fwr_s}:  frequency of silent mutations in FWR1, FWR2 and
                                           FWR3 of the V-segment.
          } 
          If \code{frequency=TRUE} and \code{combine=TRUE}, the mutations and non-N positions
          are aggregated and a single \code{mu_freq} value is returned
          \itemize{
            \item  \code{mu_freq}:  frequency of replacement and silent mutations in the 
                                     specified region
          }
}
\description{
\code{observedMutations} calculates the observed number of mutations for each 
sequence in the input \code{data.frame}.
}
\details{
Mutation counts are determined by comparing a reference sequence to the input sequences in the 
column specified by \code{sequenceColumn}. See \link{calcObservedMutations} for more technical details, 
\strong{including criteria for which sequence differences are included in the mutation 
counts and which are not}.

The mutations are binned as either replacement (R) or silent (S) across the different 
regions of the sequences as defined by \code{regionDefinition}. Typically, this would 
be the framework (FWR) and complementarity determining (CDR) regions of IMGT-gapped 
nucleotide sequences. Mutation counts are appended to the input \code{db} as 
additional columns.

If \code{db} includes lineage information, such as the \code{parent_sequence} column created by 
\link{makeGraphDf}, the reference sequence can be set to use that field as reference sequence 
using the \code{germlineColumn} argument.
}
\examples{
# Subset example data
data(ExampleDb, package="alakazam")
db <- ExampleDb[1:10, ]

# Calculate mutation frequency over the entire sequence
db_obs <- observedMutations(db, sequenceColumn="sequence_alignment",
                            germlineColumn="germline_alignment_d_mask",
                            frequency=TRUE,
                            nproc=1)

# Count of V-region mutations split by FWR and CDR
# With mutations only considered replacement if charge changes
db_obs <- observedMutations(db, sequenceColumn="sequence_alignment",
                            germlineColumn="germline_alignment_d_mask",
                            regionDefinition=IMGT_V,
                            mutationDefinition=CHARGE_MUTATIONS,
                            nproc=1)
                            
# Count of VDJ-region mutations, split by FWR and CDR
db_obs <- observedMutations(db, sequenceColumn="sequence_alignment",
                            germlineColumn="germline_alignment_d_mask",
                            regionDefinition=IMGT_VDJ,
                            nproc=1)
                            
# Extend data with lineage information
data(ExampleTrees, package="alakazam")
graph <- ExampleTrees[[17]]
clone <- alakazam::makeChangeoClone(subset(ExampleDb, clone_id == graph$clone))
gdf <- makeGraphDf(graph, clone)

# Count of mutations between observed sequence and immediate ancestor
db_obs <- observedMutations(gdf, sequenceColumn="sequence",
                            germlineColumn="parent_sequence",
                            regionDefinition=IMGT_VDJ,
                            nproc=1)    
    
}
\seealso{
\link{calcObservedMutations} is called by this function to get the number of mutations 
in each sequence grouped by the \link{RegionDefinition}. 
See \link{IMGT_SCHEMES} for a set of predefined \link{RegionDefinition} objects.
See \link{expectedMutations} for calculating expected mutation frequencies.
See \link{makeGraphDf} for creating the field \code{parent_sequence}.
}
