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

chromaquant/Match/matchMain.py

@@ -0,0 +1,233 @@
+"""
+
+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
+
+---
+
+SCRIPT THAT MATCHES FID AND MS PEAKS
+
+Julia Hancock
+Started 12/10/2023
+
+"""
+""" PACKAGES """
+import sys
+import pandas as pd
+import os
+from molmass import Formula
+import math
+import numpy as np
+from chemformula import ChemFormula
+import json
+from datetime import datetime
+import logging
+import scipy
+import importlib.util
+
+""" DIRECTORIES (MANUAL) """
+"""
+testPath = "/Users/connards/Desktop/University/Rorrer Lab/Scripts/chromaquant/src/chromaquant/"
+#Define file directory
+D_files = "/Users/connards/Documents/ChromaQuant"
+
+#Define app directory
+D_app = "/Users/connards/Desktop/University/Rorrer Lab/Scripts/chromaquant/src/chromaquant"
+    
+#Define resources directory
+D_rsc = os.path.join(D_files,'resources')
+    
+#Define theme directory
+D_theme = os.path.join(D_rsc,'forest','forest-light.tcl')
+    
+#Define response factors directory
+D_rf = os.path.join(D_files,'response-factors')
+    
+#Define data directory
+D_data = os.path.join(D_files,'data')
+    
+#Define images directory
+D_img = os.path.join(D_files,'images')
+
+directories = {'files':D_files,'resources':D_rsc,'theme':D_theme,'rf':D_rf,'data':D_data,'images':D_img}
+"""
+
+""" VARIABLES FOR TESTING"""
+
+#sname = 'example2'
+#sphase = 'L'
+
+""" LOCAL PACKAGES """
+
+#Get package directory
+app_dir =  os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+#Get absolute directories for subpackages
+subpack_dir = {'Handle':os.path.join(app_dir,'Handle','__init__.py'),
+               'Manual':os.path.join(app_dir,'Manual','__init__.py'),
+               'MatchSub':os.path.join(app_dir,'Match','MatchSub','__init__.py')}
+
+#Define function to import from path
+def import_from_path(module_name,path):
+    #Define spec
+    spec = importlib.util.spec_from_file_location(module_name,path)
+    #Define modules
+    module = importlib.util.module_from_spec(spec)
+    #Expand sys.modules dict
+    sys.modules[module_name] = module
+    #Load module
+    spec.loader.exec_module(module)
+    return module
+
+#Import all local packages
+hd = import_from_path("hd",subpack_dir['Handle'])
+mn = import_from_path("mn",subpack_dir['Manual'])
+mtsb = import_from_path("mtsb",subpack_dir['MatchSub'])
+
+""" FIT DEFINITION FUNCTION """
+
+#Function that defines fit lambda based on parameters in analysis-config
+def getFitLambda(fit_param):
+        """ This function requires a dictionary of polynomial parameters, with keys "a", "b", etc. """
+        
+        if fit_param['fit-type'] == "First Order":
+            
+            fit = lambda FID_RT: fit_param['a']*FID_RT + fit_param['b'] 
+
+        elif fit_param['fit-type'] == "Third Order":
+
+            fit = lambda FID_RT: fit_param['a']*FID_RT**3 + fit_param['b']*FID_RT**2 + fit_param['c']*FID_RT + fit_param['d']
+        
+        else:
+             
+             fit = None
+
+        return fit
+
+""" MATCH FUNCTION """
+def mainMatch(sname,sphase,model):
+
+    print("[matchMain] Beginning match...")
+
+    #Get current time
+    print("[matchMain] Getting current time...")
+    now = datetime.now()
+
+    """ DIRECTORIES """
+    print("[matchMain] Getting directories...")
+    #Get directories from handling script
+    directories = hd.handle(app_dir)
+
+    #Data file log directory
+    directories['log'] = os.path.join(directories['data'],sname,'log')
+
+    #Data file breakdowns directory
+    directories['break'] = os.path.join(directories['data'],sname,'breakdowns')
+
+    #Raw data file directory
+    directories['raw'] = os.path.join(directories['data'],sname,'raw data')
+
+    """ ANALYSIS CONFIGURATION """
+    print("[matchMain] Interpreting analysis configuration...")
+    #Read analysis configuration file
+    with open(os.path.join(directories['resources'],'analysis-config.json')) as f:
+        analysis_config = json.load(f)
+
+    #Extract analysis configuration info
+    #This dictionary contain lists of substrings to be checked against compound name strings to
+    #assign a compound type
+
+    #Six compound types exist: linear alkanes (L), branched alkanes (B), aromatics (A), cycloalkanes (C),
+    #alkenes/alkynes (E), and other (O)
+
+    #Each compound type abbreviation will have an entry in the dictionary corresponding to a list of
+    #substrings to be checked against a compound name string
+
+    contains = analysis_config["CT-assign-contains"]
+
+    #Tuple of contains keys in order of priority
+    keyloop = analysis_config["CT-assign-keyloop"]
+
+    #Tuple of elements to be excluded and automatically labelled as 'O'
+    element_exclude = analysis_config["CT-assign-element-exclude"]
+
+    #File suffixes to add to form data filenames
+    file_suffix = analysis_config["file-suffix"]
+
+    #Fit parameters for matching FID and MS accortding to polynomial fit
+    match_fit_parameters = analysis_config["match-fit-parameters"]
+
+    #Acceptable peak errors for matching
+    peak_errors = analysis_config["peak-errors"]
+
+    """ RUN FUNCTIONS """
+    print("[matchMain] Running match functions...")
+
+    #Run the file naming function – this function will create paths to all relevant files for matching FID and MS peaks according to sample name and phase
+    print("[matchMain] Getting data pths...")
+    paths = hd.fileNamer(sname,sphase,file_suffix,directories['raw'])
+
+    # Run the file checking function – this function will search for an existing FIDpMS file, creating one if it does not exist. 
+    # It will then read the file as a pandas DataFrame. The tf Boolean describes whether or not there exist manually-matched peaks.
+    print("[matchMain] Checking for FIDpMS file...")
+    fpmDF, tf = hd.checkFile(paths[2],paths[0])
+
+    # Import MS UPP data
+    print("[matchMain] Importing mass spectrometry data...")
+    mDF = pd.read_csv(paths[1])
+
+    # Get only relevant columns of MS UPP data
+    print("[matchMain] Cleaning mass spectrometry data...")
+    mDF = mDF.loc[:,['Component RT','Compound Name','Formula','Match Factor']]
+
+    # 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
+
+    # Get fit function using analysis-config
+    print("[matchMain] Extracting match fit parameters...")
+    fit = getFitLambda(match_fit_parameters)
+
+    #If model is polynomial...
+    if model == 'P':
+        # Run the matching function – this function takes a passed function describing an estimated relationship between MS RT's and FID RT's and matches peaks. 
+        # Function can be of any form as long as it returns a floating point value for the estimated MS RT
+        print("[matchMain] Matching peaks according to polynomial fit...")
+        fpmDF = mtsb.matchPeaks(fpmDF,mDF,fit,peak_errors['peak-error-third']) 
+
+    #If model is retention time...
+    if model == 'R':
+         # Run the matching function – this function takes a passed function describing an estimated relationship between MS RT's and FID RT's and matches peaks. 
+        # Function can be of any form as long as it returns a floating point value for the estimated MS RT
+        print("[matchMain] Matching peaks by retention time...")
+        fpmDF = mtsb.matchRT(fpmDF,mDF,peakError=peak_errors['peak-error-RT'])
+        fpmDF = mtsb.matchPeaks(fpmDF,mDF,fit,peak_errors['peak-error-third']) 
+
+    # Run the compound type abbreviation assignment function – this function takes a passed matched FID and MS list and assigns
+    # compound type abbreviations to each matched entry
+    print("[matchMain] Assigning compound types...")
+    fpmDF = mtsb.ctaAssign(fpmDF, contains, keyloop, element_exclude)
+
+    print("[matchMain] Handling duplicates...")
+    #Run the duplicate handling function
+    fpmDF = mtsb.duplicateHandle(fpmDF)
+
+    print("[AutoFpmMatch] Saving results...")
+    #Save the FIDpMS data
+    fpmDF.to_csv(paths[2],index=False)
+    
+    #Print computation time
+    compTime = datetime.now().timestamp()*1000 - now.timestamp()*1000
+    print("[matchMain] Time taken: {:.3f} ms".format(compTime))
+
+    #Close main function by returning
+    return None
+
+#For testing
+#mainMatch('example2','L','R')

