\chapter[\mineXp Usage] {\mineXp: \\A Powerful Mass Spectrum Viewer}
\label{chap:powerful-mass-spectrum-viewer}

Data mining, in mass spectrometry, entails, for a large part, the relentless
scrutinization of the mass spectra by an expert eye. Without a powerful mass
spectrum viewer, capable of numerous data display modes, the expert eye remains
powerless.

After having completed this chapter you will be able to perform mass spectrum
visualization and analysis, optionally reporting all the analysed peaks to a
file on disk.


\renewcommand{\sectitle}{Opening mass spectrum files}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

To start a \mineXp\ session, open one or more mass spectra using the menu\\
\guimenu{File}\guimenuitem{Open full mass spectrum file(s)}. \mineXp understands
the mzML format and the file loading procedures are delegated to the excellent
\progname{libpwiz} library from the \progname{ProteoWizard}
project\footnote{Please, see \url{http://proteowizard.sourceforge.net/}}. Simple
\fileformat{txt,asc} data where \emph{m/z} and \emph{i} values are separated by
any character that is neither a newline nor a dot nor a digit (loading is
handled by a private parser) can be loaded either from file or directly from the
clipboard. A third format is \fileformat{SQLite3}, a private open/documented
database format (private parser) that is used in \mineXp to allow slicing very
big datasets into smaller chunks. Incidentally, the \fileformat{SQLite3} format
allows for faster data loads.

There are two variants of the mass spectrometry file opening menu, one for
which \emph{all} the mass data are read from file and stored in memory and one
for which the mass data are read from file in streamed mode, used to compute
the TIC chromatogram and discarded. The latter mode is useful when the mass
data are so large that they cannot fit in memory. The TIC chromatogram that is
computed in streamed mode is then used to access the mass data in the file
according to criteria set by the user (retention time range, for example).


\renewcommand{\sectitle}{The Window Layout}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The graphical interface of \mineXp\ comprises a number of windows where data and
informations are displayed. These windows are described below (see
Figure~\vref{fig:minexpert-whole-window-set}):

\begin{itemize}

	\item \guilabel{mineXpert} main program window: this is an unintrusive
		window sporting the main menu and a status bar where messages are
		displayed;

	\item The \guilabel{Loaded mass spectrum files} window, that lists all the mass
		spectrometry data files that are currently loaded in the program;

	\item The \guilabel{TIC chromatogram} window\footnote{TIC stands for ``total
		ion current''.} where the various TIC chromatograms are displayed for the
		various mass spectrometry data files that have been loaded. There is, by
		definition, a single TIC chromatogram per data file currently loaded in
		the program. However, this window will also display TIC chromatograms that
		are computed as an integration step from the other windows, like from the
		\guilabel{Mass spectrum} window or from the \guilabel{Drift spectrum}
		window. In this case, the chromatogram is an extracted ion current
		chromatogram (XIC chromatogram);

	\item The \guilabel{Mass spectrum} window, where the various mass spectra are
		displayed. A given mass spectrum may originate from a TIC chromatogram or
		from a drift spectrum, or even from a color map. A given originating
		chromatogram or drift spectrum or color map may be the origin of more than one
		derived mass spectrum;

	\item The \guilabel{Drift spectrum} window, where the various drift spectra
		are displayed. Drift spectra can originate from the TIC chromatograms,
		from the mass spectra or from the color map;

	\item The \guilabel{Color map} window, that contains a single color map for
		each loaded mass data file. At the time of this writing, there is no way
		to produce a color map from any other window;

	\item The \guilabel{m/z integration parameters} window, where the parameters
		governing the mass data integrations to a mass spectrum are set;

	\item The \guilabel{XIC extraction parameters} window, where the parameters
		governing the XIC extractions to a XIC chromatogram are set;

	\item The \guilabel{Console} window, where the various messages or analysis
		data elements are displayed for the user to select, copy and paste in an
		electronic lab-book;

\end{itemize}


\begin{landscape}

	\begin{figure}[H]

		\centering

		\includegraphics[height=0.90\textheight]{figures/minexpert-whole-window-set.png}

		\renewcommand{\captionText}{General view of the graphical user interface}
		\caption[\captionText]{\textbf{\captionText}}

		\label{fig:minexpert-whole-window-set}

	\end{figure}

\end{landscape}


\renewcommand{\sectitle}{The Main Program Window Menu}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The menu bar in the main program window displays a number of menu
items, reviewed below:

\smallskip

\begin{itemize}

	%%%%%%% FILE
	\item \guimenu{File}

		\begin{itemize}

			\item \guimenu{File}\guimenuitem{Open full mass spectrum file(s)} Choose
				the mass spectrum file(s) to load. Note that the ``full'' descriptor
				indicates that the user wants to actually load the full data set in
				memory.  This means that she explicitely knows that the system's
				memory will cope will all the data in the file;

			\item \guimenu{File}\guimenuitem{Open streamed mass spectrum file(s)}
				Choose the mass spectrum file(s) to load. Note that the ``streamed''
				descriptor indicates that the user wants \emph{not} to actually load
				the full data set in memory. This is typically the case when the data
				file is so large that its data cannot fit in memory. The program then
				only ``looks'' at the data in the file and crafts, piecemeal, the TIC
				chromatogram and the color map. In this context, any other data
				integration will be performed by looking into the same mass data file
				since no data are available in memory;

			\item \guimenu{File}\guimenuitem{Mass spectrum from clipboard} creates a
				mass spectrum from a textual representation of \mzi pairs in the same
				format as described above for the \fileformat{txt,asc} file format;

			\item \guimenu{File}\guimenuitem{Analysis preferences} Define the
				analysis preferences. The analysis preferences govern how the data
				about scrutinized mass peaks are recorded to the console, to the
				clipboard, to a selected file, or any combination of the three.

		\end{itemize}

	%%%%%%% PLOT
	\item \guimenu{Plot}

		\begin{itemize}

			\item \guimenu{Plot}\guimenuitem{Clear plots} Clears all the plots
				currently displayed in the program. The plot items in the
				\guilabel{Loaded mass spectrum files} window are all removed. Note
				that this releases all the memory that was used by the data. This menu
				is equivalent to ``closing all files'';

		\end{itemize}

	%%%%%%% WINDOWS
		\begin{itemize}

			\item \guimenu{Windows}

				The menus are self-explanatory, as they explicitely explain which window
				is to be shown. The \guimenu{Save workspace} menu records on disk the
				position and size of all the windows, so that upon reopening the program,
				the windows all position themselves at the recorded position and size;

		\end{itemize}

		%%%%%%% HELP
		\begin{itemize}

			\item \guimenu{Help}

				This menu's items show help about the program itself and also about the Qt
				libraries that were used to build it. These informations are essential in
				case the user wants to make a bug report.

		\end{itemize}

\end{itemize}


\renewcommand{\sectitle}{The main data windows}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

This section will succinctly describe the main data windows of \mineXp. Each
window will be described in greater detail when the features of the program will
be described.

\renewcommand{\sectitle}{The TIC chromatogram window}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

\begin{figure}[H]

	\begin{center}
		\includegraphics[width=0.85\textwidth]{figures/minexpert-tic-chrom-wnd-two-traces.png}

	\end{center}

	\renewcommand{\captionText}{The TIC chromatogram window}
	\caption[\captionText]{\textbf{\captionText} This TIC chromatogram window
shows multiple chromatograms. Each plot has its own set of markers.}
\label{fig:minexpert-tic-chrom-wnd-two-traces}

\end{figure}

Each time a new mass spectrum file is loaded, its corresponding TIC
chromatogram is computed and then displayed in a new plot widget in the TIC
chromatrogram window (Figure~\vref{fig:minexpert-tic-chrom-wnd-two-traces}).
Each new TIC chromatogram plot generated as a result of the loading of a mass
spectrometry data file is plotted using a new color. That color encodes the
filiation of the whole set of plots that are generated starting from that
initial TIC chromatogram plot. For example, a red TIC chromatogram plot that
serves as the starting point for a mass spectrum integration will trigger the
creation of a mass spectrum plot widget that will have a red graph in it. Same
is true for the color map widget that has its axis and tick labels of the same
color as that of the TIC chromatogram plot.


\alertbox{The attention of the reader is drawn on the specific situation
	corresponding to the loading of mass spectrometric data from a non-profile
	acquisition data file.  For example, when a mass spectrum is opened from a
	\fileformat{txt,asc,xy} text-based format file where the data correspond to a
	\emph{single} spectrum, not a sequence of spectra.  In this case, the TIC
	chromatogram really has a single (rt,i) pair denoting the TIC intensity a the
	single retention time of that very unique spectrum. The TIC chromatogram
	window thus artificially created and displayed like shown in
	Figure~\vref{fig:minexpert-tic-chrom-wnd-when-no-profile-acquisition}. See the
caption of that figure for the explanation.}

\begin{figure}[H]

	\begin{center}

		\includegraphics{figures/minexpert-tic-chrom-wnd-when-no-profile-acquisition.png}

	\end{center}

	\renewcommand{\captionText}{The TIC chromatogram window}

	\caption[\captionText]{\textbf{\captionText} This TIC chromatogram window
	shows the peculiar situation of non-profile acquisitions, for which there is
	no real TIC chromatogram. The graph is thus artificially created. To perform
	an integration to a mass spectrum, unzoom the graph and enclose it fully in
	the integration range as shown for the integration process going on in the
	middle graph (the two extreme points of the graph need to be enclosed in the
selection).}

\label{fig:minexpert-tic-chrom-wnd-when-no-profile-acquisition}

\end{figure}


\renewcommand{\sectitle}{The mass spectrum window}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

The mass spectrum window contains all the plot widgets that display mass spectra
that originated in other windows. For example, the user might select a region in
a TIC chromatogram and then ask that a mass spectrum integration be computed. In
this case, the resulting mass spectrum is displayed in a new plot widget that is
located in the mass spectrum window
(Figure~\vref{fig:minexpert-mass-spec-wnd-two-traces}).

\begin{figure}[H]

	\begin{center}

		\includegraphics{figures/minexpert-mass-spec-wnd-two-traces.png}

	\end{center}

	\renewcommand{\captionText}{The mass spectrum window}
	\caption[\captionText]{\textbf{\captionText} This mass spectrum window
shows multiple mass spectra.} \label{fig:minexpert-mass-spec-wnd-two-traces}

	\end{figure}


	\renewcommand{\sectitle}{The drift spectrum window}
	\subsection*{\textcolor{sectioningcolor}{\sectitle}}
	\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

	As described for the mass spectrum window, the drift spectrum window contains
	all the plot widgets that display drift spectra
	(Figure~\vref{fig:minexpert-drift-spec-wnd-two-traces}).

	\begin{figure}[H]

		\begin{center}

			\includegraphics{figures/minexpert-drift-spec-wnd-two-traces.png}

		\end{center}

		\renewcommand{\captionText}{The drift spectrum window}
		\caption[\captionText]{\textbf{\captionText} This drift spectrum window
	shows multiple mass spectra.}
	\label{fig:minexpert-drift-spec-wnd-two-traces}

\end{figure}


\renewcommand{\sectitle}{The color map window}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

\begin{figure}[H]

	\begin{center}

		\includegraphics{figures/minexpert-color-map-wnd.png}

	\end{center}

	\renewcommand{\captionText}{The color map window}
	\caption[\captionText]{\textbf{\captionText} The color map window relates
mass spectra to drift times.} \label{fig:minexpert-color-map-wnd}

\end{figure}

The color map window displays a color map view of the drift data in the form of
\mz{} \textit{vs} drift time (dt). The intensity of the \mz{} values is coded in
colour. The axes can be switched, such that either the \mz{}~\textit{vs}~dt or
the dt~\textit{vs}~\mz{} representation can be obtained (see toolbar button on
Figure~\vref{fig:minexpert-color-map-wnd}).


\renewcommand{\sectitle}{General structure of the windows containing plot widgets}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The TIC chromatogram, mass spectrum and drift spectrum windows are all
structured in a similar way. The window is divided vertically  in two
compartments. The bottom compartment will host all the plot widgets stacked
vertically. The top compartment hosts a single plot widget where all the
graphs that are displayed unitarily in the lower compartment are  shown
superimposed.

\alertbox{The plot widget that is packed in the top compartment of the window is
	called the \emph{``multi-graph''} plot widget because it can hold more than
	one graph. The plot widget(s) that is(are) packed in the bottom compartment of
	the windows is(are) called \emph{``single-graph''} plot widget(s) because each
plot contains only one graph.}

The two vertical compartments of the window are resizable by dragging the
sliding horizontal bar that separates them. It is possible to totally occlude
one of the compartments by dragging that sliding bar all the way up (or down) to
the window side.

The behaviour described above does not apply to the Color map window that has
no upper compartment with all the color maps superimposed.


\renewcommand{\sectitle}{General working of the widgets displaying data}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The TIC chromatogram, color map, mass spectrum and drift spectrum windows all
contain plot widgets (or color map widgets) that have a general working scheme
as to how the data can be visualized.  The main visualization operations are
succintly described below. The following convention will be used to describe the
mouse buttons : \lmb: left mouse button, \mmb: middle mouse button and \rmb:
right mouse button.

\begin{itemize}

	\item Zooming~in and zooming~out:

		\begin{itemize}

			\item Zoom~in: \lmb-click-drag to draw a selection rectangle. When
				the mouse button is released, the new plot view contains the data
				contained in the selection rectangle;

			\item Zoom~in: \rmb-click-drag along the X-axis over the region to zoom
				and release the mouse button. The new zoomed view does not automatically
				scale to full scale in the Y-axis direction. To ensure that the new view
				automatically scales on the Y-axis, press \kbdKey{Shift} while releasing
				the mouse button. When the zoom~in operation is performed using
				\kbdKey{Shift} in the multi-graph widget, the Y-axis is set to full
				scale with respect to the point having the maximum intensity of all the
				graphs being shown at that moment;

				\begin{figure}[H]

					\begin{center}

						\includegraphics[width=0.75\textwidth]{figures/minexpert-tic-chrom-wnd-ongoing-zoom.png}
						\label{fig:minexpert-tic-chrom-wnd-ongoing-zoom}

					\end{center}

				\end{figure}

				As seen in the figure above, the region defined by the \lmb-click-dragging
				operation is delimited by green and red markers, respectively at the start
				and at the end of the selection. The distance between the start and end
				points is updated along the mouse move operation. 

			\item Zoom~in/out: \rmb-click-drag on the X- or Y-axis to interactively
				zoom in or out along the selected axis. In this mode, the zoom
				operates by contracting/expanding the data in such a manner that the
				left/bottom part of the graph (the origin of the graph) is anchored
				and does not move. When the drag occurs towards larger values on the
				clicked axis, the view is zoomed in along that axis. Conversely, it is
				possible to zoom out by dragging the mouse towards lower axis values.
				When the number of points in the plot is so large that the zoom
				operation is sluggish, pressing \kbdKey{Ctrl} will fluidify the zoom
				operation;

			\item Zoom~in/out: The \mmb-wheel-rotation can be used to zoom in or out
				the whole plot on both the X- and Y-axis simultaneously. Note that the
				position of the mouse cursor when the wheel is rolled defines the new
				view of the plot. Practising a bit allows to make that zooming in/out
				mode very powerful.

			\item Zoom~out: To reset the zoom along one axis, \lmb-double-click that
				axis.  In this case, only the clicked axis will be full-scale, the
				other axis remains unchanged. To reset the zoom such that the full
				scale is calculated on the data set displayed after the zoom, maintain
				the \kbdKey{Shift} key pressed when double-clicking. To reset the zoom
				on both axes in one go, \lmb-double-click one of the axes maintaining
				the \kbdKey{Ctrl} key pressed;

		\end{itemize}

	\item{Panning:}

		\begin{itemize}

			\item \lmb-click-drag on one of the axes to pan the plot view along that
				axis;

		\end{itemize}

	\item{History:}

		\begin{itemize}

			\item Each time a new zoomed in/out view of the plot is triggered, a history
				element is stored in the plot widget. To back-replay the various steps
				of the zoom in/out operations in sequence, from pre-last to first, hit the
				\kbdKey{Backspace} key. The exceptions to this mechanics is when the
				plot view is panned or when the mouse wheel is used.

		\end{itemize}

\end{itemize}

\alertbox{The tool bar located at the top of the windows described above
	contains two button that allow to lock the x~axis (the button icon has the
	horizontal red line) and/or the y~axis (red line is vertical) range throughout
	all the graphs displayed in the window. This of great use when the user wants
	to compare a number of graphs that have been obtained on comparable samples.
	The movements and zooming-in or zooming-out operations in one graph are then
	synchronized to all the other graphs.\\ The third button performs a transpose
	operation. When the color map is initially created, the horizontal axis (the
	keys of the map) is the drift time axis and the vertical axis (the values of
	the map) is the m/z axis. The transpose operation switches the representation
of the map such that the axes are inverted.}


\renewcommand{\sectitle}{Data integrations featured\\ by \mineXp}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

Analyzing mass spectrometric data (with or without drift data) usually involves
performing various data integrations in sequence. We saw earlier that the first
data that are plotted upon loading a mass spectrometry data file are the TIC
chromatograms along with (if applicable) the \mz{$\!\!$}\,\textit{vs}\,dt color
maps. These two graphed data sets are the starting points for the mass
spectrometric data mining, that may involve the following integration
operations:

\begin{itemize}

	\item \textbf{TIC chromatogram to mass spectrum} This kind of operation is
		triggered upon \rmb-click-dragging the mouse over the region of
		interest and maintaining the \kbdKey{s} key pressed. \mineXp integrates all
		the spectra that have been acquired at all the retention times between the
		start and the end of the selected region. A new mass spectrum is then
		plotted in a new plot widget in the mass spectrum window;

		\begin{figure}[H]

			\begin{center}

				\includegraphics[width=0.75\textwidth]{figures/minexpert-tic-chrom-wnd-ongoing-integration.png}
				\label{fig:minexpert-tic-chrom-wnd-ongoing-integration}

			\end{center}

		\end{figure}

		As seen on the figure above, the region defined by the \rmb-click-dragging
		operation is delimited by arrows, a green marker at the start and a red
		marker at the end.

	\item \textbf{TIC chromatogram to drift spectrum} This kind of operation is
		similar to the one described above, unless the \kbdKey{d} key must be
		pressed. As above, a new drift spectrum is appended to the drift spectrum
		window.

	\item \textbf{Color map to mass spectrum} This operation involves
		\rmb-selecting a rectangular region of interest on the color map and by
		maintaining the \kbdKey{s} key pressed. A new mass spectrum is then
		plotted in a new plot widget in the mass spectrum window. Note that, due to
		a bug in the plotting library, the rectangle is not currently drawn on top
		of the color map.

	\item \textbf{Color map to drift spectrum} Same as above, but with the
		\kbdKey{s} key pressed. As above, a new drift spectrum is appended to the
		drift spectrum window. Same remark as above.

	\item The same mechanics is at work in the other plot widget windows. For
		example, to trigger the integration of a mass spectrum starting from a drift
		spectrum, simply drag the mouse over the drift spectrum and maintain the
		\kbdKey{s} key pressed. Rule of thumb: when a mass spectrum is to be
		generated, use the \kbdKey{s} key, when a drift spectrum is to be generated,
		use the \kbdKey{d} key and, finally, when a TIC chromatogram is to be
		generated, use the \kbdKey{t} key.

	\item One of the most interesting features for detailed mass data mining is
		the integration to a TIC intensity. That integration can be triggered from
		any of the data window (any plot widget in any of these windows, that is).
		Not plot is created, the data are simply displayed in the status bar of the
		window.  This integration will be discussed later.

\end{itemize}


\begin{figure}[H]

	\begin{center}

		\includegraphics{figures/minexpert-colormap-wnd-shows-full-tool-bar-and-tooltips.png}

	\end{center}

	\renewcommand{\captionText}{The tool bar and its buttons}
	\caption[\captionText]{\textbf{\captionText}	The `?' button shows a tool~tip
	helping the user to select the proper keyboard/mouse combination to perform a
given integration task.}
\label{fig:minexpert-colormap-wnd-shows-full-tool-bar-and-tooltips}

\end{figure}

Figure~\vref{fig:minexpert-colormap-wnd-shows-full-tool-bar-and-tooltips} shows the various
buttons of the characteristic plot window. The button with the `?' character
will show a tool~tip describing the various keyboard/mouse combinations to use
to trigger the various data combinations described above.

The ``filiation'' of the plots is maintained using identifying colors.  However,
color is not enough to unambiguously identify the ``filiation'' of any given
plot. Indeed, the same TIC chromatogram or Color map plot can be used multiple
times to perform integrations. The newly created plots will have the same color
as the originating plot, but it will not be possible to distinguish between all
the ``child'' plots. This is why the plots maintain a ``history'' of the way
they have derived from the initial TIC chromatogram/Color map plot. This
history is shown in a small widget that shows up when the \kbdKey{O} key is
pressed while the mouse cursor hovers over the widget at hand. One example of
plot ``history'' is shown in Figure~\vref{fig:minexpert-plot-filiation-history-widget}.

\begin{figure}[H]

	\begin{center}

		\includegraphics{figures/minexpert-plot-filiation-history-widget.png}

	\end{center}

	\renewcommand{\captionText}{The plot filiation history widget}
	\caption[\captionText]{\textbf{\captionText} Each plot has a filiation
	hist\underline{o}ry that can be displayed by keying \kbdKey{o}.}
	\label{fig:minexpert-plot-filiation-history-widget}

\end{figure}


This figure shows the filiation history of plots. By necessity, the first
history item, because the first integration started from the dt~= f(\mz{}) color
map is the [File$\rightarrow$MZ][File$\rightarrow$DT] item that indicates that
the graph originates from loading a file and computing the color map.

Below, the drift time was computed by integrating from the color map according
to both indications: [MZ$\rightarrow$DT] and [DT$\rightarrow$DT]. The concerned
ranges are displayed.

The, the drift spectrum is used as a starting point for an integration to a mass
spectrum according to the history item: [DT$\rightarrow$MZ], and the range
indicated that the user dragged the integration range from 8.2 to 11.3~ms
(rounded values).

Finally, the user performed an integration from the drift spectrum to a XIC
chromatogram, as evidenced by the last history item [MZ->RT] with the
\mz{2204.117}$\rightarrow$\mz{2207.49} range.

As can be seen in the various filiation history items of
Figure~\vref{fig:minexpert-plot-filiation-history-widget}, there is always a
\guilabel{History - innermost ranges} section that lists the three ranges for
RT, MZ and DT. What is that ``innermost range'' concept? The idea is that, at
any given time, the user might desire to know what it the smallest range that a
given plot is originating from.  For example, imagine:

\begin{enumerate}

	\item \label{item:RTtoMz}  an [RT$\rightarrow$MZ] integration starting from a
		TIC chromatogram;

	\item \label{item:MZtoDT} the m/z~range obtained is [500-2500]. From that
		mass spectrum, the user integrates to a drift spectrum [MZ$\rightarrow$DT];

	\item \label{item:DTtoMZ} then, from the drift spectrum, a peak seems
		interesting and the user back-integrates to a mass spectrum
		[DT$\rightarrow$MZ];

	\item \label{item:MZtoRT} in the mass spectrum, a mass peak is of interest and
		the user want to see at which retention times the m/z~value elutes: she
		does an integration [MZ$\rightarrow$RT].

\end{enumerate}

The innermost m/z~range in the XIC chromatogram obtained will be the last range
selected, at step \ref{item:MZtoRT}, not the range at step \ref{item:MZtoDT}.


\renewcommand{\sectitle}{Detailed description of the \\integration calculations}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

Depending on the integration that is triggered in the various data plot/map
widgets, the computations vary significantly. This section will describe the
general computation algorithms in such a manner that the \mineXp user can
grasp what is actually going on in the guts of the software.

\renewcommand{\sectitle}{Integrations to a mass spectrum}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

This integration occurs when the user \rmb-selects a range in a given plot while
pressing the \kbdKey{S} key. Integrations to a mass spectrum can be elicited
from a TIC chromatogram plot, a color map plot or a drift spectrum plot. In all
these cases, the integration computation (that is, a mass spectral combination)
needs to be aware of the kind of data at hand.

In order to clarify what integration means in the context of the creation of a
mass spectrum, that is the summative integration (also known as ``combination'')
of any number of mass spectra, the following describes a combination in detail.

In this example, the user has loaded a mass data file obtained after an
acquistion of mass data in profile mode. \mineXp\ calculates the TIC
chromatogram right after having loaded the mass data. The user performs an
integration for a given retention time range in the TIC chromatogram.  If we
consider an integration range [0--15]~min, this is what would occur in the guts
of \mineXp. In this example, we omit any step corresponding to any binning.

\begin{itemize}

	\item First of all, create a new mass spectrum (let's call it newMs, also
		known as the ``combination spectrum'', that is, the result spectrum);

	\item Extract from the mass spectrometry data all the spectra that have
		their internal rt value (retention time) contained in the [0--15]~min
		interval.  The list of extracted mass spectra (let's call that list msL)
		is then processed as follows:

	\item Iterate in msL and for each iterated mass spectrum (ms):

		\begin{itemize}

			\item Iterate in all the \mzi pairs of ms and for each one check if the
				m/z~value was already found in any of the previous mass spectra, that
				is, if a \mzi pair in newMs has that m/z~value. If:

				\begin{itemize}

					\item the \mz{} was not found, copy the \mzi pair in newMs;

					\item else if the m/z~value was already encountered in previously
						iterated mass spectra, increment the intensity of the
						corresponding \mzi pair of newMs by the value of the iterated
						\mzi pair.  This is where the summative combination of mass
						spectra is at work.

				\end{itemize}

		\end{itemize}

\end{itemize}

At the end of this process, newMs will correspond to the summation of all the
spectra contained in the msL list. The newMs mass spectrum is then plotted in
the mass spectrum window as a new plot. The color of the newMs plot is the same
as the color of the initial TIC chromatogram plot.

The process described above can only work in very limited circumstances, with
data files generated with particular instruments. In general, this process does
not lead to a usable mass spectrum, as described in
Figure~\ref{fig:minexpert-unusable-mass-spectrum-combination-lumos-orbitrap}. In
this combination mass spectrum computed from Lumos Orbitrap-originating data,
the plot shows what should have been a high resolution monoisotopic peak (the
m/z delta of the whole signal is 0.009). As can be seen, the signal in this mass
spectrum is totally useless and the integration to a mass spectrum requires
binning to overcome the presence of so many peaks in that 0.009 m/z interval.

\mineXp\ provides a number of ways to configure mass spectral combinations such
that the obtained mass spectrum is usable. The m/z integration parameters that
might be set are described in the following sections.


\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.66\textwidth]{figures/minexpert-unusable-mass-spectrum-combination-lumos-orbitrap.png}

	\end{center}

	\renewcommand{\captionText}{Unusable combination spectrum without binning}
	\caption[\captionText]{\textbf{\captionText} The mass data used to compute
	this combination spectrum originate from a Lumos Orbitrap analyzer. The
	visible signal should have been a single high-resolution monoisotopic peak.
The width of signal is 0.009.}
\label{fig:minexpert-unusable-mass-spectrum-combination-lumos-orbitrap}

\end{figure}


\renewcommand{\sectitle}{Considerations on the diversity of mass data contents}
\subsubsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsubsection}{\numberline{}\sectitle}

Loading data from mass data files in \fileformat{mzML} format does not guarantee
that the data will be of the same kind if they come from different mass
spectrometers. For example, data from Orbitrap mass spectrometers have the
following characteristics:

\begin{itemize}

	\item all spectra do not start at the same m/z~value;

	\item all spectra do not have the same number of data points (they do not
		have the same size);

	\item a large number of data points might have 0 values (intensity at a
		given m/z~value is 0);

	\item the m/z~delta between two consecutive m/z~values is not constant,
		and this is the major difficulty for data integration to a mass
		spectrum.

\end{itemize}

This is the output of the statistical analysis of the data loaded from a Lumos
Orbitrap-originating file:

\begin{verbatim}

Spectral data set statistics:
Total number of spectra: 6203
Average of spectrum size: 391.311946
StdDev of spectrum size: 168.062934
Mininum m/z value: 400.007111
Average of first m/z value: 401.448935
StdDev of first m/z value: 1.590049
Maximum m/z value: 1999.928589
Average of last m/z value: 1901.852315
StdDev of last m/z value: 45.864131
Minimum m/z shift: -0.344452
Maximum m/z shift: 0.000000
Average of m/z shift: 1.097372
StdDev of m/z shift: 1.590049
Smallest Delta of m/z (step): 0.006195
Average of smallest Delta of m/z (step): 0.023757
StdDev of smallest Delta of m/z (step): 0.013179
Greatest Delta of m/z (step): 405.356934
Average of greatest Delta of m/z (step): 163.112057
StdDev of greatest Delta of m/z (step): 75.947334
\end{verbatim}

As mentioned earlier, the most interesting bit of information is in the line
reproduced below:

\texttt{Smallest Delta of m/z (step): 0.006195}

That 0.0062 value somehow gives an indication of the ``definition'' of the
spectrum, that is, the smallest distance possible between two consecutive
m/z~values. We derive from this observation that the spectral combination may
require setting up bins of a size at most of \mz{0.0062}.

In general, the fact that the spectra of an acquisition do not all have the same
m/z vector as the m/z axis is a great difficulty for mass spectral integration
because it requires setting up binning prior to performing the mass spectral
combination. That binning is nothing else than crafting a m/z value vector able
to receive the intensities of all the m/z data points in the spectra to be
combined.  These concepts are developed in the following paragraphs.


\renewcommand{\sectitle}{Statistical analysis of mass data}
\subsubsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsubsection}{\numberline{}\sectitle}

At the end of the data file loading, \mineXp\ performs a rudimentary statistical
analysis of the data. The main datum of interest is the smallest m/z~step that
is observed in the whole set of mass data loaded from disk (the mass spectrum
list, that can hold mass spectra in the thousands). For each mass spectrum in
the list, the smallest m/z~delta between any two consecutive data points is
recorded. Then, the smallest ever m/z~delta value is sought amidst all the
recorded values. Intuitively, that smallest m/z delta value provides an idea of
the resolution power of the instrument that generated the mass spectra. It is
the value that is suggested by default to arbitrarily construct the bins during
an integration to a mass spectrum, as described in
Figure~\ref{fig:minexpert-mz-integration-parameters-wnd-binning-savgol}.  In
this example, the smallest m/z~delta encountered in all the spectra loaded from
file is used to fill-in the \guilabel{Arbitrary binning} numerical value with
bin size unit \guivalue{MZ}.

\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.66\textwidth]{figures/minexpert-mz-integration-parameters-wnd-binning-savgol.png}

	\end{center}

	\renewcommand{\captionText}{The m/z~integration parameters window}
	\caption[\captionText]{\textbf{\captionText} Any integration to a mass
	spectrum can be configured to ensure the best result depending on the kind of
	mass data (typically, data from different vendors behave in distinct ways upon
integration).}
\label{fig:minexpert-mz-integration-parameters-wnd-binning-savgol}

