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

chromaquant/utils/categories.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2026, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+              URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+CLASS DEFINITION FOR CATEGORIES
+
+Julia Hancock
+Started 2-02-2026
+
+"""
+
+""" CLASS """
+
+
+# Define categories class
+class Categories:
+
+    # Initialize
+    def __init__(self):
+
+        # Create attributes
+        # Category attribute
+        # Expected format is:
+        #   {'category 1': ['keyword 1', 'keyword 2', ...], ...}
+        self._categories = {}
+
+        # Categorizer attribute
+        self.categorizer = self.IS_EQUAL
+
+        # Attribute denoting whether to ignore string case
+        self.ignore_case = True
+
+    # Define get_item to get internal categories
+    def __getitem__(self, key):
+        # Get category
+        return self._categories[key]
+
+    # Define set_item to set internal categories
+    def __setitem__(self, key, value):
+        # Set category
+        self._categories[key] = value
+
+    """ METHODS """
+    # Method to categorize by finding when tested value is equal to keyword,
+    # selecting first applicable category if more than one apply
+    def IS_EQUAL(self, test_value: str | int | float) -> str:
+
+        # For every category in categories...
+        for category in self._categories:
+
+            # For every keyword in the category...
+            for keyword in self._categories[category]:
+
+                # If the keyword is equal to the test value...
+                if keyword == test_value:
+
+                    # Return the category
+                    return category
+
+                # Otherwise, pass
+                else:
+                    pass
+
+        return ''
+
+    # Method to categorize by finding when keyword is a substring of a tested
+    # value, selecting first applicable category if more than one apply
+    def IS_IN(self, test_value: str) -> str:
+
+        # Try to get the lowercase of the test_value and all keywords
+        try:
+            test_value.lower()
+            test_keyword_list = [keyword.lower() for keyword_list in
+                                 list(self._categories.values()) for
+                                 keyword in keyword_list]
+            del test_keyword_list
+
+        # Raise error if AttributeError occurs
+        except AttributeError as e:
+            raise AttributeError(('Cannot use IS_IN for non-string'
+                                  f'values and keywords: {e}'))
+
+        # For every category in categories...
+        for category in self._categories:
+
+            # For every keyword in the category...
+            for keyword in self._categories[category]:
+
+                # If ignoring case...
+                if self.ignore_case is True:
+
+                    # If the lowercase keyword is in
+                    # the lowercase test value...
+                    if keyword.lower() in test_value.lower():
+
+                        # Return the category
+                        return category
+
+                    # Otherwise, pass
+                    else:
+                        pass
+
+                # If not ignoring case...
+                else:
+
+                    # If the keyword is in the test value...
+                    if keyword in test_value:
+
+                        # Return the category
+                        return category
+
+                    # Otherwise, pass
+                    else:
+                        pass
+
+        return ''

chromaquant/utils/chemical_formulas.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+"""
+
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2026, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+              URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+TOOLS FOR FILE IMPORTING AND EXPORTING
+
+Julia Hancock
+Started 1-16-2026
+
+"""
+
+from chemformula import ChemFormula
+
+""" FUNCTIONS """
+
+
+# Function to get the number of atoms of a given element from a formula
+def get_number_element_atoms(formula: str | list[str],
+                             element: str) -> list[int] | int:
+
+    # Try...
+    try:
+        # ...to split formula (checks if list or string)
+        formula.split()
+
+        # If it is a string, get a dictionary with
+        # key:value pairs as element:number
+        chemFormDict = ChemFormula(formula).element
+
+        # Get the number of atoms of the passed element
+        number_element_atoms: int | list[int] = chemFormDict[element]
+
+    # If an AttributeError occurs (formula is a list)...
+    except AttributeError:
+
+        # Create a new list to return
+        number_element_atoms = []
+
+        # For every formula within the list...
+        for single_formula in formula:
+
+            # Try...
+            try:
+
+                # Get a dictionary with key:value pairs as element:number
+                chemFormDict = ChemFormula(single_formula).element
+
+                # Get the number of atoms of the passed element from this
+                # dictionary and append this to the return list
+                number_element_atoms.append(int(chemFormDict[element]))
+
+            # If there is a ValueError (e.g., formula contains None or NaN)...
+            except ValueError:
+
+                # Append zero
+                number_element_atoms.append(0)
+
+    return number_element_atoms
+
+
+# Function to get the molecular weight from a chemical formula
+def get_molecular_weight(formula: str | list[str]) -> float | list[float]:
+
+    # Try...
+    try:
+        # ...to split formula (checks if list or string)
+        formula.split()
+
+        # If it is a string, get the weight
+        weight: float | list[float] = ChemFormula(formula).formula_weight
+
+    # If an AttributeError occurs (formula is a list)...
+    except AttributeError:
+
+        # Create a new list to return
+        weight = []
+
+        # For every formula within the list...
+        for single_formula in formula:
+
+            # Try...
+            try:
+
+                # Append the weight of the current formula
+                weight.append(ChemFormula(single_formula).formula_weight)
+
+            # If there is a ValueError (e.g., formula contains None or NaN)...
+            except ValueError:
+
+                # Append zero
+                weight.append(0)
+
+    return weight

chromaquant/utils/dataframe_processing.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python
+"""
+
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2026, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+              URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+SUBPACKAGE FOR ADJUSTING AND TESTING DATAFRAMES
+
+Julia Hancock
+Started 11-12-2025
+
+"""
+
+""" FUNCTIONS """
+
+
+# Function to loop through keys in a passed dictionary and
+# check them against a list of permitted keys or dictionary
+# with permitted keys
+def check_dict_keys(dictionary, permitted):
+
+    # For every key-value pair in the dictionary...
+    for key, value in dictionary.items():
+
+        # If the current key is not permitted, raise an error
+        if key not in permitted:
+            raise ValueError(f'{key} is not a valid argument')
+
+        # Otherwise, pass
+        else:
+            pass
+
+    return None
+
+
+# Function to add, remove, or rename columns in a DataFrame
+def column_adjust(dataframe, add_col=[], remove_col=[], rename_dict={}):
+    """
+    Function used to add, remove, or rename
+    columns in a passed DataFrame
+
+    Parameters
+    ----------
+    dataframe : pandas.DataFrame
+        DataFrame to have columns adjusted.
+    add_col : list, optional
+        List of column headers to add, by default [].
+    remove_col : list, optional
+        List of column headers to remove, by default [].
+    rename_dict : list, optional
+        Dictionary of headers to rename as keys and
+        new headers as values, by default {}.
+
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame post-adjustments.
+    """
+
+    # Define a new dataframe
+    new_dataframe = dataframe.copy()
+
+    # For each column in add_col...
+    if add_col:
+        for column in add_col:
+            # Create a new column and assign all values to NaN
+            # NOTE: if the column already exists, this will
+            # clear existing data
+            new_dataframe[column] = None
+
+    # Rename columns using key-value pairs in rename_dict
+    if rename_dict:
+        new_dataframe = new_dataframe.rename(columns=rename_dict)
+
+    # Remove dataframe columns as specified in remove_col...
+    if remove_col:
+        new_dataframe = dataframe.drop(remove_col, axis=1)
+
+    return new_dataframe
+
+
+# Function to filter a DataFrame based on certain values in rows
+def row_filter(dataframe, filter_dict):
+    """
+    Function used to filter a passed DataFrame
+    such that it only contains certain values
+    in specific columns
+    ...
+
+    Parameters
+    ----------
+    dataframe : pandas.DataFrame
+        DataFrame to have rows filtered.
+    filter_dict : _type_
+        Dictionary containing column names as keys and desired cell values
+        as values
+
+    Returns
+    -------
+    pandas.dataframe
+        Dataframe post-filtering.
+    """
+
+    # Define a new dataframe
+    new_dataframe = dataframe.copy()
+
+    # Filter the new dataframe to only include rows where the value
+    # in some column is equal to the value associated with the key
+    # in filter_dict that matches that column's header
+    for key, value in filter_dict.items():
+        new_dataframe = new_dataframe.loc[new_dataframe[key] == value]
+
+    return new_dataframe
+
+
+# Function to check whether a column is empty
+def verify_column_not_empty(dataframe, column):
+    """
+    Function used to test whether a column in a passed
+    DataFrame is empty
+
+    ...
+
+    Parameters
+    ----------
+    dataframe : pandas.DataFrame
+        DataFrame containing column to be tested
+    column : str
+        Header of a column which may or may not contain values
+
+    Returns
+    -------
+    bool
+        Result of the conditional test: True if the column is
+        not empty and False if the column is empty
+    """
+
+    # Define a default test result
+    test_result = False
+
+    # If there is any value in the passed column...
+    if dataframe[column].any():
+
+        # Redefine test result to True
+        test_result = True
+
+    # Otherwise, set to False
+    else:
+        test_result = False
+
+    return test_result
+
+
+# Function to test whether certain values exist in a column
+def test_for_column_values(dataframe, column, test_values):
+    """
+    Function used to test for the presence or absence of
+    passed values in some column of a given DataFrame
+
+    ...
+    Parameters
+    ----------
+    dataframe :
+        _description_
+    column : _type_
+        _description_
+    test_values : _type_
+        _description_
+
+    Returns
+    -------
+    _type_
+        _description_
+    """
+
+    # Define a default test result dictionary
+    test_result_dict = {test_value: False for test_value in test_values}
+
+    # If the dataframe is not empty...
+    if verify_column_not_empty(dataframe, column):
+
+        # For each test value in the test_values list...
+        for value in test_values:
+
+            # If the column contains the test value at at least one row...
+            if value in dataframe.loc[column].values.tolist():
+
+                # Set the test_result_dict entry to True
+                test_result_dict[value] = True
+
+            # Otherwise, pass
+            else:
+                pass
+
+    # Otherwise, pass
+    else:
+        pass
+
+    return test_result_dict
+
+
+# Function that adds data from one row to another
+def add_columns_from_one_row_to_another(first_row, second_row, add_columns):
+
+    # Create a copy of the passed first_row
+    new_first = first_row.copy()
+
+    # For every column in add_columns...
+    for column in add_columns:
+        # Set the first row's entry to the second row's entry
+        new_first.at[column] = second_row[column]
+
+    return new_first

chromaquant/utils/file_tools.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2026, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+              URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+TOOLS FOR FILE IMPORTING AND EXPORTING
+
+Julia Hancock
+Started 1-16-2026
+
+"""
+
+import logging
+import os
+import pandas as pd
+from ..logging_and_handling import setup_logger, setup_error_logging
+
+""" LOGGING AND HANDLING """
+
+# Create a logger
+logger = logging.getLogger(__name__)
+
+# Format the logger
+logger = setup_logger(logger)
+
+# Get an error logging decorator
+error_logging = setup_error_logging(logger)
+
+""" FUNCTIONS """
+
+
+# Function to export data to a .csv file
+def export_to_csv(dataframe, parent, name=''):
+    """export_to_csv _summary_
+
+    Parameters
+    ----------
+    dataframe : dataframe
+        Passed Pandas dataframe.
+    parent : string
+        Name of parent directory for exported file.
+    name : string
+        Name of file to be exported.
+
+    Returns
+    -------
+    None
+    """
+
+    # If the name argument is passed...
+    if name:
+        # Construct a full path from the passed
+        # parent directory and file name
+        full_path = os.path.join(parent, name, '.csv')
+    # Otherwise...
+    else:
+        # Set the full path to the parent
+        full_path = parent
+
+    # Export the dataframe to the full path
+    dataframe.to_csv(full_path, index=False)
+
+    return None
+
+
+# Function to try to open a file using a passed function
+def try_open_file(func, path, *args, **kwargs):
+
+    # Predefine the conditional Boolean result
+    tf = False
+
+    # Try opening the file, if it works then set tf to True
+    try:
+        data = func(path, *args, **kwargs)
+        tf = True
+
+    # If cannot open file, log and set tf to False
+    except Exception as e:
+        # logger.info(f'Could not open {path}, got {e}')
+        data = []
+        tf = False
+
+    return tf, data
+
+
+# Function to try to open a file with pandas.read_csv
+def try_open_csv(path, *args, **kwargs):
+    tf, data = try_open_file(pd.read_csv, path, *args, **kwargs)
+    return tf, data

