pycompound 0.0.1__py3-none-any.whl

pycompound_fy7392/plot_spectra_CLI.py

@@ -0,0 +1,51 @@
+
+from pycompound_fy7392.plot_spectra import generate_plots_on_HRMS_data
+from pycompound_fy7392.plot_spectra import generate_plots_on_NRMS_data
+import pandas as pd
+import argparse
+from pathlib import Path
+import sys
+
+
+parser = argparse.ArgumentParser()
+
+parser.add_argument('--query_data', type=str, metavar='\b', help='CSV file of query mass spectrum/spectra to be identified. Each row should correspond to a mass spectrum, the left-most column should contain an identifier, and each of the other columns should correspond to a single mass/charge ratio. Mandatory argument.')
+parser.add_argument('--reference_data', type=str, metavar='\b', help='CSV file of the reference mass spectra. Each row should correspond to a mass spectrum, the left-most column should contain in identifier (i.e. the CAS registry number or the compound name), and the remaining column should correspond to a single mass/charge ratio. Mandatory argument.')
+parser.add_argument('--spectrum_ID1', type=str, metavar='\b', help='The identifier of the query spectrum to be plotted. Default: first query spectrum in query_data.')
+parser.add_argument('--spectrum_ID2', type=str, metavar='\b', help='The identifier of the reference spectrum to be plotted. Default: first reference spectrum in reference_data.')
+parser.add_argument('--similarity_measure', type=str, default='cosine', metavar='\b', help='Similarity measure: options are \'cosine\', \'shannon\', \'renyi\', and \'tsallis\'. Default: cosine.')
+parser.add_argument('--chromatography_platform', type=str, metavar='\b', help='Chromatography platform: options are \'HRMS\' and \'NRMS\'. Mandatory argument.')
+parser.add_argument('--spectrum_preprocessing_order', type=str, metavar='\b', help='The LC-MS/MS spectrum preprocessing transformations and the order in which they are to be applied. Note that these transformations are applied prior to computing similarity scores. Format must be a string with 2-6 characters chosen from C, F, M, N, L, W representing centroiding, filtering based on mass/charge and intensity values, matching, noise removal, low-entropy trannsformation, and weight-factor-transformation, respectively. For example, if \'WCM\' is passed, then each spectrum will undergo a weight factor transformation, then centroiding, and then matching. Note that if an argument is passed, then \'M\' must be contained in the argument, since matching is a required preprocessing step in spectral library matching of LC-MS/MS data. Furthermore, \'C\' must be performed before matching since centroiding can change the number of ion fragments in a given spectrum. Default: FCNMWL for HRMS, FNLW for NRMS')
+parser.add_argument('--high_quality_reference_library', type=str, default='False', metavar='\b', help='True/False flag indicating whether the reference library is considered to be of high quality. If True, then the spectrum preprocessing transformations of filtering and noise removal are performed only on the query spectrum/spectra. If False, all spectrum preprocessing transformations specified will be applied to both the query and reference spectra. Default: False')
+parser.add_argument('--mz_min', type=int, default=0, metavar='\b', help='Remove all peaks with mass/charge less than mz_min in each spectrum. Default: 0')
+parser.add_argument('--mz_max', type=int, default=999999999999, metavar='\b', help='Remove all peaks with mass/charge greater than mz_max in each spectrum. Default: 999999999999')
+parser.add_argument('--int_min', type=float, default=0, metavar='\b', help='Remove all peaks with intensity less than int_min in each spectrum. Default: 0')
+parser.add_argument('--int_max', type=float, default=999999999999, metavar='\b', help='Remove all peaks with intensity greater than int_max in each spectrum. Default: 999999999999')
+parser.add_argument('--window_size_centroiding', type=float, default=0.5, metavar='\b', help='Window size parameter used in centroiding a given spectrum. Only for HRMS. Default: 0.5')
+parser.add_argument('--window_size_matching', type=float, default=0.5, metavar='\b', help='Window size parameter used in matching a query spectrum and a reference library spectrum. Only for HRMS. Default: 0.5')
+parser.add_argument('--noise_threshold', type=float, default=0, metavar='\b', help='Ion fragments (i.e. points in a given mass spectrum) with intensity less than max(intensities)*noise_threshold are removed. Default: 0')
+parser.add_argument('--wf_mz', type=float, default=0, metavar='\b', help='Mass/charge weight factor parameter. Default: 0.')
+parser.add_argument('--wf_intensity', type=float, default=1, metavar='\b', help='Intensity weight factor parameter. Default: 1.')
+parser.add_argument('--LET_threshold', type=float, default=0, metavar='\b', help='Low-entropy transformation threshold parameter. Spectra with Shannon entropy less than LET_threshold are transformed according to intensitiesNew=intensitiesOriginal^{(1+S)/(1+LET_threshold)}. Default: 0.')
+parser.add_argument('--entropy_dimension', type=float, default=1.1, metavar='\b', help='Entropy dimension parameter. Must have positive value other than 1. When the entropy dimension is 1, then Renyi and Tsallis entropy are equivalent to Shannon entropy. Therefore, this parameter only applies to the renyi and tsallis similarity measures. This parameter will be ignored if similarity measure cosine or shannon is chosen. Default: 1.1.')
+parser.add_argument('--y_axis_transformation', type=str, default='normalized', metavar='\b', help='Transformation to apply to y-axis (i.e. intensity axis) of plots. Options: \'normalized\', \'none\', \'log10\', and \'sqrt\'. Default: normalized.')
+parser.add_argument('--output_path', type=str, metavar='\b', help='Output PDF file containing the plots of the query and reference spectra before and after preprocessing transformations. If no argument is passed, then the plots will be saved to the PDF ./query_spec_{query_spectrum_ID}_reference_spec_{reference_spectrum_ID}_plot.pdf in the current working directory.')
+
+args = parser.parse_args()
+
+if args.chromatography_platform == 'HRMS':
+    spectrum_preprocessing_order = 'FCNMWL'
+elif args.chromatography_platform == 'NRMS':
+    spectrum_preprocessing_order = 'FNLW'
+else:
+    print('Error: chromatography_platform must be either \'HRMS\' or \'NRMS\'')
+    sys.exit()
+
+
+if args.chromatography_platform == 'HRMS':
+    generate_plots_on_HRMS_data(query_data=args.query_data, reference_data=args.reference_data, spectrum_ID1=args.spectrum_ID1, spectrum_ID2=args.spectrum_ID2, similarity_measure=args.similarity_measure, spectrum_preprocessing_order=spectrum_preprocessing_order, high_quality_reference_library=args.high_quality_reference_library, mz_min=args.mz_min, mz_max=args.mz_max, int_min=args.int_min, int_max=args.int_max, window_size_centroiding=args.window_size_centroiding, window_size_matching=args.window_size_matching, noise_threshold=args.noise_threshold, wf_mz=args.wf_mz, wf_intensity=args.wf_intensity, LET_threshold=args.LET_threshold, entropy_dimension=args.entropy_dimension, y_axis_transformation=args.y_axis_transformation, output_path=args.output_path)
+elif args.chromatography_platform == 'NRMS':
+    generate_plots_on_NRMS_data(query_data=args.query_data, reference_data=args.reference_data, spectrum_ID1=args.spectrum_ID1, spectrum_ID2=args.spectrum_ID2, similarity_measure=args.similarity_measure, spectrum_preprocessing_order=spectrum_preprocessing_order, high_quality_reference_library=args.high_quality_reference_library, mz_min=args.mz_min, mz_max=args.mz_max, int_min=args.int_min, int_max=args.int_max, noise_threshold=args.noise_threshold, wf_mz=args.wf_mz, wf_intensity=args.wf_intensity, LET_threshold=args.LET_threshold, entropy_dimension=args.entropy_dimension, y_axis_transformation=args.y_axis_transformation, output_path=args.output_path)
+
+
+