chromaquant/Quant/QuantSub/__init__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+ChromaQuant.Match.MatchSub package initialization
+
+Julia Hancock
+Created 10-19-2024
+
+"""
+
+from .parseTools import *
+from .liquidFID import *
+from .gasFID import *
+from .gasTCD import *

chromaquant/Quant/QuantSub/gasFID.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+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 PERFORMING GAS FID QUANTIFICATION STEPS
+
+Julia Hancock
+Started 12-29-2024
+
+"""
+""" PACKAGES """
+import pandas as pd
+import numpy as np
+from chemformula import ChemFormula
+
+#Function for quantifying gas FID data w/ external standard
+def gasFID_ES(BreakdownDF,DBRF,Label_info,gasBag_cond,total_volume,cutoff=4):
+    """
+    Function quantifies gas FID data and returns a breakdown dataframe
+
+    Parameters
+    ----------
+    BreakdownDF : DataFrame
+        Dataframe containing columns associated with matched FID and MS peak data
+    DBRF : Dataframe
+        Dataframe containing nested dataframes with associated chemical lumps,
+        likely imported from an excel sheet where each sheet is specific to
+        a given chemical lump. The top-level keys must be associated with the
+        predefined chemical lumps given in 'LABELS' section above
+    gasBag_cond : List
+        List containing gas bag temperature [0] and gas bag pressure [1]
+    Label_info : List
+        List of dictionaries containing chemical lump and compound type abbreviations
+    total_volume : Float
+        Float describing the total amount of gas estimated by the external standard volume percent, mL
+    cutoff : Integer, optional
+        Integer representing the maximum cutoff carbon number that can be 
+        quantified using FID.The default is 4.
+
+    Returns
+    -------
+    BreakdownDF : DataFrame
+        Dataframe containing columns associated with matched FID and MS peak data
+
+    """
+    #Function for assigning response factors to compounds
+    def assignRF(BreakdownDF,DBRF):
+        
+        #Get a dictionary of average response factors by carbon number
+        avgRF = {}
+        #Loop through every carbon number up to the max in DBRF
+        for i in range(1,DBRF['Carbon Number'].max()+1):
+            #Get a slice of all rows in DBRF with a given carbon number
+            slicer = DBRF.loc[DBRF['Carbon Number']==i]
+            #Average the response factor entries in this slice, appending the result to the average RF dictionary
+            avgRF['{0}'.format(i)] = slicer['RF'].mean()
+            
+        #Loop through every row in the FIDpMS dataframe
+        for i, row in BreakdownDF.iterrows():
+            #Check that the formula is not nan
+            if not pd.isna(row['Formula']):
+                #Obtain a dictionary containing key:value pairs as element:count using the formula string for the ith row
+                chemFormDict = ChemFormula(row['Formula']).element
+                #Use the carbon entry from the above dictionary to assign a carbon number to the ith row
+                BreakdownDF.at[i,'Carbon Number'] = chemFormDict['C']
+            
+                #If the row's compound name exists in the RF list explicitly, assign the row to the appropriate RF
+                if row['Compound Name'] in DBRF['Compound Name'].values:
+                    BreakdownDF.at[i,'RF (Area/vol.%)'] = DBRF.loc[DBRF['Compound Name']==row['Compound Name'],'RF'].iloc[0]
+                    #Assign response factor source
+                    BreakdownDF.at[i,'RF Source'] = 'Direct RF assignment based on compound name'
+                #Otherwise, assign response factor based on average carbon number RF
+                else:
+                    BreakdownDF.at[i,'RF (Area/vol.%)'] = avgRF['{0}'.format(int(BreakdownDF.at[i,'Carbon Number']))]
+                    #Assign response factor source
+                    BreakdownDF.at[i,'RF Source'] = 'RF assignment based on average response factor for DBRF carbon number entries'
+            #Otherwise if the row's formula is nan, pass
+            else:
+                pass
+            
+            
+        return BreakdownDF
+    
+    #Function for quantifying compounds using ideal gas law
+    def gasQuant(BreakdownDF,DBRF,total_volume,cutoff):
+        
+        #Remove rows in BreakdownDF with a carbon number at or below cutoff
+        BreakdownDF = BreakdownDF.loc[BreakdownDF['Carbon Number'] > cutoff].copy()
+        
+        #Get gas bag conditions
+        temp = gasBag_cond[0]       #temperature of gas bag, C
+        pressure = gasBag_cond[1]   #sample pressure in gas bag, psi
+        
+        #Convert gas bag conditions to new units
+        temp = temp + 273.15                    #gas bag temperature, K
+        pressure = pressure / 14.504*100000     #gas bag pressure, Pa
+        total_volume /= 10**6                   #gas bag volume, m^3
+        #Define ideal gas constant, m^3*Pa/K*mol
+        R = 8.314
+        
+        #Loop through every row in BreakdownDF
+        for i, row in BreakdownDF.iterrows():
+            
+            #Add molecular weight using ChemFormula
+            BreakdownDF.at[i,'MW (g/mol)'] = ChemFormula(row['Formula']).formula_weight
+            
+            #Get volume percent using response factor
+            BreakdownDF.at[i,'Vol.%'] = row['FID Area']/row['RF (Area/vol.%)']
+            
+            #Get moles using ideal gas law (PV=nRT)
+            BreakdownDF.at[i,'Moles'] = BreakdownDF.at[i,'Vol.%']/100*total_volume*pressure/(temp*R)
+            
+            #Get mass (mg) using moles and molar mass
+            BreakdownDF.at[i,'Mass (mg)'] = BreakdownDF.at[i,'Moles'] * BreakdownDF.at[i,'MW (g/mol)'] * 1000
+            
+        return BreakdownDF
+    
+    #Function for further breaking down product distribution
+    def moreBreakdown(BreakdownDF,CT_dict):
+        """
+        This function prepares further breakdown dictionaries for use in exporting to Excel
+    
+        Parameters
+        ----------
+        BreakdownDF : DataFrame
+            Dataframe containing columns associated with matched FID and MS peak data.
+        CT_dict : Dict
+            Dictionary of all compound type abbreviations in use and their associated expansions
+            
+        Returns
+        -------
+        BreakdownDF : DataFrame
+            Dataframe containing columns associated with matched FID and MS peak data.
+    
+        """
+        
+        #Get the total mass of product from the breakdown dataframe
+        m_total = np.nansum(BreakdownDF['Mass (mg)'])
+        
+        #Iterate through every species in the breakdown dataframe and add entries in two new columns: Compound Type and Carbon Number
+        for i, row in BreakdownDF.iterrows():
+            #If there exists a formula..
+            try:
+                #Set breakdown compound type according to the abbreviation already in the breakdown dataframe
+                BreakdownDF.at[i,'Compound Type'] = CT_dict[BreakdownDF.at[i,'Compound Type Abbreviation']]
+                #Obtain a dictionary containing key:value pairs as element:count using the formula string for the ith row
+                chemFormDict = ChemFormula(row['Formula']).element
+                #Use the carbon entry from the above dictionary to assign a carbon number to the ith row
+                BreakdownDF.at[i,'Carbon Number'] = chemFormDict['C']
+            #Otherwise, pass
+            except:
+                pass
+        
+        #Get maximum carbon number in breakdown dataframe
+        CN_max = int(BreakdownDF['Carbon Number'].max())
+    
+        #Create a dataframe for saving quantitative results organized by compound type
+        CT_DF = pd.DataFrame({'Compound Type':['Aromatics','Linear Alkanes','Branched Alkanes',
+                                                    'Cycloalkanes','Alkenes/Alkynes','Other'],
+                                    'Mass (mg)':np.empty(6),
+                                    'Mass fraction':np.empty(6)})
+        
+        #Create a dataframe for saving quantitative results organized by carbon number
+        CN_DF = pd.DataFrame({'Carbon Number':range(1,CN_max+1,1),
+                                    'Mass (mg)':np.empty(CN_max)})
+        
+        #Create a dataframe for saving quantitative results organized by both compound type and carbon number
+        CTCN_DF = pd.DataFrame({'Aromatics': pd.Series(np.empty(CN_max),index=range(CN_max)),
+                                'Linear Alkanes': pd.Series(np.empty(CN_max),index=range(CN_max)),
+                                'Branched Alkanes':pd.Series(np.empty(CN_max),index=range(CN_max)),
+                                'Cycloalkanes':pd.Series(np.empty(CN_max),index=range(CN_max)),
+                                'Alkenes/Alkynes':pd.Series(np.empty(CN_max),index=range(CN_max)),
+                                'Other':pd.Series(np.empty(CN_max),index=range(CN_max))})
+        
+        #Iterate through every compound type in the compound type dataframe, summing the total respective masses from the breakdown dataframe
+        for i, row in CT_DF.iterrows():
+            
+            #Define a temporary dataframe which contains all rows matching the ith compound type
+            tempDF = BreakdownDF.loc[BreakdownDF['Compound Type'] == row['Compound Type']]
+            #Assign the ith compound type's mass as the sum of the temporary dataframe's m_i column, treating nan as zero
+            CT_DF.at[i,'Mass (mg)'] = np.nansum(tempDF['Mass (mg)'])
+            #Calculate and assign the ith compound type's mass fraction usingthe total mass from earlier
+            CT_DF.at[i,'Mass fraction'] = CT_DF.at[i,'Mass (mg)']/m_total
+        
+        #Iterate through every carbon number in the carbon number dataframe, summing the total respective masses from the breakdown dataframe
+        for i, row in CN_DF.iterrows():
+            
+            #Define a temporary dataframe which contains all rows matching the ith carbon number
+            tempDF = BreakdownDF.loc[BreakdownDF['Carbon Number'] == row['Carbon Number']]
+            #Assign the ith carbon number's mass as the sum of the temporary dataframe's m_i column, treating nan as zero
+            CN_DF.at[i,'Mass (mg)'] = np.nansum(tempDF['Mass (mg)'])
+        
+        #Iterate through the entire dataframe, getting masses for every compound type - carbon number pair
+        for i, row in CTCN_DF.iterrows():
+            
+            #For every entry in row
+            for j in row.index:
+                
+                #Define a temporary dataframe which contains all rows matching the ith carbon number and compound type
+                tempDF = BreakdownDF.loc[(BreakdownDF['Carbon Number'] == i+1) & (BreakdownDF['Compound Type'] == j)]
+                #Assign the ith carbon number/jth compound type's mass as the sum of the temporary dataframe's m_i column, treating nan as zero
+                CTCN_DF.loc[i,j] = np.nansum(tempDF['Mass (mg)'])
+                
+                
+        #Get total masses from CT, CN, and CTCN dataframes
+        CT_mass = np.nansum(CT_DF['Mass (mg)'])
+        CN_mass = np.nansum(CN_DF['Mass (mg)'])
+        CTCN_mass = np.nansum(CTCN_DF)
+        
+        #Create total mass dataframe
+        mass_DF = pd.DataFrame({'Total mass source':['Overall breakdown','Compound Type Breakdown','Carbon Number Breakdown','Compound Type + Carbon Number Breakdown'],'Mass (mg)':[m_total,CT_mass,CN_mass,CTCN_mass]})
+        
+        return BreakdownDF, CT_DF, CN_DF, CTCN_DF, mass_DF
+    
+    #Unpack compound type and carbon number dictionaries from list
+    CL_Dict, CT_Dict = Label_info
+    
+    #Filter dataframe to remove compounds that do not contain carbon
+    BreakdownDF = BreakdownDF.drop(BreakdownDF[[not i for i in BreakdownDF['Formula'].str.contains('C')]].index)
+    #Reset the dataframe index
+    BreakdownDF.reset_index()
+    
+    #Run response factor assignment function
+    BreakdownDF = assignRF(BreakdownDF, DBRF)
+    #Run gas quantification function
+    BreakdownDF = gasQuant(BreakdownDF,DBRF,total_volume,cutoff)
+    #Run further breakdown function
+    BreakdownDF, CT_DF, CN_DF, CTCN_DF, mass_DF = moreBreakdown(BreakdownDF, CT_Dict)
+    
+    return BreakdownDF, CT_DF, CN_DF, CTCN_DF, mass_DF