additory 0.1.0a4__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

additory/utilities/units.py

@@ -1,749 +0,0 @@
-# additory/utilities/units.py
-# Unit conversion system with hardcoded conversion factors
-
-import polars as pl
-import pandas as pd
-import re
-from typing import Any, Dict, List, Optional, Union, Tuple
-from datetime import datetime
-
-from ..core.backends.arrow_bridge import EnhancedArrowBridge, ArrowBridgeError
-from ..core.logging import log_info, log_warning
-
-
-# Hardcoded unit conversion definitions
-# All conversions relative to base unit (factor = 1.0)
-UNIT_CONVERSIONS = {
-    # LENGTH - base unit: meter (m)
-    "length": {
-        "base_unit": "m",
-        "units": {
-            "m": 1.0,           # meter (base)
-            "meter": 1.0,       # meter (alternative)
-            "metres": 1.0,      # meter (alternative)
-            "cm": 0.01,         # centimeter
-            "centimeter": 0.01, # centimeter (alternative)
-            "centimetre": 0.01, # centimeter (alternative)
-            "mm": 0.001,        # millimeter
-            "millimeter": 0.001,# millimeter (alternative)
-            "millimetre": 0.001,# millimeter (alternative)
-            "km": 1000.0,       # kilometer
-            "kilometer": 1000.0,# kilometer (alternative)
-            "kilometre": 1000.0,# kilometer (alternative)
-            "in": 0.0254,       # inch
-            "inch": 0.0254,     # inch (alternative)
-            "inches": 0.0254,   # inch (alternative)
-            "ft": 0.3048,       # foot
-            "foot": 0.3048,     # foot (alternative)
-            "feet": 0.3048,     # foot (alternative)
-            "yd": 0.9144,       # yard
-            "yard": 0.9144,     # yard (alternative)
-            "yards": 0.9144,    # yard (alternative)
-            "mi": 1609.344,     # mile
-            "mile": 1609.344,   # mile (alternative)
-            "miles": 1609.344,  # mile (alternative)
-        }
-    },
-    
-    # WEIGHT/MASS - base unit: kilogram (kg)
-    "weight": {
-        "base_unit": "kg",
-        "units": {
-            "kg": 1.0,          # kilogram (base)
-            "kilogram": 1.0,    # kilogram (alternative)
-            "kilograms": 1.0,   # kilogram (alternative)
-            "g": 0.001,         # gram
-            "gram": 0.001,      # gram (alternative)
-            "grams": 0.001,     # gram (alternative)
-            "mg": 0.000001,     # milligram
-            "milligram": 0.000001, # milligram (alternative)
-            "milligrams": 0.000001, # milligram (alternative)
-            "lb": 0.453592,     # pound
-            "lbs": 0.453592,    # pound (alternative)
-            "pound": 0.453592,  # pound (alternative)
-            "pounds": 0.453592, # pound (alternative)
-            "oz": 0.0283495,    # ounce
-            "ounce": 0.0283495, # ounce (alternative)
-            "ounces": 0.0283495,# ounce (alternative)
-            "ton": 1000.0,      # metric ton
-            "tonne": 1000.0,    # metric ton (alternative)
-            "tonnes": 1000.0,   # metric ton (alternative)
-            "stone": 6.35029,   # stone (14 pounds)
-            "stones": 6.35029,  # stone (alternative)
-        }
-    },
-    
-    # TEMPERATURE - base unit: Celsius (°C)
-    # Note: Temperature requires special handling due to offset conversions
-    "temperature": {
-        "base_unit": "C",
-        "units": {
-            "C": {"factor": 1.0, "offset": 0.0},      # Celsius (base)
-            "c": {"factor": 1.0, "offset": 0.0},      # Celsius (lowercase)
-            "celsius": {"factor": 1.0, "offset": 0.0}, # Celsius (alternative)
-            "F": {"factor": 5/9, "offset": -32},      # Fahrenheit: (F-32)*5/9 = (F+(-32))*5/9
-            "f": {"factor": 5/9, "offset": -32},      # Fahrenheit (lowercase)
-            "fahrenheit": {"factor": 5/9, "offset": -32}, # Fahrenheit (alternative)
-            "K": {"factor": 1.0, "offset": -273.15},  # Kelvin: K-273.15 = (K+(-273.15))*1.0
-            "k": {"factor": 1.0, "offset": -273.15},  # Kelvin (lowercase)
-            "kelvin": {"factor": 1.0, "offset": -273.15}, # Kelvin (alternative)
-        }
-    },
-    
-    # VOLUME - base unit: liter (L)
-    "volume": {
-        "base_unit": "L",
-        "units": {
-            "L": 1.0,           # liter (base)
-            "l": 1.0,           # liter (lowercase)
-            "liter": 1.0,       # liter (alternative)
-            "liters": 1.0,      # liter (alternative)
-            "litre": 1.0,       # liter (alternative)
-            "litres": 1.0,      # liter (alternative)
-            "mL": 0.001,        # milliliter
-            "ml": 0.001,        # milliliter (lowercase)
-            "milliliter": 0.001,# milliliter (alternative)
-            "milliliters": 0.001,# milliliter (alternative)
-            "millilitre": 0.001,# milliliter (alternative)
-            "millilitres": 0.001,# milliliter (alternative)
-            "gal": 3.78541,     # US gallon
-            "gallon": 3.78541,  # US gallon (alternative)
-            "gallons": 3.78541, # US gallon (alternative)
-            "qt": 0.946353,     # US quart
-            "quart": 0.946353,  # US quart (alternative)
-            "quarts": 0.946353, # US quart (alternative)
-            "pt": 0.473176,     # US pint
-            "pint": 0.473176,   # US pint (alternative)
-            "pints": 0.473176,  # US pint (alternative)
-            "cup": 0.236588,    # US cup
-            "cups": 0.236588,   # US cup (alternative)
-            "fl_oz": 0.0295735, # US fluid ounce
-            "floz": 0.0295735,  # US fluid ounce (alternative)
-            "fluid_ounce": 0.0295735, # US fluid ounce (alternative)
-            "fluid_ounces": 0.0295735, # US fluid ounce (alternative)
-        }
-    },
-    
-    # TIME - base unit: second (s)
-    "time": {
-        "base_unit": "s",
-        "units": {
-            "s": 1.0,           # second (base)
-            "sec": 1.0,         # second (alternative)
-            "second": 1.0,      # second (alternative)
-            "seconds": 1.0,     # second (alternative)
-            "min": 60.0,        # minute
-            "minute": 60.0,     # minute (alternative)
-            "minutes": 60.0,    # minute (alternative)
-            "hr": 3600.0,       # hour
-            "hour": 3600.0,     # hour (alternative)
-            "hours": 3600.0,    # hour (alternative)
-            "day": 86400.0,     # day
-            "days": 86400.0,    # day (alternative)
-            "week": 604800.0,   # week
-            "weeks": 604800.0,  # week (alternative)
-            "month": 2629746.0, # average month (30.44 days)
-            "months": 2629746.0,# average month (alternative)
-            "year": 31556952.0, # average year (365.24 days)
-            "years": 31556952.0,# average year (alternative)
-        }
-    },
-    
-    # AREA - base unit: square meter (m²)
-    "area": {
-        "base_unit": "m2",
-        "units": {
-            "m2": 1.0,          # square meter (base)
-            "m²": 1.0,          # square meter (alternative)
-            "sq_m": 1.0,        # square meter (alternative)
-            "square_meter": 1.0,# square meter (alternative)
-            "square_metres": 1.0,# square meter (alternative)
-            "cm2": 0.0001,      # square centimeter
-            "cm²": 0.0001,      # square centimeter (alternative)
-            "sq_cm": 0.0001,    # square centimeter (alternative)
-            "km2": 1000000.0,   # square kilometer
-            "km²": 1000000.0,   # square kilometer (alternative)
-            "sq_km": 1000000.0, # square kilometer (alternative)
-            "in2": 0.00064516,  # square inch
-            "in²": 0.00064516,  # square inch (alternative)
-            "sq_in": 0.00064516,# square inch (alternative)
-            "ft2": 0.092903,    # square foot
-            "ft²": 0.092903,    # square foot (alternative)
-            "sq_ft": 0.092903,  # square foot (alternative)
-            "acre": 4046.86,    # acre
-            "acres": 4046.86,   # acre (alternative)
-        }
-    }
-}
-
-
-class UnitConversionError(Exception):
-    """Raised when unit conversion operations fail"""
-    pass
-
-
-def sanitize_column_name(col_name: str) -> str:
-    """
-    Convert column name to Python-friendly identifier
-    
-    Rules:
-    - Replace spaces and special chars with underscores
-    - Remove consecutive underscores  
-    - Remove leading/trailing underscores
-    - Ensure doesn't start with number
-    - Convert to lowercase for consistency
-    
-    Args:
-        col_name: Original column name
-        
-    Returns:
-        Sanitized column name safe for Python identifiers
-        
-    Examples:
-        "height collected on site" → "height_collected_on_site"
-        "Patient Height - Site A" → "patient_height_site_a"
-        "Weight (kg)" → "weight_kg"
-        "temp@location#1" → "temp_location_1"
-    """
-    # Convert to string and handle None/empty
-    if not col_name:
-        return "unnamed_column"
-    
-    col_str = str(col_name)
-    
-    # Replace non-alphanumeric chars with underscores
-    sanitized = re.sub(r'[^a-zA-Z0-9_]', '_', col_str)
-    
-    # Remove consecutive underscores
-    sanitized = re.sub(r'_+', '_', sanitized)
-    
-    # Remove leading/trailing underscores
-    sanitized = sanitized.strip('_')
-    
-    # Ensure doesn't start with number
-    if sanitized and sanitized[0].isdigit():
-        sanitized = f"col_{sanitized}"
-    
-    # Convert to lowercase for consistency
-    sanitized = sanitized.lower()
-    
-    return sanitized if sanitized else "unnamed_column"
-
-
-def generate_safe_column_name(base_name: str, existing_columns: List[str]) -> str:
-    """
-    Generate a safe column name that doesn't conflict with existing columns
-    
-    Args:
-        base_name: Desired column name
-        existing_columns: List of existing column names
-        
-    Returns:
-        Safe column name with _1, _2, etc. suffix if needed
-    """
-    if base_name not in existing_columns:
-        return base_name
-    
-    counter = 1
-    while f"{base_name}_{counter}" in existing_columns:
-        counter += 1
-    
-    return f"{base_name}_{counter}"
-
-
-class UnitConverter:
-    """Unit conversion system with Polars processing"""
-    
-    def __init__(self):
-        try:
-            self.arrow_bridge = EnhancedArrowBridge()
-        except ArrowBridgeError:
-            self.arrow_bridge = None
-        self.conversion_stats = {
-            "total_conversions": 0,
-            "successful_conversions": 0,
-            "failed_conversions": 0,
-            "categories_detected": set(),
-            "units_processed": set()
-        }
-        
-        log_info("[units] Unit Converter initialized")
-    
-    def harmonize_units(self, df: Any, value_column: str, unit_column: str, 
-                       target_unit: Optional[str] = None, 
-                       position: str = "end") -> Any:
-        """
-        Harmonize units in a dataframe
-        
-        Args:
-            df: Input dataframe (pandas, polars, cudf)
-            value_column: Column containing numeric values
-            unit_column: Column containing unit strings
-            target_unit: Target unit (auto-detected if None)
-            position: Where to place new columns ("end", "start", int, "after:col", "before:col")
-            
-        Returns:
-            Dataframe with harmonized columns added
-            
-        Raises:
-            UnitConversionError: If conversion fails
-        """
-        start_time = datetime.now()
-        
-        try:
-            # Validate inputs
-            self._validate_inputs(df, value_column, unit_column)
-            
-            # Detect backend
-            backend_type = self.arrow_bridge.detect_backend(df)
-            log_info(f"[units] Processing {backend_type} dataframe")
-            
-            # Convert to Arrow then Polars for processing
-            arrow_table = self.arrow_bridge.to_arrow(df, backend_type)
-            polars_df = pl.from_arrow(arrow_table)
-            
-            # Perform unit conversion in Polars
-            result_polars = self._harmonize_units_polars(
-                polars_df, value_column, unit_column, target_unit
-            )
-            
-            # Convert back to original backend
-            result_arrow = result_polars.to_arrow()
-            result_df = self.arrow_bridge.from_arrow(result_arrow, backend_type)
-            
-            # The column names should already be correct from the Polars processing
-            # Just apply positioning if needed
-            sanitized_value_col = sanitize_column_name(value_column)
-            sanitized_unit_col = sanitize_column_name(unit_column)
-            
-            # Determine target unit if not specified (should be available from processing)
-            if target_unit is None:
-                unique_units = polars_df[unit_column].unique().to_list()
-                unique_units_lower = [str(unit).strip().lower() for unit in unique_units if unit is not None]
-                category = self._detect_unit_category(unique_units_lower)
-                if category:
-                    target_unit = UNIT_CONVERSIONS[category]["base_unit"]
-                else:
-                    target_unit = "unknown"
-            
-            expected_value_col = f"{sanitized_value_col}_{target_unit}"
-            expected_unit_col = f"{sanitized_unit_col}_{target_unit}"
-            
-            # Apply column positioning with the actual column names that were created
-            actual_new_columns = [col for col in result_df.columns if col not in df.columns]
-            
-            result_df = self._apply_positioning(
-                result_df, 
-                actual_new_columns,
-                position,
-                backend_type
-            )
-            
-            # Update statistics
-            execution_time = (datetime.now() - start_time).total_seconds() * 1000
-            self.conversion_stats["total_conversions"] += 1
-            self.conversion_stats["successful_conversions"] += 1
-            
-            log_info(f"[units] Unit harmonization completed in {execution_time:.1f}ms")
-            
-            return result_df
-            
-        except Exception as e:
-            self.conversion_stats["total_conversions"] += 1
-            self.conversion_stats["failed_conversions"] += 1
-            raise UnitConversionError(f"Unit harmonization failed: {e}")
-    
-    def _harmonize_units_polars(self, df: pl.DataFrame, value_column: str, 
-                               unit_column: str, target_unit: Optional[str] = None) -> pl.DataFrame:
-        """
-        Perform unit conversion using Polars
-        
-        Args:
-            df: Polars DataFrame
-            value_column: Column containing numeric values
-            unit_column: Column containing unit strings
-            target_unit: Target unit (auto-detected if None)
-            
-        Returns:
-            Polars DataFrame with harmonized columns
-        """
-        # Get unique units in the data
-        unique_units = df[unit_column].unique().to_list()
-        unique_units = [str(unit).strip() for unit in unique_units if unit is not None]
-        
-        # Convert to lowercase for matching but preserve original case for logging
-        unique_units_lower = [unit.lower() for unit in unique_units]
-        
-        log_info(f"[units] Found units: {unique_units}")
-        
-        # Detect unit category using lowercase units
-        category = self._detect_unit_category(unique_units_lower)
-        if not category:
-            raise UnitConversionError(f"Could not detect unit category for units: {unique_units}")
-        
-        log_info(f"[units] Detected category: {category}")
-        self.conversion_stats["categories_detected"].add(category)
-        
-        # Determine target unit
-        if target_unit is None:
-            target_unit = UNIT_CONVERSIONS[category]["base_unit"]
-        else:
-            # Validate target unit
-            target_unit_lower = target_unit.lower()
-            if target_unit_lower not in UNIT_CONVERSIONS[category]["units"]:
-                available_units = list(UNIT_CONVERSIONS[category]["units"].keys())
-                raise UnitConversionError(
-                    f"Target unit '{target_unit}' not supported for category '{category}'. "
-                    f"Available units: {available_units}"
-                )
-            target_unit = target_unit_lower
-        
-        log_info(f"[units] Target unit: {target_unit}")
-        
-        # Create conversion mapping
-        conversion_map = self._create_conversion_map(category, target_unit)
-        
-        # Generate clean, descriptive column names
-        sanitized_value_col = sanitize_column_name(value_column)
-        sanitized_unit_col = sanitize_column_name(unit_column)
-        
-        harmonized_value_col = f"{sanitized_value_col}_{target_unit}"
-        harmonized_unit_col = f"{sanitized_unit_col}_{target_unit}"
-        
-        log_info(f"[units] Creating harmonized columns: {harmonized_value_col}, {harmonized_unit_col}")
-        
-        # Apply conversions using Polars
-        if category == "temperature":
-            # Special handling for temperature (offset conversions)
-            result_df = self._convert_temperature_polars(df, value_column, unit_column, 
-                                                       conversion_map, target_unit, 
-                                                       harmonized_value_col, harmonized_unit_col)
-        else:
-            # Standard factor-based conversions
-            result_df = self._convert_standard_polars(df, value_column, unit_column, 
-                                                    conversion_map, target_unit,
-                                                    harmonized_value_col, harmonized_unit_col)
-        
-        # Update statistics
-        self.conversion_stats["units_processed"].update(unique_units_lower)
-        
-        return result_df
-    
-    def _detect_unit_category(self, units: List[str]) -> Optional[str]:
-        """
-        Detect the category of units based on the units present
-        
-        Args:
-            units: List of unit strings (lowercase)
-            
-        Returns:
-            Category name or None if not detected
-        """
-        # Count matches for each category
-        category_scores = {}
-        
-        for category, config in UNIT_CONVERSIONS.items():
-            score = 0
-            for unit in units:
-                if unit in config["units"]:
-                    score += 1
-            
-            if score > 0:
-                category_scores[category] = score
-        
-        if not category_scores:
-            return None
-        
-        # Return category with highest score
-        best_category = max(category_scores, key=category_scores.get)
-        
-        # Require at least one match
-        if category_scores[best_category] > 0:
-            return best_category
-        
-        return None
-    
-    def _create_conversion_map(self, category: str, target_unit: str) -> Dict[str, float]:
-        """
-        Create conversion factors mapping from each unit to target unit
-        
-        Args:
-            category: Unit category
-            target_unit: Target unit
-            
-        Returns:
-            Dictionary mapping unit -> conversion factor
-        """
-        config = UNIT_CONVERSIONS[category]
-        target_factor = config["units"][target_unit]
-        
-        conversion_map = {}
-        
-        if category == "temperature":
-            # Temperature requires special handling
-            for unit, unit_config in config["units"].items():
-                conversion_map[unit] = unit_config
-        else:
-            # Standard factor-based conversion
-            for unit, unit_factor in config["units"].items():
-                # Convert from unit to base, then from base to target
-                conversion_map[unit] = unit_factor / target_factor
-        
-        return conversion_map
-    
-    def _convert_standard_polars(self, df: pl.DataFrame, value_column: str, 
-                               unit_column: str, conversion_map: Dict[str, float], 
-                               target_unit: str, harmonized_value_col: str, 
-                               harmonized_unit_col: str) -> pl.DataFrame:
-        """
-        Convert units using standard factor-based conversion in Polars
-        """
-        # Create a mapping expression for unit conversion
-        unit_mapping_expr = pl.col(unit_column).str.to_lowercase()
-        
-        # Build when-then chain for conversion factors
-        conversion_expr = None
-        for unit, factor in conversion_map.items():
-            condition = unit_mapping_expr == unit
-            if conversion_expr is None:
-                conversion_expr = pl.when(condition).then(pl.lit(factor))
-            else:
-                conversion_expr = conversion_expr.when(condition).then(pl.lit(factor))
-        
-        # Default to 1.0 for unknown units (no conversion)
-        conversion_expr = conversion_expr.otherwise(pl.lit(1.0))
-        
-        # Apply conversion with clear column names
-        result_df = df.with_columns([
-            (pl.col(value_column) * conversion_expr).alias(harmonized_value_col),
-            pl.lit(target_unit).alias(harmonized_unit_col)
-        ])
-        
-        return result_df
-    
-    def _convert_temperature_polars(self, df: pl.DataFrame, value_column: str, 
-                                  unit_column: str, conversion_map: Dict[str, Dict], 
-                                  target_unit: str, harmonized_value_col: str,
-                                  harmonized_unit_col: str) -> pl.DataFrame:
-        """
-        Convert temperature units with offset handling in Polars
-        """
-        unit_mapping_expr = pl.col(unit_column).str.to_lowercase()
-        
-        # Temperature conversion requires two steps:
-        # 1. Convert source unit to Celsius (base unit)
-        # 2. Convert Celsius to target unit
-        
-        # Step 1: Convert all units to Celsius first
-        celsius_conversion_expr = None
-        
-        for unit, config in conversion_map.items():
-            factor = config["factor"]
-            offset = config["offset"]
-            condition = unit_mapping_expr == unit
-            
-            # Convert to Celsius: (value + offset) * factor
-            unit_to_celsius = (pl.col(value_column) + pl.lit(offset)) * pl.lit(factor)
-            
-            if celsius_conversion_expr is None:
-                celsius_conversion_expr = pl.when(condition).then(unit_to_celsius)
-            else:
-                celsius_conversion_expr = celsius_conversion_expr.when(condition).then(unit_to_celsius)
-        
-        # Default to original value for unknown units (assume already Celsius)
-        celsius_conversion_expr = celsius_conversion_expr.otherwise(pl.col(value_column))
-        
-        # Step 2: Convert from Celsius to target unit
-        if target_unit.lower() == 'c' or target_unit.lower() == 'celsius':
-            # Target is Celsius, we're done
-            final_conversion_expr = celsius_conversion_expr
-        elif target_unit.lower() == 'f' or target_unit.lower() == 'fahrenheit':
-            # Convert Celsius to Fahrenheit: F = C * 9/5 + 32
-            final_conversion_expr = celsius_conversion_expr * pl.lit(9/5) + pl.lit(32)
-        elif target_unit.lower() == 'k' or target_unit.lower() == 'kelvin':
-            # Convert Celsius to Kelvin: K = C + 273.15
-            final_conversion_expr = celsius_conversion_expr + pl.lit(273.15)
-        else:
-            # Unknown target unit, keep as Celsius
-            final_conversion_expr = celsius_conversion_expr
-        
-        # Apply conversion with clear column names
-        result_df = df.with_columns([
-            final_conversion_expr.alias(harmonized_value_col),
-            pl.lit(target_unit).alias(harmonized_unit_col)
-        ])
-        
-        return result_df
-    
-    def _validate_inputs(self, df: Any, value_column: str, unit_column: str):
-        """Validate input parameters"""
-        # Check if dataframe is supported
-        if not self._is_dataframe(df):
-            raise UnitConversionError(
-                f"Input must be a DataFrame (pandas, polars, or cudf). Got: {type(df)}"
-            )
-        
-        # Check if dataframe is empty
-        if len(df) == 0:
-            raise UnitConversionError("Input dataframe is empty")
-        
-        # Check if columns exist
-        df_columns = list(df.columns)
-        
-        if value_column not in df_columns:
-            raise UnitConversionError(
-                f"Value column '{value_column}' not found. Available columns: {df_columns}"
-            )
-        
-        if unit_column not in df_columns:
-            raise UnitConversionError(
-                f"Unit column '{unit_column}' not found. Available columns: {df_columns}"
-            )
-        
-        # Check for column name conflicts (with new naming scheme)
-        sanitized_value_col = sanitize_column_name(value_column)
-        sanitized_unit_col = sanitize_column_name(unit_column)
-        
-        # We can't check target_unit conflicts here since target_unit might be auto-detected
-        # Conflict resolution will happen in the main function
-        
-        log_info(f"[units] Sanitized column names: {value_column} → {sanitized_value_col}, {unit_column} → {sanitized_unit_col}")
-    
-    def _is_dataframe(self, obj: Any) -> bool:
-        """Check if object is a supported dataframe type"""
-        return (
-            isinstance(obj, pd.DataFrame) or
-            (hasattr(obj, '__class__') and 'polars' in str(type(obj))) or
-            (hasattr(obj, '__class__') and 'cudf' in str(type(obj)))
-        )
-    
-    def _apply_positioning(self, df: Any, new_columns: List[str], position: str, 
-                          backend_type: str) -> Any:
-        """Apply column positioning using existing positioning system"""
-        try:
-            from ..core.column_positioning import position_columns
-            return position_columns(df, new_columns, position)
-        except Exception as e:
-            log_warning(f"[units] Column positioning failed: {e}. Using default 'end'.")
-            return df
-    
-    def _handle_column_conflicts(self, df: Any, harmonized_value_col: str, 
-                               harmonized_unit_col: str, backend_type: str) -> Tuple[Any, str, str]:
-        """
-        Handle column name conflicts by generating safe alternatives
-        
-        Args:
-            df: Input dataframe
-            harmonized_value_col: Desired harmonized value column name
-            harmonized_unit_col: Desired harmonized unit column name
-            backend_type: Backend type for column access
-            
-        Returns:
-            Tuple of (dataframe, final_value_col_name, final_unit_col_name)
-        """
-        # Get existing column names
-        if backend_type == "pandas":
-            existing_columns = list(df.columns)
-        elif backend_type == "polars":
-            existing_columns = df.columns
-        else:  # cudf
-            existing_columns = list(df.columns)
-        
-        # Generate safe column names
-        final_value_col = generate_safe_column_name(harmonized_value_col, existing_columns)
-        final_unit_col = generate_safe_column_name(harmonized_unit_col, existing_columns)
-        
-        # Log if conflicts were resolved
-        if final_value_col != harmonized_value_col:
-            log_warning(f"[units] Column conflict resolved: {harmonized_value_col} → {final_value_col}")
-        if final_unit_col != harmonized_unit_col:
-            log_warning(f"[units] Column conflict resolved: {harmonized_unit_col} → {final_unit_col}")
-        
-        return df, final_value_col, final_unit_col
-    
-    def get_supported_units(self, category: Optional[str] = None) -> Dict[str, List[str]]:
-        """
-        Get list of supported units
-        
-        Args:
-            category: Specific category to get units for (optional)
-            
-        Returns:
-            Dictionary of category -> list of units
-        """
-        if category:
-            if category not in UNIT_CONVERSIONS:
-                raise UnitConversionError(f"Unknown category: {category}")
-            return {category: list(UNIT_CONVERSIONS[category]["units"].keys())}
-        
-        return {
-            cat: list(config["units"].keys()) 
-            for cat, config in UNIT_CONVERSIONS.items()
-        }
-    
-    def get_conversion_stats(self) -> Dict[str, Any]:
-        """Get conversion statistics"""
-        stats = self.conversion_stats.copy()
-        stats["categories_detected"] = list(stats["categories_detected"])
-        stats["units_processed"] = list(stats["units_processed"])
-        
-        if stats["total_conversions"] > 0:
-            stats["success_rate"] = (stats["successful_conversions"] / stats["total_conversions"]) * 100
-        else:
-            stats["success_rate"] = 0.0
-        
-        return stats
-    
-    def reset_stats(self):
-        """Reset conversion statistics"""
-        self.conversion_stats = {
-            "total_conversions": 0,
-            "successful_conversions": 0,
-            "failed_conversions": 0,
-            "categories_detected": set(),
-            "units_processed": set()
-        }
-        log_info("[units] Conversion statistics reset")
-
-
-# Global instance
-_unit_converter = None
-
-def get_unit_converter() -> UnitConverter:
-    """Get the global unit converter instance"""
-    global _unit_converter
-    if _unit_converter is None:
-        _unit_converter = UnitConverter()
-    return _unit_converter
-
-
-def harmonize_units(df: Any, value_column: str, unit_column: str, 
-                   target_unit: Optional[str] = None, 
-                   position: str = "end") -> Any:
-    """
-    Harmonize units in a dataframe
-    
-    Args:
-        df: Input dataframe (pandas, polars, cudf)
-        value_column: Column containing numeric values
-        unit_column: Column containing unit strings
-        target_unit: Target unit (auto-detected if None)
-        position: Where to place new columns
-        
-    Returns:
-        Dataframe with harmonized columns added
-    """
-    converter = get_unit_converter()
-    return converter.harmonize_units(df, value_column, unit_column, target_unit, position)
-
-
-def get_supported_units(category: Optional[str] = None) -> Dict[str, List[str]]:
-    """Get list of supported units"""
-    converter = get_unit_converter()
-    return converter.get_supported_units(category)
-
-
-def get_conversion_stats() -> Dict[str, Any]:
-    """Get conversion statistics"""
-    converter = get_unit_converter()
-    return converter.get_conversion_stats()