\chapter[\pxc] {\pxc: A Powerful Mass Calculator}

\label{chap:polyxcalc}

After having completed this chapter you will be able to perform
sophisticated mass computations in a polymer chemistry-aware manner.

\renewcommand{\sectitle}{\pxc\ Invocation}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle} 



The \pxd\ module is easily called by pulling down the ``\pxc'' menu
item from the \pxm program's menu. The user may accomplish two
different tasks in the \pxc module:

\begin{itemize}
\item Use the calculator in a polymer chemistry-unaware manner;
\item Use the calculator in a polymer chemistry-aware manner.
\end{itemize}



\renewcommand{\sectitle}{\pxc\ Operation: An Easy Task}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle} 

When the user elects to open a \pxc module with a polymer chemistry
definition, he is provided a window where to choose an already
registered polymer chemistry definition out of the list of all the
polymer chemistry definitions available to the \pxm framework
(Figure~\vref{fig:polyxcalc-polchemdef-open-def-wnd}).


\begin{figure}
  \begin{center}
    \includegraphics [scale=1.25]
    {figures/raster/polyxcalc-polchemdef-open-def-wnd.png}
  \end{center}
  \caption[Selecting a polymer chemistry definition for use with
  \pxc]{\textbf{Selecting a polymer chemistry definition for use with
      \pxc} This figure shows that the user can only select one
    already registered polymer chemistry definition with the \pxc
    module. Choosing a polymer chemistry definition will allow to take
    advantage of all the chemical entities defined therein during the
    mass computations.}
  \label{fig:polyxcalc-polchemdef-open-def-wnd}
\end{figure}

When the user selects one polymer chemistry definition, the calculator
window comes preloaded with that definition, which allows the user to
take advantage of the chemical entities defined in that definition
when performing mass computations.


\begin{figure}
  \begin{center}
    \includegraphics [scale=2.7]
    {figures/raster/polyxcalc-calculator-wnd.png}
  \end{center}
  \caption[Interface of the \pxc\ module]{\textbf{Interface of the
      \pxc\ module.} This figure shows that the \pxc polymer
    definition-aware module can handle atoms, actforms, monomers,
    modifications and even polymer sequence\dots\ for computing
    masses.}
  \label{fig:polyxcalc-calculator-wnd}
\end{figure}

The way \pxc\ is operated is very easy. This is partly due to the very
self-explanatory graphical user interface of the module, which is
illustrated in Figure~\ref{fig:polyxcalc-calculator-wnd}. As the
reader can see, there are a number of items that \pxc\ can handle. We
are going to review these one by one:

\begin{itemize}
\item \guilabel {Initial Masses} This is the place where the mass
  calculator may be seeded so as to start computations on pre-existing
  molecules of which masses are known already. The user may enter
  either a \guilabel {Mono Mass} or an \guilabel {Avg Mass} or both
  masses.  When any of these masses is set and the \guilabel {Result
    Masses} are empty, they are taken into account (\pxc\ considers
  that the system is seeded with them) in the first mass calculation
  that is elicited by clicking onto the \guilabel {Apply} button. Once
  the \guilabel {Result Masses} are no more empty, these masses are no
  more taken into account, and instead will be updated to reflect the
  previous mass calculation results. Thus, each time a calculation is
  performed, the previous results are stored in the \guilabel {Initial
    Masses} text entry widgets. This way, the user has the ability to
  always ``undo'' the last calculation step;
\item \guilabel {Atom} This is a drop-down list widget that contains
  all the atoms available in the polymer chemistry
  definition-associated atom definition.\footnote{If no polymer
    chemistry definition is loaded into the calculator, then the
    'basic' atom definition is used. That 'basic' atom defintion is
    distributed along the \pxmcommon package that is essential to the
    proper functioning of the \pxm mass spectrometry software
    framework.} The user may select any of these atoms and enter any
  number (positive or negative) in the related \guilabel {Count} text
  entry widget.  Entering a positive value means that the selected
  chemical entity must be added to the masses, while a negative value
  will remove this entity from the masses;
\item \guilabel {Formula/Actform} This is a text entry widget where
  the user may enter as complicated actforms (or a formula) as she
  wishes. Same as above applies for the \guilabel {Count} text entry
  widget;
\item \guilabel {Monomers} If a polymer chemistry definition file was
  loaded when bringing up this \pxc calculator module, this drop-down
  list widget contains all the monomers listed in the chosen polymer
  chemistry definition. For example, if the ``protein'' polymer
  chemistry definition file had been opened in \pxc, then this
  drop-down list widget would have contained the twenty names of all
  the naturally-occurring most common monomers (amino-acids). Same as
  above applies for the \guilabel {Count} text entry widget;