chromaquant/utils/formula_tools.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+COPYRIGHT STATEMENT:
+
+ChromaQuant – A quantification software for complex gas chromatographic data
+
+Copyright (c) 2026, by Julia Hancock
+              Affiliation: Dr. Julie Elaine Rorrer
+              URL: https://www.rorrerlab.com/
+
+License: BSD 3-Clause License
+
+---
+
+COLLECTION OF VARIOUS FORMULA TOOLS
+
+Julia Hancock
+Started 1-07-2026
+
+"""
+
+import re
+from openpyxl.utils import get_column_letter, coordinate_to_tuple
+
+""" FUNCTIONS """
+
+
+# Function for checking that passed formula starts with '='
+def check_formula_starts_with_equals(formula):
+
+    # Initialize tf
+    tf = False
+
+    # If a match exists, set tf to True
+    if not re.search('^=', formula) is None:
+        tf = True
+    # Otherwise, pass
+    else:
+        pass
+
+    return tf
+
+
+# Function to get a column letter based on table
+# starting column and column's index within a table
+def get_column_letter_from_table(
+        table_reference, column_name, start_cell_column):
+
+    # Find the column's index within the DataFrame
+    column_index = \
+        table_reference['columns'].index(column_name)
+
+    # Add the column's index to the starting column
+    # and get the column letter equivalent
+    column_letter = \
+        get_column_letter(start_cell_column + column_index)
+
+    return column_letter
+
+
+# Function to construct value reference string
+def get_value_reference_string(value_reference):
+
+    # Get value's sheet string
+    value_sheet = \
+        f"'{value_reference['sheet']}'!"
+    # Get value's cell string
+    value_cell = \
+        f"{value_reference['cell']}"
+
+    # Get the reference string
+    reference = value_sheet + value_cell
+
+    return reference
+
+
+# Function to get the starting row and column of a table
+def get_table_start_coords(table_reference):
+
+    # Get the table's starting cell
+    table_start_cell = table_reference['start_cell']
+
+    # Get the starting cell's row and column
+    start_row, start_column = \
+        coordinate_to_tuple(table_start_cell)
+
+    return start_row, start_column
+
+
+# Function to replace formula raw insert with reference
+def replace_insert(formula, raw, reference):
+
+    # Replace pointer substring with value's reference
+    new_formula = \
+        formula.replace(raw, reference)
+
+    return new_formula
+
+
+# Function to get a range from passed table pointers
+def table_column_to_range(table_reference, column_key):
+
+    # Get the starting coordinates
+    start_row, start_column = get_table_start_coords(table_reference)
+
+    # Get letter for output column
+    column_letter = \
+        get_column_letter_from_table(table_reference, column_key, start_column)
+
+    # Get the final row of the table
+    end_row = start_row + table_reference['length']
+
+    # Construct the range string
+    column_range = (
+        f'${column_letter}${start_row + 1}:'
+        f'${column_letter}${end_row + 1}')
+
+    return column_range