additory 0.1.0a1__py3-none-any.whl

additory/utilities/units.py

@@ -0,0 +1,746 @@
+# 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):
+        self.arrow_bridge = EnhancedArrowBridge()
+        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()