@@ -1,8 +1,8 @@

 Package: msa

 Type: Package

 Title: Multiple Sequence Alignment

-Version: 1.7.0

-Date: 2016-08-09

+Version: 1.7.1

+Date: 2017-03-31

 Author: Enrico Bonatesta, Christoph Horejs-Kainrath, Ulrich Bodenhofer

 Maintainer: Ulrich Bodenhofer <bodenhofer@bioinf.jku.at>

 Description: The 'msa' package provides a unified R/Bioconductor interface to

@@ -16,7 +16,7 @@ Description: The 'msa' package provides a unified R/Bioconductor interface to

 URL: http://www.bioinf.jku.at/software/msa/

 License: GPL (>= 2)

 Copyright: See file inst/COPYRIGHT

-Depends: R (>= 3.1.0), methods, Biostrings (>= 2.30.0)

+Depends: R (>= 3.1.0), methods, Biostrings (>= 2.40.0)

 Imports: Rcpp (>= 0.11.1), BiocGenerics, IRanges (>= 1.20.0),

         S4Vectors, tools

 Suggests: Biobase, knitr, seqinr, ape, phangorn

@@ -28,6 +28,7 @@ Collate: AllClasses.R AllGenerics.R params-methods.R version-methods.R

         helperFunctions.R inputChecks.R convertRows.R msaPrettyPrint.R

         print-methods.R show-methods.R msa.R msaMuscle.R msaClustalW.R

         msaClustalOmega.R msaConvert.R msaCheckNames.R

+	msaConsensusSequence-methods.R msaConservationScore-methods.R

 biocViews: MultipleSequenceAlignment, Alignment, MultipleComparison,

         Sequencing

 NeedsCompilation: yes

