@@ -171,7 +171,7 @@ which allows for pretty-printing multiple alignments using the \LaTeX\ package

 \shade. As an example, the following \R\ code creates a PDF file

 \verb+myfirstAlignment.pdf+ which is shown in

 Figure~\ref{fig:myFirstAlignment}:

-<<IntegratePDF2>>=

+<<IntegratePDF2,eval=FALSE>>=

 msaPrettyPrint(myFirstAlignment, output="pdf", showNames="none",

                showLogo="none", askForOverwrite=FALSE, verbose=FALSE)

 @

@@ -6,12 +6,12 @@

 \hypersetup{colorlinks=false,

     pdfborder=0 0 0,

     pdftitle={msa - An R Package for Multiple Sequence Alignment},

-    pdfauthor={Enrico Bonatesta, Christoph Horejs-Kainrath, and Ulrich Bodenhofer}}

+    pdfauthor={Enrico Bonatesta, Christoph Kainrath, and Ulrich Bodenhofer}}

 \usepackage[OT1]{fontenc}

 \title{{\Huge msa}\\[5mm] An R Package for Multiple Sequence Alignment}

-\author{Enrico Bonatesta, Christoph Horej\v{s}-Kainrath, and Ulrich Bodenhofer}

+\author{Enrico Bonatesta, Christoph Kainrath, and Ulrich Bodenhofer}

 \affiliation{Institute of Bioinformatics, Johannes Kepler University

 Linz\\Altenberger Str. 69, 4040 Linz, Austria\\

 \email{msa@bioinf.jku.at}}

@@ -887,126 +887,6 @@ Moreover, we insist that, any time you cite the package, you also cite

 the original paper in which the original algorithm has been introduced (see

 bibliography below).

-\section{Change Log}

-

-\begin{description}

-\item[Version 1.18.0:] release as part of Bioconductor 3.10

-\item[Version 1.17.1:] \mbox{ }  \begin{itemize}

-   \item fixed regular expression to comply with PCRE2

-   \item fixed Windows makefile for gc lib

-   \item fixed Windows cleanup script

-   \item fixed\verb+ src/Makevars.win+

-  \end{itemize}

-\item[Version 1.17.0:] new branch for Bioconductor 3.10 devel

-\item[Version 1.16.0:] release as part of Bioconductor 3.9

-\item[Version 1.15.0:] new branch for Bioconductor 3.9 devel

-\item[Version 1.14.0:] release as part of Bioconductor 3.8

-\item[Version 1.13.0:] new branch for Bioconductor 3.8 devel

-\item[Version 1.12.0:] release as part of Bioconductor 3.7

-\item[Version 1.11.2:] \mbox{ }  \begin{itemize}

-   \item minor fix in ClustalW

-  \end{itemize}

-\item[Version 1.11.1:] \mbox{ }  \begin{itemize}

-   \item fix of code for using custom substitution matrices in ClustalW

-  \end{itemize}

-\item[Version 1.11.0:] new branch for Bioconductor 3.7 devel

-\item[Version 1.10.0:] release as part of Bioconductor 3.56

-\item[Version 1.9.0:] new branch for Bioconductor 3.6 devel

-\item[Version 1.8.0:] release as part of Bioconductor 3.5

-\item[Version 1.7.2:] \mbox{ }  \begin{itemize}

-   \item fix for new \verb+clang+ 4 compiler on Mac OS

-  \end{itemize}

-\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

-   \end{itemize}

-\item[Version 1.5.4:] \mbox{ }  \begin{itemize}

