Users' Guide for version 2.2.9

Last edited 9-Dec-2018

This guide can also be downloaded as a .pdf at this link

Installing Igor and TERN

1) Download the latest version of Igor Pro (current version is 8) from the Wavemetrics website (link: https://www.wavemetrics.com/order/order_igordownloads.htm).

Additional info: Earlier versions of Igor can also be used, and may be downloaded from the same website. TERN 2.2.9 is known to work in Igor 7 and 8; however, versions prior to 7 are no longer supported and some sections of code may need to be commented out. TERN is developed and tested primarily in Igor 8, and we recommend you use the most up-to-date version.

2) After downloading Igor, open the program. You will be prompted for license activation, and can either enter your activation code here, or use the 30-day free trial. License activation can be performed later if you choose to start with the free trial.

3) Igor Pro must be prepared to run TERN. The following steps are required (note, these are specific to Igor 8, although similar for Igor 7):

a) Activate H5 and CDF packages for 64-bit Igor:

i) Open up the ‘Igor Pro 8’ folder using the Help->Show Igor Pro Folder menu item.

ii) Go to ‘More extensions (64-bit)’ -> ‘File Loaders.’

iii) Select the files ‘HDF5-64’ and ‘NetCDF-64’ and create shortcuts of both files.

iv) Move both shortcuts to the Igor Pro 8 folder -> ‘Igor Extensions (64 bit)’.

b) (Uncommon) Activate H5 and CDF packages for 32-bit Igor. Note that most users should only need the 64-bit version of Igor and can disregard this step.

i) Open up the ‘Igor Pro 8’ folder using the Help->Show Igor Pro Folder menu item.

ii) Go to ‘More extensions’ -> ‘File Loaders.’

iii) Select the files ‘HDF5’ and ‘NetCDF’ and create shortcuts of both files.

iv) Move both shortcuts to the Igor Pro 8 folder -> ‘Igor Extensions’.

c) Install HDF5 Browser procedure

i) In the Igor Pro 8 folder go to ‘WaveMetrics Procedure’ -> ‘File Input Output.’

ii) Select ‘HDF5 Browser’ and create a shortcut.

iii) Move the shortcut to Igor Pro 8 folder -> ‘Igor Procedures.’

d) Note on set-up for previous Igor versions: Igor 7 (and 6) does not have native support of NetCDF files, which is necessary for file conversion from some instrument software packages (e.g. Agilent or Thermo-Fisher). Instead, importing NetCDF files requires an externally downloaded XOP, available at https://www.wavemetrics.com/users/tools. This tool works only in 32-bit Igor, so when using Igor 7, only the 32-bit executable can be used for import functions (once imported and converted to H5, analysis can be performed in either 32-bit or 64-bit version).

4) To enable mass spectral searches using the NIST database install the NIST search program and any available libraries. To enable the search function in TERN, you must manually create one file within the NIST folders: within the MSSEARCH folder, create a new folder named “data”. In this folder create a new text file called “datafile.txt”. Note that this is done automatically in the next version of TERN, currently under development.

Additional info: If your NIST library does not come with the search program, you may download and install the NIST MS Search demo from: https://chemdata.nist.gov/mass-spc/ms-search/downloads/NISTDEMO_08.exe. This demo version is fully functional and allows manual installation of any available libraries.

5) Igor is ready for TERN. Download TERN at: https://sites.google.com/site/terninigor/software-download. The latest version of TERN is v2.2.9; not all features described in this document are available in prior versions. The above link downloads TERN as a zip file. Once downloaded, locate the file, double-click and select ‘extract all’ in order to save the TERN-related Igor procedure files (.ipf) on your computer.

There are multiple ways to save and access TERN:

1) Save all .ipf files to a folder of your choice. Any time you want to use TERN you must open all TERN .ipf files by dragging them into Igor and clicking compile.

2) Set up the .ipfs to be automatically imported every time Igor is opened. To do so, use the menu item Help -> Show Igor Pro User Files. Open the folder ‘Igor Procedures’ and save all TERN .ipf files to this folder. This means TERN will always be available in Igor.

3) Create an Igor template experiment, which will open a blank experiment with all TERN ipfs. To do this, complete step (1) above. Once compile has succeeded, use the menu item File->’Save Experiment As’ and select file type “Packed Experiment Templates (*.pxt)’. Once this template has been created, the user simply opens the template to create a blank experiment with the TERN .ipf files loaded.

6) Once all TERN .ipf files have been imported and compiled (may require clicking “Compile” at the bottom of the top Procedure window), a new menu item ‘TERN’ should appear on the menu bar. In this ‘TERN’ menu, select ‘Create TERN panel’ to open the main TERN program panel that serves as the user interface.

TERN overview

TERN consists of several tabs that are generally designed to be used in order from left to right.

The general workflow for TERN is:

● Tab 0: Initialization. The user provides information about their files, system, and dataset. All TERN analysis, regardless of the instrument on which the data was acquired, occurs using custom H5 files; in this tab, raw instrument files are converted to these TERN H5 files.

● Tab 1: Explorer. Qualitative exploration of the data to identify analytes of interest. Provides features such as extracting mass-based chromatograms and mass spectra from a file, overlay of multiple mass spectral ions within a file, or overlay of one ion across many files.

● Tab 2. Template. Compile analytes of interest into lists of target analytes to be integrated, and save these lists to file. These list(s) will be used to determine the expected retention time and spectra for each analyte (i.e., template retention time becomes “true” retention time).

● Tab 3. Retention time correction. When integrating chromatographic peaks in a complex dataset, it may at times be necessary to identify a target peak in a region of the chromatogram that contains many peaks with similar mass spectra (i.e. co-eluting isomers). TERN selects the correct peak from a set of co-elutions based solely on the closest peak to the expected retention time. It is therefore critical that the retention times of peaks identified in the template match the retention times in other files as closely as possible. This tab is used to identify specific known analytes in each file in order to “correct” expected retention times to be on the same time-basis as the template. This tab is still experimental, so a current user-guide is largely unavailable but will be updated with the next TERN release.

● Tab 4. Peak fitting. Each chromatographic peak of interest is mathematically fit with an exponentially-modified Gaussian function to determine the peak area. Peak fitting can operate via an automated process. The resulting success of this auto-fit is then evaluated by the user and individual fits may receive “tweaks” to improve.

● Tab 5. Peak diagnostics. Used to quality-control the fitted-peak results. Display any metadata that describes peak fitting, such as the coefficients of all fits, or input parameters.

● Tab 6. Calibration. By default, TERN does not provide a mechanism for converting raw peak area to concentration. This is a design decision based on the broad range of instruments using this software for analysis - there are few procedures that are shared by all instruments. Instead, an empty tab is provided for the user to populate. Guidance for doing so is provided in a separate document, and examples are available on the TERN website.

● Tab 7. Display output. Plot time-series and correlations of peak areas.

Tab 0. Initialize/Index/Run Types

When TERN first opens up, it automatically opens up to the “0. Initialize/Index/Run Types” tab, with other tabs disabled. This page is used to load data files, or import files from a common netCDF format and allow TERN to convert to HDF5 (.h5) format and specify a saved location.

Note: If you cannot see all of this page (e.g. some of the text from the bottom of the screen is hidden, and you cannot scroll down), this typically means that your operating system is using a magnified view. Igor is unable to correctly resize panels when the operating system base display is not at 100%. Unfortunately, as screen higher screen resolutions and smaller laptop displays have become common, computers are often run in this mode.

There are two recommended workarounds:

1. Preferred: In the menu ‘Panel’ -> ‘Size’, click on “Make Panel Smaller” until you get the desired size such that you can see everything on the panel.
2. If (a) does not work, open up “display settings” on your computer, and change the “size of text, apps, and other items” to a smaller zoomed percentage. Close and re-open Igor. If the screen is now too zoomed out, use Panel->Size->Make Panel Bigger.’ Using this method will apply across the entire operating system.

i. DAQ file and data system. Defining data formats and instrument parameters

“Format” allows the user to select the type of file to use:

1. “TofWerk” - modern Aerodyne TOF systems
2. “TAG/AMS” - older Aerodyne TOF systems
3. “Other” – any data format other than Aerodyne TOF systems
1. “Signal” is used to select the type of data. The first two options are for unit mass resolution (UMR) data, or to work with high resolution data binned to unit mass
   1. “UMR selected m/Qs (SIM)” – for data that is not continuous for the entire chromatogram (i.e. QMS SIM mode with multiple mass scan windows)
   2. “UMR full m/Qs” – for data where all signals are continuous for the entire chromatogram (i.e. TOF, QMS in scan mode, or QMS SIM mode with a single mass select window, user-delimited files with multiple data channels).
   3. “HR” - high resolution data with signals defined as ions (or fractional masses)
   4. “One channel” – 1-D data such as a flame ionization detector
2. “Setup” identifies parallel channels in your system. Most users select “1 cell”. Select “2 cell” only if your datafiles come in numbered pairs, in other words if two sequential files should be treated as partners; this is uncommon (e.g., Berkeley dual-cell TAG system, which collects the same sample on two parallel cells). If using a 2-cell system, the checkbox indicates whether an even-numbered file is paired with the next odd-numbered file (“evens first” checked) or the previous odd (unchecked).

Note: If you accidentally pick 2 cell and you have already declared your settings, just paste “root:CT:Globals:TwoCell=0” in the command window and it will reset to 1 cell function.

1. Click on “Declare DAQ settings for your system” to store detector information and enable the rest of the panel

ii. Converting instrument data files to TERN format

If your data has been previously converted from its raw format into TERN hdf5 format, this step can be skipped. Otherwise, instrument data files, called the “data acquisition” of “DAQ” files, need to be converted into a TERN-formatted H5 using “ii. DAQ file conversion to HDF”. Note that while Tofwerk data is already stored as H5, this step cannot be skipped for older TofWare file formats (e.g. prior to TofWare 3.x) as the internal structures of older Tofware and TERN H5 files are different.

If file type selected in step i is “Other”, select your file type using the “Convert DAQ files from” pop-up menu. Currently supported file types are:

1. AIA netCDF: standard chromatogram export format CDF files generated by Agilent Chemstation, ThermoFisher Xcalibur, and perhaps others
2. A user-generated tab delimited .txt file. To use this file type, your data must be stored in a file with the following format considerations:
   1. First row is names of data columns (this row is currently not used for anything)
   2. Data is stored as columns separated by tabs
   3. The first column is date and time
   4. The second column is retention time in seconds
   5. All subsequent columns are data of interest. Each column will be stored as one “m/Q”, with starting with the third column as m/Q = 1
   6. TERN requires that one column of data also be assigned the role of total ion chromatogram (TIC) or total signal. In versions 2.2.9 and prior, this position is fixed as the fourth column. In future versions, TIC will be created by summing all data columns.
   7. TERN does not like negative data. If more than a quarter of the data in any column is negative, the 25% percentile of data will be added to all data in that column to bring it up above zero (Note: this shouldn’t impact peak areas, which include background subtraction and so are unaffected by the addition of a scalar)

"Select a folder of DAQ files” identifies the location of the files to be converted (note that this is a separate file location than the .H5 files described below). Select the folder than contains raw instrument files (e.g. .cdf files).

“Convert DAQ files to TERN HDF” will prompt you to select another folder, which is the folder where your TERN .h5 files will be stored. You can store these files in the same folder as the CDF files, but we recommend creating a new folder for them. Note that data files from multiple locations can be converted to .h5 and stored in one location, simply by selecting a new folder and converting more files. Created .h5 files will have the same name as the original datafile, but with the .h5 filetype.

iii. Importing/indexing TERN H5 files

To operate on chromatogram files, TERN must create an index of file names and locations, and a corresponding matrix of the chromatogram data. If you converted files using step ii, TERN will already know which folder contains your .h5 files, and the number of files in this folder will appear next to #HDFs. If you are working with previously converted/existing .h5 files, click on “Select a Folder of HDF files,” and browse to the folder that contains your TERN .h5 files. N.B. - TERN will rely upon this folder location to load your data - if you move files or change the path string, TERN will not know where to find your files!

1. By default, TERN will name your samples the same as their original file names. If you would like a different naming structure, this is available using “Chromatogram ID naming method.” You can use the text box and popup menu to specify naming files as a prefix set of characters, followed by the date and time or an incrementing counter.
2. Click “Index HDF chromatograms” to find and index all H5 files in the folder you specified. Note, once indexed by TERN a file cannot be unindexed. If you must “remove” a file, you can use run types to ignore it later; this is described below.
3. Additional data files can be converted and indexed during analysis, so that the TERN experiment can “grow” as data is collected. All TERN .h5 files must be in the same directory.
4. Note - this functionality broke between 2.1.10 and 2.2.9, will be fixed in the next version. Metadata relating to each run can be imported from an Excel spreadsheet using the “Import auxiliary data” button, so long as one column of the spreadsheet contains file names you imported/indexed into TERN (either with or without file suffix). Imported data will be stored in the data folder “CT:User:” with the name “Aux_XXXXX” (where XXXXX is specified by the user in step a), where each row corresponds to an indexed file in the order indexed.

iv. (optional) TERN panel settings

Various personal display and analysis settings can be modified through “iv. (optional) TERN panel settings”.

[It is not recommended at this time to use any of the three pop-up boxes described below to modify display order; as of 2.2.9 doing so leads to unpredictable behavior in other functions. The code has been patched and is currently being tested, and we expect the next release will repair these configuration settings.]

1) The default display order in pop-up menus of chromatograms, compounds, run-types and templates is creation order (or the order of indexing for chromatograms). This can be modified to another sort order as follows:

1. The order in which chromatograms are displayed can be switched to sorting by alphabetical or chronological order (based upon time of acquisition in the data file).
2. The order in which compounds are displayed can be switched to sorting by alphabetical, retention time, quantification ion.
3. The order in which templates and run-types are displayed can be switched to sorting by alphabetical order.

Note that these functions change display order, they do not rearrange the order of underlying TERN waves and matrices which remain in the order in which they were indexed.

2) The location of the NIST search function is specified by clicking “Select NIST MS application MSSEARCH folder.” This refers to the MSSEARCH folder which contains the search program executable, entering the location of any subfolder will generate an error. If you get an error saying “datafile.txt” cannot be found, see step 5 of Installation above for creating this file (this error is suppressed in versions after 2.2.9).

3) In some cases, certain masses may not be meaningful so may want to be excluded from later comparisons between expected and observed mass spectra (e.g. an air leak causes high m/Q 28 signal, or one mass is present in most or all analytes of interest). These masses can be specified in the “Chrom Peak Fitting Options” box and will be ignored during mass spectral comparisons.

v. (optional) Define, edit run types

The index of data files can be filtered and categorized by “run types” using this section. By default, a run type is created called “allChroms” which contains all imported files. This run type cannot be changed. Subsets of the master data file index can be categorized as a run type. The user can later use these run types to select only the files in these subset(s), and filter which data files are displayed, analyzed, etc. It is an optional, but strongly recommended, feature of TERN analysis.

For example, the user may create a “Samples” run type containing real data, and a “Standards” run type containing calibrant data. Each run type can later be analyzed for a different set of analytes and/or displayed independently. One file can be assigned multiple run types (for instance the run type “Samples” may contain all real data, while subsets may also be described as “Sample Type 1”, “Sample Type 2”, etc.).

1. To create a new run type, select files of interest in the list box by shift-clicking to select or deselect files. can also be used in order to create different subsets of data. Click “create a new….”, which will prompt the user for a name for a new run type that contains the selected files.
2. To add files to an exist run type: first select the run type, then select the files you want add, then click “Assign”
3. To remove files to an exist run type: first select the run type, then select the files you want remove, then click “Unassign”
4. Run types can imported as a batch using the “Load .itx file with run type” button. This requires an Igor text file (.itx) with only two columns - the first column is the name of the original instrument data file, and the second column is the name of its run type. Currently using batch import to assign multiple run types to the same file is not supported.

Tab 1. Explore Chroms

In this tab, the two central plots display data from two files, which are selected using the Chrom 1 and Chrom 2 pop-up menus. Throughout this tab, Chrom 1 refers to the file shown in the top plot and Chrom 2 refers to the file shown in the bottom plot. Checkboxes in the upper right specify total or selected mass/ion data to show for both files, cursor-dependent mass spectra are shown in the lower right, and data from multiple files can be over-layed using the “Simple Chrom Graph Generator” sub-tab.

Selecting files

“Increment Chroms via run type” allows user to select a run type containing the files you wish to explore. To see all files, simply select “allChroms” as this run type, this is default; a different run type can be selected at any time. Selecting a run type will populate the adjacent Chrom 1 or 2 pop-up menu with the list of chromatograms only in that run type, and will load the TIC of the first chromatogram of that run type in the associated plot. Use the up and down arrows next to these pop-up menus to scroll through files, or directly select a file using the pop-up menu.

Displaying total and single ion chromatograms

The total ion chromatogram (TIC) can be displayed or hidden using the TIC checkbox. In addition to the TIC, selected ion chromatograms (SIC) can be displayed using the set of checkboxes in the upper right corner, reproduced below. Up to 8 SICs can be shown at a time, which are displayed or hidden by the m/Q checkboxes, with the mass of each one specified using the value selector, and the color of the trace selected from the pop-up box. Note that at least one trace must be on, for instance TIC cannot be unchecked if no SICs are displayed; in this case the last trace to be unchecked will simply not be hidden/removed. This feature currently initializes to “NaN” in all value selectors, so a mass must be manually entered the first time (i.e. the arrows will not work until a mass is entered).

To zoom in and out of the chromatogram plots, expanding and shrinking can be performed as in a typical Igor plot. To scale or re-scale the chromatogram plots, use the arrow buttons next to the left and bottom axes:

Note: if the buttons do not display as shown above, it is likely that the needed font (e.g. Wingdings, WingDings2) is missing from your operating system. These fonts are typically supplied with Microsoft Office for Windows O/S (see: docs.microsoft.com/en-us/typography/font-list/wingdings). Wingdings fonts can be downloaded for free and installed from various websites – the specific steps will be dependent upon operating system. If you can’t sort this out on your own, please contact us.

Displaying and using mass spectra

Mass spectra are shown on the right side of the panel, again with the upper MS plot corresponding to Chrom 1 and the lower corresponding to Chrom 2. To display a mass spectrum, place cursor A onto any trace, and the mass spectrum for this point in both plots will be shown. To find cursors if not already shown, use Ctrl+I to Show Tools, which should show the tool bar (reproduced below) at the bottom of the TERN panel; if the tool bar is off screen, follow instructions in Setting Up for reducing panel size. Cursors can be placed on traces by dragging them from the tool bar to the trace.

The MS plots will update automatically as the cursor is moved. For instance, using the keyboard arrows to scroll the cursor left or right will scroll through spectra. Four types of mass spectra can be displayed, selected by the four buttons with text under the MS plots, shown below.

MS spectra types

● “A”: Single point MS. MS at the location of cursor A

● “A-B”: Background subtracted MS. MS at the location of cursor A minus MS at the location of cursor B

● “Avg(A,B)”: Average MS. Average MS between locations of cursor A and B

● “Avg(A,B)-BG”: Background subtracted average MS. Average MS between locations of cursor A and B, minus the average of the mass spectra at the locations of cursor A and B. Not generally recommended, tough to interpret/get right

Zooming in on the MS plots can be done as in typical Igor plots (expanding, shrinking, etc.). The perpendicular arrows in the lower left will auto-scale both MS plots to full scale. “Ctrl-A” will not work to autoscale to full axes.

Reading the normalized mass spectra

Mass spectra are normalized to the largest ion. For any mass but the largest, the normalized value is not easily found from the graph directly, since this requires a cursor which is already in use to define the points needed for the spectra. There are two methods to display the normalized masses:

1. Zoom:

If you zoom in on the top of the ion of interest, you can get the value from the y-axis. Then use the arrows button to return to full scale.

2. Secondary cursors

You can generate a second set of cursors for the mass spectra plots. To do this, click on the mass spectra plot area so that a dashed line surrounds it. Then type Cntrl+I twice. The first will hide the tool bar, and the second will restore the tool bar, but now for the mass spectra plots. You can now use those cursors to look up a normalized mass value, shown in the bar.[GI1]

For some purposes, it is more valuable to know the intensity of an ion not in terms of its height relative to the largest ion, but rather in terms of its fractional contribution to the mass spectrum, i.e. all ions in the mass spectrum sum to one. To obtain and print this value for a given ion, use the command line:

root:CT:explorer:MS1 = max(0,root:CT:explorer:MS1) // not needed for “A” style MS

print root:CT:Explorer:MS1[ion-1]/sum(root:CT:Explorer:MS1)

where ion is your ion of interest. Note that this command is for an ion in the top MS plot, while MS2 can be used to refer to the bottom MS plot.

NIST library search functions

To search the NIST library for either spectra, click on the corresponding question mark “?” button; the first “?” button corresponds to MS1, and the second to MS2. This will open the NIST search program and conduct a search. In rare cases, the program opens but the search is not performed, in which case just click the button again.

The image on right shows an example NIST search result. While it is up to the user to determine the identity of an analyte, reasonable guidelines are that matches between 800-900 means that this is very likely your compound. 700-800 means there is a chance that this is your compound, and below 700 means that it is unlikely that the search result is correct.

Overlaying multiple files

TICs and/or SICs can be compared across any number of files using the “Simple Chrom Graph Generator” sub-tab. To do so:

1. Select a run type in the left list box, OR, select a set of chromatograms of interest in the main list box showing all file names
2. Use radio buttons to select to overlay either TICs or SIC, in which case the mass is defined with the value selector.

Click either “Plot in external graph” to display a new graph, or “Append to top graph” to add this data to an existing graph (Note: this will not update the legend with the new traces, so you’ll need to keep track of things a bit yourself).

THE FOLLOWING FEATURE(S) WILL BE AVAILABLE IN VERSIONS AFTER 2.2.9.

To calculate the area of a peak without going through the full quantification workflow, the user can choose to use the “Quick Area” functionality at the bottom of the panel, shown below, which will print the command window the area of a peak

To do so, place cursors A and B on a trace on either side of your peak of interest. Clicking the Quick Area button will print the area. Area is calculated as the total area between A and B (i.e. Igor function areaXY(retention time, SIC, X_A,X_B), minus the baseline area (calculated as the area of the trapezoid defined by A and B, i.e.:

In cases of noisy baselines, a single point definition of the baseline area is likely insufficient, instead multiple datapoints can be averaged to estimate the values of and; the number of points used to calculate this average is defined by the user using +/- X pnts value box. For example, +/- 0 pnts uses the exact value at cursors A or B as the baseline, while +/- 2 pnts averages from the 2 points before the cursor through the 2 points after the cursor. Example output is shown:

"Sample_006 m/Q 57 area: 1.532e+06 from 785.13 to 790.30 +/- 1 pnts"

Note that the returned integration start and stop points are reported in seconds.

2. Make/Edit/Add Template

In TERN, a template is a list of analytes (compounds or unnamed peaks) that will be searched for and peak-fitted in the chromatogram data. The template contains a list of analytes with unique names, and attributes that describe the analyte (i.e. retention time, quantification ion, etc.). Multiple templates can be used in an experiment, combined into a “master template” that contains all analytes. This provides flexibility to break up your analytes of interest into related compounds that can be analyzed independently or added to multiple analyses.

For example, you may want to create a template containing all internal standards, and apply this to any dataset collected by your instrument, as well as templates containing dataset-specific analytes or analytes of specific functional groups, or templates for typical calibrant mixtures. Then, when analyzing a dataset of vehicle emissions, you may add the internal standard template, a template of alkane standards, and a template of other hydrocarbon analytes for which you don’t have authentic standards. For a dataset collected in a forest, you may add the same internal standards template, the same alkane standards template, an additional template of biogenic standards, and a template of biogenic analytes of interest for which you don’t have authentic standards.

There are three primary considerations in generating templates:

1. Currently, compound names are used as the compound identifier and must be unique across all templates added to the analysis. You cannot have a standards template with a compound named “decane”, and an analytes template that also has a compound labeled “decane”. Instead, we recommend only creating one listing for any compound of interest, i.e. doing all analysis of “decane” in your standards template and not including it in your other template(s). Alternatively, you can add a suffix or prefix to the compound name (e.g. “decane_std”, “decane_amb”) but this would result in separate data waves for the same compound.

2. Retention time of an analyte is based upon the chromatogram file being used to make the template. Since there is no objective retention time, the chromatogram used to make the template is by nature the “true” retention time, and all other files need to be brought to this time basis. This means that while multiple files can be used to make a template or templates, it is critical they all have similar retention times.

3. Once a template has been added to be used in an experiment it can be removed from the experiment, or edited, etc., so adding a template is not a one-way street. However, in versions 2.2.9 and earlier, the stability of some of this functionality is poor; it is substantially safer to add templates and compounds than remove them. Save experiments before attempting to remove templates, and if possible, choose to simply ignore unneeded compounds or templates rather than removing them.

We recognize that these three items are inconvenient to TERN users and are hoping to develop an alternative template structure in future releases (TERN version 3.x).

• Compound name (“CompName”) - must be unique across all analytes applied to the analysis
• Retention time (“RT”) - retention time in seconds of the analyte in the chromatogram used as the basis of the template
• Quantification ion (“QuantIon”) - the ion used to integrate and find the compound
• Internal standard flag (“ISFlag”) – 0 = false or 1 = true, is this compound an internal standard to be used for retention time correction?
• Qualification ions (“QualIons”) - ions other than the quantification ion that can be used support the identification of the analyte. These ions are either expected to be present in the analyte mass spectrum in some known relative quantity, or are expected to be absent (used to filter an analyte of interest from a known nearby co-eluting compound containing different ions); these ions will auto-populate by abundance in the mass spectrum
• In addition, the spectrum of the template analyte is stored, as well as some metadata related to collecting this information

It is important for the user to realize that template functions in TERN should be divided into two separate actions. This is indicated on the Template tab interface by the two grey-outlined boxes that surround the interface components. The left side of the interface is used to build and edit the analyte lists that constitute a template. The right side of the interface is used to apply templates – the sets of analytes – to the TERN experiment.

Make/Edit a single template

To generate templates, the upper half Tab 2 behaves as a pared-down version of the Tab 1 Explorer. It is centered on a plot of a user-selected chromatogram and the associated MS to the right. Functionality of the chromatogram and MS plots are similar to that of Tab 1. The major difference is that instead of 8 SICs, only two can be shown: the “Quant ion” SIC (blue) which stipulates with ion will be used for as the quantification ion of this analyte, and an “Other SIC” (orange) which serves simply as an additional SIC for the user to better explore the chromatogram.

An example of an active Tab 2 chromatogram plot is shown below:

The bottom and right plots, tables, and buttons are related to template building functionality and are described below.

Creating a new or modifying an existing template

To generate a new template, click “New” in the upper left. You will be prompted to select the chromatogram to be used as the basis for your template, which will be populated in the “Chroms” textbox.

To open an existing template, click “Load” in the upper left. You will be prompted to select a template, then all appropriate textboxes and tables will be populated.

The chromatogram being used as the template basis can be changed by clicking the “Edit” button next to “Chroms”. Other information (template name, file location, description) can also be edited in similar fashion.

Adding and editing template compounds

A compound will be added based on the location of cursor A in the chromatogram plot, using the “quant ion” mass as the quantification ion.

To add an analyte to an open/new template, use the “Add compound” button:

1. Select the quantification ion of interest. This is an art; for a given analyte you want to select an ion from the mass spectrum that is both large and unique. Small ions will suffer more noise, while non-unique ions will result in more co-elution and poorer peak resolution.
2. Place cursor A at the peak of the analyte of interest.
3. Obtain the cleanest possible mass spectrum, e.g. by background subtraction using cursor B. The MS obtained here will be saved as the “known” MS of the analyte in the template and used for all future quality control
4. Click “Add compound”. Answer the subsequent prompts regarding compound name, identification as an internal standard for retention time correction, and description, as shown below.
5. Note that the lower MS plot is populated with the mass spectrum of the added compound. This will be the reference spectrum for this analyte.

To edit existing compounds, select the compound you wish to edit from the list of compounds. If the checkbox “Move top two plots…” is checked (default), the chromatogram and MS plots will shift to the selected compound. Once a compound is selected, move cursor A to the correct location for this compound, and click “Edit compound.” A pop-up menu with prompt the user to select which compound to edit, with the default being the selected analyte, followed by a prompt to change information about a compound.

Critical note: retention time and mass spectrum will be changed to the location of cursor A; for this reason, it is recommended to (a) not edit compounds other than the one selected in the table, and (b) keep the checkbox “Move top two plots…” checked. (Note: a known bug in editing the quantification ion may impede this functionality in rare datasets).

To remove an existing analyte, select the compound you wish to remove from the and click “Kill compound.”

Saving templates

Once all analytes of interest have been added to the template, the template must be saved so that it can be used in future steps. First, give the template a name, otherwise it will not save.

Click on the edit name button at the top of the page and add the name for the template.

To save a template without applying it to this experiment, click “Save”. The folder where template will be saved to can be identified prior to saving by clicking the “Edit location” button

or if left blank the user will be prompted by the save function for a location. It is recommended to store all templates in one location to facilitate future editing of templates and compounds. The user will also be prompted for a description of the template.

Using templates

To use a template in the experiment, click “Save & Use.” The template will go through the save procedure described above, then be applied to the experiment (i.e. added the master template). The below window will appear.

This window shows you the number of new compounds you are creating and it tells you if you have any conflicting compounds. TERN does not let you create multiple compounds with the same name, as discussed above. If you have a new compound with the same name as an existing compound, you can use this panel to change the name. Once you have reviewed your compounds and have no more conflicts, click on the yellow box that says “proceed with changes, save and use active template.” This will save the template and show it on the right side of the main Template panel.

Clicking on a template name in upper list will populate the lower list box with the names of compounds stored in this template. To remove a template from this experiment, select the template and click “Kill”. As noted above, the stability of this functionality is uncertain; always save before attempting.

To edit a template, click “Edit,” which will load the template and allow the user to makes edits, then click “Save & Use” to apply these changes. Note that changing the name of a compound through this route will “orphan” it - TERN has no way to equate the changed name to the new name, and it will delete the old compound and add the new one, erasing any peak fitting or analysis you have done; to avoid this issue, use the “Rename one compound…” button.

In the case of a name conflict between a previously applied template, or to change the name of a compound without orphaning it, select the compound to change. Click “Rename one compound…”, which will prompt the user for a new name. This will re-load and re-save the relevant template, but will also change the compound name within the experiment, allowing TERN to keep track of the change and not delete existing data.

Tab 3: Correct Ret. Times

As discussed above, templates inherently describe analytes by their retention time in a given chromatogram. Changes in retention time between runs can result in incorrect peak identification, degraded automation of peak finding and fitting, and other errors. It is therefore critical to carefully “correct” all retention times back to the time basis of the template chromatogram.

The processes by which retention times are corrected can be highly instrument or operationally specific. For instance: Is there an internal standard applied to every sample? If not, are there constantly-present analytes that can be used instead? Do different run types show different retention times (e.g. humid vs dry samples)? Are there discontinuities in the chromatogram due to valve switches, etc.? For this reason, TERN provides a default retention time correction panel, but recognizes the need for users to create their own panels. Examples of how to create individualized panels will be provided in the technical document “Customizing TERN Panels” (not yet available).

Due to the current flux of this panel as we move to build the most broadly useful default panel, no manual is yet available for Tab 3.

Tab 4: Chrom Fitting

The crux of TERN as a quantification tool is the fitting of idealized mathematical peaks to chromatographic data to accurately and reproducibly calculate the area under each peak. The concepts, advantages and technical details of this approach are described in Isaacman-VanWertz et al., Journal of Chromatography A, 2017 (doi.org/10.1016/j.chroma.2017.11.005).

Getting oriented

There are several general regions of this panel:

● Navigation (top right) controls in the upper right allow the user to select which chromatograms and compounds to manually work on

● Data plots (left) show the quantification ion chromatograms of up to 10 sequential files

● Fitting parameters (lower right) vetting and adjustment across the center provide the fit inputs and outputs for the currently selected peak

● Fitting feedback plots (upper right) in the center provide qualitative data on the goodness of the fit (residual, MS matching, etc.)

● Fitting selection (bottom right) in the lower center allows the user to select which set of chromatograms and compounds to fit

● Peak results (bottom right corner) in the lower right provides the quantitative peak area and any errors

Navigation and data display

The navigation controls shown below allow the user to select which subset of chromatograms and compounds are being analyzed. Here the user selects which run type to work on (“allChroms” means all indexed chromatograms), which template to work on (“allComps” means all compounds in the master template). Under these pop-up menus are pop-up menus specifying exactly which chromatogram and compound is displayed, as well as information about the compound (on the right) and the ability to “Hop” ahead to compounds that fail specific quality control checks such as failed automated fitting. Scrolling through compounds within a template is done with the left and right arrows on either side of the compound pop-up menu.

Once a chromatogram and compound are selected, the data plots will be populated as shown below. Ten plots show the SIC of the compound quantification ion of the selected chromatogram, along with the previous five files, and the next four files. The selected chromatogram is in the center right, with a vertical axis bolded. The ten files are presented in a “Z” fashion - file 1 is in the upper left, file 2 at upper right, file 3 on the row below and on the left, etc. until file 10 is in the lower right.

In the example below, the active file is Spot_07a, the next file in the sequence is Spot_07b, then Spot_08a, etc. To scroll through files one at a time, use the single arrow buttons; to scroll by ten files at a time (one “page” at a time) use the double arrow button. [Note: In the “2 cell” setting, the single arrows scroll by 2 at a time to keep pairs together. To swap the left and right columns in this mode, use the left-right bidirectional arrow on the left side of the navigation controls.]

By default, only the quantification ion is shown in the plots. One additional SIC can be added to the plots using the “Other SIC” function in the navigation controls. The dashed green line indicates the expected retention time of the selected compound.

Many keyboard shortcuts exist to assist in navigation and peak fitting. Using the shortcut keys can greatly improve the efficiency of performing analysis with TERN, and it strongly encouraged. Some of these are provided at the top of the panel and shown below.

Others are provided in parentheses on their buttons, menus, etc. For most of these shortcuts to work, the mouse focus must be on the data plots. This is shown via a dashed box drawn around the ten data plots, as shown above.

A keyboard map and table summarizing all shortcut keys during peak fitting is available on the TERNinIgor website at:

sites.google.com/site/terninigor/software-manual/chrom-fitting-shortcut-keys

Peak fitting basics

To fit the selected chromatogram and compound (the “active” peak), click the big green “Fit” button or press spacebar. By default, this will fit only the active peak, using the automated peak fitting algorithm and default input parameters.

If a peak is found, a blue fit peak will appear on the active plot, and the feedback plots will update, as in the example below:

In the lower feedback plot, raw data is shown in black with markers, and the fit is shown in blue. The difference (residual) is shown in red, as well as a quantitative estimate of the percentage of signal variance not accounted for by the fit. Note that this calculation incorporates the S:N ratio and baseline variability, and therefore won’t be very small (e.g. <1%) unless the peak height is much larger than the baseline signal shown in this example. This is a qualitatively good fit, with small residual and no clear “structure” to the residual but rather flat noise, suggesting a fitted peak that well-describes the measured signal. On the right, the expected MS stored for this compound in the template is shown in black, and the MS at the peak of the fit peak is shown below in blue.

The summary results of the fit are shown in the lower left of the panel, with a (different) example shown below. Results include the area of the fitted peak, any error codes associated with the fit and their meaning, the full-width at half-max of the fitted peak (a measure of chromatographic peak width), and a quantitative comparison between the found and expected mass spectra. The correlation coefficient is shown for both the comparison between the complete mass spectra (“all ions”) and only the ions specified as qual ions; note the higher correlation coefficient in this example in the qual ion case, suggesting the found pick has the appropriate ions, but also has many other unexpected ions and may suffer a co-elution or be a structurally related compound but not the expected one.

Peak fitting with the default values tends to provide reasonably good results across many peak shapes and widths and always improving [see Isaacman-VanWertz et al., 2017 for more info]. However, it is not uncommon that either a fit is poor, or that the algorithm is unable to find and fit the peak. In this case, the user may alter or “tweak” the fit by adjusting the fitting parameters. This is a bit of an art, so a separate document is available to guide the user in doing so (available here but not yet complete):

https://docs.google.com/document/d/1NW9wrkNK8xsOYdbPnlGbjqV2Xb9-v3g8omOIT9GqO1o/).

In brief, the user can first alter the input to the automated fitting routine. The most common correction is to correct the retention time - a small 0.5 or 1.0 second shift can greatly improve the fit. Use the RT offset or left and right arrows for this fix.

The next most important change is to enter an estimate of the peak width (FWHM) in the “additional vetting” window. This helps TERN to filter out peaks that deviate significantly from the expected width of the peak. Note that peak width is effectively independent of peak height.

Other alterations to the automated fit include: the width of the fit window (10 seconds by default), the relative fractional height below which a peak is ignored (0.05 is default), the baseline type (linear is default), the distance from the expected retention time that a peak can be considered acceptable (RT max delta), and the acceptable height above the noise.

Where baseline appears to be the issue (i.e. constant, linear and cubic functions are unsatisfactory), baseline estimation “Via smoothing” may be helpful.

When no changes to the automated routine are successful, the user may manually “tweak” the fit by clicking on the check box next to “Tweak (t)” or pressing the “t” key, and then specifying the smoothing factor, data noise, and whether to account for tailing or fronting in the peak (i.e. whether the idealized Gaussian peak needs to be “modified” with an exponential term).

When tweaking and altering fits is still not successful, the user has two options. “Allow non peakfit (n)” tells TERN that if it finds only a single peak, to forgo any peak fitting and rather integrate the peak via a simple baseline estimate. Alternately, the user may select the baseline type “Hand draw BL”. As soon as this baseline type is selected, the cursor will change to allow direct interaction with the active plot - the user can draw a line where the baseline should be (if you are too slow, it will time out, just try again). [Note: Hand draw BL functionality is limited or non-existent in versions 2.2.9 and before and has been corrected in future versions. It you would like to use it in the older versions, be aware that the function can “hang” and freeze Igor. To regain control, simply enter a break command from the keyboard (e.g. Command+Break)]

Note that adjusting the peak fit window (using the w,W shortcut keys) is independent of adjusting the width of plot that is displayed (using the x,X shortcut keys), which is adjusted using the “X-axis delta” value adjustment. Also, the total peak fit window width is limited to 40 seconds, so increasing the data window delta to values larger than 20 sec provides no additional benefit.

To remove a fit from the active peak, press “delete”, or make any change to the input parameters, which will clear the fit.

Peak fitting in batch

While fitting individual peaks is reasonable for small datasets, it is typically more efficient to get a “feel” for the best peak fitting parameters, then fit a compound in a batch, either for the entire run-type, or even for all chromatograms. A large range of subsets of chromatograms and compounds can be fit en masse by selecting one of the radio buttons before clicking the “Fit” button. These are fairly self-explanatory, but as examples:

● To work on only the active peak, select the default “current” compound (shortcut 6), “current” chromatogram (shortcut 1)

● To fit the active compound in all files, select “current” compound (shortcut 6) and “all” chromatograms (shortcut 5)

● To fit the active compound in the 10 chromatograms in the display plots, select “current” compound (shortcut 6) and “all shown” chromatograms (shortcut 2)

● To fit all compounds in a template and run type (for instance, all calibrants in a run type that contains your standards), select “all in temp” compound (shortcut 7) and “all in run type” chromatograms (shortcut 4)

During batch runs, all peaks start with default fitting parameters as discussed above. However, if altered or tweaked parameters are found to work better for a compound, these same radio buttons can be used to assign the fitting of the active peak to all selected compounds and chromatograms by clicking “Set non RT params to sel. chroms”. Similarly, if there is a systemic offset in the correct retention time for a subset of chromatograms, this can be set en masse with the “Set RT offset to sel. Chroms”. If a batch of peaks is found to have a bad fit, they can be clear by clicking “Clear fit results of sel. chroms”

When working on batches of chromatograms, it is often helpful to declare which peaks have been already quality controlled and approved, and which are still open for alteration. To approve the selected subset of chromatograms and compounds, click “Lock sel. chroms”, which prevents any future operations from altering or any way changing the fit. This was previously referred to as “approving” fits. This can be undone with “Unlock sel. chroms”. Locked/approved peaks are shown in green instead of blue.

Tab 5: TERN Diagnostics

A major benefit of peak fitting over traditional hand-drawn baselines is that quantitative parameters describe the fit, which can be used to improve quality control. Tab 5 allows the user to see time series of all fit parameters and metadata.

Once a run type, template, and compound have been selected, the “Parameter” pup-up menu will be populated with all available graphable parameters. These can be plot on new plots, or appended to existing plots based on the radio buttons. (Uncommon: Elution region value selector is used if multiple elution regions have been defined in during retention time correction)

A wide range of parameters are available to be plotted. Some of the most likely useful ones include:

● PeakFitOutputParams_Coef1: center of the fit in seconds

● PeakFitOutputParams_Coef2: width of the fit in seconds

● PeakFitOutputParams_Coef3: height of the fit in detector signal

● PeakFitOutputParams_Coef4: decay coefficient of exponentially modified Gaussian fits

● PeakFitOutputParams_FWHM: full-width at half-maximum of fit in seconds

● PeakFitDiagnosticsErrors_msCorrAllIons : correlation coefficient between expected and found MS (all ions)

● PeakFitDiagnosticsErrors_msCorrQualIons : correlation coefficient between expected and found MS (qual ions only)

● PeakFitDiagnosticsErrors_Error : fit error code

For example, if you select “PeakFitDiagnosticsErrors_msCorrAllIons”, you can view how well the MS of each fit correlated with the template MS. An example is shown below. Values near 1 indicate high correlation (likely correct), and low values suggest incorrect peaks have been identified and highlight data that should be manually inspected or rejected.

To inspect a suspect peak, the user simply moves the A cursor to a point on the plot and selects one of the buttons above the plot to bring up the time series in the explorer tab, or the peak fir in the ChromFit tab, respectively.

Tab 6. Calibrations

This tab is reserved for user functions that convert peak areas to concentrations. Because this step is specific to the instrument and analytic process, we currently leave this tab unpopulated.

The Virginia Tech group (GIVW) uses this tab for conversion of their data. In the future, they will provide sample procedure files and a manual for customizing this panel in the technical document “Customizing TERN Panels.”

Tab 7. Results

Uncalibrated peak areas of a given compound can be plotted as a function of time, or correlated against other compounds.

Select a template and compound, as well as a run type. Peak areas of the selected compound can be plotted - by selecting radio buttons - as a time series by acquisition time, diurnal “diel” using acquisition time as the binning axis, or correlation against any other compound in the experiment.

Leave the “calibrated/corrected” checkbox unchecked – this is reserved for results from Tab 6.

To plot only locked/approved fits, check the “Approved only…” checkbox. This functionality not yet active in versions 2.2.9 and prior, but will be active in the next release.

Click “Plot this” to plot. In versions 2.2.9 and prior, masking by run type is non-functional, corrected for future releases.

At this time, it is not recommended that you use the “Import…” buttons/region.

To export peak areas as a CSV, click “Export…”. Note: due to a bug in version 2.2.9 and prior, this will export only approved/locked peak areas. This has been corrected for future versions. Export format is:

● First row is compound names

● First column is acquisition time as day of year

● All data are otherwise in this matrix as comma separated values