Skip to content

PAMPA CLASSIFY

Jump to bottom
touzet edited this page Dec 13, 2024 · 31 revisions

The module PAMPA CLASSIFY is for species identification. It processes a set of MS mass spectra as input and determines the best taxonomic assignment for each spectrum using a curated collection of peptide markers. Users also have the option to provide their own customized set of peptide markers and taxonomies for species. Furthermore, when marker peptides are not available, genetic sequences can be supplied to enable the automatic inference of peptides through in silico digestion.

PAMPA is capable of processing any number of mass spectra in a single run and conducting in-depth exploration of diverse assignment possibilities within the taxonomic space.

Quick start

In the most basic usage of PAMPA, you only need to know three parameters:

  • -s: Path to the spectra files. Authorized formats are cvs, mgd and mzML.
  • -e: Error margin tolerance for the peaks (in Dalton or ppm).
  • -o: Output path (should include the output file name)

The command below executes the program on all mass spectra within the 'SpectraFolder' directory, compiles the primary results into the TSV file 'resultFile.tsv'. The taxonomic model utilized is 'mammals', and the error margin tolerance for masses is set to 0.1.

python3 pampa_classify.py -s SpectraFolder -e 0.1 -o resultFile.tsv --mammals

Command-line

usage: 
 
 python3 pampa_classify.py 
	[-h]
	(-s SPECTRA PATH)
	(-e ERROR MARGIN)
	(-o OUTPUT FILE)
	(-p PEPTIDE TABLE... | -f FASTA file | -d FASTA dir)
	[-l LIMIT]
	[-t TAXONOMY]
	[-n NEIGHBOURING]
	[-a]
        [--deamidation]

options:
  -h, --help        show this help message and exit

general options:
  -s SPECTRA        Path to the spectra files. Authorized formats are  cvs, mgd and mzML. csv and mgd files should contain one 
                    spectrum per file. mzML files can contain several spectra
  -e ERROR          Maximal error margin tolerance for the observation (in Dalton or ppm). 
  -o OUTPUT         Output path (should include the output file name)

options for organism and peptide marker selection:
  -p PEPTIDE_TABLE  Peptide table (TSV file)
  -f FASTA          Fasta sequences, for in silico digestion
  -d DIRECTORY      Directory where to find Fasta files
  -l LIMIT          XXXXLimit the set of peptides or fasta sequences to organisms, molecules or sequence ID specified
                    in this file (TSV file), optional.
  -t TAXONOMY       Taxonomy (TSV file), optional.
  --deamidation.    XXXX

options for suboptimal solutions:
  -n NEIGHBOUR      Provide near-optimal solutions within a specified percentage margin, ranging between 0 and 100.
                    Default is 100. With -n 100, only optimal solutions are provided.
  -a                Provide all solutions, and not only suboptimal solutions, within the percentage margin specified
                    with option -n.

Required options

Mass spectra (-s)

The program processes a batch of mass spectra simultaneously. All mass spectra files are contained within the same folder, with one of the following extensions: .csv or .txt (in CSV format), .mgf (in MGF format), or .mzML (in mzML format). Any other files present will be disregarded. See Mass spectra for more information about the format and the requirements.

Error margin tolerance (-e)

The error margin is related to the resolution of the mass spectrometer, that is its ability to distinguish closely spaced peaks. We employ it to set an upper bound on the deviation between a peak and the theoretical mass of the marker peptide. This option can be expressed in Daltons or in ppm.

  • If the value is smaller than 1, it is assumed to be in Da (Daltons). In this case, recommended values are 0.1 for maldi TOF, and 0.01 for maldi FT.
  • If the value is larger than 1, it is assumed to be in ppm (parts per million). In this case, recommended values are 50 for maldi TOF, and 5 for maldi FTICR.

Output files (-o)

This option enables you to specify the name of the main output file, in TSV format. You can include the desired path to the directory where the file should be created. If the specified directory does not exist, it will be created automatically.

Selection of organisms, basic usage