-   \item bug fix in \verb+msaClustalW()+: unsupported parameter `\verb+tree+' deactivated

-   \item fixes in ClustalOmega source code to ensure GCC 6 compatibility

-   \item fix in \verb+msaConvert()+ function to improve safety of call to suggested

-  package \verb+phangorn+

-  \end{itemize}

-\item[Version 1.5.3:] \mbox{ }  \begin{itemize}

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

-   \item corresponding changes in documentation

-  \end{itemize}

-\item[Versions 1.5.1 and 1.5.2:] version number bumps for technical reasons

-  related to Bioconductor build servers

-\item[Version 1.5.0:] new branch for Bioconductor 3.4 devel

-\item[Version 1.4.0:] release as part of Bioconductor 3.3

-\item[Version 1.3.7:] \mbox{ }  \begin{itemize}

-   \item fixes in \verb+msaPrettyPrint()+ function

-  \end{itemize}

-\item[Version 1.3.6:] \mbox) { }  \begin{itemize}

-   \item \verb+msaPrettyPrint()+ now also accepts dashes in file names

-   \item added section about pretty-printing wide alignments to package vignette

-  \end{itemize}

-\item[Version 1.3.5:] \mbox{ }  \begin{itemize}

-   \item adaptation of displaying help text by \verb+msa()+ function

-  \end{itemize}

-\item[Version 1.3.4:] \mbox{ }  \begin{itemize}

-   \item added function for checking and fixing sequence names for

-     possibly problematic characters that could lead to \LaTeX\ errors

-     when using \verb+msaPrettyPrint()+

-   \item corresponding changes in documentation

-   \item minor namespace fix

-  \end{itemize}

-\item[Version 1.3.3:] \mbox{ }  \begin{itemize}

-   \item added function for converting multiple sequence alignments for

-     use with other sequence alignment packages

-   \item corresponding changes in documentation

-  \end{itemize}

-\item[Version 1.3.2:] \mbox{ }  \begin{itemize}

-   \item further fixes in Makefiles and Makevars files to account for changes in build system

-   \item update of citation information

-  \end{itemize}

-\item[Version 1.3.1:] \mbox{ }  \begin{itemize}

-   \item fixes in Makefiles and Makevars files to account for changes in build system

-  \end{itemize}

-\item[Version 1.3.0:] new branch for Bioconductor 3.3 devel

-\item[Version 1.2.0:] release as part of Bioconductor 3.2

-\item[Version 1.1.3:] \mbox{ }  \begin{itemize}

-    \item bug fix related to custom substitution matrices

-      in the MUSCLE interface

-    \item corrections and updates of documentation

-  \end{itemize}

-\item[Version 1.1.2:] \mbox{ }  \begin{itemize}

-    \item new \verb+print()+ function for multiple alignments that also

-      allows for displaying alignments in their entirety (plus additional

-      customizations)

-    \item strongly improved handling of custom substitution matrices by

-      \verb+msaClustalW()+: now custom matrices can also be supplied for nucleotide

-      sequences which can also be passed via the \verb+substitutionMatrix+ argument.

-      The \verb+dnamatrix+ argument is still available for the sake of backwards

-      compatibility.

-    \item strongly improved handling of custom substitution matrices by

-      \verb+msaMuscle()+

-    \item fix of improperly aligned sequence logos produced by

-      \verb+msaPrettyPrint()+

-    \item updated citation information

-  \end{itemize}

-\item[Version 1.1.1:]  \mbox{ }  \begin{itemize}

-    \item fix of \verb+msa()+ function

-  \end{itemize}

-\item[Version 1.1.0:] new branch for Bioconductor 3.2 devel

-\item[Version 1.0.0:] first official release as part of Bioconductor 3.1

-\end{description}

-

 \bibliographystyle{plain}

 \bibliography{lit}

@@ -890,6 +890,18 @@ bibliography below).

 \section{Change Log}

 \begin{description}

+\item[Version 1.18.0:] release as part of Bioconductor 3.10

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

+   \item fixed regular expression to comply with PCRE2

+   \item fixed Windows makefile for gc lib

+   \item fixed Windows cleanup script

+   \item fixed\verb+ src/Makevars.win+

+  \end{itemize}

+\item[Version 1.17.0:] new branch for Bioconductor 3.10 devel

+\item[Version 1.16.0:] release as part of Bioconductor 3.9

+\item[Version 1.15.0:] new branch for Bioconductor 3.9 devel

+\item[Version 1.14.0:] release as part of Bioconductor 3.8

+\item[Version 1.13.0:] new branch for Bioconductor 3.8 devel

 \item[Version 1.12.0:] release as part of Bioconductor 3.7

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

    \item minor fix in ClustalW

@@ -111,8 +111,9 @@ available via Bioconductor. The simplest way to install the package

 is the following:

 <<InstallMSA,eval=FALSE>>=

-source("http://www.bioconductor.org/biocLite.R")

-biocLite("msa")

+if (!requireNamespace("BiocManager", quietly=TRUE))

+    install.packages("BiocManager")

+BiocManager::install("msa")

 @

 To test the installation of the \MSA\ package, enter

@@ -890,6 +890,9 @@ bibliography below).

 \begin{description}

 \item[Version 1.12.0:] release as part of Bioconductor 3.7

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

+   \item minor fix in ClustalW

+  \end{itemize}

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

    \item fix of code for using custom substitution matrices in ClustalW

   \end{itemize}

@@ -889,6 +889,14 @@ bibliography below).

 \section{Change Log}

 \begin{description}

+\item[Version 1.12.0:] release as part of Bioconductor 3.7

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

+   \item fix of code for using custom substitution matrices in ClustalW

+  \end{itemize}

+\item[Version 1.11.0:] new branch for Bioconductor 3.7 devel

+\item[Version 1.10.0:] release as part of Bioconductor 3.56

+\item[Version 1.9.0:] new branch for Bioconductor 3.6 devel

+\item[Version 1.8.0:] release as part of Bioconductor 3.5

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

    \item fix for new \verb+clang+ 4 compiler on Mac OS

   \end{itemize}

@@ -889,6 +889,9 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

+   \item fix for new \verb+clang+ 4 compiler on Mac OS

+  \end{itemize}

 \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

@@ -925,7 +928,7 @@ bibliography below).

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

    \item fixes in \verb+msaPrettyPrint()+ function

   \end{itemize}

-\item[Version 1.3.6:] \mbox{ }  \begin{itemize}

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

    \item \verb+msaPrettyPrint()+ now also accepts dashes in file names

    \item added section about pretty-printing wide alignments to package vignette

   \end{itemize}

@@ -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

@@ -834,6 +834,10 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

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

+   GCC6 compatibility fix

+   \end{itemize}

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

    \item bug fix in \verb+msaClustalW()+: unsupported parameter `\verb+tree+' deactivated

    \item fixes in ClustalOmega source code to ensure GCC 6 compatibility