\end{figure}


The bin size units, when using \guilabel{Arbitrary binning}, might be
\guivalue{MZ}, \guivalue{PPM} or \guivalue{RES}. In the two latter cases, the
bin size changes along the m/z axis. It increases along with increasing m/z
values. For example, if the bin size unit is \guivalue{PPM} and the size unit is
\guivalue{10}, then at \mz{300}, the bin size  would be \mz{0.003}, while at
\mz{2000}, the bin size would be \mz{0.02}. If the bin size unit is
\guivalue{RES} and the bin size is \guivalue{10000}, then at \mz{300}, the bin
size would be \mz{0.003}, while at \mz{2000}, the bin size would be \mz{0.02}.

Once the \guilabel{Arbitrary binning} is selected in the m/z integration
parameters window, the bin size and bins size unit have been set, the program
creates the bins in the combination mass spectrum according to these settings.
The first bin  and the last bin are simply the smallest and greatest m/z values
found in all the spectra to be combined. The program fills in the void in
between these two values in steps matching the bin size with or without PPM/RES
ponderation: In case the bin size unit is \guivalue{MZ}, there is no specific
calculation; if the bin size unit is either \guivalue{PPM} or \guivalue{RES},
then the bins are calculated accordingly, as shown in the examples above.  Once
the bins have been set up in the combination spectrum, the actual combination of
all the mass spectra can take place.