@@ -14,5 +14,5 @@ export(msa, msaMuscle, msaClustalW, msaClustalOmega, msaPrettyPrint,

 exportClasses(MsaDNAMultipleAlignment, MsaRNAMultipleAlignment,

               MsaAAMultipleAlignment, MsaMetaData)

-exportMethods(params, version, show, print)

-

+exportMethods(params, version, show, print, msaConservationScore,

+              msaConsensusSequence)

@@ -1 +1,7 @@

 setGeneric("version", function(object) standardGeneric("version"))

+

+setGeneric("msaConsensusSequence",

+           function(x, ...) standardGeneric("msaConsensusSequence"))

+

+setGeneric("msaConservationScore",

+           function(x, ...) standardGeneric("msaConservationScore"))

new file mode 100644

@@ -0,0 +1,122 @@

+msaConsensusSequence.matrix <- function(x, type=c("Biostrings", "upperlower"),

+                                        thresh=c(80, 20), ignoreGaps=FALSE,

+                                        ...)

+{

+    type <- match.arg(type)

+

+    if (is.null(rownames(x)) ||

+        any(!(rownames(x) %in% c(LETTERS, "-", "+", "."))))

+        stop("consensus matrix 'x' is not in proper format")

+

+    sel <- match(c("+", "."), rownames(x))

+    sel <- sel[which(!is.na(sel))]

+    if (length(sel) > 0)

+        x <- x[-sel, ]

+

+    if (!is.numeric(thresh) || length(thresh) !=2 ||

+        thresh[1] > 100 || thresh[2] < 0 || thresh[1] < thresh[2])

+        stop("'thresh' must be a decreasing sequence of two numbers ",

+             "between 0 and 100")

+

+    thresh <- thresh / 100

+

+    if (type == "Biostrings")

+    {

+        cs <- colSums(x)

+

+        if (any(is.na(cs)))

+        {

+            res <- rep.int("#", ncol(x))

+

+            sel <- which(!is.na(cs))

+

+            if (length(sel) > 0)

+            {

+                sstr <- consensusString(x[, sel, drop=FALSE], ...)

+                res[sel] <- unlist(strsplit(sstr, ""))

+            }

+

+            out <- paste(res, collapse="")

+        }

+        else

+            out <- consensusString(x, ...)

+    }

+    else

+    {

+        if (ignoreGaps)

+        {

+            sel <- match("-", rownames(x))

+

+            if (!is.na(sel))

+                sel <- (1:nrow(x))[-sel]

+            else

+                sel <- (1:nrow(x))

+

+            perColFunc <- function(y)

+            {

+                if (any(is.na(y)))

+                    char <- "#"

+                else

+                {

+                    y <- y[sel] / length(sel)

+

+                    maxw <-which.max(y[sel])

+                    maxi <- y[sel[maxw]]

+

+                    char <- rownames(x)[sel[maxw]]

+

+                    if (maxi < thresh[1])

+                    {

+                        if (maxi >= thresh[2])

+                            char <- tolower(char)

+                        else

+                            char <- "."

+                    }

+                }

+

+                char

+            }

+        }

+        else

+        {

+            perColFunc <- function(y)

+            {

+                if (any(is.na(y)))

+                    char <- "#"

+                else

+                {

+                    y <- y / length(y)

+

+                    maxw <- which.max(y)

+                    maxi <- y[maxw]

+

+                    char <- rownames(x)[maxw]

+

+                    if (maxi < thresh[1])

+                    {

+                        if (maxi >= thresh[2])

+                            char <- tolower(char)

+                        else

+                            char <- "."

+                    }

+                }

+

+                char

+            }

+        }

+

+        out <- paste(apply(x, 2, perColFunc), collapse="")

+    }

+

+    out

+}

+

+setMethod("msaConsensusSequence", signature("matrix"), msaConsensusSequence.matrix)

+

+

+setMethod("msaConsensusSequence", signature("MultipleAlignment"),

+          function(x, ...)

+          {

+              mat <- consensusMatrix(x)

+              msaConsensusSequence(mat, ...)

+          })

new file mode 100644

@@ -0,0 +1,60 @@

+msaConservationScore.matrix <- function(x, substitutionMatrix, gapVsGap=NULL,

+                                        ...)

+{

+    if (!is.matrix(substitutionMatrix) ||

+        nrow(substitutionMatrix) != ncol(substitutionMatrix) ||

+        any(!(rownames(substitutionMatrix) %in% c(LETTERS, "-", "*"))) ||

+        any(!(colnames(substitutionMatrix) %in% c(LETTERS, "-", "*"))) ||

+        any(rownames(substitutionMatrix) != colnames(substitutionMatrix)))

+        stop("substitution matrix is not in proper format")

+

+    if (is.null(rownames(x)) ||

+        any(!(rownames(x) %in% c(LETTERS, "-", "+", "."))))

+        stop("consensus matrix 'x' is not in proper format")

+

+    sel <- match(c("+", "."), rownames(x))

+    sel <- sel[which(!is.na(sel))]

+    if (length(sel) > 0)

+        x <- x[-sel, ]

+

+    sel <- match(c("*", "-"), rownames(substitutionMatrix))

+

+    if (is.na(sel[2]) && !is.na(sel[1]))

+    {

+        rownames(substitutionMatrix)[sel[1]] <- "-"

+        colnames(substitutionMatrix)[sel[1]] <- "-"

+    }

+

+    sel <- match(rownames(x), rownames(substitutionMatrix))

+

+    if (any(is.na(sel)))

+        stop("some letters occurring in alignment 'x' are missing ",

+             "in substitution matrix")

+

+    substitutionMatrix <- substitutionMatrix[sel, sel]

+

+    if (!is.null(gapVsGap))

+    {

+        if (!is.numeric(gapVsGap) || length(gapVsGap) != 1)

+            stop("'gapVsGap' must be NULL or a single number")

+

+        substitutionMatrix["-", "-"] <- gapVsGap

+    }

+

+    out <- drop(apply(x, 2, function(y) crossprod(y, substitutionMatrix %*% y)))

+

+    names(out) <- unlist(strsplit(msaConsensusSequence(x, ...), ""))

+

+    out

+}

+

+setMethod("msaConservationScore", signature("matrix"),

+          msaConservationScore.matrix)

+

+

+setMethod("msaConservationScore", signature("MultipleAlignment"),

+          function(x, ...)

+          {

+              mat <- consensusMatrix(x)

+              msaConservationScore.matrix(mat, ...)

+          })

@@ -2,7 +2,8 @@ msaConvert <- function(x, type=c("seqinr::alignment",

                                  "bios2mds::align",

                                  "ape::AAbin",

                                  "ape::DNAbin",

-                                 "phangorn::phyDat"))

+                                 "phangorn::phyDat",

+                                 "bio3d::fasta"))

 {

     type <- match.arg(type)

@@ -57,6 +58,14 @@ msaConvert <- function(x, type=c("seqinr::alignment",

         else

             stop("conversion to 'phyDat' requires package 'phangorn'")

     }

+    else if (type == "bio3d::fasta")

+    {

+        out <- list(id=names(xn),

+                    ali=.Call("SplitCharVector2Matrix", xn, "-"),

+                    call=x@call)

+        rownames(out$ali) <- out$id

+        class(out) <- "fasta"

+    }

     out

 }

@@ -79,7 +79,7 @@ print.MsaMultipleAlignmentChunk <- function(str, names=NULL, halfNrow=9, pos="",

 print.MsaMultipleAlignment <- function(x, show=c("alignment", "version", "call"),

                                        showNames=TRUE, showConsensus=TRUE,

-                                       halfNrow=9, nameWidth=20)

+                                       halfNrow=9, nameWidth=20, ...)

 {

     show <- match.arg(show,

                       choices=c("alignment", "complete", "version", "call",

@@ -154,7 +154,7 @@ print.MsaMultipleAlignment <- function(x, show=c("alignment", "version", "call")

             if (showConsensus)

             {

-                cons <- consensusString(consensusMatrix(unmasked(x)))

+                cons <- msaConsensusSequence(x, ...)

                 strings <- c(strings, cons)

                 if (length(names(strings)) > 0)

@@ -1,6 +1,25 @@

 Change history of package msa:

 ==============================

+Version 1.7.1:

+- additional conversions implemented for msaConvert() function

+- added a new method msaConsensusSequence() that extends the

+  functionality provided by Biostring's consensusString() method

+- added a new method msaConservationScore()

+- print() method extended such that it now also allows for

+  customization of the consensus sequence (via the new

+  msaConsensusSequence() method)

+- package now depends on Biostrings version >= 2.40.0 in order

+  to make sure that consensusMatrix() also works correctly

+  for masked alignments

+- corresponding changes in documentation and vignette

+

+Version 1.7.0:

+- new branch for Bioconductor 3.5 devel

+

+Version 1.6.0:

+- release as part of Bioconductor 3.4

+

 Version 1.5.5:

 - fixes in ClustalOmega source code to ensure Windows compatibility of

   GCC6 compatibility fix

@@ -46,7 +46,7 @@

 \section{Methods}{

   \describe{

     \item{\code{print(x, show=c("alignment", "version", "call"),

-      showNames=TRUE, showConsensus=TRUE, halfNrow=9, nameWidth=20)}:}{

+      showNames=TRUE, showConsensus=TRUE, halfNrow=9, nameWidth=20, ...)}:}{

       prints information about the object \code{x}; the \code{show}

       argument allows for determining what should be printed.

       The \code{show} must be a character vector and may contain any

@@ -95,6 +95,9 @@

       where the masked sequences/positions are shown as hash marks.

       However, the consensus sequences are computed from the

       complete, unmasked alignment and displayed as such.

+      Additional arguments are passed on to

+      \code{\link{msaConsensusSequence}} for customizing how the

+      consensus sequence is computed.

     }

     \item{\code{show(object)}:}{displays the alignment along with

       metadata; synonymous to calling \code{print} with default

@@ -138,12 +141,14 @@ show(myAlignment)

 ## print the results

 print(myAlignment, show="alignment")

 print(myAlignment, show="alignment", showConsensus=FALSE)

-print(myAlignment, show="complete")

 print(myAlignment, show=c("alignment", "version"))

 print(myAlignment, show="standardParams")

 print(myAlignment, show="algParams")

 print(myAlignment, show=c("call", "version"))

+## print results with custom consensus sequence

+print(myAlignment, show="complete", type="upperlower", thresh=c(50, 20))

+

 ## show the params

 params(myAlignment)

 }

new file mode 100644

@@ -0,0 +1,120 @@

+\name{msaConsensusSequence}

+\alias{msaConsensusSequence}

+\alias{msaConsensusSequence,MultipleAlignment-method}

+\alias{msaConsensusSequence,matrix-method}

+\title{Computation of Consensus Sequence from Multiple Alignment}

+\description{

+  This method computes a consensus sequence from a multiple alignment

+  or a previously computed consensus matrix. Currently, two different

+  ways of these computations are available.

+}

+\usage{

+\S4method{msaConsensusSequence}{matrix}(x, type=c("Biostrings", "upperlower"),

+    thresh=c(80, 20), ignoreGaps=FALSE, ...)

+\S4method{msaConsensusSequence}{MultipleAlignment}(x, ...)

+}

+\arguments{

+  \item{x}{an object of class \code{\linkS4class{MultipleAlignment}}

+    (which includes objects of classes

+    \code{\linkS4class{MsaAAMultipleAlignment}},

+    \code{\linkS4class{MsaDNAMultipleAlignment}}, and

+    \code{\linkS4class{MsaRNAMultipleAlignment}}) or a previously

+    computed consensus matrix (see details below).}

+  \item{type}{a character string specifying how to compute the consensus

+    sequence. Currently, types \code{"Biostrings"} and

+    \code{"upperlower"} are available (see details below).}

+  \item{thresh}{a decreasing two-element numeric vector of numbers

+    between 0 and 100 corresponding to the two conservation thresholds.

+    Only relevant for \code{type="upperlower"} (see details below),

+    otherwise ignored.}

+  \item{ignoreGaps}{a logical (default: \code{FALSE})

+    indicating whether gaps should be

+    considered when computing the consensus sequence. 

+    Only relevant for \code{type="upperlower"} (see details below),

+    otherwise ignored.}

+  \item{...}{when the method is called for a

+    \code{\linkS4class{MultipleAlignment}} object, the consensus matrix is

+    computed and, including all further arguments, passed

+    passed on to the \code{msaConsensusSequence} method with signature

+    \code{matrix}. The method with signature \code{matrix} forwards

+    additional arguments to the \code{\link{consensusString}} method

+    from the \pkg{Biostrings} package if \code{type="Biostrings"}.}

+  }

+\details{

+  The method takes a \code{\linkS4class{MultipleAlignment}} object or a

+  previously computed consensus matrix and computes a consensus

+  sequence. For \code{type="Biostrings"}, the method

+  \code{\link{consensusString}} from the \pkg{Biostrings} package is

+  used to compute the consensus sequence. For \code{type="upperlower"},

+  two thresholds (argument \code{thresh}, see above) are used to

+  compute the consensus sequence:

+  \itemize{

+    \item{If the relative frequency of the most frequent letter at a

+      given position is at least as large as the first threshold (default:

+      80\%), then this most frequent letter is used for the consensus

+      sequence at this position as it is.}

+    \item{If the relative frequency of the most frequent letter at a

+      given position is smaller than the first threshold, but at least

+      as large as the second threshold (default: 20\%), then this

+      most frequent letter is used for the consensus sequence at this

+      position, but converted to lower case.}

+    \item{If the relative frequency of the most frequent letter in a

+      column is even smaller than the second threshold, then a dot is

+      used for the consensus sequence at this position.}

+    \item{If \code{ignoreGaps=FALSE} (which is the default),

+      gaps are treated like all other

+      letters except for the fact that obviously no lowercase conversion

+      takes place in case that the relative frequency is between the

+      two thresholds. If \code{ignoreGaps=TRUE}, gaps are ignored

+      completely, and the consensus sequence is computed from the

+      non-gap letters only.}

+  }

+

+  If the consensus matrix of a multiple alignment of nucleotide

+  sequences contains rows labeled \sQuote{+} and/or \sQuote{.}, these

+  rows are ignored.

+}

+\value{

+  The function returns a character string with the consensus sequence.

+}

+\author{Ulrich Bodenhofer <msa@bioinf.jku.at>

+}

+\references{

+  \url{http://www.bioinf.jku.at/software/msa}

+  

+  U. Bodenhofer, E. Bonatesta, C. Horejs-Kainrath, and S. Hochreiter

+  (2015). msa: an R package for multiple sequence alignment. 

+  \emph{Bioinformatics} \bold{31}(24):3997-3999. DOI:

+  \href{http://dx.doi.org/10.1093/bioinformatics/btv494}{10.1093/bioinformatics/btv494}.

+}

+\seealso{\code{\link{msa}}, \code{\linkS4class{MsaAAMultipleAlignment}},

+  \code{\linkS4class{MsaDNAMultipleAlignment}},

+  \code{\linkS4class{MsaRNAMultipleAlignment}},

+  \code{\linkS4class{MsaMetaData}},

+  \code{\linkS4class{MultipleAlignment}},

+  \code{\link{consensusString}}

+}

+\examples{

+## read sequences

+filepath <- system.file("examples", "HemoglobinAA.fasta", package="msa")

+mySeqs <- readAAStringSet(filepath)

+

+## perform multiple alignment

+myAlignment <- msa(mySeqs)

+

+## regular consensus sequence using consensusString() method from the

+## 'Biostrings' package

+msaConsensusSequence(myAlignment)

+

+## use the other method

+msaConsensusSequence(myAlignment, type="upperlower")

+

+## use the other method with custom parameters

+msaConsensusSequence(myAlignment, type="upperlower", thresh=c(50, 20),

+                     ignoreGaps=TRUE)

+

+## compute a consensus matrix first

+conMat <- consensusMatrix(myAlignment)

+msaConsensusSequence(conMat)

+}

+\keyword{manip}

new file mode 100644

@@ -0,0 +1,139 @@

+\name{msaConservationScore}

+\alias{msaConservationScore}

+\alias{msaConservationScore,MultipleAlignment-method}

+\alias{msaConservationScore,matrix-method}

+\title{Computation of Conservation Scores from Multiple Alignment}

+\description{

+  This method computes a vector of conservation scores from a

+  multiple alignment or a previously computed consensus matrix.

+}

+\usage{

+\S4method{msaConservationScore}{matrix}(x, substitutionMatrix, gapVsGap=NULL,

+    ...)

+\S4method{msaConservationScore}{MultipleAlignment}(x, ...)

+}

+\arguments{

+  \item{x}{an object of class \code{\linkS4class{MultipleAlignment}}

+    (which includes objects of classes

+    \code{\linkS4class{MsaAAMultipleAlignment}},

+    \code{\linkS4class{MsaDNAMultipleAlignment}}, and

+    \code{\linkS4class{MsaRNAMultipleAlignment}}) or a previously

+    computed consensus matrix (see details below).}

+  \item{substitutionMatrix}{substitution matrix (see

+    details below).}

+  \item{gapVsGap}{score to use for aligning gaps versus gaps (see

+    details below).}

+  \item{...}{when the method is called for a

+    \code{\linkS4class{MultipleAlignment}} object, the consensus matrix is

+    computed and, including all further arguments,

+    passed on to the \code{msaConservationScore} method with signature

+    \code{matrix}. This method passes all further arguments on to the

+    \code{\link{msaConsensusSequence}} method to customize the way

+    the consensus sequence is computed.}

+  }

+\details{

+  The method takes a \code{\linkS4class{MultipleAlignment}} object or a

+  previously computed consensus matrix and computes the sum of pairwise

+  scores for all positions of the alignment. For computing these scores,

+  it is compulsory to specify a substitution/scoring matrix. This matrix

+  must be provided as a \code{\link{matrix}} object. This can either be

+  one of the ready-made matrices provided by the \pkg{Biostrings}

+  package (e.g. \code{\link{BLOSUM62}}) or any other hand-crafted

+  matrix. In the latter case, the following restrictions apply:

+  \itemize{

+    \item{The matrix must be quadratic.}

+    \item{For reasonable results, the matrix should be symmetric (note

+      that this is not checked).}

+    \item{Rows and columns must be named and the order of letters/symbols

+      in row names and column names must be identical.}

+    \item{All letters/symbols occurring in the multiple alignment,

+      including gaps \sQuote{-}, must also be found in the row/column

+      names of the substitution matrix. For consistency with the

+      matrices from the \pkg{Biostrings} package, the

+      row/column corresponding to gap penalties

+      may also be labeled \sQuote{*} instead of \sQuote{-}.}

+  }

+  So, nucleotide substitution matrices created by

+  \code{\link{nucleotideSubstitutionMatrix}} can be used for multiple

+  alignments of nucleotide sequences, but must be

+  completed with gap penalty rows and columns (see example below).

+

+  If the consensus matrix of a multiple alignment of nucleotide

+  sequences contains rows labeled \sQuote{+} and/or \sQuote{.}, these

+  rows are ignored.

+  

+  The parameter \code{gapVsGap} can be used to control how

+  pairs of gaps are scored. If \code{gapVsGap=NULL} (default), the

+  corresponding diagonal entry of the substitution matrix is used as is.

+  In the BLOSUM matrices, this is usually a positive value, which may

+  not make sense under all circumstances. Therefore, the parameter

+  \code{gapVsGap} can be set to an alternative value, e.g. 0 for

+  ignoring gap-gap pairs.

+

+  The method, in any case, returns a vector of scores that is as long

+  as the alignment/consensus matrix has columns. The names of the vector

+  entries are the corresponding positions of the consensus sequence of

+  the alignment. How this consensus sequence is computed, can be

+  controlled with additional arguments that are passed on to the

+  \code{\link{msaConsensusSequence}} method.

+}

+\value{

+  The function returns a vector as long as the alignment/consensus

+  matrix has columns. The vector is named with the consensus sequence

+  (see details above).

+}

+\author{Ulrich Bodenhofer <msa@bioinf.jku.at>

+}

+\references{

+  \url{http://www.bioinf.jku.at/software/msa}

+  

+  U. Bodenhofer, E. Bonatesta, C. Horejs-Kainrath, and S. Hochreiter

+  (2015). msa: an R package for multiple sequence alignment. 

+  \emph{Bioinformatics} \bold{31}(24):3997-3999. DOI:

+  \href{http://dx.doi.org/10.1093/bioinformatics/btv494}{10.1093/bioinformatics/btv494}.

+}

+\seealso{\code{\link{msa}}, \code{\linkS4class{MsaAAMultipleAlignment}},

+  \code{\linkS4class{MsaDNAMultipleAlignment}},

+  \code{\linkS4class{MsaRNAMultipleAlignment}},

+  \code{\linkS4class{MsaMetaData}},

+  \code{\linkS4class{MultipleAlignment}},

+  \code{\link{msaConsensusSequence}}

+}

+\examples{

+## read sequences

+filepath <- system.file("examples", "HemoglobinAA.fasta", package="msa")

+mySeqs <- readAAStringSet(filepath)

+

+## perform multiple alignment

+myAlignment <- msa(mySeqs)

+

+## compute consensus scores using the BLOSUM62 matrix

+data(BLOSUM62)

+msaConservationScore(myAlignment, BLOSUM62)

+

+## compute consensus scores using the BLOSUM62 matrix

+## without scoring gap-gap pairs and using a different consensus sequence

+msaConservationScore(myAlignment, BLOSUM62, gapVsGap=0,

+                     type="upperlower")

+

+## compute a consensus matrix first

+conMat <- consensusMatrix(myAlignment)

+data(PAM250)

+msaConservationScore(conMat, PAM250, gapVsGap=0)

+

+

+## DNA example

+filepath <- system.file("examples", "exampleDNA.fasta", package="msa")

+mySeqs <- readDNAStringSet(filepath)

+

+## perform multiple alignment

+myAlignment <- msa(mySeqs)

+

+## create substitution matrix with gap penalty -8

+mat <- nucleotideSubstitutionMatrix(4, -1)

+mat <- cbind(rbind(mat, "-"=-8), "-"=-8)

+

+## compute consensus scores using this matrix

+msaConservationScore(myAlignment, mat, gapVsGap=0)

+}

+\keyword{manip}

@@ -9,7 +9,7 @@

     msaConvert(x,

                type=c("seqinr::alignment", "bios2mds::align",

                       "ape::AAbin", "ape::DNAbin",

-                      "phangorn::phyDat"))

+                      "phangorn::phyDat", "bio3d::fasta"))

 }

 \arguments{

   \item{x}{an object of class \code{\linkS4class{MultipleAlignment}}

@@ -20,8 +20,8 @@

   \item{type}{a character string specifying to which type of object

     \code{x} should be converted; currently, the

     values \code{"seqinr::alignment"}, \code{"bios2mds::align"},

-    \code{"ape::AAbin"}, \code{"ape::DNAbin"}, and

-    \code{"phangorn::phyDat"}.}

+    \code{"ape::AAbin"}, \code{"ape::DNAbin"},

+    \code{"phangorn::phyDat"}, and \code{"bio3d::fasta"}.}

   }

 \details{

   The function converts \code{x} to the class of object as

@@ -382,8 +382,8 @@ both as setter and getter functions. To set row or column masks, an

 \verb+IRanges+ object must be supplied:

 <<maskExample>>=

 myMaskedAlignment <- myFirstAlignment

-rowM <- IRanges(start=1, end=2)

-rowmask(myMaskedAlignment) <- rowM

+colM <- IRanges(start=1, end=100)

+colmask(myMaskedAlignment) <- colM

 myMaskedAlignment

 @

@@ -400,16 +400,26 @@ conMat <- consensusMatrix(myFirstAlignment)

 dim(conMat)

 conMat[, 101:110]

 @

-Note that \verb+consensusMatrix()+ cannot handle

-alignments with active masks. So, the masks in multiple alignment objects must

-must be removed prior to the computation of the consensus matrix:

+If called on a masked alignment, \verb+consensusMatrix()+ only uses those

+sequences/rows that are not masked. If there are masked columns,

+the matrix contains \verb+NA+'s in those columns:

 <<consensusExample2>>=

-conMat <- consensusMatrix(unmasked(myMaskedAlignment))

+conMat <- consensusMatrix(myMaskedAlignment)

+conMat[, 95:104]

 @

-Consensus strings can be computed from consensus matrices:

+Multiple alignments also inherit the \verb+consensusString()+ method from

+the \verb+Biostrings+ package. However, for more flexibility and consistency,

+we rather advise users to use the method \verb+msaConsensusSequence()+

+method (see below).

+

+\subsection{Consensus Sequences and Conservation Scores}

+

+With version 1.7.1 of \MSA, new methods have been provided that allow for

+the computation of consensus sequences and conservation scores.

+By default, the \verb+msaConsensusSequence()+ method is a wrapper around the

+\verb+consensusString()+ method from the \verb+Biostrings+:

 <<consensusExample3>>=

-## auxiliary function for splitting a string into displayable portions

 printSplitString <- function(x, width=getOption("width") - 1)

 {

     starts <- seq(from=1, to=nchar(x), by=width)

@@ -418,20 +428,55 @@ printSplitString <- function(x, width=getOption("width") - 1)

         cat(substr(x, starts[i], starts[i] + width - 1), "\n")

 }

-printSplitString(consensusString(conMat))

+printSplitString(msaConsensusSequence(myFirstAlignment))

 @

-\noindent Consensus sequences can also be computed directly without computing

-intermediate consensus matrices. However, the \verb+consensusString()+

-function cannot handle the

-masks contained in the multiple alignment objects (no matter whether

-there are active masks or not). Therefore, it is necessary to remove

-the masks beforehand:

+However, there is also a second method for computing consensus sequence that

+has been implemented in line with a consensus sequence method implemented

+in \TeXshade\ that allows for specify an upper and a lower conservation threshold

+(see example below). This method can be accessed via the argument

+\verb+type="upperlower"+. Additional customizations are available, too:

 <<consensusExample4>>=

-printSplitString(consensusString(unmasked(myFirstAlignment)))

-printSplitString(consensusString(unmasked(myMaskedAlignment)))

+printSplitString(msaConsensusSequence(myFirstAlignment, type="upperlower",

+                                      thresh=c(40, 20)))

+@

+

+Regardless of which method is used, masks are taken into account: masked

+rows/sequences are neglected and masked columns are shown as ``\verb+#+'' in

+the consensus sequence:

+<<consensusExample5>>=

+printSplitString(msaConsensusSequence(myMaskedAlignment, type="upperlower",

+                                      thresh=c(40, 20)))

+@

+

+The main purpose of consensus sequences is to get an impression of conservation

+at individual positions/columns of a multiple alignment. The \MSA\ package also

+provides another means of analyzing conservation: the method

+\verb+msaConservationScore()+ computes sums of pairwise scores for a given

+substitution/scoring matrix. Thereby, conservation can also be analyzed in a

+more sensible way than by only taking relative frequencies of letters into

+account as \verb+msaConsensusSequence()+ does.

+<<conservationExample1>>=

+data(BLOSUM62)

+msaConservationScore(myFirstAlignment, BLOSUM62)

+@

+As the above example shows, a substitution matrix must be provided. The result

+is obviously a vector as long as the alignment has columns. The entries of the

+vector are labeled by the consensus sequence. The way the consensus sequence is

+computed can be customized:

+<<conservationExample2>>=

+msaConservationScore(myFirstAlignment, BLOSUM62, gapVsGap=0,

+                     type="upperlower", thresh=c(40, 20))

+@

+The additional argument \verb+gapVsGap+ allows for controlling how pairs of

+gap are taken into account when computing pairwise scores (see

+\verb+?msaConservationScore+ for more details).

+

+Conservation scores can also be computed from masked alignments. For masked

+columns, \verb+NA+'s are returned:

+<<conservationExample3>>=

+msaConservationScore(myMaskedAlignment, BLOSUM62, gapVsGap=0,

+                     type="upperlower", thresh=c(40, 20))

 @

-\noindent Actually, the \verb+print()+ method (see Section~\ref{sec:msaPrint} above)

-uses this function to compute the consensus sequence.

 \subsection{Interfacing to Other Packages}

@@ -795,6 +840,16 @@ source package tarball, untar it, comment/uncomment the corresponding line in

 \verb+msa/src/ClustalOmega/msaMakefile+ (see first six lines), and

 build/install the package from source.

+\subsubsection*{Build/installation issues}

+

+Some users have reported compiler and linker errors when building \MSA\ from

+source on Linux systems. In almost all cases, these could have been tracked down

+to issues with the \R\ setup on those systems (e.g.\ a \verb+Rprofile.site+ file

+that makes changes to the \R\ environment that are not compatible with \MSA's

+Makefiles).\footnote{See, e.g., \url{https://support.bioconductor.org/p/90735/}}

+In most cases, these issues can be avoided by installing \MSA\ in a ``vanilla \R\ session'',

+i.e.\ starting \R\ with option \verb+--vanilla+ when installing \MSA.

+

 \section{Future Extensions}\label{sec:future}

 We envision the following changes/extensions in future versions of the package:

@@ -834,6 +889,21 @@ bibliography below).

 \section{Change Log}

 \begin{description}

+\item[Version 1.7.1:] \mbox{ }  \begin{itemize}

+   \item additional conversions implemented for \verb+msaConvert()+ function

+   \item added a new method \verb+msaConsensusSequence()+ that extends the

+     functionality provided by \verb+Biostring+'s \verb+consensusString()+ method

+   \item added a new method \verb+msaConservationScore()+

+   \item \verb+print()+ method extended such that it now also allows for

+     customization of the consensus sequence (via the new

+     \verb+msaConsensusSequence()+ method)

+   \item package now depends on \verb+Biostrings+ version $\geq$2.40.0 in order

+     to make sure that \verb+consensusMatrix()+ also works correctly

+     for masked alignments

+   \item corresponding changes in documentation and vignette

+  \end{itemize}

+\item[Version 1.7.0:] new branch for Bioconductor 3.5 devel

+\item[Version 1.6.0:] release as part of Bioconductor 3.4

 \item[Version 1.5.5:] \mbox{ }  \begin{itemize}

    \item fixes in ClustalOmega source code to ensure Windows compatibility of

    GCC6 compatibility fix