########################################################################/**
# @RdocFunction cdfAddBaseMmCounts
#
# @title "Adds the number of allele A and allele B mismatching nucleotides of the probes in a CDF structure"
#
# \description{
#  @get "title".
#
#  This @function is design to be used with @see "applyCdfGroups"
#  on an Affymetrix Mapping (SNP) CDF @list structure.
#
#  Identifies the number of nucleotides (bases) in probe sequences that
#  mismatch the the target sequence for allele A and the allele B,
#  as used by [1].
# }
#
# @synopsis
#
# \arguments{
#  \item{groups}{A @list structure with groups.  
#    Each group must contain the fields \code{tbase}, \code{pbase}, and 
#    \code{offset} (from @see "cdfAddProbeOffsets").
#  }
#  \item{...}{Not used.}
# }
#
# \value{
#  Returns a @list structure with the same number of groups as the 
#  \code{groups} argument.  To each group, two fields is added:
#   \item{mmACount}{The number of nucleotides in the probe sequence 
#      that mismatches the target sequence of allele A.}
#   \item{mmBCount}{The number of nucleotides in the probe sequence 
#      that mismatches the target sequence of allele B.}
# }
#
# \details{
#  Note that the above counts can be inferred from the CDF structure alone, 
#  i.e. no sequence information is required.
#  Consider a probe group interrogating allele A.  First, all PM probes
#  matches the allele A target sequence perfectly regardless of shift.
#  Moreover, all these PM probes mismatch the allele B target sequence 
#  at exactly one position.  Second, all MM probes mismatches the
#  allele A sequence at exactly one position.  This is also true for
#  the allele B sequence, \emph{except} for an MM probe with zero offset,
#  which only mismatch at one (the middle) position.
#  For a probe group interrogating allele B, the same rules applies with
#  labels A and B swapped.
#  In summary, the mismatch counts for PM probes can take values 0 and 1,
#  and for MM probes they can take values 0, 1, and 2.
# }
#
# \seealso{
#  To add required probe offsets, @see "cdfAddProbeOffsets".
#  @see "applyCdfGroups".
# }
#
# @author "HB"
#
# \references{
#  [1] LaFramboise T, Weir BA, Zhao X, Beroukhim R, Li C, Harrington D, 
#      Sellers WR, and Meyerson M. \emph{Allele-specific amplification in 
#      cancer revealed by SNP array analysis}, PLoS Computational Biology,
#      Nov 2005, Volume 1, Issue 6, e65.\cr
#  [2] Affymetrix, \emph{Understanding Genotyping Probe Set Structure}, 2005.
#      \url{http://www.affymetrix.com/support/developer/whitepapers/genotyping_probe_set_structure.affx}\cr
# }
#
# @keyword programming
# @keyword internal
#**/#######################################################################
cdfAddBaseMmCounts <- function(groups, ...) {
  for (gg in seq_along(groups)) {
    group <- groups[[gg]];

    # Find PM probes
    tbase <- group$tbase;
    pbase <- group$pbase;
    isPm <- ((tbase == "a" | tbase == "A") &
             (pbase == "t" | pbase == "T")) |
            ((tbase == "t" | tbase == "T") &  
             (pbase == "a" | pbase == "A")) |
            ((tbase == "c" | tbase == "C") &  
             (pbase == "g" | pbase == "G")) |
            ((tbase == "g" | tbase == "G") &
             (pbase == "c" | pbase == "C"));

    # Find the center probes
    isCentered <- (group$offset == 0);

    dim <- dim(isCentered);
    if (is.null(dim)) {
      mmACount <- mmBCount <- rep(as.integer(1), length(isCentered));
    } else {
      mmACount <- mmBCount <- array(as.integer(1), dim=dim,
                                            dimnames=dimnames(isCentered));
    }
    
    # Is this probe group interrogating allele A?
    isA <- (gg %% 2 == 1);
    if (isA) {
      mmACount[isPm] <- as.integer(0);
      mmBCount[!isPm & !isCentered] <- as.integer(2);
    } else {
      mmBCount[isPm] <- as.integer(0);
      mmACount[!isPm & !isCentered] <- as.integer(2);
    }

    # Add the new fields
    group$mmACount <- mmACount;
    group$mmBCount <- mmBCount;

    groups[[gg]] <- group;
  }

  groups;
}

############################################################################
# HISTORY:
# 2006-06-19
# o Added more Rdoc help.
# 2006-03-07
# o Created.
############################################################################