Lutefisk1900 Operators Manual

LutefiskXP v1.0.5 Operators Manual

Documentation updated Aug. 26, 2005
Copyright © 2005 Rich Johnson (jsrichar@alum.mit.edu)
All rights reserved worldwide
Lutefisk Homepage: lutefiskxp.sourceforge.net

Table of Contents
Overview Lutefisk files Compilation notes Contact information Version history

Overview

Lutefisk is a program for the de novo interpretation of peptide CID spectra. While it has a rudimentary interface, it can be compiled for virtually any operating system with a C compiler. [Source code and instructions are provided for MacOS, Win32, OSF, Solaris, Irix, and Linux.].

Lutefisk can be used in conjunction with homology-based database search programs (e.g., OpenSea, MS-BLAST, or CIDentify) as a supplement to standard MS/MS database search programs. We use it to find modified peptides or sequence variants, as well as to help validate the results obtained from database search programs (e.g, Mascot, Sequest, etc). We also find it useful for flagging high quality data that the search programs (Mascot, etc) fail to identify, which may be due to a variety of reasons (searching a human protein sequence database for an MSMS spectrum of a mycobacterial derived peptide, for example).

Lutefisk Files

To run Lutefisk, you need to have four files within the same directory or folder:

1. CID data file (data files can be specified with a full or partial pathname)
2. Lutefisk.details
3. Lutefisk.params
4. Lutefisk.residues

One additional file is optional:

1. Database.sequence

Once these files (containing the appropriate information as described below) and the Lutefisk application are gathered together in one folder, you start the application. Once execution begins, Lutefisk proceeds with minimal user intervention.

On a Mac, a single dialog box appears where you can specify a variety of command line arguments (if interested type -h to see help); in most cases, you will click on the "Ok" button and use all of the default values. On Windows, there is no such dialog box; however, command-line arguments can be implemented by starting Lutefisk from the Command Prompt program supplied with the Windows operating system.

A simulated teletype interface appears and indicates the various stages of processing that have been achieved. When it is finished, the teletype interface provides an initial list of sequences ranked in order of the "intensity score", followed by a more refined and shorter list of sequences. This short list of sequences is also placed in a file with the default name identical to the CID data file name with ".lut" appended. The header to this file contains the information found in the parameter file "Lutefisk.params".

Note regarding use of Lutefisk with CIDentify: The output file can be read directly by the modified FASTA program called CIDentify. If you don't like Lutefisk, you can still use CIDentify without using Lutefisk. This can easily be done by editing a Lutefisk output file so that it contains your own sequences (determined by hand or another sequencing program). Alternatively, you can obtain the CIDentify source code and modify the data input format to suit yourself. It is also worth pointing out that the Lutefisk output file can be edited in order to eliminate any sequences that you somehow know are incorrect.

CID data files

Lutefisk can read CID data files in four different formats:

1. ASCII files created by the Finnigan TSQ program called "List". These are created by starting the "List" program within ICIS Executive" and opening the data file of interest within "List". Under the "File" menu, go to "Print...". A dialog box appears wherein you select "ASCII" as the saved formats, and under "Text Displays" select "Multiple Pages". Provide a file name and select the "Save to File" button (don't select "Print" or else you will have reams of scratch paper).
2. ASCII files created by the Finnigan LCQ File Converter program. From the destination box select "text" as the format, select the LCQ .raw files to convert, click on the arrow button, and then click on the convert button.
3. Tab-delineated ASCII text files. The first column contains m/z values followed by a tab and the second column is unitless relative intensity (an example is shown on the web site).

For any of these first three formats, the data can contain profile data with multiple data points per mass unit, or it can be centroided (or peak top) m/z values.

4. In addition, Lutefisk can read the Sequest ".dta" files; for ".dta" files "C" should be selected for the parameter "Profile or Centroid" found in the Lutefisk.params file (see below). This is our favorite data file format, since our Micromass Qtof and Thermofinnigan ion traps all have software that converts raw LC/MS/MS data to dta files.

Lutefisk.details

