MultiTrace Tutorial: Creating methods

From MassFinder

Jump to: navigation, search
MultiTrace 3: Tutorial

This lesson will demonstrate how to create and modify own method definition files. This is the important prerequisite to be able to analyse your own data.

Only those operators who will actually create and administrate methods have to follow this lession. Operators who will not be involved in method administration, but only in routine analysis using given methods, can skip this lesson. However, it might be interesting to all users to learn the principles and to know what kind of information is stored in method definition files.

Contents

Acquisition method vs. method definition files

It is important to understand, that Agilent ChemStation uses acquisition methods and stores the name of the method used for acquisition in the raw data file. Every single reference and sample file contains the name of acquisition method used; which acquisition method is actually used to acquire a data file is given in the acquisition setup of a sample and usally set automatically via ChemStation's sequence table.

MultiTrace can not access the definitions of an acquisition method nor would that be sufficient to analyse and evaluate the data. Thus, MultiTrace does not read acquisition methods. It only knows the name of the acquisition method. MultiTrace strictly enforces that all reference data files and the sample data file to be evaluated have been acquired using the same acquisition method. The open sample dialog shows only samples with identical acquisition methods as the opened reference files.

MultiTrace's method definition files are human-readable text files in Windows configuration file format (*.ini) that contain some header data and define the evaluation data for each parameter, e.g. name, ID, time window, retention time, m/z of ion traces and so on.

All MultiTrace method definition files are stored in the MultiTrace method folder. The file names follow the scheme "METHOD#version.ini" where METHOD is exactly the name of the acquisition method in Agilent ChemStation, the "#" is a necessary separator character, the "version" is a freely chosen name for this method version. Thus, it is possible to have several different method definition files for the same acquisition method.

We recommend to name the default method definition file "METHOD#default.ini" if only this one exists or this definition is the base or default method. If there are more method definitions than one, name the file in a way that every user can easily distinguish and recognise the methods he needs for evaluation.

Two major ways to go...

  • Method creation and maintenance can be done inside MultiTrace using an interactive editor. This method is recommended for small changes or for writing methods from scratch without any other source available.
  • Alternatively, method creation and maintenance can be done using Microsoft Excel. MultiTrace can export and import Excel tables directly via the clipboard. This method is recommended if you already have Excel tables of your parameter lists, ions and other data. In many cases, using Excel accelerates method development and maintenance.

Take a look on methods in Excel

Please have the reference open, the sample closed. If you start this section directly after starting MultiTrace, just open the reference. If you continue the tutorial, simply close the sample.

Open the options dialog, select the Convert method tab sheet, then click on the second button from top named copy current method to clipboard. Start Excel and select Edit > Paste.

image:Tutorial-MethodExcel1.png


The rows 1 to 12 constitute the header data. The cell A1 must contain the token "MultiTrace3" to identify this table as MultiTrace method definition file. The lines 2 to 12 contain a token in column A and an associated value in column B. The order of tokens is not fixed; new tokens might be added in the future along with new features.

  • ##Method = must be exactly the name of the associated Agilent ChemStation acquisition method
  • ##column = text field without any further significance; can be printed on reports
  • ##temperature = text field without any further significance; can be printed on reports
  • ##comment = text field without any further significance; can be printed on reports
  • ##threshold = number, given in primary units, used by result filter table "thr"
  • ##primary unit = text used as primary unit on screen and in reports
  • ##secondary unit = text used as primary unit on screen and in reports
  • ##tertiary unit = text used as primary unit on screen and in reports
  • ##primary digits = number of digits after the decimal point used by values in primary units
  • ##secondary digits = number of digits after the decimal point used by values in secondary units
  • ##tertiary digits = number of digits after the decimal point used by values in tertiary units

The cell that contains the token "TABLE" (here A14) triggers the start of the parameter table. The line after this is ignored and may contain the human-readable headers of the columns. The following lines each represent one parameter and have the meaning as described below:

  • compound = name of the parameter
  • PN = parameter ID code (must be a number)
  • CAS = CAS registry number (text)
  • RT = retention time (optional, not necessary)
  • Amount = concentration of parameter in the reference, in primary units (must be a number)
  • LoQ = level of quantitation, shown in the trace graph and result table in full view
  • VisibleFrom ... VisibleTo = visible time window, that MultiTrace displays after selecting this parameter
  • SearchFrom ... SearchTo = search window, in which MultiTrace looks for the largest peak
  • Default_Eva = enhanced feature: default ion to be exported to LIMS
  • m/z sample = list of m/z ions separated by semicolon; used for sample
  • m/z reference = list of m/z ions separated by semicolon; used for reference
  • refNo = number of reference if more than one loaded to be taken by default
  • ISTD = this parameter is the internal standard (value = 1) or no standard (value 0)

The further columns are for special features and can stay "0" at the moment.

m/z values for sample and reference are given separately, because some applications require different ions to be compared with each other as if they were identical, particularly isotopically enriched standards in the reference in comparison with natural-abundant targets in the sample, e.g. typically used in dioxine analysis. However, for most applications both m/z fields will be identical.

The retention time field is not used in the search algorithm for the significant peak. Instead, MultiTrace looks for the largest peak in the given search window. The retention time field is mostly meant for information only, but can be used to automatically calculate the visible time window and the search time window when managing the method inside MultiTrace. You might also want to use this field inside Excel, when converting proprietary table from other sources to MultiTrace methods. In that case, you might want to replace the time window columns with formula like "D16-1,0" and "D16+1,0" and let Excel calculate reasonable time windows from given retention times.

The PN column should reflect your database's parameter identifier. The number or code should be bijective (i.e. only one parameter has this code and the code only relates to one parameter). When creating method definitions without database connectivity in mind, the column might remain empty (fill in zeros), but we strongly recommend to start with reasonable parameter identifiers from the start on, so as to be able to evolve to database and LIMS connectivity later on.

Editing methods

You may edit the demo method, e.g. change the names of the parameters or modify the m/z ion trace values. When done, click on the Excel table header (upper left corner: left of A, on top of 1), select Edit > Copy and return to MultiTrace's options > convert method dialog.

Click the button named save clipboard method and select an appropriate name, e.g. "MS3#demo.ini" and click save. The method folder now contains two versions of methods related to acquisition method MS3.


image:Tutorial-MethodExcel2.png


Please click on the open new sequence button and double-click the REF.D file to add it to the reference list box below, then select the new MS3#demo.ini file in the combo selection box. Click open.

You see the same main view as in the first tutorial lesson, but with your changed parameter names and ions. Check it out.

New methods

The easiest way to write methods for new acquisition methods is to just start from the demo method and edit the Excel table accordingly. Remember to change the ##Method field to the correct acquisition method and save the method using options > convert method >> save clipboard method to a new file with the correct syntax NEWMETHOD#default.ini.

Alternatively, you can use the button named copy empty method template to clipboard and paste an empty template into Excel and start from scratch.

We suggest that you start with your most often used routine analysis method, so that co-worker already can start learning MultiTrace analysis workflow.

Method editor

Please click on the method editor'# button (hammer symbol) to open the method editor dialog.

The method editor dialog is split in three areas: On the left hand side is the parameter table, where you select the current parameter to be edited. The right hand side is split in one upper half with the header data (identical for all parameters) and the lower half with the parameter values. The fields are self-explanatory and identical to the columsn described for Excel table.

The time window fields have additional width fields and calculator buttons in order to convert a given retention time to symmetrical time windows. You may use this feature, but you do not need to use it. You may also enter time windows manually, which also offers you set asymmetrical time windows, where the peak is not centered, but shifted towards the beginning or end of the time window. If you want to set time windows based on retention times for several parameters in one operation, there are respective buttons in the lower left corner of the header group box.


image:Tutorial-MethodEditor.png

Optimising time windows

Now you have everything you need to analyse your own data. Just click on open new sequence and direct MultiTrace to you raw data files. Open a reference, select the desired method definition file and check whether all parameters are inside the visible time windows, the search time windows fit your requirements and the ion traces are correct.

You may interactively optimise the time windows. This feature is only meant for administrator and can be disabled using the configuration file. Adjust the visible range to fit the time window you want to set. Hold down the Ctrl-key while clicking on the time axis to set the visible time range. Hold down Ctrl-key and Shift-key while clicking on the time axis to set the search time range. Then double-click the time axis to check whether the new settings apply as desired. Remember, the bold gray line above the time axis visualises the search time range.

Analysing your own data

Open your first sample and evaluate it. Everything should work out like the demo files did. If not, do not hesitate to contact our support. We will be glad to assist you.

If working in teams, we recommend to assign one entire sequence to one operator. Thus, multiple operators influence each other the least.


Continue with the next lesson of this tutorial: MultiTrace Tutorial: Important features

Personal tools