\item \guilabel {Modifications} This is exactly the same as for the
  \guilabel {Monomers} drop-down list widget, unless the ``chemical
  elements'' listed here are the modifications described in the
  polymer chemistry definition file, such as ``Acetylation'' or
  ``Phosphorylation'', for example. Same as above applies for the
  \guilabel {Count} text entry widget;
\item \guilabel {Polymer Sequence} This is a text entry widget were
  the user may enter a polymer sequence complying with the polymer
  definition currently opened in \pxc. A ``protein'' sequence may be
  this ``MAMISGMSGRKASPTSPINADK'', for example, which is the
  N-terminal end of the chicken gizzard telokin.\footnote {If I
    remember well my PhD experimental work\dots} Same as above applies
  for the \guilabel {Count} text entry widget;
\end {itemize}

Noteworthy, when \pxc is launched without specifying a polymer
chemistry definition, the polymer chemistry definition-specific
widgets (monomers, modifications, polymer sequence; all described
above) are made insensitive. This is to make sure that the user cannot
enter data that would not make sense because the chemistry definition
is loaded.

Also, interesting from a graphical user interface point of view, the
fact that the user might ``collapse'' parts of the calculator window
widgets. For example, if the user does not make use of monomers, she
might click onto the \guilabel{Monomers} checkbutton to have the whole
monomers-related frame collapse. This is true for all the other frames
on that window. More radically, if no polymer chemistry definition was
loaded when launching the \pxc module, the whole series of widgets
pertaining to the polymer chemistry definition may be collapse in one
step by clicking onto the \guilabel{Polymer Chemistry-Defined
  Elements} checkbutton.


Note also, that a series of buttons, located both in the
\guilabel{Initial Masses} and \guilabel{Result Masses} frames are made
available to the user in order to perform sophisticated combinations
of calculations\dots\ The reader is invited to experiment with these
buttons'-triggered actions.


The mass calculation operation is actually triggered by clicking onto
the \guilabel{Apply} button. When this button is pressed, then the
program goes through all the valid widgets an applies all the
requirements that are listed in the window. From the
Figure~\ref{fig:polyxcalc-calculator-wnd}, we can see that the user
asked a number of chemical operations to be performed in one
\guilabel{Apply} button click:

\begin{itemize}
\item Add one \guival{Mg} atom;
\item Add the net mass corresponding to the \guival{+H2SO4-H}
  action-formula;
\item Add one \guival{Glycine} residue;
\item Modifiy the substrate using one \guival{Phosphorylation}
  chemical modification entity;
\item Add one protein sequence: \guival{MAMISGMSGRKAS};
\end{itemize}

When all these operations are performed, starting from empty
\guilabel{Initial Masses}, the result is displayed in the text entry
widgets located in the \guilabel{Result Masses} frame:
\guival{1565.547233} as the monoisotopic mass, and the
\guival{1567.008188} as the average mass.

\medskip

As a final point, the reader may have noticed that, with this
interface, any possibly imaginable molecule can be constructed since
the ``granularity'' of the \pxc module is atomic.


\renewcommand{\sectitle}{\pxc\ Contains A m/z Ratio Calculator}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle} 

\label{sect:polyxcalc-mz-ratio-calculator}

It very often happens that the massist doing electrospray analyzes is
faced with a challenging task: to compute by mind all the m/z ratios
for a given family of charge peaks. To ease that daunting task, \pxc
contains a m/z ratio calculator that is called by clicking onto the
\guilabel{m/z Ratio Calculator} button. This action pops up a window
that is shown in Figure~\ref{fig:polyxmass-mz-ratio-calculator}. 

In order to compute the m/z ratios requested by the user, the program
needs to have some seeding data, which have to be entered in the
\guilabel{Initial Data} frame widget. Of course, initial m/z values
have to be entered (both monoisotopic and average m/z values need to
be entered). The user must inform the calculator about how these m/z
values were calculated, that is what was the ionization status of the
analyte when these m/z values were measured (either virtually or
effectively).  These ionization data are entered in the
\guilabel{Ionization Status} frame, which is subdivided into two
frames, where the user enters how the ionization is performed (in our
example, the ionization is a protonation, thus bringing one charge per
protonation event (\guilabel{Ionization Unitary Charge} is
\guival{1})) and what's the level of the ionization, that is how many
times the ionization was performed (in our example, the ionization
level is \guival{1}, that is the analyte was mono-protonated). With
all these data, the m/z ratio calculator can compute the molecular
mass of the analyte. That mass will be used to perform the requested
m/z ratio calculations (\guilabel{Requested Ionization Status} frame,
which behaves identically to the one described above). The computed
m/z ratios are displayed in a treeview widget.