The Lutefisk.details file contains the so-called "ion probabilities" for each type of ion. Here is an example. Each column in the file contains the "ion probabilities" for different fragmentation patterns (see the description of "fragmentation patterns" below). Currently there are only two types of fragmentation pattern that have been coded, which is for low energy CID of tryptic peptides on triple quadrupole (or Qtof) instruments or ion traps, and these ion probabilities are listed in the second and third columns. The first column is not used (oddly enough).

Lutefisk.residues

The Lutefisk.residues file contains the single letter code, monoisotopic masses, average masses, and nominal masses for each amino acid. The default Lutefisk.residue file is shown here. To add an additional residue to the list, replace the 0's in one of the rows w/ the corresponding monoisotopic, average, and nominal masses. Up to five additional non-traditional residues can be entered here, and will be given the single letter code of J, O, U, X, or Z. Also, if you don't like my masses for the usual amino acids, you should feel free to change them here.

Database.sequence

The Database.sequence file is a text file containing a sequence or a list of sequences that might have been derived from a sequence database search. An example of such a file is shown here. Although this seems like one is giving Lutefisk the answers up front, in fact, Lutefisk will do its usual de novo sequencing regardless of the Database.sequence list. In the final steps, where it determines scores for the candidate sequences, Lutefisk tosses in these database-derived sequences along with the de novo sequence candidates to determine if the database sequences are as good as or better than the de novo sequences. If so, then this constitutes evidence that the database derived sequences might actually be correct.

Lutefisk.params

The Lutefisk.params file is where most of the user-selected variables are altered. Once appropriate parameters have been chosen for a given set of data, one usually needs to change three parameters -- "CID Filename", "Peptide MW", and "Charge-state" (of the precursor ion). If the CID file is in the "dta" format, the latter two parameters can be automatically read from the file header and invoking the program like 'lutefisk <dta_file>' will override all three parameters with those in the specifed data file(s).

Certain parameters need to be changed to accommodate data obtained from different instruments. The mass tolerances should match the anticipated errors for each type of instrument. The tolerance parameter "Final Fragment Err" should be set to zero unless the data was obtained from a Qtof, in which case, it should be a value of 0.02 - 0.05 ( I currently use 0.04). The "Peak Width" parameter should be set to 1 for unit resolved data (ion trap), and 0.75 for higher resolution data obtained from a Qtof. Triple quads are often run in a low resolution mode to enhance sensitivity, so the peak widths might be 2-3 u. For less than unit resolved spectra (triple quad, say) set the "Transition Mass" to 1800. This is the mass above which average (rather than monoisotopic) masses are used in the calculations; for unit resolved or better data, set this high (5000) so that average masses are never used. Since fragmentation patterns are slightly different for triple quads, ion traps, and Qtof's, set the parameter "Fragmentation Pattern" accordingly. Finally, the parameter "Auto Tag" should be set to N for ion trap data, and Y for Qtof or triple quad data. Here are the parameter files I use for data obtained by LC/MS/MS using an ion trap, and LC/MS/MS using a Qtof.

Here is a more complete description of the Lutefisk.params file parameters.

Output files (.lut)

The header repeats the information contained in the params file, and also lists several scores that need some explanation. The candidate sequences are ranked according to Pr(C) which is the estimated probability of being correct. I find that values over 0.5 are worth submitting to a homology-based sequence database search program, and anything over 0.8 is particularly worthy of serious consideration. Pr(C) is calculated from an empirically-derived 2-order polynomial fit to a weighted average of the four remaining scores (Pevzscr, Quality, Intscr, and X-corr). Pevzscr is an adaptation of the ideas presented by Dancik et al (J. of Comput. Biol (1999) Vol 6, 327), which is a score that penalizes for the absence of expected ions and accounts for the possibility of random matches. Quality is the percentage of the peptide mass that can be accounted for by a contiguous ion series. Intscr is the percentage of the fragment ion intensity that can be accounted for as b, y, internal fragment, etc, ions. X-corr is the cross-correlation score that has been normalized by its auto-correlation score.