@@ -834,6 +834,12 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

+   \item bug fix in \verb+msaClustalW()+: unsupported parameter `\verb+tree+' deactivated

+   \item fixes in ClustalOmega source code to ensure GCC 6 compatibility

+   \item fix in \verb+msaConvert()+ function to improve safety of call to suggested

+  package \verb+phangorn+

+  \end{itemize}

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

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

    \item corresponding changes in documentation

@@ -436,14 +436,16 @@ uses this function to compute the consensus sequence.

 \subsection{Interfacing to Other Packages}

 There are also other sequence analysis packages that use or make use of multiple

-sequence alignments. The \msa\ package does not directly interface to any of these packages

+sequence alignments. The \msa\ package does not directly interface to these packages

 in order to avoid dependencies and possible incompatibilities. However, \msa\ provides

 a function \verb+msaConvert()+ that allows for converting multiple sequence alignment

-objects to other types/classes. Currently, two such conversions are available, namely to

-objects of class \verb+alignment+ (as defined and used by the \verb+seqinr+ package) and

-to objects of class \verb+align+ (as defined and used by the \verb+bios2mds+ package).

-Note that the conversion is performed without loading or depending on the respective

-packages.

+objects to other types/classes. Currently, five such conversions are available, namely to

+the classes \verb+alignment+ (\verb+seqinr+ package \cite{CharifLobry2007}),

+\verb+align+ (\verb+bios2mds+ package \cite{PeleBecuAbdiChabbert2012}),

+\verb+AAbin+/\verb+DNAbin+ (\verb+ape+ package \cite{ParadisClaudeStrimmer2004}),

+and \verb+phyDat+ (\verb+phangorn+ package \cite{Schliep2011}). Except for the

+conversion to the class \verb+phyDat+, these conversion are performed without loading

+or depending on the respective packages.

 In the following example, we perform a multiple alignment of Hemoglobin alpha

 example sequences and convert the result for later processing with the \verb+seqinr+

@@ -461,14 +463,15 @@ the \verb+seqinr+ package:

 library(seqinr)

 d <- dist.alignment(hemoAln2, "identity")

-as.matrix(d)[3:4, 3:4]

+as.matrix(d)[2:5, "HBA1_Homo_sapiens", drop=FALSE]

 @

-Now we can construct a draft phylogenetic tree using the \verb+hclust()+ function from

-the \verb+stats+ package:

-<<HemoglobinTree,output.width='0.8\\textwidth',output.height='0.5\\textwidth'>>=

-hemoTree <- hclust(d)

-plot(hemoTree, main="Phylogenetic Tree of Hemoglobin Alpha Sequences",

-     xlab="", sub="")

+Now we can construct a phylogenetic tree with the neighbor joining algorithm using the

+\verb+nj()+ function from the \verb+ape+ package:

+<<HemoglobinTree,output.width='0.8\\textwidth',output.height='0.5\\textwidth',message=FALSE,results='hide'>>=

+library(ape)

+

+hemoTree <- nj(d)

+plot(hemoTree, main="Phylogenetic Tree of Hemoglobin Alpha Sequences")

 @

 The following example shows how to convert a multiple alignment object in an object of

@@ -478,6 +481,20 @@ hemoAln3 <- msaConvert(hemoAln, type="bios2mds::align")

 str(hemoAln3)

 @

+The conversions to the standard \verb+Biostrings+ classes are straightforward using

+standard \verb+as()+ methods and not provided by the \verb+msaConvert()+ function.

+The following example converts a multiple alignment object to class \verb+BStringSet+

+(e.g.\ the \verb+msaplot()+ function from the \verb+ggtree+ package

+\cite{YuSmithZhuGuanLam2016} accepts \verb+BStringSet+ objects):

+<<Hemoglobin4>>=

+hemoAln4 <- as(hemoAln, "BStringSet")

+hemoAln4

+@

+

+\notebox{The \texttt{msaConvert()} function has been introduced in version 1.3.3 of the

+  \MSA\ package. So, to have this function available, at least Bioconductor 3.3

+  is required, which requires at least R 3.3.0.}

+

 \section{Pretty-Printing Multiple Sequence Alignments}\label{sec:msaPrettyPrint}

 As already mentioned above, the \MSA\ package offers the function

@@ -817,6 +834,13 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

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

+   \item corresponding changes in documentation

+  \end{itemize}

+\item[Versions 1.5.1 and 1.5.2:] version number bumps for technical reasons

+  related to Bioconductor build servers

+\item[Version 1.5.0:] new branch for Bioconductor 3.4 devel

 \item[Version 1.4.0:] release as part of Bioconductor 3.3

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

    \item fixes in \verb+msaPrettyPrint()+ function

@@ -847,7 +871,7 @@ bibliography below).

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

    \item fixes in Makefiles and Makevars files to account for changes in build system

   \end{itemize}

-\item[Version 1.3.0:] devel branch created from version 1.2.0

+\item[Version 1.3.0:] new branch for Bioconductor 3.3 devel

 \item[Version 1.2.0:] release as part of Bioconductor 3.2

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

     \item bug fix related to custom substitution matrices

@@ -872,84 +896,11 @@ bibliography below).

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

     \item fix of \verb+msa()+ function

   \end{itemize}

-\item[Version 1.1.0:] devel branch created from version 1.0.0

+\item[Version 1.1.0:] new branch for Bioconductor 3.2 devel

 \item[Version 1.0.0:] first official release as part of Bioconductor 3.1

 \end{description}

-%\bibliographystyle{plain}

-%\bibliography{lit}

-

-\begin{thebibliography}{10}

-

-\bibitem{Beitz2000}

-E.~Beitz.

-\newblock {\TeX shade}: shading and labeling of multiple sequence alignments

-  using {\LaTeX2e}.

-\newblock {\em Bioinformatics}, 16(2):135--139, 2000.

-

-\bibitem{Edgar2004b}

-R.~C. Edgar.

-\newblock {MUSCLE}: a multiple sequence alignment method with reduced time and

-  space complexity.

-\newblock {\em BMC Bioinformatics}, 5(5):113, 2004.

-

-\bibitem{Edgar2004a}

-R.~C. Edgar.

-\newblock {MUSCLE:} multiple sequence alignment with high accuracy and high

-  throughput.

-\newblock {\em Nucleic Acids Res.}, 32(5):1792--1797, 2004.

-

-\bibitem{Lamport1999}

-L.~Lamport.

-\newblock {\em {\LaTeX} --- A Document Preparation System. User's Guide and

-  Reference Manual}.

-\newblock Addison-Wesley Longman, Amsterdam, 1999.

-

-\bibitem{Leisch2002}

-F.~Leisch.

-\newblock Sweave: dynamic generation of statistical reports using literate data

-  analysis.

-\newblock In W.~H\"ardle and B.~R\"onz, editors, {\em Compstat 2002 ---

-  Proceedings in Computational Statistics}, pages 575--580, Heidelberg, 2002.

-  Physica-Verlag.

-

-\bibitem{Morgenstern1999}

-B.~Morgenstern.

-\newblock {DIALIGN 2}: improvement of the segment-to-segment approach to

-  multiple sequence alignment.

-\newblock {\em Bioinformatics}, 15(3):211--218, 1999.

-

-\bibitem{Nethercote2007}

-N.~Nethercote and J.~Seward.

-\newblock Valgrind: A framework for heavyweight dynamic binary instrumentation.

-\newblock In {\em Proc. of the ACM SIGPLAN 2007 Conf. on Programming Language

-  Design and Implementation}, San Diego, CA, 2007.

-

-\bibitem{Notredame2000}

-C.~Notredame, D.~G. Higgins, and J.~Heringa.

-\newblock {T-Coffee}: A novel method for fast and accurate multiple sequence

-  alignment.

-\newblock {\em J. Mol. Biol.}, 302(1):205--217, 2000.

-

-\bibitem{Sievers2011}

-F.~Sievers, A.~Wilm, D.~Dineen, T.~J. Gibson, K.~Karplus, W.~Li, R.~Lopez,

-  H.~McWilliam, M.~Remmert, J.~S\"oding, J.~D. Thompson, and D.~G. Higgins.

-\newblock Fast, scalable generation of high-quality protein multiple sequence

-  alignments using {Clustal Omega}.

-\newblock {\em Mol. Syst. Biol.}, 7:539, 2011.

-

-\bibitem{Thompson1994}

-J.~D. Thompson, D.~G. Higgins, and T.~J. Gibson.

-\newblock {CLUSTAL W}: improving the sensitivity of progressive multiple

-  sequence alignment through sequence weighting, position-specific gap

-  penalties and weight matrix choice.

-\newblock {\em Nucleic Acids Res.}, 22(22):4673--4680, 2004.

-

-\bibitem{Xie2014}

-Y.~Xie.

-\newblock {\em Dynamic Documents with R and knitr}.

-\newblock Chapman \&\ Hall/CRC, 2014.

-

-\end{thebibliography}

+\bibliographystyle{plain}

+\bibliography{lit}

 \end{document}

@@ -817,6 +817,10 @@ bibliography below).

 \section{Change Log}

 \begin{description}

+\item[Version 1.4.0:] release as part of Bioconductor 3.3

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

+   \item fixes in \verb+msaPrettyPrint()+ function

+  \end{itemize}

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

    \item \verb+msaPrettyPrint()+ now also accepts dashes in file names

    \item added section about pretty-printing wide alignments to package vignette

@@ -843,9 +847,8 @@ bibliography below).

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

    \item fixes in Makefiles and Makevars files to account for changes in build system

   \end{itemize}

-\item[Version 1.3.0:] \mbox{ }  \begin{itemize}

-    \item new branch for Bioconductor 3.3 devel

-  \end{itemize}

+\item[Version 1.3.0:] devel branch created from version 1.2.0

+\item[Version 1.2.0:] release as part of Bioconductor 3.2

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

     \item bug fix related to custom substitution matrices

       in the MUSCLE interface

@@ -866,8 +869,10 @@ bibliography below).

       \verb+msaPrettyPrint()+

     \item updated citation information

   \end{itemize}

-\item[Version 1.1.1:] fix of \verb+msa()+ function

-\item[Version 1.1.0:] new branch for Bioconductor 3.2 devel

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

+    \item fix of \verb+msa()+ function

+  \end{itemize}

+\item[Version 1.1.0:] devel branch created from version 1.0.0

 \item[Version 1.0.0:] first official release as part of Bioconductor 3.1

 \end{description}

@@ -684,6 +684,41 @@ is to check sequence names carefully and to avoid problematic sequence names fro

 Note, moreover, that too long sequence names will lead to less appealing outputs,

 so users are generally advised to consider sequence names carefully.

+\subsection{Pretty-Printing Wide Alignments}

+

+If the alignment to be printed with \verb+msaPrettyPrint()+ is wide

+(thousands of columns or wider), \LaTeX\ may terminate prematurely because of

+exceeded \TeX\ capacity. Unfortunately, this problem remains opaque to the

+user, since \verb+texi2dvi()+ and \verb+texi2pdf()+ do not convey much details

+about \LaTeX\ problems when typesetting a document. We recommend the following

+if a user encounters problems with running \verb+msaPrettyPrint()+'s output

+with \verb+texi2dvi()+ and \verb+texi2pdf()+:

+\begin{enumerate}

+\item Run \verb+pdflatex+ on the generated \verb+.tex+ file to see

+  whether it is actually a problem with \TeX\ capacity.

+\item If so, split the alignment into multiple chunks and run

+  \verb+msaPrettyPrint()+ on each chunk separately.

+\end{enumerate}

+

+The following example

+demonstrates this approach for a multiple aligment object `\verb+aln+':