\begin{figure}
  \begin{center}
    \includegraphics [scale=3]
    {figures/raster/polyxmass-mz-ratio-calculator.png}
  \end{center}
  \caption[The m/z ratio calculator]{\textbf{The m/z ratio
      calculator.} The m/z ratio calculator is rather straight forward
    to use. Given initial m/z values with details on how they were
    computed, the program computes m/z ratios as requested.}
  \label{fig:polyxmass-mz-ratio-calculator}
\end{figure}

\renewcommand{\sectitle}{\pxc\ Is A Programmable Calculator}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle} 

For the scientists who work on molecules that are often modified in
the same usual ways, \pxc features a built-in mechanism by which they
can easily program their calculator. This programming involves the
definition of how a \emph{chemical pad} (or \emph{chempad}) may be
arranged, exactly the same way as a usual calculator would display its
numerical keypad. 

\begin{figure}
  \begin{center}
    \includegraphics [scale=3]
    {figures/raster/polyxcalc-chempad-wnd.png}
  \end{center}
  \caption[Interface of the chemical pad]{\textbf{Interface of the
      chemical pad.} This figure shows that the chemical pad is very
    similar to what a numerical calculator would display. Here, the
    user has programmed a number of chemical reactions.} 
  \label{fig:polyxcalc-chempad-wnd}
\end{figure}

An example of such a chemical pad is shown in
Figure~\ref{fig:polyxcalc-chempad-wnd}, where a ``protein'' polymer
chemistry definition-associated chempad is featured. As shown, the
user has programmed a number of chemical reactions that may be applied
to the masses in the \pxc calculator window by simply clicking on
their respective item. 

The configuration of the chemical pad is very easy, as shown in the
code below (excerpt taken from file
\filename{/usr/share/polyxmass/polchem-defs/protein/chempad.conf}):

\begin{alltt}
chempad_columns\$3

chempadkey=protonate%+H1%adds a proton
chempadkey=hydrate%+H2O1%adds a water molecule
chempadkey=0H-ylate%+O1H1%adds an hydroxyl group
chempadkey=acetylate%-H1+C2H3O1%adds an acetyl group
chempadkey=phosphorylate%-H+H2PO3%add a phosphate group
chempadkey=sulfide bond%-H2%oxydizes with loss of hydrogen
\end{alltt}

\medskip

\noindent What this text file says is very simple:
\begin {itemize}
\item That the buttons should be arranged in rows of three columns;
\item Follows the description of a number of buttons (chempad keys) to
  be laid out in the chempad (each line describes one button). 
\end {itemize}

\noindent Each button is defined in a line that begins with the text
\verb#chempadkey=#. Let's look at one button definition, the
``phosphorylate'' button. The \verb#phosphorylate# text string after
the \verb#=# character is the label that will decorate the button that
is being configured. The \verb#-H+H2PO3# text string is the actform
that should be applied to the result masses in the \pxc\ main window
when this button is clicked; that's a chemical reaction, in fact. The
\verb#add a phosphate group# is a text string that is displayed as a
tooltip when the mouse cursor stays for a number of milliseconds over
the button. 

From a geometrical layout point of view, the user is allowed to set
either a number of rows (\verb#chempad_rows$3#, in our example) or a
number of columns (\verb#chempad_columns$3#, in the example). The
program then chooses the best layout corresponding to the user's
requirement. 


\renewcommand{\sectitle}{\pxc\ Is LogBook-Friendly}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle} 



Each time an action that is chemically relevant ---from a molecular
mass perspective--- is performed, the program dumps the calculations
to the \pxc recorder window. 

\begin{figure}
  \begin{center}
    \includegraphics [scale=2.5]
    {figures/raster/polyxcalc-recorder-wnd.png}
  \end{center}
  \caption[The \pxc\ recorder window]{\textbf{The \pxc\ recorder
      window.} This figure shows that the recorder window is a simple
    textview widget that records all the mass-significant operations
    in the \pxc calculator. The text in the recorder may be selected
    and later used in an electronic logbook or printed.} 
  \label{fig:polyxcalc-recorder-wnd}
\end{figure}

This recorder window is shown in
Figure~\ref{fig:polyxcalc-recorder-wnd}. The text in the recorder
window is editable for the user to customize the \pxc\ output, and
selectable so that pasting to text editors or word processors is easy. 

\cleardoublepage


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "polyxmass"
%%% End: