########################################################################/**
 # @RdocFunction cdfMergeStrands
 #
 # @title "Function to join CDF groups with the same names"
 #
 # \description{
 #  @get "title".
 #
 #  This @function is design to be used with @see "applyCdfGroups"
 #  on an Affymetrix Mapping (SNP) CDF @list structure.
 #
 #  This can be used to join the sense and anti-sense groups of the same 
 #  allele in SNP arrays.
 # }
 #
 # @synopsis
 #
 # \arguments{
 #  \item{groups}{A @list structure with groups.}
 #  \item{...}{Not used.}
 # }
 #
 # \value{
 #  Returns a @list structure with only two groups.
 # }
 #

 # \details{
 #  If a unit has two strands, they are merged such that the elements

 #  for the second strand are concatenated to the end of the elements
 #  of first strand (This is done separately for the two alleles).

 # }
 #

 # \seealso{
 #  @see "applyCdfGroups".
 # }
 #

 # @author "HB"

 #
 # \references{
 #  [1] 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
 #**/#######################################################################
 cdfMergeStrands <- function(groups, ...) {
   nbrOfGroups <- length(groups);

   if (nbrOfGroups != 2 && nbrOfGroups != 4 && nbrOfGroups %% 2 != 0)

     return(groups);
 
   names <- names(groups);
   unames <- unique(names);
 
   res <- list();

 
   # For each allele...

   for (name in unames) {
     idx <- which(name == names);

     group <- .subset2(groups, idx[1]);
     nfields <- length(group);
     if (nfields > 0) {
       ffs <- 1:nfields;
       idx <- idx[-1];
       while(length(idx) > 0) {
         groupNext <- .subset2(groups, idx[1]);
   
         # For each field...
         for (ff in ffs) {
           fields <- .subset2(group, ff);
           fieldsNext <- .subset2(groupNext, ff);
           ndim <- length(dim(fields));
           if (ndim <= 1) {

             fields <- c(fields, fieldsNext);

           } else if (ndim == 2) {
             fields <- cbind(fields, fieldsNext);
           } else {
             # This should never occur for a normal CDF structure.

             fields <- c(fields, fieldsNext);

           }
           group[[ff]] <- fields;
         }
   
         idx <- idx[-1];
       } # while(...)

     }

 
     res[[name]] <- group;
   } # for (name ...)

 
   res;

 } # cdfMergeStrands()

 
 
 ############################################################################
 # HISTORY:

 # 2008-02-22
 # o Updated so it now merges any unit with a even number of groups;
 #   a custom SNP CDF had three pairs of groups in part of their units.

 # 2006-03-07
 # o Renamed from cdfStandJoiner() to cdfMergeStrands().
 # 2006-02-23
 # o Created.
 ############################################################################