Working with MSstatsConvert

  collapse = TRUE,
  comment = "#>"

Purpose of MSstatsConvert

The MSstatsConvert package is a member of the MSstatst family of packages, MSstats and MSstatsTMT. It creates an abstraction for the steps in mass spectrometry (MS) data analysis that are required before a dataset can be used for statistical modeling. In short, the package is responsible for converting output from signal processing tools such as OpenMS or MaxQuant into a format suitable for statistical analysis. This includes:

MSstatsConvert allows for transforming any MS quantification result into a format required by MSstats and MSstatsTMT packages. Additionally, it provides built-in cleaning functions for outputs of DIAUmpire, MaxQuant, OpenMS, OpenSWATH, Progenesis, ProteomeDiscoverer, Skyline, Spectromine, and Spectronaut. These functions serve as a base for converter functions (called *toMSstatsFormat or *toMSstatsTMTFormat) provided by the MSstats and MSstatsTMT packages.

MSstats data format

MSstats family packages works with label-free, SRM and TMT datasets. The following column are required.

Additionally, if the experiment involves fractionation, Fraction column can be added to store fraction labels.


MSstatsConvert allows for flexible logging based on the log4r package. Information about preprocessing steps can be written to a file, to a console, to both or to neither. The MSstatsLogsSettings function helps manage log settings. The user can pass a path to an existing file to the log_file_path parameter. Combined with setting append = TRUE, this allows writing all information related to a specific data analysis to a single file. If a user does not specify a file, a new file will be created automatically with a name starting with "MSstats_log", followed by a timestamp.

# default - creates a new file
MSstatsLogsSettings(use_log_file = TRUE, append = FALSE) 

# default - creates a new file
MSstatsLogsSettings(use_log_file = TRUE, append = TRUE, 
                    log_file_path = "log_file.log") 

# switches logging off
MSstatsLogsSettings(use_log_file = FALSE, append = FALSE) 

# switches off logs and messages
MSstatsLogsSettings(use_log_file = FALSE, verbose = FALSE) 

Additionally, session info generated by the utils::sessionInfo() function can be saved to file with the MSstatsSaveSessionInfo function.


By default, the output file name will start with "MSstats_session_info" and end with a current timestamp.

Importing and cleaning data

MS data processing by MSstatsConvert starts with importing and cleaning data. The MSstatsImport function produces a wrapper for possibly multiple files that may describe a single dataset. For example, MaxQuant output consists of two files, while OpenMS outputs just a single file.

maxquant_evidence = read.csv(system.file("tinytest/raw_data/MaxQuant/mq_ev.csv",
                                         package = "MSstatsConvert"))
maxquant_proteins = read.csv(system.file("tinytest/raw_data/MaxQuant/mq_pg.csv",
                                         package = "MSstatsConvert"))
maxquant_imported = MSstatsImport(list(evidence = maxquant_evidence,
                                       protein_groups = maxquant_proteins),
                                  type = "MSstats", tool = "MaxQuant")