+<<SplitAlignmentIntoJunks,eval=FALSE>>=

+chunkSize <- 300 ## how much fits on one page depends on the length of

+                 ## names and the number of sequences;

+                 ## change to what suits your needs

+

+for (start in seq(1, ncol(aln), by=chunkSize))

+{

+    end <- min(start + chunkSize - 1, ncol(aln))

+    alnPart <- DNAMultipleAlignment(subseq(unmasked(aln), start, end))

+

+    msaPrettyPrint(x=alnPart, output="pdf", subset=NULL,

+                   file=paste0("aln_", start, "-", end, ".pdf"))

+}

+@

+\noindent This creates multiple PDF files all of which show one part of the alignment.

+Please note, however, that the numbering of columns is restarted for each chunk.

+

 \subsection{Further Caveats}

 \begin{itemize}

@@ -782,6 +817,10 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

+   \item \verb+msaPrettyPrint()+ now also accepts dashes in file names

+   \item added section about pretty-printing wide alignments to package vignette

+  \end{itemize}

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

    \item adaptation of displaying help text by \verb+msa()+ function

   \end{itemize}

@@ -782,6 +782,9 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

+   \item adaptation of displaying help text by \verb+msa()+ function

+  \end{itemize}

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

    \item added function for checking and fixing sequence names for

      possibly problematic characters that could lead to \LaTeX\ errors

