Package: breathXplorer
breathXplorerbreathXplorerIntroductionQuick startInstallationFile formatFeature table CSVAligned feature table CSVMS/MS spectra MGFFeature extractionFeature alignmentUtilitiesMS/MS spectra exportPeak recognitionCitationIntroductionBreathXplorer is a swiss army knife for breath analysis. It provides a set of tools for breath analysis, including
feature extraction, feature alignment, and breath recognition.Quick startInstallationThe package can be installed using pip, supported python version are 3.7, 3.8, 3.9 and 3.10.
It's recommended to install the package in a virtual environment or a conda environment,
after activating the environment, run the following command to install the package:pip install breathXplorerFile formatThe input file should be in mzML or mzXML format (Perhaps more in the future). For the output,
the single or aligned feature table can be exported as csv file.
The related MS/MS spectra can be exported in an mgf file.Feature table CSVIDm/zintensity0.00720.02670.0438070.00434283190863349550170.06507697202671424564769096479075270.073018459000370.125765085000The index of the table is the m/z value of the features, and the 1st column is the total intensity of the feature.
The other columns are the intensity of the feature over time, the time is the name of the corresponding column.Aligned feature table CSVIDm/zS01_BeforeS02_BeforeS03_Before070.0652840025832292428472742171.048944989611058413906271.068338603012110398033The index of the table is the m/z value of the features, and each column is the total intensity of the feature in a
sample (
experiment of a subject). The name of the column is the sample name.MS/MS spectra MGFBEGIN IONS
PEPMASS=70.0040
MSLEVEL=2
50.6306 1466
50.6316 2041
END IONS

BEGIN IONS
PEPMASS=70.0649
MSLEVEL=2
53.0012 1509
71.0627 7731
71.0650 870
END IONSThe file contains the MS/MS spectra of the features, each feature has a PEPMASS (precursor mass) and MSLEVEL field, and
the following
pairs are the m/z and intensity of the MS/MS spectra.Feature extractionFeature extraction is used to find the volatile organic compound (VOC) in the breath sample.
The feature extraction is performed using thefind_featurefunction. The function takes the path to an mzMl/mzXML file
as input, and returns an object containing the extracted feature table:frombreathXplorerimportfind_featurefs=find_feature("sample.mzML",False,.8,"Topological",6)TheFalseindicates that the input file is not a line spectrum, and the.8controls the quality of the extracted
features, higher value means higher quality. The"Topological"indicates the algorithm used for feature extraction,
the other option is"Gaussian". The6is the prior knowledge of the number of breath in an experiment (only used
for Gaussian algorithm, and you don't need to impute it if using Topological).Thefsis a FeatureSet object, it contains the following information:fs.mz# m/z values of the extracted featuresfs.scan_time# scan time of the experimentfs.intensity# the total intensity of each feature (calculated by integrating the intensity over scan time)len(fs)# the number of extracted featuresfs[96.7654]# get the intensity with m/z value 96.7654 over scan timefs.rsd# the relative standard deviation of each feature for quality controlIn practice, the relative standard deviation (RSD) can be used to filter out the noise which doesn't have a consistent intensity with breath peaks:fs=fs.rsd_control(.1)# use specific RSD valuefs=fs.rsd_control(fs.rsd.quantile(0.1))# use the 10% quantile of the RSDFeatureSet object can be exported as csv file using theto_csvmethod:fs.to_csv("feature_table.csv")BreathXplorer can infer the adducts and isotope of the features, to enable this function:fs.to_csv("feature_table.csv",adduct=True,isotope=True)Feature alignmentThemerge_featurefunction takes as input a list of FeatureSet objects, and returns a Sample object. It aligns the
features with the similar m/z value from different samples, and calculate the total intensity of each feature in each
sample. To use the function, you can do the following:frombreathXplorerimportmerge_result,find_featurefss=[find_feature(f,False,.8,"Gaussian",6)forfin["sample1.mzML","sample2.mzXML","sample3.mzML"]]fss=[fs.rsd_control(fs.rsd.quantile(0.1))forfsinfss]# filter out the noise (optional)sample=merge_result(fss,["sample1","sample2","sample3"])The first statement creates a list of FeatureSet objects.
One thing very cool is the function can deal with different file formats in one line of code (though it's not
recommended to do so, because we usually want to keep our experiment data in a more consistent way).The second statement aligns those FeatureSet objects usingmerge_result.
Thefssis a list of FeatureSet objects, the["sample1", "sample2", "sample3"]is the customizable names assigned
to each sample.Just like the FeatureSet object, the Sample object contains the following information:sample.mz# m/z values of the extracted featuressample.sample_name# the name of each samplelen(sample)# the number of extracted featuressample[96.7654]# get the total intensity with m/z value 96.7654 of all samplessample.to_csv("aligned_table.csv")# export the feature table of all samples as csv filesample.to_csv("aligned_table.csv",adduct=True)# export the feature table of all samples as csv file with adductsUtilitiesMS/MS spectra exportIf you're using tandem MS, you can also export the MS/MS spectra as mgf file using theto_mgffunction:frombreathXplorerimportretrieve_tandemtandem=retrieve_tandem("sample.mzML",fs,0.005)tandem.to_mgf("ms2.mgf")The filesample.mzMLcontains tandem MS data. Thefsobject represents either a FeatureSet or a Sample, from which
the m/z values are extracted. These m/z values are then used to obtain the corresponding MS/MS spectra. A tolerance
of0.005is applied to the m/z values. Any MS/MS spectra with a difference smaller than0.005between the precursor
m/z value and the feature's m/z value will be retrieved.Peak recognitionThe total ion current (TIC) of mass spectral data from breath analysis exhibits two key properties that preclude the use
of existing peak detection methods but facilitate the development of specialized breath analysis algorithms:Breath peaks are characteristically irregular and contain a substantial number of subsidiary peaks.Prior knowledge about the expected number of breath peaks is typically available.We developed 2 algorithms to detect breath peaks from the TIC of mass spectral data from breath analysis: Topological
and
Gaussian mixture model (GMM). Both the 2 methods share the similar interface, and can be imported as follows:frombreathXplorer.find_peakimportfind_peak,find_gaussianBoth function takes in two arrays,xrepresenting the time points andyrepresenting the corresponding values such
as
concentration or intensity. Besides, when usingfind_gaussian, the parameterndetermines the number of peaks to be
considered. The output is a list of
tuples, where each tuple contains the start and end time point values of the identified ranges, along with the maximum
intensity values of the respective peaks.CitationIf you use this package in your research, please cite the following paper: