chromaquant 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

chromaquant/Match/MatchSub/matchTools.py

@@ -0,0 +1,282 @@
+"""
+
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2024, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+	      URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+SUBPACKAGE FOR MATCHING FID AND MS PEAKS ACCORDING TO A PASSED MODEL
+
+Julia Hancock
+Started 12/10/2024
+
+"""
+
+""" PACKAGES """
+import pandas as pd
+
+""" FUNCTIONS """
+
+#Third order function for testing
+fit = lambda FID_RT: 0.0252*FID_RT**3 - 0.5274*FID_RT**2 + 4.8067*FID_RT - 3.0243
+
+#Function that estimates unknown MS RT's and matches FID and MS peaks using a provided fit
+def matchPeaks(fpmDF,mDF,fit,peakError=0.06):
+
+    """
+    Parameters
+    ----------
+    fpmDF : DataFrame
+        Dataframe containing FID and MS peak info
+    mDF : DataFrame
+        Dataframe containing MS info about identified compounds (UA_UPP)
+    linfits : Function
+        Function that returns an estimated MS RT with a passed FID RT
+    peakError : Float, optional
+        Allowable error between estimated MS RT's and actual MS RT's. The default is 0.01.
+
+    Returns
+    -------
+    fpmDF : DataFrame
+        Dataframe containing FID and MS peak info
+    """
+    
+    def matchOne(fpmDF,fpmiter,fit,peakError):
+        """
+        Parameters
+        ----------
+        fpmDF : DataFrame
+            Dataframe containing FID and MS peak info
+        fpmiter : List
+            List containing current index and row in fpmDF of interest in form [i,row]
+        linfits : List
+            List containing info about a linear fit for estimated MS RT's in the form [m,b,r2]
+        peakError : float
+            Allowable error between estimated MS RT's and actual MS RT's
+
+        Returns
+        -------
+        fpmDF : DataFrame
+            Dataframe containing FID and MS peak info
+        """
+        
+        #Unpack fpmDF iterating info
+        fpmi = int(fpmiter[0])
+        fpmrow = fpmiter[1]
+        
+        #Estimate an MS RT for the row's FID RT using the fit
+        est_MSRT = fit(fpmrow['FID RT'])
+        #Compare the estimated MS RT to all real MS RT's, seeing if there is a match within error
+        mDF_match = mDF.loc[(mDF['Component RT'] >= est_MSRT-peakError) & (mDF['Component RT'] <= est_MSRT+peakError)].copy()
+        #If there is more than one match, select the entry with the smallest error
+        if len(mDF_match) > 1:
+            #Add an RT error to all mDF_match entries
+            for i, row in mDF_match.iterrows():
+                mDF_match.at[i,'RT Error'] = abs(fpmrow['FID RT']-est_MSRT)
+            
+            #Set mDF_match to the row with minimum RT Error
+            mDF_match = mDF_match.nsmallest(1,'RT Error')
+            
+        #Reset the mDF_match index
+        mDF_match = mDF_match.reset_index().copy()
+        
+        #If the length of mDF_match is greater than zero..
+        if len(mDF_match) > 0:
+            
+            #Add the MS info to the FIDpMS dataframe
+            fpmDF.at[fpmi,'MS RT'] = mDF_match.at[0,'Component RT']
+            fpmDF.at[fpmi,'Compound Name'] = mDF_match.at[0,'Compound Name']
+            fpmDF.at[fpmi,'Formula'] = mDF_match.at[0,'Formula']
+            fpmDF.at[fpmi,'Match Factor'] = mDF_match.at[0,'Match Factor']
+            fpmDF.at[fpmi,'Compound Source'] = 'Automatically assigned using a linear fit of manual peak assignments'
+            
+        #Otherwise, pass
+        else:
+            pass
+        
+        return fpmDF
+    
+    #Loop through every row in the dataframe
+    for i, row in fpmDF.iterrows():
+        #If the row's compound name is not blank
+        if not pd.isna(row['Compound Name']):
+            #If the row's compound source is either manual or blank, skip it
+            if row['Compound Source'] == 'Manual' or pd.isna(row['Compound Source']):
+                pass
+            #Otherwise..
+            else:
+                #Match one FID peak
+                fpmDF = matchOne(fpmDF, [i,row], fit, peakError)
+        #Otherwise, if the row's compound name is blank..
+        else:
+            #Match one FID peak
+            fpmDF = matchOne(fpmDF, [i,row], fit, peakError)
+    
+    return fpmDF
+
+#Function that matches FID and MS peaks by their retention time
+def matchRT(fpmDF,mDF,peakError=0.06):
+    """
+    Parameters
+    ----------
+    fpmDF : DataFrame
+        Dataframe containing FID and MS peak info
+    mDF : DataFrame
+        Dataframe containing MS info about identified compounds (UA_UPP)
+    peakError : Float, optional
+        Allowable error between estimated MS RT's and actual MS RT's. The default is 0.01.
+
+    Returns
+    -------
+    fpmDF : DataFrame
+        Dataframe containing FID and MS peak info
+    """
+    
+    def matchOne(fpmDF,fpmiter,peakError):
+        """
+        Parameters
+        ----------
+        fpmDF : DataFrame
+            Dataframe containing FID and MS peak info
+        fpmiter : List
+            List containing current index and row in fpmDF of interest in form [i,row]
+        peakError : float
+            Allowable error between estimated MS RT's and actual MS RT's
+
+        Returns
+        -------
+        fpmDF : DataFrame
+            Dataframe containing FID and MS peak info
+        """
+        
+        #Unpack fpmDF iterating info
+        fpmi = int(fpmiter[0])
+        fpmrow = fpmiter[1]
+        
+        #Compare the FID RT to the MS RT, collecting all matches within the specified peak error
+        mDF_match = mDF.loc[(mDF['Component RT'] >= fpmrow['FID RT']-peakError) & (mDF['Component RT'] <= fpmrow['FID RT']+peakError)].copy()
+        #If there is more than one MS RT match, select the entry with the smallest error from the FID RT
+        if len(mDF_match) > 1:
+            #Add an RT error to all mDF_match entries
+            for i, row in mDF_match.iterrows():
+                mDF_match.at[i,'RT Error'] = abs(fpmrow['FID RT']-row['Component RT'])
+            
+            #Set mDF_match to the row with minimum RT Error
+            mDF_match = mDF_match.nsmallest(1,'RT Error')
+            
+        #Reset the mDF_match index
+        mDF_match = mDF_match.reset_index().copy()
+        
+        #If the length of mDF_match is greater than zero..
+        if len(mDF_match) > 0:
+            
+            #Add the MS info to the FIDpMS dataframe
+            fpmDF.at[fpmi,'MS RT'] = mDF_match.at[0,'Component RT']
+            fpmDF.at[fpmi,'Compound Name'] = mDF_match.at[0,'Compound Name']
+            fpmDF.at[fpmi,'Formula'] = mDF_match.at[0,'Formula']
+            fpmDF.at[fpmi,'Match Factor'] = mDF_match.at[0,'Match Factor']
+            fpmDF.at[fpmi,'Compound Source'] = 'Automatically assigned by comparing FID and MS retention times'
+            
+        #Otherwise, pass
+        else:
+            pass
+        
+        return fpmDF
+    
+    #Loop through every row in the dataframe
+    for i, row in fpmDF.iterrows():
+        #If the row's compound name is not blank
+        if not pd.isna(row['Compound Name']):
+            #If the row's compound source is either manual or blank, skip it
+            if row['Compound Source'] == 'Manual' or pd.isna(row['Compound Source']):
+                pass
+            #Otherwise..
+            else:
+                #Match one FID peak
+                fpmDF = matchOne(fpmDF, [i,row], peakError)
+        #Otherwise, if the row's compound name is blank..
+        else:
+            #Match one FID peak
+            fpmDF = matchOne(fpmDF, [i,row], peakError)
+    
+    return fpmDF
+
+#Function that performs a subset of speculative labeling, using known peaks hard-coded in a file gasPairs_FIDpMS.csv 
+def matchKnownPeaks(fpmDF,mDF,gp_rsc):
+    def matchOne(fpmDF,fpmiter,gp_rsc):
+        """
+        Parameters
+        ----------
+        fpmDF : DataFrame
+            Dataframe containing FID and MS peak info
+        fpmiter : List
+            List containing current index and row in fpmDF of interest in form [i,row]
+        gp_rsc : DataFrame
+            Dataframe containing opened gasPairs resource.
+        peakError : float
+            Allowable error between estimated MS RT's and actual MS RT's
+
+        Returns
+        -------
+        fpmDF : DataFrame
+            Dataframe containing FID and MS peak info
+        """
+        
+        #Unpack fpmDF iterating info
+        fpmi = int(fpmiter[0])
+        fpmrow = fpmiter[1]
+        
+        #Search the gasPairs resource to see if any known peaks/RT's match the FID peak list
+        for i, row in gp_rsc.iterrows():
+            #Set gp_match to empty string
+            gp_match = pd.Series()
+            #Define error as two times the standard deviation for the FID RT in the gasPeaks resource
+            gp_error = row['Stdev FID RT']*2
+            #Extract the FID RT from the resource
+            gp_FIDRT = row['Average FID RT']
+            #If the current fpmrow FID RT is within the error bounds of an entry in the resource, match it
+            #NOTE: prefers the first match, even if the next match is closer. Most resourceRT's are more than 
+            #2*error away from each other
+            if (fpmrow['FID RT'] >= gp_FIDRT - gp_error) and (fpmrow['FID RT'] <= gp_FIDRT + gp_error):
+                gp_match = row
+                break
+            #Otherwise, pass
+            else:
+                pass
+        
+        #If gp_match is empty, pass
+        if gp_match.empty:
+            pass
+        #Otherwise, add the match info
+        else:
+            #Add the resource match info to the FIDpMS dataframe
+            fpmDF.at[fpmi,'Compound Name'] = gp_match['Species']
+            fpmDF.at[fpmi,'Formula'] = gp_match['Formula']
+            fpmDF.at[fpmi,'Compound Source'] = 'Automatically assigned using gas pairs provided in resources'
+        
+        return fpmDF
+    
+    #Loop through every row in the dataframe
+    for i, row in fpmDF.iterrows():
+        #If the row's compound name is not blank
+        if not pd.isna(row['Compound Name']):
+            #If the row's compound source is either manual or blank, skip it
+            if row['Compound Source'] == 'Manual' or pd.isna(row['Compound Source']):
+                pass
+            #Otherwise..
+            else:
+                #Match one FID peak
+                fpmDF = matchOne(fpmDF, [i,row], gp_rsc)
+        #Otherwise, if the row's compound name is blank..
+        else:
+            #Match one FID peak
+            fpmDF = matchOne(fpmDF, [i,row], gp_rsc)
+    
+    return fpmDF