@@ -11,7 +11,7 @@

 \usepackage[OT1]{fontenc}

 \title{{\Huge msa}\\[5mm] An R Package for Multiple Sequence Alignment}

-\author{Enrico Bonatesta, Christoph Horejs-Kainrath, and Ulrich Bodenhofer}

+\author{Enrico Bonatesta, Christoph Horej\v{s}-Kainrath, and Ulrich Bodenhofer}

 \affiliation{Institute of Bioinformatics, Johannes Kepler University

 Linz\\Altenberger Str. 69, 4040 Linz, Austria\\

 \email{msa@bioinf.jku.at}}

@@ -666,10 +666,28 @@ the \shade\ package must be loaded in the preamble:

 \end{verbatim}

 \end{quote}

+\subsection{Sequence Names}

+

+The \verb+Biostrings+ package does not impose any restrictions on the names of

+sequences. Consequently, \MSA\ also allows all possible ASCII strings as

+sequence (row) names in multiple alignments. As soon as \verb+msaPrettyPrint()+

+is used for pretty-printing multiple sequence alignments, however, the sequence

+names are interpreted as plain \LaTeX\ source code. Consequently, \LaTeX\ errors

+may arise because of characters or words in the sequence names that \LaTeX\

+does not or cannot interpret as plain text correctly. This particularly includes