[Required] With this option, PAMPA utilizes a predefined set of peptide markers in conjunction with the NCBI taxonomy for species identification. The markers are accessible through peptide tables, which are distributed with the code (see the [Peptide tables](Peptide tables) page), together with the taxonomy (see the Taxonomy section). Please avoid relocating or altering these files, as it may damage the behaviour of PAMPA.

If you want to use custom peptide tables containing your own set of peptide markers, or generate markers form genetic sequences, you may use option -p, -t, -f and -d options, which allows for more flexibility. These options are described below.

Selection of organisms, advanced usage

Peptide table (-p)

This option allows you to employ your own set of peptide markers. This set should be structured within a peptide table, formatted as a TSV (Tab-Separated Values) file. The specific format details for peptide tables are described in the Peptide tables section.

Note that you can specify multiple peptide tables by using the -p option repeatedly.

Running the program without peptide tables (-f and -d)

When no peptide markers are available, it is possible to provide FASTA sequences for the representative species instead. These sequences will undergo in silico digestion to identify all tryptic peptides, allowing for up to one missed cleavage. Masses are then automatically computed.

The provided sequences can be available either in a (multi-)FASTA file ('-f'option), or in a directory containing FASTA files ('-d' option). In both cases, the set of sequences can optionnally be limited to a subset of organisms, molecules or sequence identifiers with '-l' option.

Option -f : The specified file can contain an arbitrary number of FASTA sequences, coming from various organisms. Refer to the [FASTA sequences](#FASTA sequences) section for details on the syntax used in FASTA headings.

Option -d: The directory can contain an arbitrary number of FASTA files, following the same requirements as with '-f' option. Only files with extension .fa or .fasta will be examined.

Taxonomy (-t)

[Optional] The program provides an optional feature to include taxonomic information in species identification. In this scenario, you can either provide a taxonomy file or utilize a pre-defined taxonomy file available in the Taxonomy directory. Instructions for constructing your own taxonomy file are detailed in the Taxonomy section.

When this option is invoked, the software will indicate, for each spectrum, the taxonomic resolution of the assignment. This is computed as the largest clade of the taxonomy that is compatible with the prediction.

Deamidation

--deamidation

Apply deamidation to peptide markers. This parameter can be used in conjunction with the -l option with the tag _Deamidation to specify the list of peptide markers to process. See below ans Limiting searches. By default, all markers are processed.

Options to limit peptide markers

Limiting search (-l)

[Optional] It is possible to filter the marker peptides to consider to limit the search according to various criteria such as organism (OS=), taxid (OX=), gene name (GN=), sequence identifier (SeqID=), or PTMs (PTM=), etc. For that, you can use the '-l' option together with a limit file . The full description of the syntax is given in section Limiting searches.

Options for suboptimal solutions

By default, PAMPA identifies the species with the lower P-value. The -n option allows to obtain also near-optimal solutions. For that, you can set the suboptimality range as a percentage from 0 to 100, with the default being 100 (corresponding to solutions with the highest number of marker peptides). For example, if the optimal solution has 11 marker peptides, '-n 80' will provide solutions with 9 markers or more.

The '-a' option is linked to the '-n' option and modifies its behavior. When the '-n' option is used alone, it generates only near-optimal solutions that are not included in any other solution. However, when used together with '-n,' the '-a' option makes the program compute all solutions, even those that are included in other solutions.

Description of output files

For each spectrum, the output file will give the best assignment, based on the best P-value. It contains the following information:

  • Peaks from the spectrum that match the marker peptides,
  • Pvalue: Pvalue of the assignment
  • Score: the total number of marker peptides,
  • Assignment: largest subtree of the taxonomy that is compatible with the marker peptides found,
  • Rank: Taxonomic rank of the assignment (e.g. species, genus, family),
  • Species: the list of species supporting the assignment.

Two other accompanying files are automatically created, in the same directory.

  • detail_<outputfile> (TSV file): this file contains the detail of the assignment: which markers are found for which species. It also provides the intensity of the peaks used in the assignment.
  • report_<outputfile> (TXT file): this file contains a report on the run's inputs (number of mass spectra, number of species tested, parameters...)

Clone this wiki locally