\section{Dessert: Alignments, Utils, and goodies}\label{goodies}

\setcounter{off}{596}

In this section, we present a motley composition of interesting classes of Jstacs.

\subsection{Alignments}

In this subsection, we present how to compute Alignments using Jstacs.

If we like to compute an alignment, we first have to define the costs for match, mismatch, and gaps. In Jstacs, we provide the interface \Costs~that declares all necessary method used during the alignment. In this example, we restrict to simple costs that are 0 for match, 1 for match, 0.5 for a gap.
 
\addtocounter{off}{3}
\code{0}

Second, we have to provide an instance of \Alignment. This instance contains all information needed for an alignment and stores for instance matrices used for dynamic programming. When creating an instance, we have to specify which kind of alignment we like to have. Jstacs supports local, global and semi-global alignments (cf. \AlignmentType).  

\addtocounter{off}{4}
\code{0}

In second constructor it is also possible to specify the number of off-diagonals to be used in the alignment leading to a potential speedup. 

Finally, we can compute the optimal alignment between two \Sequence s and write the result to the standard output.

\stepcounter{off}
\code{0}

The alignment instance can be reused for aligning further sequences.

In Jstacs, we also provide the possibility of computing optimal alignments with affine gap costs. For this reason, we implement the class \AffineCosts~that is used to specify the cost for a gap opening. The costs for gap elongation are given by the gap costs of the internally used instance of \Costs.

\stepcounter{off}
\code{3}


\subsection{REnvironment: Connection to R}

In this subsection, we show how to access R (cf. \url{http://www.r-project.org/}) from Jstacs. R is a project for statistical computing that allows for performing complex computations and creating nice plots.

In some cases, it is reasonable to use R from within Jstacs. To do so, we have to create a connection to R. We utilize the package \lstinline+Rserve+ (cf. \url{http://www.rforge.net/Rserve/}) of R that allows to communicate between Java and R. Having a running instance of \lstinline+Rserve+, we can create a connection via  

\addtocounter{off}{9}
\code{0}

However, in some cases we have to specify the login name, a password, and the port for the communication which is possible via alternative constructors.

Now, we are able to do diverse things in R. Here, we only present three methods, but \REnvironment~provides more functionality. First, we copy an array of \lstinline+double+s from Java to R 

\addtocounter{off}{4}
\code{0}

and second, we modify it 

\stepcounter{off}
\code{0}

Finally, the \REnvironment~allows to create plots as PDF, TeX, or \lstinline+BufferedImage+. 

\addtocounter{off}{3}
\code{0}

\subsection{ArrayHandler: Handling arrays}

In this subsection, we present a way to easily handle arrays in Java, i.e., to cast, clone, and create arrays with elements of generic type. To this end, we implement the class \ArrayHandler~in Jstacs. 

Let's assume we have a two dimensional array of either primitives of some Java class and we like to create a deep clone as it is necessary for member fields in clone methods.

\addtocounter{off}{2}
\code{0}

Traditionally, we would have to implement \lstinline+for+-loops to do so. However, the \ArrayHandler~implements this functionality in a generic manner providing one method for this purpose.

\addtocounter{off}{2}
\code{0}

A second use case, is the creation of arrays, where each and every entry is a clone of some instance.

\addtocounter{off}{3}
\code{1}

The third use case is to cast an array. Even if all elements of the array are from the same class, the component type of the array might be different (some super class). A simple cast will fail in those cases. However, the \ArrayHandler~provides two methods for casting arrays. Here, we present the more important method, which allows to specify the array component type and performs the cast operation.

\addtocounter{off}{4}
\code{4}

\subsection{ToolBox}

The class \ToolBox~contains several static methods for recurring tasks. 
For example, you can compute the maximum of an array of \lstinline+double+s
\addtocounter{off}{7}
\code{0}
or the sum of the values
\addtocounter{off}{3}
\code{0}
or you can obtain the index of the first maximum value in the provided array
\addtocounter{off}{3}
\code{0}

\subsection{Normalisation}

Another frequently needed functionality is the handling of log-values. Assume that we have an array \lstinline+values+ containing a number of log-probabilities $l_i$. What we want to compute is the logarithm of the sum of the original probabilities, i.e., $\log(\sum_i \exp(l_i))$. The naive computation of this sum often results in numerical problems, especially, if the original probabilities are very different.
A more exact solution is provided by the static method \lstinline+getLogSum+ of the class \Normalisation, which can be accessed by calling
\addtocounter{off}{3}
\code{0}
Of course, this method does not only work for probabilities, but for general log-values.

Sometimes, we also want to normalize the given probabilities. That means, given the log-probabilities $l_i$, we want to obtain normalized probabilities $p_i = \frac{\exp(l_i)}{\sum_j \exp(l_j)}$. This normalization is performed by calling
\addtocounter{off}{3}
\code{0}
and after the call, the array \lstinline+values+ contains the normalized probabilities (not log-probabilities!).

Finally, we might want to do the same for probabilities, i.e. given probabilities $q_i$ in an array \lstinline+values+, we want to compute $p_i = \frac{q_i}{\sum_j q_j}$ using
\addtocounter{off}{3}
\code{0}
A typical application for the last two methods are (log) joint probabilities that we want use to compute conditional probabilities by dividing by a marginal probability.

\subsection{Goodies}
The class \SafeOutputStream~is a simple way to switch between writing outputs of a program to standard out, to a file, or to completely suppress output. This class is basically a wrapper for other output streams that can handle \lstinline+null+ values. You can create a \SafeOutputStream~writing to standard out with
\addtocounter{off}{3}
\code{0}
If you provided \lstinline+null+ to the factory method instead, output would be suppressed, while no modifications in code using this \SafeOutputStream~ would be necessary.

Finally, the class \SubclassFinder~can be used to search for all subclasses of a given class in a specified package and its sub-packages. For example, if we want to find all concrete sub-classes of \TrainSM, i.e., classes that are not abstract and can be instantiated, in all sub-packages of \lstinline+de.jstacs+, we call
\addtocounter{off}{7}
\code{0}
and obtain a linked list containing all such classes. Other methods in \SubclassFinder~allow for searching for general sub-types including interfaces and abstract classes, or for filtering the results by further required interfaces.
