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

chromaquant/import_local_packages.py

@@ -0,0 +1,55 @@
+"""
+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
+
+---
+
+FUNCTIONS FOR IMPORTING LOCAL PACKAGES
+
+Julia Hancock
+Started 1-7-2026
+
+"""
+
+import os
+import importlib.util
+import sys
+
+
+# Function to get a dictionary of subpackage directories
+def get_local_package_directories():
+
+    # Get package directory
+    app_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # Get absolute directories for subpackages
+    subpack_dir = {'utils': os.path.join(app_dir, 'utils', '__init__.py'),
+                   'Signal': os.path.join(app_dir, 'Signal', '__init__.py'),
+                   'Results': os.path.join(app_dir, 'Results', '__init__.py')}
+
+    return subpack_dir
+
+
+# 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 module
+    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

chromaquant/logging_and_handling.py

@@ -0,0 +1,76 @@
+"""
+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
+
+---
+
+FUNCTIONS FOR HANDLING LOGGING AND ERRORS
+
+Julia Hancock
+Started 1-7-2026
+
+"""
+
+import logging
+from functools import wraps
+from collections.abc import Callable
+from typing import Any
+
+
+# Function to format logger
+def setup_logger(logger: logging.Logger) -> logging.Logger:
+
+    # Check if logger has handlers, clear if so
+    if (logger.hasHandlers()):
+        logger.handlers.clear
+
+    # Add a handler for the console
+    console_handler = logging.StreamHandler()
+    logger.addHandler(console_handler)
+
+    # Create a formatter object
+    formatter = logging.Formatter(
+                "{asctime} - [{name:^8s}][{levelname:^8s}] {message}",
+                style='{',
+                datefmt='%Y-%m-%d %H:%M')
+
+    # Set the console handler's format using the new formatter
+    console_handler.setFormatter(formatter)
+
+    # Set logger level - NOTE: Change before commit if debugging
+    logger.setLevel(logging.INFO)
+
+    return logger
+
+
+# Function that sets up a decorator to log errors while handling them
+def setup_error_logging(logger: logging.Logger) -> \
+   Callable[[Callable[..., Any]], Callable[..., Any]]:
+
+    # Decorator to log and handle errors
+    def error_logging(f: Callable[..., Any]) -> Callable[..., Any]:
+
+        # Define decorated function (wrapper)
+        @wraps(f)
+        def decorated_func(*args: Any, **kwargs: Any) -> Callable[..., Any]:
+
+            # Try to get the function's result
+            try:
+                result = f(*args, **kwargs)
+                return result
+
+            # Log errors if they occur
+            except Exception as e:
+                logger.error(e)
+                raise
+
+        return decorated_func
+
+    return error_logging