chromaquant/Match/MatchSub/peakTools.py

@@ -0,0 +1,259 @@
+"""
+
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2024, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+	      URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+SUBPACKAGE FOR POSTPROCESSING AFTER MATCHING
+
+Julia Hancock
+Started 12/10/2024
+
+"""
+
+""" PACKAGES """
+import pandas as pd
+
+""" FUNCTIONS """
+
+#Function that performs compound type abbreviation assignment
+def ctaAssign(importDF, contains, keyLoop, elementExclude):
+
+    #Function that returns a compound type abbreviation corresponding to a compound
+    def assignType(compoundName,contains,keyLoop):
+        
+        #Define default compound type abbreviation as 'O'
+        CTA = 'O'
+        
+        #Function that accepts a list of substrings to check against a string and returns a boolean
+        def stringSearch(string,subList):
+            #Define export boolean default value
+            checkTF = False
+            #For every substring in subList...
+            for i in range(len(subList)):
+                
+                #If the substring can be found in the string...
+                if subList[i] in string:
+                    #Assign boolean to True and break
+                    checkTF = True
+                    break
+                #Otherwise, pass
+                else:
+                    pass
+            
+            return checkTF
+        
+        #Loop through every key (compound type abbreviation) in contains
+        for i in keyLoop:
+            
+            #If at least one substring in the key's list is found in compoundName...
+            if stringSearch(compoundName,contains[i]):
+                #Assign the compound type abbreviation to the current key and break the loop
+                CTA = i
+                break
+            #Otherwise, pass
+            else:
+                pass
+        
+        return CTA
+
+    #Function that checks if formula string contains any of a list of elements
+    def checkElements(compoundFormula,elementList):
+        #Assign default export boolean to False
+        checkTF = False
+        
+        #For every substring in elementList...
+        for i in range(len(elementList)):
+            #If the substring can be found in the compound formula...
+            if elementList[i] in compoundFormula:
+                #Set boolean to True and break
+                checkTF = True
+                break
+            #Otherwise, pass
+            else:
+                pass
+        
+        return checkTF
+
+    #For every entry in the csv, assign a compound type abbreviation
+    for i, row in importDF.iterrows():
+        
+        #Retrieve compound name and formula from row entry
+        compoundName = row['Compound Name']
+        compoundFormula = row['Formula']
+        
+        #If the compound formula is a string...
+        if isinstance(compoundFormula,str):
+            
+            #If the formula contains excluded elements...
+            if checkElements(compoundFormula,elementExclude):
+                
+                #Assign 'O' to the row's compound type abbreviation entry
+                importDF.at[i,'Compound Type Abbreviation'] = 'O'
+            
+            #Otherwise...
+            else:
+                
+                #If the compound name is a string...
+                if isinstance(compoundName,str):
+                
+                    #Change compound name to lowercase
+                    compoundName = compoundName.lower()
+                    #Get a corresponding compound type abbreviation
+                    CTA = assignType(compoundName, contains, keyLoop)
+                    #Assign this CTA to the row's compound type abbreviation entry
+                    importDF.at[i,'Compound Type Abbreviation'] = CTA
+                
+                #Otherwise, pass
+                else:
+                    pass
+    
+    return importDF
+
+
+#Define function that loops through every row in a DataFrame and modifies rows with duplicate compounds
+def duplicateHandle(DF):
+    
+    #Define function that searches for rows in a DataFrame with duplicate compound names
+    def duplicateSearch(DF,cmp_name):
+        
+        #Get a new dataframe that is a copy of the first argument
+        DF_out = DF.copy()
+        
+        #Filter the dataframe using the provided compound name
+        DF_out = DF_out[DF_out['Compound Name'] == cmp_name]
+        
+        #Define a Boolean describing whether or not there are duplicate rows
+        duplicate_TF = False
+        
+        #If the DF_out dataframe is longer than one (if there are duplicate rows)...
+        if len(DF_out) > 1:
+            
+            #Assign the Boolean to true
+            duplicate_TF = True
+            
+            #Define the dataframe to be returned
+            DF_return = DF_out.copy()
+            
+        #Otherwise, define the return dataframe as empty
+        else:
+            DF_return = pd.DataFrame()
+            
+        #Return the boolean and the filtered DataFrame
+        return duplicate_TF, DF_return
+    
+    #Define function that handles a given DataFrame of duplicates
+    def duplicateLogic(DF_search):
+        
+        #Define the output DataFrame as an in copy
+        DF_logic = DF_search.copy()
+        
+        #Get the row in the DataFrame with the largest area
+        maxSeries = DF_logic.loc[DF_logic['FID Area'].idxmax()]
+        
+        #Get the name and compound type of this compound
+        max_name = maxSeries['Compound Name']
+        max_type = maxSeries['Compound Type Abbreviation']
+        
+        #Get the remaining entries in the DataFrame
+        DF_logic = DF_logic.drop([maxSeries.name],axis=0)
+        
+        #For every row in the remaining entries DataFrame, rename the compound to 'Isomer of..' 
+        for i, row in DF_logic.iterrows():
+            
+            #Get the new compound name
+            new_cmp_name = 'Isomer of ' + max_name
+            
+            #Replace the compound name
+            DF_logic.at[i,'Compound Name'] = new_cmp_name
+            
+            #If the compound type of the maxSeries is linear alkanes...
+            if max_type == 'L':
+                
+                #Set the current row's compound type to branched alkanes
+                DF_logic.at[i,'Compound Type Abbreviation'] = 'B'
+                
+            #Otherwise, pass
+            else:
+                pass
+        
+        #Return the logic DataFrame
+        return DF_logic
+    
+    #Define a function that replaces rows in the primary DataFrame with matches in the secondary, assuming the indices match
+    def duplicateReplace(pDF,sDF):
+        
+        #For every entry in the secondary DataFrame...
+        for i, row in sDF.iterrows():
+            
+            #Get the row's name, which is the numeric index in the DataFrame
+            row_name = row.name
+            
+            #For every index in the row...
+            for j in row.index:
+                
+                #Replace the corresponding entry in the pDF at the preserved sDF index
+                pDF.at[row_name,j] = row[j]
+        
+        return pDF
+        
+    #Define a list of compound names already handled
+    cmp_nameList = []
+    
+    #Create a copy of the argument DataFrame to be used
+    DF_in = DF.copy()
+    
+    #Initialize a DataFrame for the logic output
+    DF_logic = pd.DataFrame()
+    
+    #Initialize a DataFrame for the output DF, create a copy of original DF in case there are no duplicates
+    DF_done = DF.copy()
+
+    #For every row in the provided DataFrame
+    for i, row in DF_in.iterrows():
+        
+        #Get the compound name in that row
+        cmp_name = row['Compound Name']
+        
+        #If the compound name is in the list of compound names handled, pass
+        if cmp_name in cmp_nameList:
+            pass
+        
+        #Otherwise...
+        else:
+                
+            #If the compound name is 'No Match' or 'No match' or nan, pass
+            if cmp_name == 'No Match' or cmp_name == 'No Match' or pd.isna(cmp_name):
+                pass
+            
+            #Otherwise...
+            else:
+                
+                #Run the duplicate search function for that compound name
+                duplicate_TF, DF_search = duplicateSearch(DF_in,cmp_name)
+                
+                #If duplicate_TF is True...
+                if duplicate_TF:
+
+                    #Run the duplicate logic funcion
+                    DF_logic = duplicateLogic(DF_search)
+                    
+                    #Run the duplicate replace function
+                    DF_done = duplicateReplace(DF_in,DF_logic)
+                    
+                #Otherwise, pass
+                else:
+                    pass
+                
+                #Add the compound name to the compound name list
+                cmp_nameList.append(cmp_name)
+        
+    return DF_done

chromaquant/Match/__init__.py

@@ -9,4 +9,5 @@ Created 10-19-2024
 
 """
 
-from .AutoFpmMatch import main_AutoFpmMatch
+from .AutoFpmMatch import main_AutoFpmMatch
+from .matchMain import mainMatch