Package: tmasque
tmasque: Targeted Mass Spectrometry Quality EncoderFor processing datastes of targeted mass spectrometry, this tmasque package helps to evaluate peak quality of chromatograms objectively after running automatic peak-picking software. We conducted an unsupervised learning approach, the beta-total correlation variational autoencoder (beta-TCVAE), to learn peak quality from our collected TargetedMS data cohort (including both MRM and PRM experiments). The data cohort contains 1,703,827 peak groups from 75 studies and was produced from 22 different models of mass spectrometers, manufactured by the four leading brands: AB Sciex, Agilent Technologies, Thermo Fisher Scientific, and Waters Corporation. Such versatile datasets can contribute to a reliable quality encoder to provide objective scoring of chromatographic peaks.This Python package carries a command line tool and provides a programming interface to calculate TMSQE scores and generate friendly reports.InstallationThe package is published as a python package. You need to have a Python with version >=3.8 installed and can then usepipto install tmasque.pip install tmasqueThen, you can usetmasque -hortmasque --helpto see the arguments.
You can also usetmasque exampleto have a quick example (see below).Required data formatWe currently support the TSV (tab-separated values) format file for chromatograms and the CSV (comma-separated values) format file for peak boundaries.These two files can be directly exported via Skyline.The required nine column headers for chromatograms are listed as follows.FileNamePeptideModifiedSequencePrecursorChargeProductMzFragmentIonProductChargeIsotopeLabelTypeTimesIntensitiesFor peak boundary CSV file, the following five column headers are required.File NamePeptide Modified SequenceMin Start TimeMax End TimePrecursor ChargeYou may notice that the spaces between words in the above column headers.
This is because that these column headers followed the Skyline output formats for chromatograms and peak boundaries.ThePeptideModifiedSequenceandPeptide Modified Sequencecolumns are used for display and for identifications of analyte targets. For metabolites, you may ignore the header and using metabolite name for this column is fine.We followed the Skyline exported file formats for chromatograms and peak boundaries.Command line toolOnce you have installed tmasque, you can usetmasqueas the command line tool.
In your terminal, typetmasque --helpto see the detailed descriptions for arguments.
The full arguments are also listed in the next section.1. Quick exampleUse the following command to run the quick example.tmasqueexampleWe have prepared a small example in this package. After running thetmasque examplecommand, a folder will be created in your current working directory.
This folder will also contain input files:chromatogram.tsvandpeak_boundary.csv. You may also take a look the column headers and the formats.
This folder aresample_quality.xlsxandchromatogram_plots.pdf. The former is the summarized peak quality scores for each sample, and the latter is the chromatogram plots.
Also, this folder has atransition_qualityfolder in it. You can see one excel file for each target. The excel file displays the transition quality scores with all the underlying quality features.2. The basic usage:tmasquerun<chromatogram_path><peak_boundary_path><output_sample_quality_excel_path><output_transition_quality_folder_path>In the above command, the former two argumentschromatogram_pathandpeak_boundary_pathare the two required input files of the TSV and CSV formats, while the latter two are the output paths.output_sample_quality_excel_pathexpects an Excel file path andoutput_transition_quality_folder_pathexpects a folder path. If the folder path does not exist, the folder will be created during tmasque execution. In this folder, detailed quality feature values of each target would be exported in an Excel file.3. Quality scores with additional chromatogram plotsWe offer an option to plot chromatograms for visual examinations and easy identifications of problematic cases.
Use the following command arguments to perform quality evaluation and generate chromatogram plots.tmasquerun<chromatogram_path><peak_boundary_path><output_sample_quality_excel_path><output_transition_quality_folder_path>--output_chromatogram_pdf<output_chromatogram_pdf_path>By adding the optional argument--output_chromatogram_pdfwith the value of the expected output PDF path, a PDF file will be generated to display all chromatogram plots with color indications of good, acceptable, and poor peak quality.4. Sample grouping for batches or response curve experimentsWe can group a couple of samples and summarize the peak quality scores with medians to examine batche quality or the peak quality at different concentrations for response curve experiments.
To deal with sample grouping, we can use arguments offile_group_delimiterandfile_group_suffix_typeto specify the rules for grouping.
For example, if the sample names are listed as follows, we can usefile_group_delimiter=-andfile_group_suffix_type='d'to extract the suffix of the filename as the group name.Sample nameGroup20210727_DSS Response curve_121plex_150um_1-001.wiff120210727_DSS Response curve_121plex_150um_2-001.wiff120210727_DSS Response curve_121plex_150um_1-002.wiff220210727_DSS Response curve_121plex_150um_2-002.wiff2Once thefile_group_delimiterandfile_group_suffix_typeare set, quality scores will be further summarized from sample quality.
An additional sheetGroup Qualitywill be created in theoutput_sample_quality_excel_pathfile.Full command argument list fortmasque runArgumentDescriptionValue TypeDefault ValuesINPUTchromatogram_tsvThe chromatogram TSV file pathFile pathno defaultpeak_boundary_csvThe Peak Boundary CSV file pathFile pathno defaultOUTPUToutput_quality_xlsxThe output peak quality Excel file pathFile pathno defaultoutput_transition_folderThe output transition quality folder pathFolder pathno defaultOPTIONAL--help-hShow the detailed argument list(no value)unset--version-vDisplay the package version(no value)unset--thread_num-tThe parallel thread number to calculate quality feature values for all peak groupsinteger4--internal_standard_type-sSet the internal standards to heavy or light ions.{heavy,light}heavyGROUPING--file_group_delimiter-gsThe delimiter of filename to define file groups{None,-,_}None--file_group_suffix_type-gtThe suffix character type to define file groups (d for digit number; w for words){d,w}NoneSCORING--type1_acceptable_threshold-t1aThe threshold of acceptable quality of Type 1 quality score. Scores greater than or equal to threshold value are considered as poor quality.float6.7--type1_good_threshold-t1bThe threshold of good quality of Type 1 quality score. Scores greater or equal to this threshold are considered as good quality.float7.7--type2_acceptable_threshold-t2aThe threshold of acceptable quality of Type 2 quality score. Scores greater than or equal to threshold value are considered as poor quality.float5.0--type2_good_threshold-t2bThe threshold of good quality of Type 2 quality score. Scores greater or equal to this threshold are considered as good quality.float7.2--type3_acceptable_threshold-t3aThe threshold of acceptable quality of Type 3 quality score. Scores greater than or equal to threshold value are considered as poor quality.float7.901--type3_good_threshold-t3bThe threshold of good quality of Type 3 quality score. Scores greater or equal to this threshold are considered as good quality.float8.665CHROMATOGRAM PLOTS--output_chromatogram_pdf-plotThe output chromatogram pdf path to draw chromatogram plots. If set, all chromatograms will be plotted in a PDF file.File pathNone--output_mixed_mol-mixIf set, chromatogram data for each target will be mixed in one pdf page.(no value)unset--output_chromatogram_nrow-nrowThe number of chromatograms per row in one pdf pageinteger6--output_chromatogram_ncol-ncolThe number of chromatograms per columne in one pdf pageinteger6--output_chromatogram_fig_w-figwThe figure width in inchesinteger30--output_chromatogram_fig_h-fighThe figure height in inchesinteger42--output_chromatogram_dpi-dpiThe dpi of chromatogram plotsinteger200--output_chromatogram_threads-pthreadUsing more threads will consume more memoryinteger1Use tmasque as a moduleThe tmasque package can also be used as a module to integrate quality scoring functions in Python scripts.fromtmasqueimportTargetedMSQualityEncoderasTMSQEchromatogram_tsv='/path/to/chromatogram.tsv'peak_boundary_csv='/path/to/peak_boundary.csv'tmsqe=TMSQE(chromatogram_tsv,peak_boundary_csv)tmsqe.run_encoder()# Get all quality features for all transitions in transition_df and summarized sample quality in sample_quality_dftransition_df,sample_quality_df=tmsqe.summarize_dataset()# Output quality results in Excel filesoutput_transition_folder='/path/to/a/folder'output_summarized_sample_quality_xlsx='/path/to/output_sample_quality.xlsx'tmsqe.output_transition_quality(output_transition_folder)# Output quality scores for each transition with all the underlying quality features. One excel per target.tmsqe.output_sample_quality(output_summarized_sample_quality_xlsx)# Output summarized quality scores for each sample.# Generate all chromatogram plots in a PDF file.output_chromatogram_pdf='/path/to/output_chromatogram_plots.pdf'tmsqe.plot_chromatograms(output_chromatogram_pdf)For sample grouping# for sample names like xxxx-01.raw or xxxx-02.raw, the suffix 01 and 02 will be parsed as numbers (1 and 2) and group quality will be summarized in a different sheet in output_summarized_sample_quality_xlsx.transition_df,sample_quality_df=tmsqe.summarize_dataset(file_group_delimiter='-',file_group_suffix_type='d')tmsqe.output_transition(output_transition_folder,file_group_delimiter='-',file_group_suffix_type='d')tmsqe.output_quality(output_summarized_sample_quality_xlsx,file_group_delimiter='-',file_group_suffix_type='d')