AA_stat

An open source software for amino acid residue modification analyses in proteomics

Overview

AA_stat is a tool for shotgun proteomics that uncovers unexpected peptide modifications, as well as possible artefacts of data acquisition or processing, in the results of proteome analysis. AA_stat calculates and visualizes amino acid occurrence frequencies for the identified peptides. AA_stat processes the results of open search and composes a list of identified mass shifts that can be attributed to modifications.

The processing involves Gaussian fitting of potential peaks, group-specific FDR filtering, amino acid counting, and appearance frequency normalization for the observed mass shifts.

Installation

AA_stat requires Python 3.6 or newer. AA_stat GUI requires Python 3.7 or newer.

Install from PyPI (all platforms):

pip install AA_stat

Alternatively, you can install directly from GitHub:

pip install git+https://github.com/SimpleNumber/aa_stat

Create a desktop shortcut

To create a desktop shortcut for AA_stat_GUI, call another command after pip install:

AA_stat_GUI --create-shortcut

Quickstart

Command line

Just call AA_stat with your open search results. Pass spectrum files, as well, if they are available:

AA_stat --pepxml *.pepXML --mzml *.mzML

To check results, open the file called report.html in your browser. Example reports are shown here.

GUI

Run AA_stat_GUI on the command line or do AA_stat_GUI --create-shortcut once and use the desktop shortcut.

User manual

Command line options

usage: AA_stat [-h] [--params PARAMS] [--dir DIR] [-v {0,1,2,3}] [--mgf MGF [MGF ...] | --mzml MZML [MZML ...]] (--pepxml PEPXML [PEPXML ...] | --csv CSV [CSV ...])

optional arguments:
  -h, --help            show this help message and exit
  --params PARAMS       CFG file with parameters. If there is no file, AA_stat uses default one. An example can be found at https://github.com/SimpleNumber/aa_stat
  --dir DIR             Directory to store the results. Default value is current directory.
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Output verbosity.
  --mgf MGF [MGF ...]   MGF files to localize modifications.
  --mzml MZML [MZML ...]
                        mzML files to localize modifications.
  --pepxml PEPXML [PEPXML ...]
                        List of input files in pepXML format.
  --csv CSV [CSV ...]   List of input files in CSV format.

Instead of file lists, you can pass directory names. This will process all files in the directory.

Configuration file

Configuration parameters can be set in a config file (default values and comments are in default.cfg).

AA_stat supports the following parameters:

Open search results

AA_stat deals with open search results in pepXML or CSV formats.

AA_stat is compatible with the search results obtained using most existing search engines. By default, it is recommended to use MSFragger search engine, available from Nesvizhskii lab website. For details of its operation, see MSFragger User manual.

Examples

An example of the open search parameters file can be found in the repository here.

Example of MSFragger usage:

java -Xmx8G MSFragger.jar open_search.params HeLa_run1.mzML HeLa_run2.mzML

Example of using AA_stat:

AA_stat --pepxml *.pepXML --mzml *.mzML

Output files

An example of AA_stat output can be found here.

AA_stat produces the following files:

A. Gaussian fit report (gauss_fit.pdf).

B. Summary histogram (summary.png).

C. Charts (PNG and SVG files) of normalized frequencies for each significant mass shift interval. If MGF or mzML files are provided, tables with modifies peptide sequences and localization scores are generated.

D. Summary table (aa_statistics_table.csv) of amino acid frequencies for all mass shifts with Unimod.org links for possible modifications.

E. Summary table (p_values.csv) with p-values for each amino acid frequencies in each mass shift.

F. HTML file (report.html) aggregates and illustrates all results.

G. If MGF or mzML files are provided, a table with localization results is created (localization_statistics.csv).

A. Gaussian fit file shows PSM distributions in intervals that were considered as mass shift peaks. Subplot titles correspond to mass shifts (interval center). Peaks are classified into 3 groups: PASSED - mass shift with good fit, which are considered for subsequent analysis; NO FIT - mass shifts for which the algorithm could not find Gaussian function; FAILED - mass shift with a fit not passing the configured filtering criteria.

Figure 1. Examples of Gaussian fit results in gauss_fit.pdf.