openms_input = read.csv(system.file(
  package = "MSstatsConvert"
openms_imported = MSstatsImport(list(input = openms_input),
                                "MSstatsTMT", "OpenMS")

The getInputFile method allows user to retrieve the files:

getInputFile(maxquant_imported, "evidence")[1:5, 1:5]

As a next step of the analysis, input files are combined into a single data.table with standardized column names by the MSstatsClean function. It is a generic function with built-in support for outputs of tools listed in the "Purpose of the MSstatsConvert package" section. The type parameter is equal to either MSstats or MSstatsTMT and indicates if the data comes from a labelled TMT experiment.

For some datasets, MSstatsClean may require additional parameters described in the respective help files. For our example datasets, the following calls merge input files into a single table.

maxquant_cleaned = MSstatsClean(maxquant_imported, protein_id_col = "Proteins")

openms_cleaned = MSstatsClean(openms_imported)

If a user wants to use MSstatsConvert package with data in a format that is not currently supported, it is enough to first re-format the data into a data.table with column ProteinName, PeptideSequence, PrecursorCharge, FragmentIon, ProductCharge (with the latter two possibly equal to NA), Run and IsotopeLabelType (in case of non-TMT data) or Channel (in case of TMT data). Moreover, the dataset may include any column that will be used for filtering the dataset (for example a column that stores q-values). In our example, such additional columns are "Modifications" and "Score" from MaxQuant files.

Annotation columns should be called Condition and BioReplicate. For TMT data, Mixture, TechRepMixture columns may be added. Fractionation should be indicated by a Fraction column.


The goal of MSstatsPreprocess function is to transform cleaned MS data into a format ready for statistical analysis with MSstats or MSstatsTMT packages. This function accepts several parameters, and each corresponds to a preprocessing step.

maxquant_annotation = read.csv(system.file(
  package = "MSstatsConvert"
maxquant_annotation = MSstatsMakeAnnotation(maxquant_cleaned,
                                            Run = "Rawfile")
m_filter = list(col_name = "PeptideSequence", 
                pattern = "M", 
                filter = TRUE, 
                drop_column = FALSE)

oxidation_filter = list(col_name = "Modifications", 
                        pattern = "Oxidation", 
                        filter = TRUE, 
                        drop_column = TRUE)

feature_columns = c("PeptideSequence", "PrecursorCharge")
maxquant_processed = MSstatsPreprocess(
  remove_shared_peptides = TRUE, 
  remove_single_feature_proteins = FALSE,
  pattern_filtering = list(oxidation = oxidation_filter,
                           m = m_filter),
  feature_cleaning = list(remove_features_with_few_measurements = TRUE,
                          summarize_multiple_psms = max),
  columns_to_fill = list("FragmentIon" = NA,
                         "ProductCharge" = NA,
                         "IsotopeLabelType" = "L"))

# OpenMS - TMT data
feature_columns_tmt = c("PeptideSequence", "PrecursorCharge")
openms_processed = MSstatsPreprocess(
  remove_shared_peptides = TRUE,
  remove_single_feature_proteins = TRUE,
  feature_cleaning = list(remove_features_with_few_measurements = TRUE,
                          summarize_multiple_psms = max)

Annotation is created via the MSstatsMakeAnnotation function. It takes the cleaned dataset and annotation file as input. Additionally, key-value pairs can be passed to this function to change column names (not including dots and other symbols) in the annotation from names given by values to names given by keys.

For programmatic applications and consistency of the interface, filtering is done with the help of lists.

For filtering based on numerical scores (for example q-value filtering), the list should consist of elements named

For example, to remove intensities smaller than 1, we could pass the following list to the score_filtering parameters:

  list(score_column = "Intensity", score_threshold = 1,
       direction = "greater", behavior = "remove", 
       handle_na = "remove", fill_value = NA, filter = TRUE, drop = FALSE

For filtering based on patterns (for example, removing oxidation peptides), the list should consist of elements named

For filtering based on exact values (for example, removing iRT proteins), the list should consists of elements named

Fractions and balanced design

Finally, after preprocessing, MSstatsBalancedDesign function can be applied to handle fractions and create balanced design. For label-free and SRM data, it means that fractionation or technical replicates will be detected if these information is not provided. Features measured in multiple fractions (overlapped) will be assigned to a unique fraction. Then, the data will be adjusted so that within each fraction, every feature has a row for certain run. If the intensity value is missing, it will be denoted by NA.

For TMT data, a unique fraction will be selected for each overlapped feature and the data will adjusted so that within each run, every feature has a row for each channel. If the intensity is missing for a channel, it will be denoted by NA.

maxquant_balanced = MSstatsBalancedDesign(maxquant_processed, feature_columns)

openms_balanced = MSstatsBalancedDesign(openms_processed, feature_columns_tmt)

MSstatsBalancedDesign output is a data.frame of class MSstatsValidated. Such a data.frame will be recognized by statistical processing functions from MSstats and MSstatsTMT packages as a valid input, which will allow them to skip checks and transformation necessary to fit data into this format.

Try the MSstatsConvert package in your browser

Any scripts or data that you put into this service are public.

MSstatsConvert documentation built on Nov. 8, 2020, 5:49 p.m.