If "Mass Scrambles for Statistics" in the params file was used, then the bottom of the output file contains a summary of the statistical analysis. The first column "1st ranked" lists the un-normalized scores for the top ranked sequence. The column "St Deviations" shows how many standard deviations the top ranked sequence scores were compared to the average wrong scores. The column "Average Wrong" lists these wrong score averages, and the column "Correct/Wrong" shows the ratio of the top correct score versus the wrong score. Currently, I don’t recommend using this, so just give a zero value for the parameter “Mass Scrambles for Statistics” (lutefisk.params file).

Compilation Notes

See the 'README' file for compilation information.

Unix/Linux:

After untarring the archive, copy the makefile for your system to "Makefile". Use the "make lutefisk" command.

Win32:

Current Metrowerks Projects are included in the "Win32" folder. If you have an older compiler you will need to create a new "C Console App" project and add the source files as specified in the '0_ReadMe' file.

Macintosh:

Current Metrowerks Projects are included in the "Macintosh" folder (provided as a self- extracting archive to maintain fidelity). If you have an older compiler you will need to create a new "Std C Console PPC" project and add the source files as specified in the '0_ReadMe' file. Set the preferred heap size to 16M, the minimum heap size to 8M, and the stack size to 512k.

Contact Information

Lutefisk is software for de novo sequencing of peptides from tandem mass spectra.

Copyright (C) 1995 Richard S. Johnson

This program is free software; you can redistribute it and/or

modify it under the terms of the GNU General Public License

as published by the Free Software Foundation; either version 2

of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Contact:

Richard S Johnson

4650 Forest Ave SE

Mercer Island, WA 98040

jsrichar@alum.mit.edu

Version History

LutefiskXP version 1.0.4 – External release

· When Q is in the second position, then a c1 ion is present. It is now scored, and used to distinguish the two amino acids if they are not already.

· Limits placed on the number of subsequences (drops by half) if the program has been processing for over 30 seconds. It drops by another half if the processing is over a minute. This will speed long ones up.

· Limits placed on the deconvolution of the C-terminal unsequenced chunk of mass (in Haggis). If the overall processing has gone on for over 45 sec then it drops the mass to 600.

· For LCQ data, b/y pairs are found and labeled as "golden boys" that cannot be gotten rid of as easily. These could also be considered "favored sons", although we can all hope that the favored son "W" is eliminated in November (post-election news: sadly the favored son is still in DC).

· Fixed the ranking so that the db derived sequences don't fowl up the rank numbering.

· Fixed a bug that, in certain cases, produced negative values for summed residue masses displayed within brackets

· Changed the LCQ b/y pair procedures (both in GetCID and main) such that pairs were either both singly charged, or one was singly-charged and the other doubly-charged (but only if the precursor is > 2 charge state).

· Changed Haggis a bit so that the minimum number of edges required to be considered a sequence varied with the number of Lutefisk sequences already obtained as well as peptide molecular weight. Minimum stayed at 4, but could be higher.

· Changed Haggis so that if the array capacity was exceeded, it dumped the results obtained with the Lutefisk sequences and then continued to run (rather than exit(1), which is a waste).

· Changed the way the ion intensity is altered in the final scoring. The high intensity ions are reduced, but the low intensity ones are not increased

LutefiskXP version 1.0 – External release

· The Haggis sequencing was modified so that two ion series could be combined.

· The Haggis sequencing was modified so that the two unsequenced masses at either end could be matched to randomly

· derived sequences. The random sequences that fit with the most b and y ions is saved and replaces the chunk of mass.

· Added two output variables to the params file. Now can specify the number of sequences and their Pr(c) limit.

· Modified final scoring slightly, such that "quality" has less of an influence.

Lutefisk1900 version 1.3.8 - Internal release only