\renewcommand{\sectitle}{Effects of the m/z integration parameters}
\subsubsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsubsection}{\numberline{}\sectitle}


This section provides some examples of how the integration parameters might
impact the mass spectrum resulting from combination of mass spectra. Also, this
section details the general guidelines for ensuring the best combination
calculation.

\paragraph{When \guivalue{Data-based binning} is recommended} Data-based binning
means that the bins in the combination spectrum are nothing but the m/z values
of the first spectrum of the mass spectral set to be combined. This is the
simplest integration mechanism and is recommended when the mass data are
perfectly coherent, that is, when all the mass spectra are rooted in the
(roughly) same m/z~value and the vector of m/z values along the m/z axis is
reproduced over all the mass spectra of the combination set. This situation is
exemplified in
Figure~\vref{fig:minexpert-bruker-microqtof-mz-integration-examples}.

\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.85\textwidth]{figures/minexpert-bruker-microqtof-mz-integration-examples.png}

	\end{center}

	\renewcommand{\captionText}{Bruker microQTof acquisition of a protein mass
	data} \caption[\captionText]{\textbf{\captionText} In this example, the
	various m/z integration settings produce acceptable results for the
	combination mass spectrum. Note that the best results are for
	\guivalue{Data-based binning} and that in the case of \guivalue{Arbitrary
	binning}, applying the m/z shift is beneficial.}
	\label{fig:minexpert-bruker-microqtof-mz-integration-examples}