+appearances of special characters and backslash characters in the sequence names.

+

+The \MSA\ package offers a function \verb+msaCheckNames()+ which allows for finding

+and replacing potentially problematic characters in the sequence names of

+multiple alignment objects (see \verb+?msaCheckNames+). However, the best solution

+is to check sequence names carefully and to avoid problematic sequence names from the beginning.

+Note, moreover, that too long sequence names will lead to less appealing outputs,

+so users are generally advised to consider sequence names carefully.

+

 \subsection{Further Caveats}

 \begin{itemize}

-  \item Note that \verb+texi2dvi()+ and \verb+ttexi2pdf()+ always

+  \item Note that \verb+texi2dvi()+ and \verb+texi2pdf()+ always

     save the resulting DVI/PDF files to the current working directory,

     even if the \LaTeX\ source file is in a different directory.

     That is also the reason why the temporary file is created in the

@@ -764,6 +782,13 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

+   \item added function for checking and fixing sequence names for

+     possibly problematic characters that could lead to \LaTeX\ errors

+     when using \verb+msaPrettyPrint()+

+   \item corresponding changes in documentation

+   \item minor namespace fix

+  \end{itemize}

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

    \item added function for converting multiple sequence alignments for

      use with other sequence alignment packages

@@ -39,6 +39,7 @@ Linz\\Altenberger Str. 69, 4040 Linz, Austria\\

 options(width=65)

 set.seed(0)

 library(msa)

