dragon-ml-toolbox 10.2.1__py3-none-any.whl → 10.4.0__py3-none-any.whl

{dragon_ml_toolbox-10.2.1.dist-info → dragon_ml_toolbox-10.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 10.2.1
+Version: 10.4.0
 Summary: A collection of tools for data science and machine learning projects.
 Author-email: Karl Loza <luigiloza@gmail.com>
 License-Expression: MIT

{dragon_ml_toolbox-10.2.1.dist-info → dragon_ml_toolbox-10.4.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-dragon_ml_toolbox-10.2.1.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
-dragon_ml_toolbox-10.2.1.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=lY4_rJPnLnMu7YBQaY-_iz1JRDcLdQzNCyeLAF1glJY,1837
+dragon_ml_toolbox-10.4.0.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
+dragon_ml_toolbox-10.4.0.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=lY4_rJPnLnMu7YBQaY-_iz1JRDcLdQzNCyeLAF1glJY,1837
 ml_tools/ETL_cleaning.py,sha256=lSP5q6-ukGhJBPV8dlsqJvPXAzj4du_0J-SbtEd0Pjg,19292
-ml_tools/ETL_engineering.py,sha256=sgpIhlFIeId4eSJ-a33MnVuPNXs50msxFWa8-kw2hOI,36369
+ml_tools/ETL_engineering.py,sha256=LuOEIc2TMR6c1eXhh4-Budj0mTtZyrzE4yU7HPYxDds,49207
 ml_tools/GUI_tools.py,sha256=kEQWg-bog3pB5tI22gMGKWaCGHnz9TB2Lvvfhf5F2CI,45412
 ml_tools/MICE_imputation.py,sha256=kVSythWfxJFR4-2mtcYCWQaQ1Oz5yyx_SJu5gjnS7H8,11670
 ml_tools/ML_callbacks.py,sha256=JPvEw_cW5tYNJ2rMSgnNrKLuni_UrmuhDFaOw-u2SvA,13926
@@ -28,9 +28,9 @@ ml_tools/ensemble_learning.py,sha256=3s0kH4i_naj0IVl_T4knst-Hwg4TScWjEdsXX5KAi7I
 ml_tools/handle_excel.py,sha256=He4UT15sCGhaG-JKfs7uYVAubxWjrqgJ6U7OhMR2fuE,14005
 ml_tools/keys.py,sha256=HtPG8-MWh89C32A7eIlfuuA-DLwkxGkoDfwR2TGN9CQ,1074
 ml_tools/optimization_tools.py,sha256=P3I6lIpvZ8Xf2kX5FvvBKBmrK2pB6idBpkTzfUJxTeE,5073
-ml_tools/path_manager.py,sha256=TJgoqMAryc5F0dal8W_zvJgE1TpOzlskIyYJk614WW4,13809
+ml_tools/path_manager.py,sha256=7sRvAoNrboRY6ef9gH3_qdzoZ66iLs7Aii4P39K0kEk,13819
 ml_tools/utilities.py,sha256=SVMaSDigh6SUoAeig2_sXLLIj5w5mUs5KuVWpHvFDec,19816
-dragon_ml_toolbox-10.2.1.dist-info/METADATA,sha256=zBNbArgUJkZxhs6hnjwgZX9rrjIKPKLRKxSKlPVqvLE,6968
-dragon_ml_toolbox-10.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dragon_ml_toolbox-10.2.1.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
-dragon_ml_toolbox-10.2.1.dist-info/RECORD,,
+dragon_ml_toolbox-10.4.0.dist-info/METADATA,sha256=wD3UR2VUKd0JbxZF5r6HG2_8tdwZIfP6deIQZ8Y0mDs,6968
+dragon_ml_toolbox-10.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dragon_ml_toolbox-10.4.0.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
+dragon_ml_toolbox-10.4.0.dist-info/RECORD,,

ml_tools/ETL_engineering.py

@@ -1,6 +1,9 @@
 import polars as pl
 import re
+from pathlib import Path
 from typing import Literal, Union, Optional, Any, Callable, List, Dict, Tuple
+from .utilities import load_dataframe, save_dataframe
+from .path_manager import make_fullpath
 from ._script_info import _script_info
 from ._logger import _LOGGER
 
@@ -14,7 +17,10 @@ __all__ = [
     "KeywordDummifier",
     "NumberExtractor",
     "MultiNumberExtractor",
+    "TemperatureExtractor",
+    "MultiTemperatureExtractor",
     "RatioCalculator",
+    "TriRatioCalculator",
     "CategoryMapper",
     "RegexMapper",
     "ValueBinner",
@@ -182,9 +188,28 @@ class DataProcessor:
         if not processed_columns:
             _LOGGER.error("The transformation resulted in an empty DataFrame.")
             return pl.DataFrame()
-            
+        
+        _LOGGER.info(f"Processed dataframe with {len(processed_columns)} columns.")
+
         return pl.DataFrame(processed_columns)
     
+    def load_transform_save(self, input_path: Union[str,Path], output_path: Union[str,Path]):
+        """
+        Convenience wrapper for the transform method that includes automatic dataframe loading and saving.
+        """
+        # Validate paths
+        in_path = make_fullpath(input_path, enforce="file")
+        out_path = make_fullpath(output_path, make=True, enforce="file")
+        
+        # load df
+        df, _ = load_dataframe(df_path=in_path, kind="polars", all_strings=True)
+        
+        # Process
+        df_processed = self.transform(df)
+        
+        # save processed df
+        save_dataframe(df=df_processed, save_dir=out_path.parent, filename=out_path.name)
+        
     def __str__(self) -> str:
         """
         Provides a detailed, human-readable string representation of the
@@ -302,6 +327,15 @@ class AutoDummifier:
     A transformer that performs one-hot encoding on a categorical column,
     automatically detecting the unique categories from the data.
     """
+    def __init__(self, drop_first: bool = False):
+        """
+        Initializes the AutoDummifier.
+
+        Args:
+            drop_first (bool): If True, drops the first dummy column.
+        """
+        self.drop_first = drop_first
+
     def __call__(self, column: pl.Series) -> pl.DataFrame:
         """
         Executes the one-hot encoding logic.
@@ -315,7 +349,7 @@ class AutoDummifier:
                           '{original_col_name}_{category_value}'.
         """
         # Ensure the column is treated as a string before creating dummies
-        return column.cast(pl.Utf8).to_dummies()
+        return column.cast(pl.Utf8).to_dummies(drop_first=self.drop_first)
 
 
 class MultiBinaryDummifier:
@@ -617,16 +651,200 @@ class MultiNumberExtractor:
         return pl.select(output_expressions)
 
 
+class TemperatureExtractor:
+    """
+    Extracts temperature values from a string column.
+
+    This transformer assumes that the source temperature values are in Celsius.
+    It can extract a single value using a specific regex or find all numbers in
+    a string and calculate their average. It also supports converting the final
+    Celsius value to Kelvin or Rankine.
+
+    Args:
+        regex_pattern (str):
+            The regex to find a single temperature. MUST contain exactly one
+            capturing group `(...)`. This is ignored if `average_mode` is True.
+        average_mode (bool):
+            If True, extracts all numbers from the string and returns their average.
+            This overrides the `regex_pattern` with a generic number-finding regex.
+        convert (str | None):
+            If "K", converts the final Celsius value to Kelvin.
+            If "R", converts the final Celsius value to Rankine.
+            If None (default), the value remains in Celsius.
+    """
+    def __init__(
+        self,
+        regex_pattern: str = r"(\d+\.?\d*)",
+        average_mode: bool = False,
+        convert: Optional[Literal["K", "R"]] = None,
+    ):
+        # --- Store configuration ---
+        self.average_mode = average_mode
+        self.convert = convert
+        self.regex_pattern = regex_pattern
+        
+        # Generic pattern for average mode, defined once for efficiency.
+        self._avg_mode_pattern = r"(\d+\.?\d*)"
+
+        # --- Validation ---
+        if not self.average_mode:
+            try:
+                if re.compile(self.regex_pattern).groups != 1:
+                    _LOGGER.error("'regex_pattern' must contain exactly one capturing group '(...)' for single extraction mode.")
+                    raise ValueError()
+            except re.error as e:
+                _LOGGER.error(f"Invalid regex pattern provided: {e}")
+                raise ValueError()
+
+        if self.convert is not None and self.convert not in ["K", "R"]:
+            _LOGGER.error("'convert' must be either 'K' (Kelvin) or 'R' (Rankine).")
+            raise ValueError()
+
+    def __call__(self, column: pl.Series) -> pl.Series:
+        """
+        Applies the temperature extraction and conversion logic.
+
+        Args:
+            column (pl.Series): The input Polars Series with string data.
+
+        Returns:
+            pl.Series: A new Series containing the final temperature values as floats.
+        """
+        # --- Step 1: Extract number(s) to get a Celsius value expression ---
+        if self.average_mode:
+            # Extract all numbers and compute their mean. Polars' list.mean()
+            # handles the casting to float automatically.
+            celsius_expr = column.str.extract_all(self._avg_mode_pattern).list.mean()
+        else:
+            # Extract a single number using the specified pattern.
+            # Cast to Float64, with non-matches becoming null.
+            celsius_expr = column.str.extract(self.regex_pattern, 1).cast(pl.Float64, strict=False)
+
+        # --- Step 2: Apply conversion if specified ---
+        if self.convert == "K":
+            # Celsius to Kelvin: C + 273.15
+            final_expr = celsius_expr + 273.15
+        elif self.convert == "R":
+            # Celsius to Rankine: (C * 9/5) + 491.67
+            final_expr = (celsius_expr * 1.8) + 491.67
+        else:
+            # No conversion needed
+            final_expr = celsius_expr
+
+        # --- Step 3: Round the result and return as a Series ---
+        # The select().to_series() pattern is a robust way to execute an
+        # expression and guarantee a Series is returned.
+        return pl.select(final_expr.round(2)).to_series()
+
+
+class MultiTemperatureExtractor:
+    """
+    Extracts multiple temperature values from a single string column into
+    several new columns, assuming the source values are in Celsius.
+
+    This one-to-many transformer is designed for cases where multiple readings
+    are packed into one field, like "Min: 10C, Max: 25C".
+
+    Args:
+        num_outputs (int):
+            The number of numeric columns to create.
+        regex_pattern (str):
+            The regex to find all numbers. Must contain exactly one capturing
+            group around the number part (e.g., r"(-?\\d+\\.?\\d*)").
+        convert (str | None):
+            If "K", converts the final Celsius values to Kelvin.
+            If "R", converts the final Celsius values to Rankine.
+            If None (default), the values remain in Celsius.
+        fill_value (int | float | None):
+            A value to use if a temperature is not found at a given position.
+            For example, if `num_outputs=3` and only two temperatures are
+            found, the third column will be filled with this value. If None,
+            it will be filled with null.
+    """
+    def __init__(
+        self,
+        num_outputs: int,
+        regex_pattern: str = r"(\d+\.?\d*)",
+        convert: Optional[Literal["K", "R"]] = None,
+        fill_value: Optional[Union[int, float]] = None
+    ):
+        # --- Validation ---
+        if not isinstance(num_outputs, int) or num_outputs <= 0:
+            _LOGGER.error("'num_outputs' must be a positive integer.")
+            raise ValueError()
+        
+        try:
+            if re.compile(regex_pattern).groups != 1:
+                _LOGGER.error("'regex_pattern' must contain exactly one capturing group '(...)'.")
+                raise ValueError()
+        except re.error as e:
+            _LOGGER.error(f"Invalid regex pattern provided: {e}")
+            raise ValueError()
+
+        if convert is not None and convert not in ["K", "R"]:
+            _LOGGER.error("'convert' must be either 'K' (Kelvin) or 'R' (Rankine).")
+            raise ValueError()
+
+        # --- Store configuration ---
+        self.num_outputs = num_outputs
+        self.regex_pattern = regex_pattern
+        self.convert = convert
+        self.fill_value = fill_value
+
+    def __call__(self, column: pl.Series) -> pl.DataFrame:
+        """
+        Applies the multi-temperature extraction and conversion logic.
+        """
+        output_expressions = []
+        for i in range(self.num_outputs):
+            # --- Step 1: Extract the i-th number as a Celsius value ---
+            celsius_expr = (
+                column.str.extract_all(self.regex_pattern)
+                .list.get(i)
+                .cast(pl.Float64, strict=False)
+            )
+
+            # --- Step 2: Apply conversion if specified ---
+            if self.convert == "K":
+                # Celsius to Kelvin: C + 273.15
+                converted_expr = celsius_expr + 273.15
+            elif self.convert == "R":
+                # Celsius to Rankine: (C * 9/5) + 491.67
+                converted_expr = (celsius_expr * 1.8) + 491.67
+            else:
+                # No conversion needed
+                converted_expr = celsius_expr
+            
+            # --- Step 3: Apply fill value and handle original nulls ---
+            final_expr = converted_expr.round(2)
+            if self.fill_value is not None:
+                final_expr = final_expr.fill_null(self.fill_value)
+
+            # Ensure that if the original row was null, all outputs are null
+            final_expr = (
+                pl.when(column.is_not_null())
+                .then(final_expr)
+                .otherwise(None)
+                .alias(f"col_{i}") # Temporary name for DataProcessor
+            )
+            
+            output_expressions.append(final_expr)
+        
+        # Execute all expressions at once for performance
+        return pl.select(output_expressions)
+
+
 class RatioCalculator:
     """
     A transformer that parses a string ratio (e.g., "40:5" or "30/2") and
-    computes the result of the division. It gracefully handles strings that
-    do not match the pattern by returning null.
+    computes the result of the division. Includes robust handling for
+    zeros and single numbers.
     """
     def __init__(
         self,
-        # Default pattern includes the full-width colon '：'
-        regex_pattern: str = r"(\d+\.?\d*)\s*[:：/]\s*(\d+\.?\d*)"
+        regex_pattern: str = r"(\d+\.?\d*)\s*[:：/]\s*(\d+\.?\d*)",
+        handle_zeros: bool = False,
+        handle_single_number: bool = False
     ):
         # --- Robust Validation ---
         try:
@@ -642,26 +860,120 @@ class RatioCalculator:
             raise ValueError()
 
         self.regex_pattern = regex_pattern
+        self.handle_zeros = handle_zeros
+        self.handle_single_number = handle_single_number
 
     def __call__(self, column: pl.Series) -> pl.Series:
         """
-        Applies the ratio calculation logic to the input column.
-        This version uses .str.extract() for maximum stability.
+        Applies the ratio calculation logic to the input column. Uses .str.extract() for maximum stability and includes optional handling for zeros and single numbers.
         """
         # Extract numerator (group 1) and denominator (group 2) separately.
         numerator_expr = column.str.extract(self.regex_pattern, 1).cast(pl.Float64, strict=False)
         denominator_expr = column.str.extract(self.regex_pattern, 2).cast(pl.Float64, strict=False)
 
-        # Calculate the ratio, handling division by zero.
-        final_expr = pl.when(denominator_expr != 0).then(
-            numerator_expr / denominator_expr
-        ).otherwise(
-            None # Handles both null denominators and division by zero
-        )
+        # --- Logic for Requirement A: Special zero handling ---
+        if self.handle_zeros:
+            ratio_expr = (
+                pl.when(numerator_expr.is_not_null() & denominator_expr.is_not_null())
+                .then(
+                    pl.when((numerator_expr == 0) & (denominator_expr == 0)).then(pl.lit(0.0))
+                    .when((numerator_expr != 0) & (denominator_expr == 0)).then(numerator_expr)
+                    .when((numerator_expr == 0) & (denominator_expr != 0)).then(denominator_expr)
+                    .otherwise(numerator_expr / denominator_expr)  # Default: both are non-zero
+                )
+            )
+        else:
+            # Original logic
+            ratio_expr = pl.when(denominator_expr != 0).then(
+                numerator_expr / denominator_expr
+            ).otherwise(
+                None # Handles null denominators and division by zero
+            )
+
+        # --- Logic for Requirement B: Handle single numbers as a fallback ---
+        if self.handle_single_number:
+            # Regex to match a string that is ONLY a valid float/int
+            single_number_regex = r"^\d+\.?\d*$"
+            single_number_expr = (
+                pl.when(column.str.contains(single_number_regex))
+                .then(column.cast(pl.Float64, strict=False))
+                .otherwise(None)
+            )
+            # If ratio_expr is null, try to fill it with single_number_expr
+            final_expr = ratio_expr.fill_null(single_number_expr)
+        else:
+            final_expr = ratio_expr
 
         return pl.select(final_expr.round(4)).to_series()
 
 
+class TriRatioCalculator:
+    """
+    A transformer that handles three-part ("A:B:C") and two-part ("A:C")
+    ratios, enforcing a strict output structure.
+
+    - Three-part ratios produce A/B and A/C.
+    - Two-part ratios are assumed to be A:C and produce None for A/B.
+    - Single values produce None for both outputs.
+    """
+    def __init__(self, handle_zeros: bool = False):
+        """
+        Initializes the TriRatioCalculator.
+
+        Args:
+            handle_zeros (bool): If True, returns a valid value if either the denominator or numerator is zero; returns zero if both are zero.
+        """
+        self.handle_zeros = handle_zeros
+
+    def _calculate_ratio(self, num: pl.Expr, den: pl.Expr) -> pl.Expr:
+        """Helper to contain the core division logic."""
+        if self.handle_zeros:
+            # Special handling for zeros
+            expr = (
+                pl.when((num == 0) & (den == 0)).then(pl.lit(0.0))
+                .when((num != 0) & (den == 0)).then(num) # Return numerator
+                .when((num == 0) & (den != 0)).then(den) # Return denominator
+                .otherwise(num / den)
+            )
+        else:
+            # Default behavior: return null if denominator is 0
+            expr = pl.when(den != 0).then(num / den).otherwise(None)
+
+        return expr.round(4)
+
+    def __call__(self, column: pl.Series) -> pl.DataFrame:
+        """
+        Applies the robust tri-ratio logic using the lazy API.
+        """
+        # Wrap the input Series in a DataFrame to use the lazy expression API
+        temp_df = column.to_frame()
+
+        # Define all steps as lazy expressions
+        all_numbers_expr = pl.col(column.name).str.extract_all(r"(\d+\.?\d*)")
+        num_parts_expr = all_numbers_expr.list.len()
+
+        expr_A = all_numbers_expr.list.get(0).cast(pl.Float64)
+        expr_B = all_numbers_expr.list.get(1).cast(pl.Float64)
+        expr_C = all_numbers_expr.list.get(2).cast(pl.Float64)
+
+        # Define logic for each output column using expressions
+        ratio_ab_expr = pl.when(num_parts_expr == 3).then(
+            self._calculate_ratio(expr_A, expr_B)
+        ).otherwise(None)
+
+        ratio_ac_expr = pl.when(num_parts_expr == 3).then(
+            self._calculate_ratio(expr_A, expr_C)
+        ).when(num_parts_expr == 2).then(
+            self._calculate_ratio(expr_A, expr_B) # B is actually C in this case
+        ).otherwise(None)
+
+        # Execute the expressions and return the final DataFrame
+        return temp_df.select(
+            A_div_B=ratio_ab_expr,
+            A_div_C=ratio_ac_expr
+        )
+
+
 class CategoryMapper:
     """
     A transformer that maps string categories to specified numerical values using a dictionary.

ml_tools/path_manager.py

@@ -20,7 +20,7 @@ class PathManager:
     """
     Manages and stores a project's file paths, acting as a centralized
     "path database". It supports both development mode and applications
-    bundled with Pyinstaller.
+    bundled with Pyinstaller or Nuitka.
     
     Supports python dictionary syntax.
     """