chromaquant/match/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+ChromaQuant.match module initialization
+
+Julia Hancock
+Created 10-19-2024
+
+"""
+
+from .match_config import MatchConfig
+from .match_tools import match_dataframes
+from .match import match

chromaquant/match/match.py

@@ -0,0 +1,184 @@
+#!/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
+
+---
+
+MATCH FUNCTION FOR DATAFRAME COMPARISONS
+
+Julia Hancock
+Started 1-15-2026
+
+"""
+
+import logging
+from .match_config import MatchConfig
+from .match_tools import match_dataframes
+from ..utils.file_tools import try_open_csv, export_to_csv
+from ..utils.dataframe_processing import column_adjust, \
+                                         row_filter
+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)
+
+""" FUNCTION """
+
+
+# Match function
+def match(first_DF,
+          second_DF,
+          match_config=MatchConfig()):
+    """Matches data from two DataFrames
+
+    Parameters
+    ----------
+    first_DF: pandas DataFrame
+        A DataFrame containing data to be matched to data
+        in second_DF, processed, then returned as match_data.
+    second_DF: pandas DataFrame
+        A DataFrame containing data to be matched to data in first_DF.
+    match_config: MatchConfig object
+        A MatchConfig instance containing information on how to match
+        the two data sets.
+
+    Returns
+    -------
+    match_data : pandas DataFrame
+        A DataFrame containing the results from matching.
+
+    """
+
+    """ EVALUATING ARGUMENTS """
+
+    # If the match_config import_include_col list is empty...
+    if not match_config.import_include_col:
+        # Add all columns from the second dataframe
+        match_config.import_include_col = \
+            [column for column in second_DF.columns.tolist()
+             if column not in first_DF.columns.tolist()]
+    # Otherwise, pass
+    else:
+        pass
+
+    """ CREATE OR LOAD MATCH DATAFRAME """
+
+    # Check if a match file already exists at the specified path
+    try_open_tf, match_data = \
+        try_open_csv(match_config.output_path)
+
+    # If a match file already exists,
+    # open it and save it to data object **SEE NOTE
+    if try_open_tf:
+        # NOTE: Commented out potential feature to reopen previous match
+        # file if one exists at the output path, untested
+        # logger.info((f'Opening match file at '
+        #            f'{self.match_config.output_path}'))
+        # self.data[match_key] = match_data
+        # logger.warning('Overwriting previous match data.')
+        pass
+
+    # Otherwise, pass
+    else:
+        # NOTE: See comment in if statement
+        # Create a copy of the locally_defined dataframe
+        # self.data[match_key] = \
+        #    self.data[match_dict.local_data_key].copy()
+        pass
+
+    # Create a copy of the first DF
+    match_data = \
+        first_DF.copy()
+
+    """ FILTER ROWS """
+    # Adjust the dataframe according to match_config
+    # Filter rows first in case desired filter includes a column
+    # that will be renamed or removed
+    match_data = row_filter(
+                    match_data,
+                    match_config.local_filter_row
+    )
+
+    # Add column headers for columns to include from import
+    match_data = column_adjust(
+                    dataframe=match_data,
+                    add_col=match_config.import_include_col
+    )
+
+    """ MATCH DATAFRAMES """
+    # Match the local and import data sets
+    match_data = \
+        match_dataframes(match_data,
+                         second_DF,
+                         match_config)
+
+    """ ADJUST OUTPUT """
+
+    # Get the current columns in match_data
+    match_cols = match_data.columns.tolist()
+
+    # If the output_cols_dict is not empty...
+    if match_config.output_cols_dict:
+
+        # Get the keys for output_cols_dict as list of original columns
+        output_cols_keys = list(
+            match_config.output_cols_dict.keys()
+        )
+        # Get the values for output_cols_dict as list of new columns
+        output_cols_values = list(
+            match_config.output_cols_dict.values()
+        )
+
+        # Filter the dataframe according to output_cols
+        # NOTE: This preserves the column order as seen in output_cols_dict
+        # First, add columns present in output_cols but not match_cols
+        # And then rename columns using output_cols_dict
+        columns_to_add = list(
+            set(output_cols_keys).difference(set(match_cols))
+        )
+        match_data = column_adjust(
+                        dataframe=match_data,
+                        add_col=columns_to_add,
+                        rename_dict=match_config.output_cols_dict
+        )
+        # Finally, filter
+        match_data = \
+            match_data[output_cols_values]
+
+    # Otherwise, pass
+    else:
+        pass
+
+    """ (OPTIONAL) EXPORT TO FILE """
+
+    # If the do_export value is True, export to output path
+    if match_config.do_export:
+        export_to_csv(
+            match_data,
+            match_config.output_path
+        )
+        # logger.info('Match results exported to '
+        #            f'{match_config.output_path}')
+
+    # Otherwise, pass
+    else:
+        pass
+
+    return match_data

chromaquant/match/match_config.py

@@ -0,0 +1,296 @@
+#!/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 MATCH CONFIGURATION
+
+Julia Hancock
+Started 1-12-2026
+
+"""
+
+import pandas as pd
+from typing import Any
+from collections.abc import Callable
+
+""" CLASS """
+
+
+# Define ConfigProperty class
+class ConfigProperty():
+
+    # Descriptor __set_name__
+    def __set_name__(self, owner, name):
+        self.name = '_' + name
+
+    # Getter
+    def __get__(self, obj, type=None):
+        return getattr(obj, self.name)
+
+    # Setter
+    def __set__(self, obj, value):
+        setattr(obj, self.name, value)
+
+    # Deleter
+    def __delete__(self, obj):
+        delattr(obj, self.name)
+
+
+# Define MatchConfig class
+class MatchConfig():
+
+    # Create class instances of ConfigProperty for every property
+    do_export = ConfigProperty()
+    import_include_col = ConfigProperty()
+    local_filter_row = ConfigProperty()
+    match_conditions = ConfigProperty()
+    multiple_hits_rule = ConfigProperty()
+    multiple_hits_column = ConfigProperty()
+    output_cols_dict = ConfigProperty()
+    output_path = ConfigProperty()
+
+    # Initialize
+    def __init__(self,
+                 do_export: bool = False,
+                 import_include_col: list[str] | None = None,
+                 local_filter_row:
+                 dict[str, str | bool | float | int] | None = None,
+                 match_conditions: list[dict[str, Any]] | None = None,
+                 multiple_hits_rule:
+                 Callable[[pd.DataFrame, str], pd.Series] | None = None,
+                 multiple_hits_column: str = 'default',
+                 output_cols_dict: dict[str, str] | None = None,
+                 output_path: str = 'match_results.csv'):
+
+        # Expected structure of match_conditions:
+        # self.match_conditions = [{
+        #                          'condition': self.IS_EQUAL,
+        #                          NOTE: or another condition
+        #                          'first_DF_column': {STRING},
+        #                          'second_DF_column': {STRING},
+        #                          'error': {FLOAT},
+        #                          'or_equal': {BOOLEAN}
+        #                          },
+        #                         ...]
+
+        # Define default match comparison function
+        def default_comp_function(x):
+            return x
+
+        # Set descriptor values
+        self.do_export = do_export
+        self.import_include_col = import_include_col \
+            if import_include_col is not None else []
+        self.local_filter_row = local_filter_row \
+            if local_filter_row is not None else {}
+        self.match_conditions = match_conditions \
+            if match_conditions is not None else []
+        self.multiple_hits_rule = multiple_hits_rule \
+            if multiple_hits_rule is not None else self.SELECT_FIRST_ROW
+        self.multiple_hits_column = multiple_hits_column
+        self.output_cols_dict = output_cols_dict\
+            if output_cols_dict is not None else {}
+        self.output_path = output_path
+
+    """ METHODS """
+
+    # Method to add a new match condition
+    def add_match_condition(self,
+                            condition: Callable[[pd.DataFrame, str],
+                                                pd.Series],
+                            comparison: str | list[str],
+                            error: int | float = 0,
+                            or_equal: bool = False):
+
+        # Check if comparison is a string
+        try:
+            comparison.split()
+            # If can split comparison, assign both first and second
+            # comparison to this one value
+            first_comparison = comparison
+            second_comparison = comparison
+        # If comparison is not a string
+        except Exception:
+            # If the length is one...
+            if len(comparison) == 1:
+                # Set first and second comparison to this one value
+                first_comparison = comparison[0]
+                second_comparison = comparison[0]
+            # If the length is two...
+            if len(comparison) == 2:
+                # Set the first and second comparison respectively
+                first_comparison = comparison[0]
+                second_comparison = comparison[1]
+            # If the length is neither one or two, raise an error
+            else:
+                raise ValueError('Unexpected value passed for comparison.')
+
+        # Append new match condition to list of conditions
+        self.match_conditions.append(
+            {
+                'condition': condition,
+                'first_DF_column': first_comparison,
+                'second_DF_column': second_comparison,
+                'error': error,
+                'or_equal': or_equal
+            }
+        )
+
+        return None
+
+    """ STATIC METHODS """
+
+    # Method to get a slice of a DataFrame where one of its
+    # column's values are equal to some value
+    @staticmethod
+    def IS_EQUAL(value: Any,
+                 DF: pd.DataFrame,
+                 DF_column_name: str,
+                 error: float | int = 0,
+                 or_equal: bool = False) -> pd.DataFrame:
+
+        # Get a slice where the comparisons are exactly equal
+        DF_slice = DF.loc[DF[DF_column_name] == value].copy()
+
+        # Try to get a slice where the comparison is
+        # within specified error margins
+        try:
+
+            # Define upper and lower limits
+            series_value_max = value + error
+            series_value_min = value - error
+
+            # Get a slice
+            DF_slice = \
+                DF.loc[(DF[DF_column_name] >= series_value_min) &
+                       (DF[DF_column_name] <= series_value_max)].copy()
+
+        # If an error occurs when trying to get such a slice, pass
+        # NOTE: This is intended to catch cases where comparison
+        # values are non-numbers
+        except Exception:
+            pass
+
+        return DF_slice
+
+    # Method to get a slice of a DataFrame where one of its
+    # column's values are less than some value
+    # (i.e., a value is *greater than* the DataFrame value)
+    @staticmethod
+    def GREATER_THAN(value: Any,
+                     DF: pd.DataFrame,
+                     DF_column_name: str,
+                     error: float | int = 0,
+                     or_equal: bool = False) -> pd.DataFrame:
+
+        # Try to get a slice with condition
+        try:
+
+            # If the values can be equal...
+            if or_equal:
+                # Get a slice
+                DF_slice = \
+                    DF.loc[DF[DF_column_name] <= value].copy()
+
+            # If the values cannot be equal...
+            else:
+                # Get a slice
+                DF_slice = \
+                    DF.loc[DF[DF_column_name] < value].copy()
+
+        # If an error occurs when trying to get such a slice, pass
+        # NOTE: This is intended to catch cases where comparison
+        # values are non-numbers
+        except Exception:
+
+            # Get an empty DataFrame
+            DF_slice = DF.loc[pd.Index([]), :].copy()
+
+        return DF_slice
+
+    # Method to get a slice of a DataFrame where one of its
+    # column's values are greater than some value
+    # (i.e., a value is *less than* the DataFrame value)
+    @staticmethod
+    def LESS_THAN(value: Any,
+                  DF: pd.DataFrame,
+                  DF_column_name: str,
+                  error: float | int = 0,
+                  or_equal: bool = False) -> pd.DataFrame:
+
+        # Try to get a slice with condition
+        try:
+
+            # If the values can be equal...
+            if or_equal:
+                # Get a slice
+                DF_slice = \
+                    DF.loc[DF[DF_column_name] >= value].copy()
+
+            # If the values cannot be equal...
+            else:
+                # Get a slice
+                DF_slice = \
+                    DF.loc[DF[DF_column_name] > value].copy()
+
+        # If an error occurs when trying to get such a slice, pass
+        # NOTE: This is intended to catch cases where comparison
+        # values are non-numbers
+        except Exception:
+
+            # Get an empty DataFrame
+            DF_slice = DF.loc[pd.Index([]), :].copy()
+
+        return DF_slice
+
+    # Method that gets the first row of a slice, used as the default
+    # method of selecting one row of a slice that meets match conditions
+    @staticmethod
+    def SELECT_FIRST_ROW(DF: pd.DataFrame,
+                         column_name: str) -> pd.Series:
+
+        # Get the first row of the DataFrame
+        first_row = DF.loc[DF.index.min()]
+
+        return first_row
+
+    # Method that selects the row with the smallest value in a given column
+    # NOTE: will return the first occurrence of the smallest value if multiple
+    # values share the same minimum
+    @staticmethod
+    def SELECT_LOWEST_VALUE(DF: pd.DataFrame,
+                            column_name: str) -> pd.Series:
+
+        # Get the minimum value
+        min_value_index = DF[column_name].idxmin()
+
+        # Get the row with the smallest value
+        min_value_row = DF.loc[min_value_index]
+
+        return min_value_row
+
+    # Method that selects the row with the largest value in a given column
+    # NOTE: will return the first occurrence of the largest value if multiple
+    # values share the same maximum
+    @staticmethod
+    def SELECT_HIGHEST_VALUE(DF: pd.DataFrame,
+                             column_name: str) -> pd.Series:
+
+        # Get the maximum value
+        max_value_index = DF[column_name].idxmax()
+
+        # Get the row with the largest value
+        max_value_row = DF.loc[max_value_index]
+
+        return max_value_row