\end{figure}


These combination spectra were obtained by performing a mass spectral
integration of mass data acquired for a protein solution in a microQTof Bruker
instrument. The mass acquisition settings were characteristic of a protein
analysis in the 25--35~kDa range. The third spectrum from bottom was obtained by
performing an integration with data-based binning, without applying any m/z
shift and without removing m/z data points that have a 0-intensity value. The
spectrum is perfect.  The statistical analysis of the mass data calculated after
loading of the mass data had shown that the smallest m/z~delta value was of
0.017. The second spectrum from bottom was obtained after an integration with an
arbitrary binning of size \guivalue{0.017} and with bin size unit \guivalue{MZ}
(constant bin size throughout the m/z vector).  In this case m/z shift was
applied so as to realign slightly m/z~axis-misaligned spectra. The result is
pretty similar to the one obtained earlier.There is a slight noise appearing on
the lowest intensity peaks, denoting that the spectra, although pretty well
m/z~axis-aligned were not \emph{perfectly} aligned. To check for that
hypothesis, the same integration was performed but without performing the
spectrum alignment (not m/z shift is applied in this case). The obtained
spectrum is indeed more noisy, and the noise also appears on the highest
intensity peaks. This unequivocably demonstrates that the spectra acquired by
the instrument were not \emph{precisely} aligned.


