# XpertCalc: a Powerful Mass Calculator

chemical formula action-formula calculator

After having completed this chapter you will be able to perform sophisticated polymer chemistry-aware mass calculations.

## XpertCalc Invocation

The &xpc; module is easily called by pulling down the XpertCalc menu item from the &massXp; program's menu. The user is presented with a window to select the polymer chemistry definition that should be used for the calculations ().

Selecting a polymer chemistry definition for use with XpertCalc

This figure shows that the user can either select one already registered polymer chemistry definition (listed in the drop-down widget) or browse the filesystem to select one polymer chemistry definition file. Choosing a polymer chemistry definition allows to take advantage, during the mass calculations, of all the chemical entities defined therein.

## An Easy Operation

Once the polymer chemistry definition has been correctly selected, it is parsed by the &xpc; module and its entities are automatically made available in the calculator window, as shown in . The way &xpc; is operated is very easy. This is partly due to the very self-explanatory graphical user interface of the module, which is illustrated in . &xpc; can handle a number of items that are reviewed below:

- The user may (is not obliged to) seed the calculation by setting masses manually in the Seed masses line edit widgets (the left line edit is for mono and the right one for avg);

  Both monoisotopic and average &mz; values need to be entered.

  For example, imagine that a mass spectrum analysis session ends up like this: —There is a peak with &mz; 1000.55, z=1 and another one roughly 80 Da more. Is it possible that the analyte showing up at &mz; 1000.55 is phopshorylated?. The mass spectrometrist would seed the calculator with mass 1000.55 and ask that one Phosphorylation modification be added to it by setting 1 in front of the corresponding drop-down widget. Clicking Apply triggers the calculation, with the resulting masses being displayed in the Result masses line edit widgets. We can see that the phosphorylation of our analyte shifts its &mz; value from 1000.55 to 1080.5163.

  Each time a calculation is triggered by clicking Apply (or the chemical pad's buttons; see below), the values already present in the Result masses line edit widgets are transferred to the Seed masses line edit widgets. This provides a 1-level undo;

- The Formula group box widget contains two widgets: a line edit widget where the formula is typed and a count spin box widget where the user sets the number of times that the formula should be applied. Setting the formula to H2O and the count to 2 would hydrate the analyte twice.

- The Polymer Chemistry Definition Entities group box widget contains two drop-down widgets and a line edit widget. The drop-down widget on the left lists all the monomers defined in the protein-1-letter polymer chemistry definition; the drop-down widget on the right lists all the modifications defined in the protein-1-letter polymer chemistry definition. Each drop-down widget has its corresponding count spin box widget. In the example, the user asked that one (1) Phosphorylation modification be applied during the calculation. The line edit widget below the first row of widgets is the polymer sequence widget where the user might enter a sequence of monomers. It is possible to apply many times the sequence by setting the count spin box widget value to something greater than 1 (either positive or negative);

It is possible to perform a set of calculations in one go, that is, the user may ask for a formula, a monomer, a modification, a sequence to be accounted in one single calculation operation. Once all the chemical entities to be taken into account have been set, the user clicks Apply: all the entities are parsed in sequence and their mass equivalent are added to the result masses. Other prominent features of &xpc; are described in the following sections.

Interface of the XpertCalc module

This figure shows that the &xpc; polymer chemistry definition-aware module can handle atoms, formulæ, monomers, modifications and even polymer sequences for computing masses.

## The Programmable Calculator

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

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.

The chemical pad can be shown/hidden by using the Show Chemical Pad check box widget. An example of such a chemical pad is shown in , where a protein-1-letter 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 &xpc; calculator window by simply clicking on their respective button (see ). The configuration of the chemical pad is very easy.

It is recommended to copy one of the `chemPad.conf` configuration files in any of the polymer chemistry definitions distributed within &massXp; and to modify it according to the instructions at the top of the file.

One example of such a configuration file is shown below along with explanations:

    					color%aliceblue%240,248,255
    					color%antiquewhite%250,235,215
    					color%aqua%0,255,255

    					chempad_columns%3

    					chempadgroup%Generic

    					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

    					chempadgroup%Hexoses & Fucose%[seagreen]

    					chempadkey%Res-1bRE-Hexose%C6H11O6%residue Hexose (1bRE)%[lawngreen,black]
    					chempadkey%Res-1bRE-Hexalditol%C6H12O6%residue Hexalditol (1bRE-ol)%[lawngreen,black]

It is possible to define as many colors as necessary (red,blue, green format, on a scale of 0–255).

The calculator chemical pad shall have its buttons organized in three columns.

This separator will create a group box widget labelled "Generic" that will be populated with all the items found below (until another separator is encountered).

A button definition is introduced by the chempadkey= string. Separated by % characters, follow the name of the chemical reaction that will label the button (protonate), the chemical formula of the reaction (+H2O1) and finally the tooltip text that displays when the cursor stays on the button.

Separator that starts a new button group box labelled Hexoses & Fucose. This syntax allows for the coloring of the group box widget.

A button definition that also specifies the coloring of the button. lawngreen is the background color and black is the color of the text.

These buttons might be used in two distinct ways:

- Upon clicking the button, its formula is evaluated and the corresponding masses are added to (or subtracted from) the Result masses;

- Upon simultaneous clicking the button and keeping the key pressed, its formula is inserted into the Formula line edit widget. In this case, the formula is not evaluated and the Result masses are not modified.

  Clicking sequentially on various chemical pad buttons, append the formulæ in the Formula line edit widget, which can be useful for storing the whole formula string in the memory using the Add formula to memory menu item from the drop-down menu before clicking Apply.

## The Log Book Recorder

Each time an action that is chemically relevant—from a molecular mass point of view—is performed, the program dumps the calculations to the &xpc; recorder window (). The recorder can be shown/hidden by using the Show Recorder check box widget. The text in the recorder window is editable for the user to edit the &xpc; output, and selectable also, so that pasting to text editors or word processors is easy via the clipboard.

The XpertCalc recorder window

This figure shows that the recorder window is a simple text edit widget that records all the mass-significant operations in the &xpc; calculator. The text in the recorder may be selected and later used in an electronic logbook or printed.

## The m/z Ratio Calculator

It very often happens that the mass spectrometrist doing electrospray analyzes is faced with a challenging task: to compute by mind all the &mz; ratios for a given family of charge peaks. To ease that daunting task, &xpc; contains a &mz; ratio calculator that is called by clicking onto the m/z calculation button.

The m/z ratio calculator has been described at (see Figure .

## The Isotopic Peaks Calculator

It is sometimes useful to predict (or calculate a posteriori) the isotopic peaks pattern of a given analyte (also called an isotopic cluster). This calculation takes a number of parameters, as shown in :

The isotopic pattern calculator

The isotopic pattern calculator is rather straight forward to use. Given some initial parameters, the results are displayed in the Results tab page widget. the Log tab page widget will display all the details of the ongoing calculation.

- The Formula of the chemical entity of which the isotopic cluster needs to be computed is entered;

- z The charge of the analyte. This value will set the distance between the centroids of two consecutives peaks of the cluster. For a mono-charged ion, that distance will be &mz; 1, for a bi-charged ion, that distance will be &mz; 0.5;

- m/z The mass-to-charge ratio that is dynamically calculated on the basis of the formula and the charge above. It is considered that the formula already accounts for the ionization chemical agent if z is greater than 0;

- Min. Probability The minimum probability value to find a given &mz; peak in the isotopic pattern. This allows a degree of optimization when calculations are too long to perform, by removing all isotopic peaks for which the probability of occurrence is lower than the set value;

- Resolution Resolution of the mass spectrometer. Should be of a compatible value with respect to the &mz; of the analyte;

- FWHM Full width at half-maximum of each peak. This is calculated from the m/z ratio and the value in the Resolution line edit widget. It is possible to set the FWHM directly;

- gaussian or lorentzian Kind of curve that is calculated for each peak in the cluster. The gaussian curves have a steeper ascending and descending segments than the lorentzian curves. Experiment with both to find the best one;

- Points Set the number of points desired to make the curve of a single isotopic peak. Entering 100 means that there will be 50 points on the left of the centroid of the isotopic peak and 49 on its right;

- Increment Interval between any two points of the curve making the isotopic peak. This value is calculated on the basis of m/z, Points and Resolution;

- Max. Peaks Maximum number of peaks in the isotopic pattern. This allows a degree of optimization when calculations are too long to perform by limiting the number of isotopic peaks in the pattern to the set value (the number of peaks in the isotopic peaks pattern increases exponentially with the numer of atoms);

- Output File... Button to click so as to choose a file in which all the data are to be stored for later plotting of the isotopic peaks pattern spectrum;

- Locale If checked, the results should be displayed (or written to file) using the current locale. It might be useful not to check this check box widget in case the plotting program does not understand numerical values as produced by the currrent locale. For example, some plotting programs do not understand values like 140,000.00 (that is one hundred and fourty thousands with a comma separating thousands and dot as the decimal separator).

During the calculation, the details of that calculation are displayed in the Log tab page widget. Upon clicking onto the Execute button, the tab widget will automatically switch to that page. The Results tab page widget is updated at the end of the calculation and will contain both the input data (as a record) and the results data if no output file was first selected. If an Output File name was set (see above), the (x,y) coordinates of the isotopic peaks pattern graph are not displayed in the Results tab page widget. The results for the given example are shown in .

An isotopic pattern calculator output example

The graph, plotted in &mineXp; shows the isotopic pattern that should be expected to be obtained by performing a mass spectrometric analysis of a protein (cyan fluorescent protein, [M+H+]+, formula C1209H1865N318O366S6) protonated ten times.