- Changed final scoring of candidate sequences. About 150 spectra from both LCQ and Qtof were examined and sequence candidates with particularly high or low values for Pevscr (pavel pevzner), Intscr (intensity based scoring, quality (fraction of peptide mass accounted for by contiguous ion series) and xcorr (cross correlation score) were retained or discarded. An average of these four scores was calculated and an emperically derived probability of being correct was determined. The output is an estimated probability of being correct (Pr(c)).
- Looks for pairs of y/b ions to re-determine the peptide MW in LCQ data.

Lutefisk1900 version 1.3.7 - Internal release only

- Made it so that the y1 and y2 goldenboy ions could not be removed on the basis of their intensity.
- Added the Haggis type of subsequencing. This finds series of ions connected by single amino acids, makes two sequences (forward and backward), and adds it to the list of sequence candidates.
- Changed the "fuzzy logic" bit in LutefiskScorer so that mass variation from the calculated values have an affect on ion scores in a manner that follows a normal distribution (instead of a linear drop off).

Lutefisk1900 version 1.3.5 - Internal release only

- Changed the way that the N- and C-terminal masses are entered. Now it is possible to provide any mass rather than specific ones.

Lutefisk1900 version 1.3.4 - Internal release only

- Fixed a buffer overflow problem in PeptideString() caused by long peptides.

Version 1900 1.3.2 – Released 1/28/02

- Revamped command-line invocation to be more intuitive. Now can say 'lutefisk *.dta'
- The '-q' flag now completely quiets STDOUT output.
- Fixed bug in GetCID so that plusArgLys array is initialized properly
- Set limits on "quality" and final combined scores, below which the sequences are trashed
- Minor change in final scoring of database-derived sequence
- Changed LutefiskScore so that when Qtof sequences are expanded, any given original sequence can only generate 250 new ones. When doing this procedure using the wrong peptide mass (statistical analysis) the program is limited to 50 new sequences for every old one.
- Various minor bug fixes to aid compilation on some systems.

Version 1900 1.2.9 - Internal release only

- The quality score from v1.2.8 is now used for screening candidate sequences. A minimum quality score is determined from the highest quality candidate, and candidates below this minimum are tossed out.
- Various bug fixes.

Version 1900 1.2.8 - Internal release only

- changed the cross-correlation scoring so that instead of subtracting the average value of tau from -75 to 75, it does a point by point subtraction of the two numbers on each side of tau, takes the absolute value, and sums this over the range of -250 to 250. In other words, it subtracts tau(250) from tau(-250) and adds that to tau(249)-tau(-249), etc. This value is subtracted from tau(0) to give the cross-correlation score.
- changed the normalization of the cross-correlation score so that it is normalized to the auto-correlation of the spectrum itself (after the funny intensity normalizations).
- The program can determine best scoring sequences for incorrect peptide molecular weights. It determines the best sequences for MW +/- 14xN where N is any number from zero to 20 (or more if you want). It determines an average best wrong score and standard deviations around the mean, and then compares this with the best score for the correct peptide molecular weight. This allows for a statistical evaluation of the Lutefisk1900 results.
- Because of all this looping, I found some memory leaks (fixed).
- Found a place where peptides exceeding the allowed length were stomping on some memory.
- Added a spectrum quality assessment following completion of the sequencing. Its based on Pavel Pevzner comment that quality = #y or b ions / number of possible y or b ions. In practice, lutefisk will find the longest contiguous stretch of uninterrupted y or b ions and divide this by the (total number of amino acids minus one). A dipeptide in the sequence is not counted as an interrupted series; however, the dipeptide counts as two amino acids in the denominator. No skips are allowed.

Version 1900 1.2.7 - Internal release only

- changed ExpandSequence in LutefiskScore.c so that it checks to see how many new qtof sequences could be generated for each original sequence. In some rare instances (particularly for longer sequences), it was possible to expand a single sequence into many thousand related sequences (oxMet replacing Phe, or Gln replacing Lys, etc). Although not a bug, it was bogging things down. It now checks to make sure that there are no more than 500 new sequences expanded from the original; if there are too many, then it only allows sequence expansion for single amino acids (oxMet/Phe and Gln/Lys), and other reasons for expansion (multiple dipeptide choices, or Trp plus three dipeptides of the same mass) are eliminated. This should keep Lutefisk from getting hung up on certain spectra.
- checks to make sure that peptide lengths do not exceed the array limits -- if they do, then it just exits w/o going any further.

Version 1900 1.2.6 - Released 10/15/00

- changed LutefiskGetCID so that it would not bomb-out when looking for a header to 'tab text' input file formats .
- changed LutefiskScore so that it would include losses of CH3SOH from oxidized methionine. If the mass accuracy is sufficient to distinguish oxMet from Phe, then this loss is only considered for b and y ions that contain the oxMet. For lower accuracy, losses of 64 u from b and y ions that contain either Phe or oxMet are considered.

Version 1900 1.2.5 - Internal release only

- changed LutefiskMakeGraph so that +2 y ions resulting from the loss of a single N-terminal amino acid is graphe d as a node even if there is no corresponding +1 y ion.
- changed main so that if the peakWidth parameter is set to zero for centroided data, that the autopeak width fea ture is not used. Its not possible to determine peakwidths from centroided data, and was getting slightly screwy results. If peakwidth is zero, then reasonable values are inserted depending on the instrument (0.75 for qtof a nd 1 for lcq).
- changed LutefiskGetCID where there was an error in reading LCQ text files. The intensity values in the file ar e real, but were read into a struct value that needed an int; hence the intensity values were getting garbled.

Version 1900 1.2.4 - Released 4/6/00

- changed code so that data was not converted to nominal masses; this means that high mass accuracy measurements will not be wasted.
- because of temperature dependent drifts in the calibration slope of qtof data, the program will recalibrate the data for each candidate sequence. This allows for poorly calibrated qtof data to still have a tight fragment ion tolerance applied.
- the program will input sequences derived from database matches and compare these with the de novo derived candidate sequences. This allows for an electronic validation of a database hit.
- a CID data quality check has been added as an option. It looks for low mass amino acid related ions, high mass ions that can be connected by amino acid residue masses, as well as a general check on data strangeness (few ions, negative masses, precursor charge, etc).
- code was modified to accomodate data that had been processed using Micromass's Maxent3 software. This software converts fragments to corresponding singly-charged values, and also removes isotope peaks.
- the lutefisk.residues file was added in order for people to add unusual amino acids to the list of common ones.
- some bugs were removed and others were added
- Compiled and run under MacOS, Win32, Solaris, OSF, SGI, & Linux.

Version 2.0.5 - Released 10/16/98

- bugs and the like

Version 2.0.4

- added stuff to make compatible with Codewarrior compilier for Win32
- added stuff to allow it to compile on DEC alpha

Version 2.0.3

- found a spot in GetCID where dividing by zero
- added function to GetCID that eliminates ions below a specific s/n (SIGNAL_NOISE in the definitions file). The noise is determined in a 100 da range local to each ion.
- added ability to read Sequest .dta files (Martin Baker)
- added default output to match input name plus ".lut" (Martin Baker)

Version 2.0.2

- added ability to directly read Finnigan .dat files
- rearranged the .params file into a more sensible order

Verson 2.0.1

- more bug fixes
- modified to better handle ion trap data

Version 1.4.8

- a few more bugs were found and fixed

Version 1.4.7

- a few bugs that affected Unix operation were fixed

Version 1.4.6

- auto-tag altered so that N-terminal mass can be three amino acids
- in final scoring, sequences not ending in R or K for tryptic peptides are penalized
- ions that connect to 147 or 175 for tryptic peptides were retained regardless of the intensity

Version 1.4.5

- monoisotopic to average mass switch occurs over a 400 Da range
- auto-tag automatically finds sequence tags prior to sequencing
- auto-peakwidth automatically finds the peakwidth of profile data
- for unit resolved spectra, the 2xC13 peak is discarded
- cross-correlation bins every 0.5 Da instead of 1 Da
- over-used ions in the final scoring are identified (same ions considered to be b and y) and final score reduced
- the final scoring section was more carefully debugged and simplified

Version 1.3 - Released 11/17/97

- Compilable with gcc 2.7 on UNIX.
- Command line options added to specify the output and param files.

Version 1.1 - Released 6/22/97

- Fixed some problems in GetCidData() with reading of Finnigan ASCII files.

Version 1.0 - Released 5/30/97