+library(seqinr)

 msaVersion <- packageDescription("msa")$Version

 msaDateRaw <- packageDescription("msa")$Date

 msaDateYear <- as.numeric(substr(msaDateRaw, 1, 4))

@@ -366,6 +367,8 @@ print(myFirstAlignment, showNames=FALSE, show="complete")

 \section{Processing Multiple Alignments}\label{sec:msaProc}

+\subsection{Methods Inherited From {\tt Biostrings}}

+

 The classes defined by the \MSA\ package for storing multiple alignment results

 have been derived from the corresponding classes defined by the

 \verb+Biostrings+ package. Therefore, all methods for processing

@@ -430,6 +433,51 @@ printSplitString(consensusString(unmasked(myMaskedAlignment)))

 \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}

+

+There are also other sequence analysis packages that use or make use of multiple

+sequence alignments. The \msa\ package does not directly interface to any of these packages

+in order to avoid dependencies and possible incompatibilities. However, \msa\ provides

+a function \verb+msaConvert()+ that allows for converting multiple sequence alignment

+objects to other types/classes. Currently, two such conversions are available, namely to

+objects of class \verb+alignment+ (as defined and used by the \verb+seqinr+ package) and

+to objects of class \verb+align+ (as defined and used by the \verb+bios2mds+ package).