\paragraph{When removing 0-intensity m/z data points is useful} The setting up
of bins ultimately consists in creating a mass spectrum out of preexisting data
(the first mass spectrum of the set in the case of \guilabel{Data-based
binning}) or out of arbitrary values (the smallest and greatest m/z values of
the spectral set, the bin size and finally the bin size unit). In the latter
case, the data points making the newly created mass spectrum have their m/z
value calculated and their intensity set to 0. Because the m/z value is
calculated starting from an arbitrary bin size value, it might be possible that
not a single data point in the whole set of mass spectra has a m/z value
matching that bin m/z value. In that case, the m/z data point still has a
0-intensity value at the end of the mass spectral combination. This is
illustrated in
Figure~\vref{fig:minexpert-mz-integration-parameters-wnd-effect-remove-zero-val-datapoints}.
When the 0-intensity data points are not removed (upper spectrum), the signal is
deteriorated by these inverted spikes. Removal of the 0-intensity data points,
cleans the trace perfectly.

\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.45\textwidth]{figures/minexpert-mz-integration-parameters-wnd-effect-remove-zero-val-datapoints.png}

	\end{center}

	\renewcommand{\captionText}{Removing 0-intensity data points}
	\caption[\captionText]{\textbf{\captionText} When arbitrary binning is
	performed, residual 0-intensity data points might survive in the combination
	spectrum, which deteriorates the resulting mass spectrum. Removing these data
points from the combined mass spectrum cleans the trace.}
\label{fig:minexpert-mz-integration-parameters-wnd-effect-remove-zero-val-datapoints}

\end{figure}


\paragraph{Savitzky-Golay filtering of the data might be useful} The
Savitzky-Golay filtering method is widely known for its effectiveness in
removing noise from mass spectral data. It is possible to apply that filter at the
end of a mass spectral combination. The m/z integration parameters window allows
setting the Savitzky-Golay parameters:

\begin{itemize}

	\item \guilabel{nL}: specifies the number of data points to the left of the
		point being filtered;

	\item \guilabel{nR}: specifies the number of data points to the right of the
		point being filtered;

		\begin{center} The total number of points in the window that is considered for
			the regresssion is thus nL + nR + 1\end{center}

	\item \guilabel{m}: specifies the order of the polynomial to use in the
		regression analysis leading to the Savitzky-Golay coefficients (typically
		between 2 and 6);

	\item \guilabel{lD}: specifies the order of the derivative to extract from the
		Savitzky-Golay smoothing algorithm (for regular smoothing, use 0);

\end{itemize}



\renewcommand{\sectitle}{Integrations to a drift spectrum}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

This integration occurs when the user \rmb-selects a range in a given
plot while pressing the \kbdKey{D} key. The integration occurs for
a given retention time range in the TIC chromatogram.  If we consider an
integration range [0--15]~min, this is what would occur in the guts of \mineXp:

\begin{itemize}

	\item First of all, create a <dt,tic> map to store all the drift time values
		encountered below, along with the cumulated total ion current intensity
		value of the spectra acquired at the corresponding dt drift time.

	\item Extract from the mass spectrometry data all the spectra that have
		their internal rt value (retention time) contained in the [0--15]~min
		interval.  The list of extracted mass spectra (msL) is then processed as
		follows:

	\item Iterate in msL and for each iterated mass spectrum (ms):

		\begin{itemize}

			\item Get the dt at which ms was acquired;

			\item Calculate the total ion current (tic) for ms;

			\item In the <dt,tic> map, check if the dt value was already found. If:

				\begin{itemize}

					\item the dt was not already found, create one (dt,tic) pair and
						insert it in the map;

					\item else if the dt was already encountered in previously iterated mass
						spectra, increment the tic value of the
						corresponding (dt,tic) pair in the map by the tic value calculated
						above for ms.

				\end{itemize}

		\end{itemize}