B. Summary histogram shows numbers of filtered PSMs in all mass shift intervals. Number on top of the bin indicates the percentage of all identified PSMs. Each mass shift interval is filtered separately to the user-specified FDR level, using target-decoy approach.

Figure 2. Example of Summary histogram.

C. Charts of normalized frequencies for each significant mass shift. Each chart is named according to the mass shift. Each bar in the chart denotes the normalized occurrence frequency of a specific amino acid residue in the given mass shift interval. The normalized frequency is calculated by:

1. Counting all amino acids in all non-redundant peptides identified with the given mass shifts;

2. Dividing the count for the given residue by the total amino acid count for the interval to obtain the occurrence frequency of the residue;

3. Normalizing the occurrence frequency of the residue by the occurrence frequency of the same residue for the zero mass shift interval.

If the normalized frequency of a residue significantly exceeds 1, that means that this residue is "enriched" in the peptides identified with the corresponding mass shift, suggesting that there is a connection between this residue and the cause of the mass shift. In the simplest case, this residue is modified:

Figure 3. Example of a normalized frequency chart for 15.9943 mass shift (green). Orange -- the percentage of peptides that contain at least one AA residue of a certain kind. Blue -- successful localizations of mass shifts at each AA (only if MS/MS spectra are provided). The counts are not normalized.

D. Summary table (aa_statistics_table.csv) of amino acid frequencies for all mass shifts with peptide counts and Unimod.org links for possible modifications.

E. Summary table (p_values.csv) with p-values for all amino acid frequencies in all mass shifts that indicates the significant deviation amino acid frequency from zero mass shift peak.

F. HTML file (report.html) aggregates and illustrates all results. Examples can be found here.

G. A summary of localization shows the number of peptides in each bin for which a modification was successfully localized in MS/MS. Localization is done by generating theoretical spectra of possible isoforms and scoring them against the experimental spectrum. If there is a clear winner in terms of score, the spectrum is considered localized.

AA_search option

If AA_stat used in "AA_search" mode, MSFragger is run prior to AA_stat. AA_search can also optimize fixed modifications that are used for open search, and repeat open search if needed. This is enabled with -x option (or --optimize-fixed-mods). Full list of supported comman-line options:

AA_search [-h] [--params PARAMS] [--MSFragger MSFRAGGER] [--dir DIR] [-v {0,1,2,3}] (--mgf MGF [MGF ...] | --mzml MZML [MZML ...]) [-db FASTA] [--os-params OS_PARAMS] [-x] [-s [SKIP]] [-je JAVA_EXECUTABLE] [-ja JAVA_ARGS]

optional arguments:
  -h, --help            show this help message and exit
  --params PARAMS       CFG file with parameters. If there is no file, AA_stat uses default one. An example can be found at https://github.com/SimpleNumber/aa_stat
  --MSFragger MSFRAGGER
                        Path to MSFragger .jar file. If not specified, MSFRAGGER environment variable is used.
  --dir DIR             Directory to store the results. Default value is current directory.
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Output verbosity.
  --mgf MGF [MGF ...]   MGF files to search.
  --mzml MZML [MZML ...]
                        mzML files to search.
  -db FASTA, --fasta FASTA
                        FASTA file with decoys for open search. None: with included MSFragger parameters, the database is expected to contain decoys. Default decoy prefix is "rev_". If it differs, do not forget to specify it in
                        AA_stat params file.
  --os-params OS_PARAMS
                        Custom open search parameters.
  -x, --optimize-fixed-mods
                        Run multiple searches, automatically determine which fixed modifications to apply.
  -s [SKIP], --skip [SKIP]
                        Skip search if pepXML files exist already. If not specified, no steps are skipped. If specified without value, first step may be skipped. Value is number of steps to skip. Only works with "-x".
  -je JAVA_EXECUTABLE, --java-executable JAVA_EXECUTABLE
  -ja JAVA_ARGS, --java-args JAVA_ARGS

Example of using AA_search:

AA_search --MSFragger /path/to/MSFragger/MSFragger-2.4.jar -x -db fasta_file.fasta --mzml mzml_files.mzML --dir ./save_dir

All searches are saved in separate folders: "step 1", "step 2", etc. In these folders, pepXML files and open search parameters file (os.params) are saved, together with AA_stat results.