pycompound_fy7392/processing.py

@@ -0,0 +1,316 @@
+
+# This script contains the functions used to transform spectra prior to computing similarity scores
+
+from pycompound_fy7392.build_library import build_library_from_raw_data
+import scipy.stats
+import numpy as np
+import pandas as pd
+
+def wf_transform(spec_mzs, spec_ints, wf_mz, wf_int):
+    '''
+    This function performs a weight factor transformation on a spectrum
+    
+    input:
+    wf_int: float
+    wf_mz: float
+    spec_mzs: 1d np array representing mass/charge values 
+    spec_ints: 1d np array representing intensity values 
+
+    spec_mzs and spec_ints must be of the same length N
+
+    output:
+    spec_ints: 1d np array of weight-factor-transformed spectrum intensities
+    '''
+
+    spec_ints = np.power(spec_mzs, wf_mz) * np.power(spec_ints, wf_int)
+    return(spec_ints)
+
+
+def LE_transform(intensity, thresh, normalization_method):
+    '''
+    This transformation was presented by: 
+    Li, Y.; Kind, T.; Folz, J.; Vaniya, A.; Mehta, S. S.; Fiehn, O.
+    Spectral entropy outperforms MS/MS dot product similarity for small-molecule compound identification. 
+    Nature Methods 2021, 18, 1524–1531
+    
+    input:
+    intensity: 1d np array
+    thresh: nonnegative float
+    normalization_method: either 'standard' or 'softmax'
+    
+    output:
+    1d np array of transformed intensities
+    '''
+
+    intensity_tmp = normalize(intensity, method=normalization_method)
+    if np.sum(intensity_tmp) > 0:
+        S = scipy.stats.entropy(intensity_tmp.astype('float'))
+        if S > 0 and S < thresh:
+            w = (1 + S) / (1 + thresh) 
+            intensity = np.power(intensity_tmp, w)
+    else:
+        intensity = np.zeros(len(intensity))
+    return intensity 
+
+
+def normalize(intensities,method='standard'):
+    '''
+    Normalizes a given vector to sum to 1 so that it represents a probability distribution
+
+    input:
+    intensities: 1d np array
+    method: normalization method; either 'standard' or 'softmax'
+
+    output:
+    1d np array of normalized intensities
+    '''
+
+    if np.sum(intensities) > 0:
+        if method == 'softmax':
+            if np.any(intensities > 700):
+                print("Warning: some intensities are too large to exponentiate. Applying standard normalization.")
+                intensities /= np.sum(intensities)
+            else:
+                intensities2 = np.exp(intensities)
+                if np.isinf(intensities2).sum() == 0:
+                    intensities = intensities / np.sum(intensities2)
+        elif method == 'standard':
+            intensities /= np.sum(intensities)
+    return(intensities)
+
+
+def filter_spec_lcms(spec, mz_min = 0, mz_max = 999999999999, int_min = 0, int_max = 999999999999, is_matched = False):
+    '''
+    keep points in a given spectrum in a given range of mz values and intensity values
+
+    input:
+    spec: Nx2 np array representing a mass spectrum with each row representing a peak, the first column representing mass/charge ratio, and the second column representing intensity
+    mz_min: remove peaks with mass/charge value smaller than mz_min
+    mz_max: remove peaks with mass/charge value larger than mz_max
+    int_min: remove peaks with intensity value smaller than int_min
+    int_max: remove peaks with intensity value larger than int_max
+
+    output:
+    Mx2 np array representing a mass spectrum with M <= N
+    '''
+
+    if is_matched == False:
+        spec = spec[spec[:,0] >= mz_min]
+        spec = spec[spec[:,0] <= mz_max]
+        spec = spec[spec[:,1] >= int_min]
+        spec = spec[spec[:,1] <= int_max]
+    else:
+        spec = spec[spec[:,0] >= mz_min]
+        spec = spec[spec[:,0] <= mz_max]
+        spec[spec[:,1] >= int_min] = 0
+        spec[spec[:,1] <= int_max] = 0
+    return(spec)
+
+
+def filter_spec_gcms(spec, mz_min = 0, mz_max = 999999999999, int_min = 0, int_max = 999999999999):
+    '''
+    keep points in a given spectrum in a given range of mz values and intensity values
+
+    input:
+    spec: 1d np array representing the intensities of a nominal-resolution mass spectrum
+    mz_min: remove peaks with mass/charge value smaller than mz_min
+    mz_max: remove peaks with mass/charge value larger than mz_max
+    int_min: remove peaks with intensity value smaller than int_min
+    int_max: remove peaks with intensity value larger than int_max
+
+    output:
+    spec: 1d np array representing the intensities of a nominal-resolution mass spectrum post-filtering
+    '''
+
+    spec[np.where(spec[:,0] < mz_min)[0],1] = 0
+    spec[np.where(spec[:,0] > mz_max)[0],1] = 0
+    spec[np.where(spec[:,1] < int_min)[0],1] = 0
+    spec[np.where(spec[:,1] > int_max)[0],1] = 0
+    return(spec)
+
+
+def remove_noise(spec, nr):
+    '''
+    removes points with intensity less than max(intensities)*nr
+
+    input:
+    spec: Nx2 np array representing a mass spectrum with each row representing a peak, the first column representing mass/charge ratio, and the second column representing intensity
+    nr: positive float
+
+    output:
+    Nx2 np array representing a mass spectrum with low-intensity peaks assigned intensity of 0
+    '''
+
+    if spec.shape[0] > 1:
+        if nr is not None:
+            spec[np.where(spec[:,1] < np.max(spec[:,1]) * nr)[0]] = 0
+
+    return(spec)
+
+
+def centroid_spectrum(spec, window_size):
+    '''
+    This function was presented by: 
+    Li, Y.; Kind, T.; Folz, J.; Vaniya, A.; Mehta, S. S.; Fiehn, O.
+    Spectral entropy outperforms MS/MS dot product similarity for small-molecule compound identification. 
+    Nature Methods 2021, 18, 1524–1531
+
+    input:
+    spectrum: Nx2 np array with first column being mass/charge and second column being intensity
+    window_size: window-size parameter
+
+    output:
+    Mx2 np array representing the centroided spectrum with M <= N
+    '''
+
+    spec = spec[np.argsort(spec[:,0])]
+
+    #Fast check is the spectrum needs centroiding
+    mz_array = spec[:, 0]
+    need_centroid = 0
+    if mz_array.shape[0] > 1:
+        mz_delta = mz_array[1:] - mz_array[:-1]
+        if np.min(mz_delta) <= window_size:
+            need_centroid = 1
+
+    if need_centroid:
+        intensity_order = np.argsort(-spec[:, 1])
+        spec_new = []
+        for i in intensity_order:
+            mz_delta_allowed = window_size
+
+            if spec[i, 1] > 0:
+                #Find left bound for current peak
+                i_left = i - 1
+                while i_left >= 0:
+                    mz_delta_left = spec[i, 0] - spec[i_left, 0]
+                    if mz_delta_left <= mz_delta_allowed:
+                        i_left -= 1
+                    else:
+                        break
+                i_left += 1
+
+                #Find right bound for current peak
+                i_right = i + 1
+                while i_right < spec.shape[0]:
+                    mz_delta_right = spec[i_right, 0] - spec[i, 0]
+                    if mz_delta_right <= mz_delta_allowed:
+                        i_right += 1
+                    else:
+                        break
+
+                #Merge those peaks
+                intensity_sum = np.sum(spec[i_left:i_right, 1])
+                intensity_weighted_sum = np.sum(spec[i_left:i_right, 0] * spec[i_left:i_right, 1])
+
+                spec_new.append([intensity_weighted_sum / intensity_sum, intensity_sum])
+                spec[i_left:i_right, 1] = 0
+
+        spec_new = np.array(spec_new)
+        spec_new = spec_new[np.argsort(spec_new[:, 0])]
+        if spec_new.shape[0] > 1:
+            spec_new = spec_new[np.argsort(spec_new[:, 0])]
+            return spec_new
+        else:
+            return np.array([[0,0]])
+    else:
+        return spec
+
+
+
+def match_peaks_in_spectra(spec_a, spec_b, window_size):
+    '''
+    This function was presented by: 
+    Li, Y.; Kind, T.; Folz, J.; Vaniya, A.; Mehta, S. S.; Fiehn, O.
+    Spectral entropy outperforms MS/MS dot product similarity for small-molecule compound identification. 
+    Nature Methods 2021, 18, 1524–1531
+
+    This function matches two spectra to find common peaks in order
+    to obtain two lists of intensities of the same length
+
+    input:
+    spec_a: Nx2 np array with first column being mass/charge and second column being intensity
+    spec_b: Mx2 np array with first column being mass/charge and second column being intensity
+    window_size: window-size parameter
+
+    output:
+    Kx3 np array with first column being mass/charge, second column being matched intensities of spec_a, and third column being matched intensities of spec_b
+    '''
+
+    a = 0
+    b = 0
+
+    spec_merged = []
+    peak_b_int = 0.
+    while a < spec_a.shape[0] and b < spec_b.shape[0]:
+        mass_delta = spec_a[a, 0] - spec_b[b, 0]
+        
+        if mass_delta < -window_size:
+            # Peak only existed in spec a.
+            spec_merged.append([spec_a[a, 0], spec_a[a, 1], peak_b_int])
+            peak_b_int = 0.
+            a += 1
+        elif mass_delta > window_size:
+            # Peak only existed in spec b.
+            spec_merged.append([spec_b[b, 0], 0., spec_b[b, 1]])
+            b += 1
+        else:
+            # Peak existed in both spec.
+            peak_b_int += spec_b[b, 1]
+            b += 1
+
+    if peak_b_int > 0.:
+        spec_merged.append([spec_a[a, 0], spec_a[a, 1], peak_b_int])
+        peak_b_int = 0.
+        a += 1
+
+    if b < spec_b.shape[0]:
+        spec_merged += [[x[0], 0., x[1]] for x in spec_b[b:]]
+
+    if a < spec_a.shape[0]:
+        spec_merged += [[x[0], x[1], 0.] for x in spec_a[a:]]
+
+    if spec_merged:
+        spec_merged = np.array(spec_merged, dtype=np.float64)
+    else:
+        spec_merged = np.array([[0., 0., 0.]], dtype=np.float64)
+    return spec_merged
+
+
+
+def convert_spec(spec, mzs):
+    '''
+    imputes intensities of 0 where there is no mass/charge value reported in a given spectrum
+    input: 
+    spec: Nx2 numpy array
+    mzs: list of entire span of mass/charge values considering both the query and reference libraries
+
+    output: 
+    Nx2 numpy array
+    '''
+
+    ints_tmp = []
+    for i in range(0,len(mzs)):
+        if mzs[i] in spec[:,0]:
+            int_tmp = spec[np.where(spec[:,0] == mzs[i])[0][0],1]
+        else:
+            int_tmp = 0
+        ints_tmp.append(int_tmp)
+    out = np.transpose(np.array([mzs,ints_tmp]))
+    return out
+
+
+def get_reference_df(reference_data, likely_reference_IDs=None):
+    extension = reference_data.rsplit('.',1)
+    extension = extension[(len(extension)-1)]
+    if extension == 'mgf' or extension == 'MGF' or extension == 'mzML' or extension == 'mzml' or extension == 'MZML' or extension == 'cdf' or extension == 'CDF':
+        output_path_tmp = reference_data[:-3] + 'csv'
+        build_library_from_raw_data(input_path=reference_data, output_path=output_path_tmp, is_reference=True)
+        df_reference = pd.read_csv(output_path_tmp)
+    if extension == 'csv' or extension == 'CSV':
+        df_reference = pd.read_csv(reference_data)
+    if likely_reference_IDs is not None:
+        likely_reference_IDs = pd.read_csv(likely_reference_IDs, header=None)
+        df_reference = df_reference.loc[df_reference.iloc[:,0].isin(likely_reference_IDs.iloc[:,0].tolist())]
+    return df_reference
+

pycompound_fy7392/similarity_measures.py

@@ -0,0 +1,100 @@
+
+##### Similarity Score Functions #####
+# Note that the input for all similarity measures are two 1-d np arrays of the same length. 
+# These 1-d arrays must be normalized to sum to 1 for the Shannon, Renyi, and Tsallis Entropy Similarity Measures.
+
+import scipy.stats
+import numpy as np
+import sys
+
+
+def S_cos(ints_a, ints_b):
+    # Cosine Similarity Measure
+    if np.sum(ints_a) == 0 or np.sum(ints_b) == 0:
+        return(0)
+    else:
+        return np.dot(ints_a,ints_b) / (np.sqrt(sum(np.power(ints_a,2))) * np.sqrt(sum(np.power(ints_b,2))))
+
+
+def ent_renyi(ints, q):
+    # Computes the Renyi entropy of a probability distribution for a given positive entropy dimension q
+    return np.log(sum(np.power(ints,q))) / (1-q)
+
+
+def ent_tsallis(ints, q):
+    # Computes the Tsallis entropy of a probability distribution for a given positive entropy dimension q
+    return (sum(np.power(ints,q))-1) / (1-q)
+
+
+def S_shannon(ints_a, ints_b):
+    '''
+    Shannon Entropy Similarity Measure
+
+    This similarity function was presented by: 
+    Li, Y.; Kind, T.; Folz, J.; Vaniya, A.; Mehta, S. S.; Fiehn, O.
+    Spectral entropy outperforms MS/MS dot product similarity for small-molecule compound identification. 
+    * Note that since scipy.stats.entropy normalizes the input vector to sum to 1, vec1 and vec1 need not be normalized when computing ent_ab
+    '''
+
+    ent_a = scipy.stats.entropy(ints_a)
+    ent_b = scipy.stats.entropy(ints_b)
+    ent_ab = scipy.stats.entropy(ints_a + ints_b)
+    return(1 - (2 * ent_ab - ent_a - ent_b)/np.log(4))
+
+
+def S_renyi(ints_a, ints_b, q):
+    '''
+    Renyi Entropy Similarity Measure
+    * This is a novel similarity measure which generalizes the Shannon Entropy Similarity Measure
+    * The Renyi Similarity Measure approaches the Shannon Entropy Similiarity Measure as q approaches 1
+    * ints_a and ints_b must be normalized to sum to 1
+    '''
+    if q == 1:
+        print('Warning: the Renyi Entropy Similarity Measure is equivalent to the Shannon Entropy Similarity Measure when the entropy dimension is 1')
+        return S_shannon(ints_a, ints_b)
+    else:
+        ent_a = ent_renyi(ints_a, q)
+        ent_b = ent_renyi(ints_b, q)
+        ent_merg = ent_renyi(ints_a/2 + ints_b/2, q)
+        N = (1/(1-q)) * (2*np.log(np.sum(np.power(ints_a/2,q))+np.sum(np.power(ints_b/2,q))) - np.log(np.sum(np.power(ints_a,q))) - np.log(np.sum(np.power(ints_b,q))))
+        return 1 - (2 * ent_merg - ent_a - ent_b) / N
+
+
+def S_tsallis(ints_a, ints_b, q):
+    '''
+    Tsallis Entropy Similarity Measure
+    * This is a novel similarity measure which generalizes the Shannon Entropy Similarity Measure
+    * The Tsallis Similarity Measure approaches the Shannon Entropy Similiarity Measure as q approaches 1
+    * ints_a and ints_b must be normalized to sum to 1
+    '''
+    if q == 1:
+        print('Warning: the Tsallis Entropy Similarity Measure is equivalent to the Shannon Entropy Similarity Measure when the entropy dimension is 1')
+        return S_shannon(ints_a, ints_b)
+    else:
+        ent_a = ent_tsallis(ints_a, q)
+        ent_b = ent_tsallis(ints_b, q)
+        ent_merg = ent_tsallis(ints_a/2 + ints_b/2, q)
+        N = np.sum(2*np.power(ints_a/2,q)+2*np.power(ints_b/2,q)-np.power(ints_a,q)-np.power(ints_b,q)) / (1-q)
+        return 1 - (2 * ent_merg - ent_a - ent_b) / N
+
+def S_mixture(ints_a, ints_b, weights={'Cosine':0.25, 'Shannon':0.25, 'Renyi':0.25, 'Tsallis':0.25}, q=1.1):
+    '''
+    Mixture similarity measure that is a weighted sum of any combination of the four similarity measures of Cosine, Shannon, Renyi, and Tsallis
+    '''
+    if set(weights.keys()).issubset(set(['Cosine','Shannon','Renyi','Tsallis'])) is False:
+        print('Error: the keys to the weight parameter dict of the function S_mixture must be one of the four: Cosine, Shannon, Renyi, Tsallis')
+        sys.exit()
+
+    similarity = 0
+    for key, value in weights.items():
+        if key == 'Cosine':
+            similarity += value * S_cos(ints_a,ints_b)
+        if key == 'Shannon':
+            similarity += value * S_shannon(ints_a,ints_b)
+        if key == 'Renyi':
+            similarity += value * S_renyi(ints_a,ints_b,q)
+        if key == 'Tsallis':
+            similarity += value * S_tsallis(ints_a,ints_b,q)
+    return similarity
+
+