\end{itemize}

At the end of this process, the <dt,tic> map will correspond to the drift
spectrum. That spectrum is then plotted in the drift spectrum window as a new
plot with the same color as that of the initial TIC chromatogram plot.


\renewcommand{\sectitle}{Integrations to a TIC intensity value}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

This integration occurs when the user \rmb-selects a range in the TIC chromatogram
plot while pressing the \kbdKey{I} key. The integration is performed by looking
into the mass data for \mzi{} pairs that match the current integration history
of the current data plot and sums all the intensities to yield a final TIC
intensity value. This value is printed in the status bar of the window. Be aware
that if you move the cursor right after having performed the computation, the
message in the status bar of the window will be erased. In this case, that same
value is printed in the console window in the same color as the color of the
plot from which it was computed.

\alertbox{Worthy of note is the fact that this kind of integration can be
	performed in the exact same way in the various data plots (TIC chromatogram,
mass spectrum, drift spectrum, mz=f(dt) color~map).}




\renewcommand{\sectitle}{Integrations to a XIC chromatogram}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

When a given ion of interest is researched in a mass spectral data set, usually
the user asks the following question: \textsl{``When is the ion at m/z xxx.yyy
eluting from the chromatography column''?} To extract the total ion current for
a given m/z value as a function of the retention time, the XIC extraction
parameters window can be filled-in as shown in
Figure~\vref{fig:minexpert-xic-extraction-parameters-wnd}. In this process, the
whole data set is searched for the requested ion.

\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.45\textwidth]{figures/minexpert-xic-extraction-parameters-wnd.png}

	\end{center}

	\renewcommand{\captionText}{Extraction of an ion current}
	\caption[\captionText]{\textbf{\captionText} It is possible to extract from a
	mass spectra data set the total ion current for that m/z value. The result is a
TIC chromatogram for that m/z value: a XIC chromatogram.}
\label{fig:minexpert-xic-extraction-parameters-wnd}

\end{figure}

The extracted ion current chromatogram is displayed in the TIC chromatogram
window.


\renewcommand{\sectitle}{Chained Integrations}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

The user, in the process of mining the data, will inevitably chain
integrations to pinpoint a specific feature of interest. For example, let's
say that the user performs the following chained integrations (see
Figure~\vref{fig:minexpert-chained-integrations}):

\begin{enumerate}

	\item From a TIC chromatogram that spans [0--1] min, integrate to a mass
		spectrum the [0.3--0.6] range;

	\item From the mass spectrum, that spans a m/z~range of [500--5000],
		integrate to a drift spectrum the [2202.4--2204.4] range;

	\item From the drift spectrum that spans [0--22]~ms, where two unresolved
		peaks are visible, integrate back to a mass spectrum the drift region
		spanning [10.29--12]~ms and then the drift region spanning [12--14]~ms.

\end{enumerate}

What happens during all these integrations? In the first integration, the
whole m/z~range of the mass spectrometric data is considered and the data
filtering is only based on the retention time of the spectra that were
acquired. Only those spectra, acquired at retention times between
0.3~and~0.6~min are considered for the combination that will lead to the
production of a mass spectrum. In the second integration, two elements are to
be taken into account for the filtering of the mass data: the fact that we
only care of spectra acquired in the [0.3--0.6] retention time range
\emph{and} the fact that we are only interested in the mobility of ions whose
m/z~value is contained in the [2202.4--2204.4] range.  The mobility spectrum
shows a broad peak with a poorly resolved shoulder. The user wants to get the
m/z~values that are responsible for these unresolved peaks. She integrates to
a mass spectrum the drift region [10.29--12]~ms. In this integration the
initial mass spectrometric data are filtered according to all the criteria
mentioned above: retention time range \emph{and} m/z~range \emph{and} drift
time range. The same applies for the other drift spectrum to mass spectrum
integration starting from drift time range [12--14]~ms. As shown in the last
two mass spectra, the data is indeed contained in the \mz{[2202--2204]} range.
Incidentally, it appears from the analysis that the same ions have different
drift times, since both drift spectrum shoulders back-integrate to very
similar mass spectral patterns.

\enlargethispage{1cm}

\begin{landscape}

	\begin{figure}[H]

		\centering

		\includegraphics[height=0.9\textheight]{figures/minexpert-chained-integrations.png}

		\renewcommand{\captionText}{Example of chained integrations}
		\caption[\captionText]{\textbf{\captionText}}

		\label{fig:minexpert-chained-integrations}

	\end{figure}

\end{landscape}



\renewcommand{\sectitle}{Mass spectral feature analysis}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

When analysing a mass spectrum, two major deconvolutions are performed to get
back to the M$\rm _r$ mass of the analyte while reading m/z~values: the
charge-based deconvolution and the monoisotopic cluster-based deconvolution.  In
the following sections, both deconvolutions are described.


\renewcommand{\sectitle}{Mass spectral deconvolution based on charge state}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

In this kind of deconvolution, at the present time, the software assumes that
the ionization agent is the proton and that the ionization is positive.

The deconvolution is based on the determination of the distance between
consecutive (or not) peaks of a given charge state envelope. When the user
\lmb-click-drags the cursor from one peak to another, the program tries to
calculate if the distance between two peaks matches a charge difference. If so,
it computes the molecular (Mr) mass of the analyte whose mass peak is located
under the cursor.
Figure~\vref{fig:minexpert-charge-based-deconvolution-consecutive-peaks}
shows that precise state for two \emph{consecutive} peaks of a charge state
envelope.

Note that the charge calculation almost never produces an integer value with no
fractional part (say, charge z=15.0) because it is almost impossible to drag the
mouse cursor the exact interval that would lead to such integral charge value.
Almost every time, the charge that is calculated is like 14.995 or 15.001, for
example. Why is it impossible to drag the mouse cursor exactly the interval that
would produce an integral charge value? Simply because the mouse moves at
discrete positions that might be more or less far apart, depending on the mouse
capabilities. The zoom state over the two peaks also plays a role. It is advised
to zoom in as much as possible the peaks that serve as the basis for the
deconvolution so as to minimize the difficulties above. It may happen however
that even zoomed in peaks are not sufficiently distant to allow a charge
calculation. In this case, reduce the stringency over the fractional part that
is allowed in the charge. By default, the stringency is set at 0.99, that is,
any calculated value that has a fractional part either superior or equal to 0.99
or inferior or equal to 0.01 would lead to a successful round-up/round-down to
the nearest integer value. Outside of the ]0.01-0.99[ interval, no charge
	calculation is performed and thus no deconvolution is performed. When the
	stringency is too high, reducing it will allow the deconvolution to be
	carried-over (see
	Figure~\vref{fig:minexpert-charge-based-deconvolution-consecutive-peaks}).


\begin{figure}[H]

	\centering

	\includegraphics{figures/minexpert-charge-based-deconvolution-consecutive-peaks.png}

	\renewcommand{\captionText}{Charge-based mass deconvolution}
	\caption[\captionText]{\textbf{\captionText} Approach using two
	\emph{consecutive} mass peaks. Note that the 0.99 stringency set in the spin
	box in the status bar could not allow any deconvolution to be carried-over,
	while reducing that stringency to 0.98 allowed it to proceed successfully.}
	\label{fig:minexpert-charge-based-deconvolution-consecutive-peaks}

\end{figure}

The status bar of the window documents the current inter-peak distance
measurement operation that is performed by \lmb-click-drag of the cursor
starting at the left peak towards the right peak. The start peak is marked with
a green marker and the end peak is marked with a red marker. Start and end
positions are documented in the form (m/z~start, i)$\rightarrow$(m/z~end, i).
Then, the delta, that is, the distance between both positions is provided. When
the end position matches a theoretically expected distance corresponding to a
charge difference of 1, then the charge \emph{z} of the peak under the cursor is
provided and the molecular mass (Mr) is provided for the analyte whose peak is
under the cursor.

It might happen that two \emph{consecutive} peaks of the charge state
envelope are not of a good shape enough to point and click precisely in the
center of the peaks. In that case, the software allows indicating the number
of intervals that run between two \lmb-click-drag-connected peaks. This is
illustrated in
Figure~\vref{fig:minexpert-charge-based-deconvolution-non-consecutive-peaks}.
The user knew that she had to measure the distance between two peaks that
were separated by two intervals. She thus incremented the interval value in
the status bar to \guivalue{2} and performed the measurement. The Mr value
that is displayed is different than the previous one because without
enlarging the window, it is more difficult to click right at the center of
the gaussian shape of each peak. Theoretically, the Mr values should be
identical, and actually are when the measurements are performed cleanly in
widely-laid mass spectra.


\begin{figure}[H]

	\centering

	\includegraphics{figures/minexpert-charge-based-deconvolution-non-consecutive-peaks.png}
	\renewcommand{\captionText}{Charge-based mass deconvolution}
	\caption[\captionText]{\textbf{\captionText} Approach using two
	\emph{non}-consecutive mass peaks. Note the \guivalue{2} interval value in the
status bar of the window.}
\label{fig:minexpert-charge-based-deconvolution-non-consecutive-peaks}

\end{figure}

Note that the \lmb-click-draggging direction (left$\rightarrow$right or
right$\rightarrow$left) has an impact on the value of the charge (\emph{z})
that is obtained, since that charge value is relative to the peak
\emph{under} the cursor at the moment of the deconvolution. Conversely, the
mouse-dragging direction has no effect on the Mr (molecular mass) of the
analyte obtained as a result of the deconvolution process.


\renewcommand{\sectitle}{Mass spectral deconvolution based on isotopic cluster peaks}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

In this kind of deconvolution, the user \lmb-click-drags the cursor between
the first two peaks (when possible) of the isotopic cluster. The charge
state of the ion is $\rm \frac{1}{\Delta\mz{}}$, with $\Delta$\mz{} the
distance between the two consecutive peaks.
Figure~\vref{fig:minexpert-isotopic-cluster-deconvolution} shows that
deconvolution process at work.

\begin{figure}[H]

	\centering

	\includegraphics{figures/minexpert-isotopic-cluster-deconvolution.png}

	\renewcommand{\captionText}{Isotopic cluster-based mass deconvolution}
	\caption[\captionText]{\textbf{\captionText}}
	\label{fig:minexpert-isotopic-cluster-deconvolution}

\end{figure}

Note that the direction of \lmb-click-dragging (left$\rightarrow$right or
right$\rightarrow$left) does not have any effect on the Mr value that is
obtained as a result of the deconvolution process.


\renewcommand{\sectitle}{Reading the resolving power based on mass spectral data}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

When \lmb-click-dragging the mouse cursor between two mass spectrum locations of
interest, the program computes the apparent resolving power. This process is
shown on Figure~\vref{fig:minexpert-resolving-power-calculation}, where the
resolving power is calculated by dragging the mouse cursor from one edge of a
peak to the other at half maximum height.


\begin{figure}[H]

	\centering

	\includegraphics{figures/minexpert-resolving-power-calculation.png}

	\renewcommand{\captionText}{Calculation of the resolving power}
	
	\caption[\captionText]{\textbf{\captionText}
	\lmb-click-dragging the mouse cursor will trigger the calculation of the
	resolving power of the instrument. That value is printed in the status bar.  }
	\label{fig:minexpert-resolving-power-calculation}

\end{figure}


\renewcommand{\sectitle}{Recording the data mining work}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

When doing mass analysis work it is often desirable to store the
painstakingly manually picked \mz{$\!\!$} or Mr values for later use.
\mineXp provides a number of solutions to record the data mining work.


\renewcommand{\sectitle}{Simplest data record: \\in-console feature labeling}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

The simplest way to record any graph feature is to point that feature with the
mouse and press the \kbdKey{l} ('el') key.  That key shortcut prints to the
console window the coordinates of the current mouse cursor location. To be able
to trace back the graph source of that (x,y) pair, the text is printed in the
console using the same color as the graph whence the labelling action came. The
console is actually a rich text format editor in which it is possible to edit
the text contents so as to copy/paste them in the lab-book or an email to a
colleague, for example. This is shown in
Figure~\vref{fig:minexpert-console-based-feature-labeling-record}. The label
operation described here does not require any previous integration operation.
This is in contrast to the requirements of the mass spectral data analysis
recording described below.

\begin{figure}[H]

	\centering

	\includegraphics{figures/minexpert-console-based-feature-labeling-record.png}
	\renewcommand{\captionText}{Recording the peak feature coordinates to the
	console} \caption[\captionText]{\textbf{\captionText} The text color helps
to identify the graph being analyzed.}
\label{fig:minexpert-console-based-feature-labeling-record}

	\end{figure}

	\alertbox{The label recording process works without ambiguity when the cursor
		is located in the single-graph plot widgets. However, when the cursor is
		located in the multi-graph plot widget (top part of the window displaying
		TIC chromatograms, mass spectra or drift spectra) then, only the graph(s)
		currently selected in the \guilabel{Loaded mass spectrum files} window
	is(are) concerned by the label operation.}


	\renewcommand{\sectitle}{Console-/Clipboard-/File-Based \\Data Analysis Recording}
	\subsection*{\textcolor{sectioningcolor}{\sectitle}}
	\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

	In order to record the innumerous analysis steps that make a data mining
	session, the \guimenu{File}\guimenuitem{Analysis preferences} might be called
	to display the window shown in
	Figure~\ref{fig:minexpert-analysis-preferences-wnd}. In that window, the user
	can select the destination of the data analysis recording system: console,
	clipboard, file or any combination of the three. When selecting file
	recording, the user might specify if the recording whould overwrite any
	preexisting file or, instead, append to that file. Depending on the kind of
	graph where data mining occurs, the format of the data to be recorded will
	change. For example, it makes no sense to record the charge \emph{z} when
	mining data in the \guilabel{Drift spectrum} window. This is why the text
	format of the data export might be defined for the three kinds of graphs: TIC
	chromatogram, mass spectrum or drift spectrum.

	\begin{figure}[H]

		\begin{center}

			\includegraphics[width=0.8\textwidth]{figures/minexpert-analysis-preferences-wnd.png}

		\end{center}

		\renewcommand{\captionText}{Setting-up of the recording of the data
		analysis} \caption[\captionText]{\textbf{\captionText} It is possible to
		configure the recording system to record to either the console, the
		clipboard, a file (in append mode or in overwrite mode) or any combination
		of the three.  The format of the string is defined using special
		characters (see text) and might be defined specifically for the three main
	graphs: TIC chromatogram, mass spectrum and drift spectrum.}
	\label{fig:minexpert-analysis-preferences-wnd}

\end{figure}

The format used to define the text string to be stored on console and/or in
file can contain particular tokens as described below:

\begin{itemize}

	\item \%f : mass spectrometry data file name
	\item	\%X : value on the X axis of the graph (no unit)
	\item \%Y : value on the Y axis of the graph (no unit)
	\item \%x : delta value on the X axis (when appropriate, no unit)
	\item \%y : delta value on the Y axis (when appropriate, no unit)
	\item \%I : TIC intensity after TIC integration over a graph range
	\item \%s : X axis range start for computation (where applicable)
	\item \%e : X axis range end for computation (where applicable)\\

		For mass spec plot widgets:

	\item \%z : charge
	\item \%M : Mr

\end{itemize}


\alertbox{It is important to keep in mind that the \%z and \%M format strings
	can only work if the user is actually analyzing a mass spectrum and if the
	user has \emph{effectively} performed a deconvolution operation that has
	allowed computing these two values. If the values are not available, the
	program shows \guivalue{nan} (``not a number'') in the textual output when the
	space bar is hit (see below). \\[2mm] In the drift spectrum window, the data
	recording processes data matching the cursor position at the last
	\lmb-single-click. The program tries to define the intensity by looking at the
	graph ordinate (y axis) matching the nearest abscissa point (x axis) to the
	last \lmb-clicked location.\\[2mm] Also, as stated above for the simple
	labelling of cursor location points, the recording of data analysis steps work
	both in the multi-graph plot widgets (those at the top of the plot windows)
	and in the single-graph plot widgets (those at the bottom of the windows).
	When doing data analysis in the top multi-graph widget, it is necessary to
	select the traces to be analyzed in the \guilabel{Loaded mass spectrum files}
	window, otherwise no data will be recorded. This is of course not necessary
	when working in bottom plot widgets because in that case there is no ambiguity
on what data to record.}


It is possible to store the format strings in a drop down box for later
reuse. Simply click onto the \guilabel{Add to history} button while having
the format text displayed in the text editor and it will be appended to the
drop-down list. The list gets stored when the dialog window is closed and
will be filled-up again when the program is restarted.

As an example, if the user defined the following format string for a mass
spectrum graph:

\begin{verbatim}
Mass spec. :
mz = (%X, %Y) z = %z
filename = %f
date = 20161021
session = 20161021
mslevel = 1 msion = esi msanal = tof
chrom = DEAE fraction = 25
seq =  pos =     oxlevel = 0 pos =
intensity =
comment =
\end{verbatim}

then, a resulting data mining stanza that would be recorded will look like
this:

\begin{verbatim}
Mass Spec. :
mz = (1051.8, 50863) z = 1
filename = 20161017-rusconi-frac-25-deae-20160712.db
date = 20161021
session = 20161021
mslevel = 1 msion = esi msanal = tof
chrom = DEAE fraction = 25
seq =  pos =     oxlevel = 0 pos =
intensity =
comment =
\end{verbatim}

Interestingly, the user can define any kind of format, leaving fields available
for later filling-in. This feature is of immense value when the analysis file is
used later to fill-in a database for easy storage and interrogation of the
mining findings.

At this point, it would be useful to have the file opened in an editor and at
each new stanza edit the \guilabel{comment} field if something needs to be
commented, like the shape/intensity of a mass peak, for example.

Note that the program closes the file each time a new stanza has been written.
This makes it possible to edit that file safely in between each stanza record.
Remember to force the editor to reload the file from disk after each stanza
recording.

When the recording involves sending the analysis data to the console, the data
are sent to it as text colored the same as the spectrum that was under scrutiny.

When the mouse cursor has been placed at the proper location (with or without
\lmb-click-dragging, depending on the situation) on the graph, the user hits the
space bar and the data analysis stanza is recorded to the selected
destination(s): console, clipboard, file.


\renewcommand{\sectitle}{Splitting very large files into smaller chunks}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

Mass spectrometry data acquisitions performed in line with a chromatography
setup generally yields massive data files holding mass data acquired all along a
chromatographic development. Depending on the application, the data in the
obtained file might not be of interest throughout all the acquisition duration.
For example, a size exclusion chromatography might have resolved the molecular
species of interest only in a very short retention time range. In this case, it
might be useful to extract the data corresponding to that retention time range
of interest from the initial very large file and store them in another file that
will be sufficiently light to be loaded and analyzed quickly and easily.

\mineXp can export data according to various modes, as illustrated in
Figure~\ref{fig:minexpert-data-export-slice-count}.


\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.5\textwidth]{figures/minexpert-data-export-slice-count.png}

	\end{center}

	\renewcommand{\captionText}{Setting-up of the data export}
	\caption[\captionText]{\textbf{\captionText} It is possible to split very
	large files into smaller chunk files. In this example, the number of slices to be
	created is \guivalue{2}. The program computes automatically the size of the
	chunks by looking at the \guilabel{rangeStart} and \guilabel{rangeEnd}
values.}
\label{fig:minexpert-data-export-slice-count}