+Note that the conversion is performed without loading or depending on the respective

+packages.

+

+In the following example, we perform a multiple alignment of Hemoglobin alpha

+example sequences and convert the result for later processing with the \verb+seqinr+

+package:

+<<Hemoglobin1>>=

+hemoSeq <- readAAStringSet(system.file("examples/HemoglobinAA.fasta",

+                                       package="msa"))

+hemoAln <- msa(hemoSeq)

+hemoAln

+hemoAln2 <- msaConvert(hemoAln, type="seqinr::alignment")

+@

+Now we compute a distance matrix using the \verb+dist.alignment()+ function from

+the \verb+seqinr+ package:

+<<Hemoglobin2>>=

+library(seqinr)

+

+d <- dist.alignment(hemoAln2, "identity")

+as.matrix(d)[3:4, 3:4]

+@

+Now we can construct a draft phylogenetic tree using the \verb+hclust()+ function from

+the \verb+stats+ package:

+<<HemoglobinTree,output.width='0.8\\textwidth',output.height='0.5\\textwidth'>>=

+hemoTree <- hclust(d)

+plot(hemoTree, main="Phylogenetic Tree of Hemoglobin Alpha Sequences",

+     xlab="", sub="")

+@

+

+The following example shows how to convert a multiple alignment object in an object of

+class \verb+align+ as defined by the \verb+bios2mds+ package:

+<<Hemoglobin3>>=

+hemoAln3 <- msaConvert(hemoAln, type="bios2mds::align")

+str(hemoAln3)

+@

+

 \section{Pretty-Printing Multiple Sequence Alignments}\label{sec:msaPrettyPrint}

 As already mentioned above, the \MSA\ package offers the function

@@ -716,6 +764,11 @@ bibliography below).

 \section{Change Log}

 \begin{description}

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

+   \item added function for converting multiple sequence alignments for

+     use with other sequence alignment packages

+   \item corresponding changes in documentation

+  \end{itemize}

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

    \item further fixes in Makefiles and Makevars files to account for changes in build system

    \item update of citation information

@@ -699,8 +699,9 @@ We envision the following changes/extensions in future versions of the package:

 If you use this package for research that is published later, you are kindly

 asked to cite it as follows:

 \begin{quotation}

-\noindent E.~Bonatesta, C.~Horejs-Kainrath, and U.~Bodenhofer, (2015).

-msa: An R Package for Multiple Sequence Alignment.

+\noindent U.~Bodenhofer, E.~Bonatesta, C.~Horej\v{s}-Kainrath, and S.~Hochreiter (2015).

+msa: an R package for multiple sequence alignment. {\em Bioinformatics} {\bf 31}(24):3997--3999.

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

 \end{quotation}

 To obtain a Bib\TeX\ entries of the reference, enter the

 following into your R session:

@@ -715,8 +716,15 @@ bibliography below).

 \section{Change Log}

 \begin{description}

-\item[Version 1.2.0:] \mbox{ }  \begin{itemize}

-    \item new branch for Bioconductor 3.2 release

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

+   \item further fixes in Makefiles and Makevars files to account for changes in build system

+   \item update of citation information

+  \end{itemize}

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

+   \item fixes in Makefiles and Makevars files to account for changes in build system

+  \end{itemize}

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

+    \item new branch for Bioconductor 3.3 devel

   \end{itemize}

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

     \item bug fix related to custom substitution matrices

@@ -209,7 +209,7 @@ The example in Section~\ref{sec:impatient} above simply called

 the function \verb+msa()+ without any additional arguments.

 We mentioned already that, in this case, ClustalW is called with default

 parameters. We can also explicitly request ClustalW or one of the two

-other algorithms ClustalOmega or Muscle:

+other algorithms ClustalOmega or MUSCLE:

 <<OtherAlgorithms,>>=