\end{figure}

Depending on the ``slicing'' configuration, the program will calculate the
missing data to perform the required action. If the user specifies the number of
slices, the size of the slices is automatically calculated. Conversely, if the
user specifies the size of the slices, the number of slices is deduced. Note
that the \guilabel{Range start} and \guilabel{Range end} values correspond to
the limits of the data range currently displayed in the plot widget from which
the data export was triggered using the \guimenu{Export}\guimenuitem{data}
context menu (right-click the mouse when the cursor is over the plot widget of
interest). If the \guilabel{Export the whole region in a single file} is
checked, the data relating to the range displayed in the plot widget is exported
to a single file. For this operation to be meaningful, either zoom-in the data
to the desired data range in the plot widget and start the configuration of the
slicing process, or set manually the \guilabel{Range start} and \guilabel{Range
end} values.

The file naming pattern used for the various data files generated in the process
of the data export is governed by the format string displayed at the top of the
window. By default, the generated files are located in the same directory as the
source data file. If a new directory is to be used, it can be selected by
pressing the \guilabel{Directory...} push button.

Once the configuration is done, the \guilabel{Validate} push button needs to be
pressed so that the user can review the various file names that have been
choosen for the various data slices to be written to
(Figure~\ref{fig:minexpert-data-export-slice-count-after-validation}). If the
configuration is correct, the user clicks the \guilabel{Confirm and start data
export} button.

\begin{figure}[H]

	\begin{center}

		\includegraphics[width=0.8\textwidth]{figures/minexpert-data-export-slice-count-after-validation.png}

	\end{center}

	\renewcommand{\captionText}{Setting-up of the data export - validation}
	\caption[\captionText]{\textbf{\captionText} Once the configuration has been
	done, the user clicks the \guilabel{Validate} push button and the program
	checks the consistency of all the parameters, then designs the slices and
	crafts file names for these various slices. The user has the opportunity to
	check that the file names match her desire. If so, clicking the
	\guilabel{Confirm and start data export} button starts the data export
process.} \label{fig:minexpert-data-export-slice-count-after-validation}

\end{figure}

\fbox{\parbox{0.9\textwidth}{Note that the data export feature can only be used
	with the following two data ranges:

	\begin{itemize}

		\item Retention time ranges: the data export configuration window must be
			activated from one of the TIC chromatogram plot widgets;

		\item Ion mobility drift time ranges: the data export must be triggered
			from one of the Drift spectrum plot widgets;

	\end{itemize}

	This is because it does not make sense to split up a given data file into
smaller files on the basis of m/z data ranges.} }


\chapter[Conversions] {Converting \fileformat{mzML} to \fileformat{SQLite3}}
\label{chap:convert-mzml-to-sqlite3}

The \fileformat{mzML} format is very verbose and parsing it causes a notable
delay during loading of mass spectrometry files. \mineXp allows one to convert
\fileformat{mzML} files to a private open file format based on the
\progname{SQLite3} database software.

Using the \fileformat{SQLite3} format also allows to slice very large data files
into smaller files on the basis of user-selected criteria (see \mineXp
manual).\\

\progname{\minexp} can be used in a console without needing to open any window.
To show a detailed help, type the following:\\

\command{\minexp{} ---help}\\

Use the following parameters (or flags) to perform a data file conversion:\\

\command{\minexp{} -x -o <db file name> <mzML file name>}\\

For example, to convert file \filename{test-file.mzML} into
\filename{test-file.db}, the command line would be:\\

\command{\minexp{} -x -o test-file.db test-file.mzml}\\

Alternatively, the \command{-o} flag can specify a directory, in which case the
new file name is crafted from the \fileformat{mzML} file and written into that
directory.  In that case, the extension of the \fileformat{mzML} file needs to
be either \guilabel{mzML} or \guilabel{mzml} for the automatic renaming to
occur.\\

Note that \emph{in batch} conversion is possible using this kind of command
line:\\

\command{\minexp{} -x -o /tmp /home/<user>/lab/mzml/*.mzml}\\

In this case, automatic file renaming happens and the new \fileformat{db} files
are all stored in the \filename{/tmp} directory.

