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

additory/__init__.py

@@ -1,19 +1,63 @@
-# additory/__init__.py
+"""
+Additory v0.1.1 - Data Augmentation Library
 
-from .dynamic_api import add as _api_instance
+A Polars-first data augmentation library with 5 main functions:
+- to: Add columns from other DataFrames
+- transform: Transform columns (transpose, encode, extract, etc.)
+- snapshot: Filter and select data
+- synthetic: Generate synthetic data
+- analyze: Analyze data quality and patterns
+- expressions: Evaluate expressions and add computed columns
 
-# Version information
-__version__ = "0.1.0a4"
+Usage:
+    import additory
+    
+    # Add columns
+    result = additory.add.to(df, reference_df, on='id', bring='price')
+    
+    # Transform columns
+    result = additory.add.transform(df, mode='onehotencoding', columns=['category'])
+    
+    # Filter data
+    result = additory.add.snapshot(df, where='age > 18')
+    
+    # Generate synthetic data
+    result = additory.add.synthetic(df, rows=1000)
+    
+    # Analyze data
+    result = additory.add.analyze(df, preset='quick')
+    
+    # Evaluate expressions
+    result = additory.add.expressions(df, 'inbuilt:bmi', 'age * 12')
+"""
 
-# Expose the API instance normally
-add = _api_instance
+from types import SimpleNamespace
 
-# Module-level __getattr__ to forward dynamic attributes
-def __getattr__(name):
-    # Delegate all unknown attributes to the API instance
-    return getattr(_api_instance, name)
+# Import main functions
+from additory.functions.to import to
+from additory.functions.transform import transform
+from additory.functions.snapshot import snapshot
+from additory.functions.synthetic import synthetic
+from additory.functions.analyze import analyze
+from additory.functions.expressions import expressions
 
-__all__ = [
-    "add",
-    "__version__",
-]
+# Import configuration functions
+from additory.core.config import set_expressions_folder, set_default_backend
+
+# Create simple API namespace
+add = SimpleNamespace(
+    to=to,
+    transform=transform,
+    snapshot=snapshot,
+    synthetic=synthetic,
+    analyze=analyze,
+    expressions=expressions,
+    set_expressions_folder=set_expressions_folder,
+    set_default_backend=set_default_backend
+)
+
+# Version
+__version__ = "0.1.1a1"
+
+# Public API
+__all__ = ['add', '__version__']

additory/common/__init__.py

@@ -1,157 +1,41 @@
 """
-Common Utilities Module
-
-Shared functionality used by both synthetic and expressions modules:
-- Distribution functions (normal, uniform, skewed, etc.)
-- List file management (.list format)
-- Pattern file management (.properties format)
-- Fallback resolution logic
-
-This module eliminates code duplication and provides consistent behavior
-across synthetic and expression data generation.
+Common utilities for Additory.
+
+This module provides shared utilities used across all functions:
+- validation: Input validation
+- strategy_parser: Strategy parsing
+- column_selector: Column selection
+- result: Result wrappers
+- extractors: Feature extractors
+- unit_conversions: Unit conversion utilities
+- knn_imputation: KNN imputation
+- distributions: Distribution generation
 """
 
-from .distributions import (
-    generate_normal,
-    generate_uniform,
-    generate_skewed,
-    generate_beta,
-    generate_gamma,
-    generate_exponential_dist,
-    generate_kde,
-    generate_multivariate_normal,
-    generate_distribution_values,
-    estimate_distribution_params,
-    calculate_skewness,
-    detect_distribution_type,
-    DistributionType,
-)
-
-from .lists import (
-    load_list_file,
-    parse_list_file,
-    get_list_values,
-    list_all_lists,
-)
-
-from .patterns import (
-    load_properties_file,
-    parse_properties_file,
-    get_pattern,
-    list_all_patterns,
-)
-
-from .resolver import (
-    resolve_pattern,
-    resolve_with_logging,
-    PatternResolutionResult,
-    PreferMode,
-)
-
-from .backend import (
-    detect_backend,
-    is_dataframe,
-    to_polars,
-    from_polars,
-    BackendType,
-)
-
 from .validation import (
     validate_dataframe,
-    validate_columns_exist,
-    validate_positive_number,
-    validate_non_negative_number,
-    validate_parameter_choice,
-    validate_ratio,
-    validate_string_not_empty,
-    validate_integer_in_range,
-    ValidationError,
-)
-
-from .exceptions import (
-    AdditoryError,
-    ValidationError,
-    BackendError,
-    ConversionError,
-    ExpressionError,
-    ConfigurationError,
-    UnitConversionError,
-    EncodingError,
-    LookupError,
-    SyntheticDataError,
-    AugmentError,
-)
-
-from .column_utils import (
-    sanitize_column_name,
-    generate_safe_column_name,
+    validate_not_empty,
     validate_column_name,
-    truncate_column_name,
-    generate_column_names_with_prefix_suffix,
+    validate_positive_integer,
+    validate_percentage,
+    validate_mode,
+    validate_dict,
+    validate_list,
+    validate_string,
+    validate_boolean,
+    validate_optional
 )
 
 __all__ = [
-    # Distribution functions
-    "generate_normal",
-    "generate_uniform",
-    "generate_skewed",
-    "generate_beta",
-    "generate_gamma",
-    "generate_exponential_dist",
-    "generate_kde",
-    "generate_multivariate_normal",
-    "generate_distribution_values",
-    "estimate_distribution_params",
-    "calculate_skewness",
-    "detect_distribution_type",
-    "DistributionType",
-    # List management
-    "load_list_file",
-    "parse_list_file",
-    "get_list_values",
-    "list_all_lists",
-    # Pattern management
-    "load_properties_file",
-    "parse_properties_file",
-    "get_pattern",
-    "list_all_patterns",
-    # Resolution
-    "resolve_pattern",
-    "resolve_with_logging",
-    "PatternResolutionResult",
-    "PreferMode",
-    # Backend detection
-    "detect_backend",
-    "is_dataframe",
-    "to_polars",
-    "from_polars",
-    "BackendType",
-    # Validation
-    "validate_dataframe",
-    "validate_columns_exist",
-    "validate_positive_number",
-    "validate_non_negative_number",
-    "validate_parameter_choice",
-    "validate_ratio",
-    "validate_string_not_empty",
-    "validate_integer_in_range",
-    "ValidationError",
-    # Exceptions
-    "AdditoryError",
-    "ValidationError",
-    "BackendError",
-    "ConversionError",
-    "ExpressionError",
-    "ConfigurationError",
-    "UnitConversionError",
-    "EncodingError",
-    "LookupError",
-    "SyntheticDataError",
-    "AugmentError",
-    # Column utilities
-    "sanitize_column_name",
-    "generate_safe_column_name",
-    "validate_column_name",
-    "truncate_column_name",
-    "generate_column_names_with_prefix_suffix",
+    'validate_dataframe',
+    'validate_not_empty',
+    'validate_column_name',
+    'validate_positive_integer',
+    'validate_percentage',
+    'validate_mode',
+    'validate_dict',
+    'validate_list',
+    'validate_string',
+    'validate_boolean',
+    'validate_optional'
 ]

additory/common/column_selector.py

@@ -0,0 +1,255 @@
+"""
+Column selection and validation utilities for Additory.
+
+Provides pattern matching and type-based column selection.
+"""
+
+import re
+from typing import Any, List, Optional, Union
+import polars as pl
+
+
+def select_columns(df: pl.DataFrame, columns: Union[str, List[str], None]) -> List[str]:
+    """
+    Select columns from DataFrame with pattern matching support.
+    
+    Args:
+        df: DataFrame to select columns from
+        columns: Column specification (None='*', str pattern, or list)
+        
+    Returns:
+        List of selected column names
+        
+    Raises:
+        ValueError: If no columns match the pattern
+        
+    Example:
+        # Select all columns
+        cols = select_columns(df, '*')
+        
+        # Select by pattern
+        cols = select_columns(df, 'age_*')
+        
+        # Select specific columns
+        cols = select_columns(df, ['name', 'email', 'age'])
+    """
+    # None means all columns
+    if columns is None:
+        return df.columns
+    
+    # String pattern
+    if isinstance(columns, str):
+        # '*' means all columns
+        if columns == '*':
+            return df.columns
+        
+        # Check if it's a pattern or exact match
+        if '*' in columns:
+            # Pattern matching
+            matched = []
+            for col in df.columns:
+                if match_pattern(col, columns):
+                    matched.append(col)
+            
+            if not matched:
+                raise ValueError(f"No columns match pattern '{columns}'")
+            
+            return matched
+        else:
+            # Exact match
+            if columns not in df.columns:
+                raise ValueError(f"Column '{columns}' not found in DataFrame")
+            return [columns]
+    
+    # List of columns
+    if isinstance(columns, list):
+        # Expand any patterns in the list
+        expanded = expand_column_patterns(df, columns)
+        
+        # Validate all columns exist
+        validate_columns_exist(df, expanded)
+        
+        return expanded
+    
+    raise TypeError(
+        f"columns must be None, str, or list, got {type(columns).__name__}"
+    )
+
+
+def match_pattern(column_name: str, pattern: str) -> bool:
+    """
+    Check if column name matches pattern.
+    
+    Args:
+        column_name: Column name to check
+        pattern: Pattern to match ('*', 'prefix_*', '*_suffix', 'exact')
+        
+    Returns:
+        True if matches, False otherwise
+        
+    Example:
+        match_pattern('age_years', 'age_*')  # True
+        match_pattern('total_age', '*_age')  # True
+        match_pattern('age', 'age')          # True
+    """
+    # Exact match
+    if pattern == column_name:
+        return True
+    
+    # Wildcard match all
+    if pattern == '*':
+        return True
+    
+    # Convert pattern to regex
+    # Escape special regex characters except *
+    regex_pattern = re.escape(pattern).replace(r'\*', '.*')
+    
+    # Anchor to start and end
+    regex_pattern = f'^{regex_pattern}$'
+    
+    return bool(re.match(regex_pattern, column_name))
+
+
+def validate_columns_exist(df: pl.DataFrame, columns: List[str]) -> bool:
+    """
+    Validate that all columns exist in DataFrame.
+    
+    Args:
+        df: DataFrame to check
+        columns: List of column names to validate
+        
+    Returns:
+        True if all exist
+        
+    Raises:
+        ValueError: If any columns are missing
+        
+    Example:
+        validate_columns_exist(df, ['name', 'age', 'email'])
+    """
+    missing = []
+    for col in columns:
+        if col not in df.columns:
+            missing.append(col)
+    
+    if missing:
+        if len(missing) == 1:
+            raise ValueError(f"Column '{missing[0]}' not found in DataFrame")
+        else:
+            raise ValueError(
+                f"Columns {missing} not found in DataFrame. "
+                f"Available columns: {df.columns}"
+            )
+    
+    return True
+
+
+def expand_column_patterns(df: pl.DataFrame, patterns: List[str]) -> List[str]:
+    """
+    Expand column patterns to actual column names.
+    
+    Args:
+        df: DataFrame to expand patterns from
+        patterns: List of patterns to expand
+        
+    Returns:
+        List of expanded column names (no duplicates)
+        
+    Example:
+        # Input: ['age_*', 'total_*']
+        # Output: ['age_years', 'age_months', 'total_sales', 'total_orders']
+        cols = expand_column_patterns(df, ['age_*', 'total_*'])
+    """
+    expanded = []
+    seen = set()
+    
+    for pattern in patterns:
+        # If pattern contains wildcard, expand it
+        if '*' in pattern:
+            matched = False
+            for col in df.columns:
+                if match_pattern(col, pattern):
+                    if col not in seen:
+                        expanded.append(col)
+                        seen.add(col)
+                    matched = True
+            
+            if not matched:
+                raise ValueError(f"No columns match pattern '{pattern}'")
+        else:
+            # Exact column name
+            if pattern not in seen:
+                expanded.append(pattern)
+                seen.add(pattern)
+    
+    return expanded
+
+
+def get_column_type(df: pl.DataFrame, column: str) -> str:
+    """
+    Get the data type of a column.
+    
+    Args:
+        df: DataFrame containing the column
+        column: Column name
+        
+    Returns:
+        Type string ('numeric', 'string', 'datetime', 'boolean', 'other')
+        
+    Raises:
+        ValueError: If column doesn't exist
+    """
+    if column not in df.columns:
+        raise ValueError(f"Column '{column}' not found in DataFrame")
+    
+    dtype = df[column].dtype
+    
+    # Numeric types
+    if dtype in [pl.Int8, pl.Int16, pl.Int32, pl.Int64,
+                 pl.UInt8, pl.UInt16, pl.UInt32, pl.UInt64,
+                 pl.Float32, pl.Float64]:
+        return 'numeric'
+    
+    # String types
+    if dtype in [pl.Utf8, pl.Categorical]:
+        return 'string'
+    
+    # Datetime types
+    if dtype in [pl.Date, pl.Time, pl.Duration]:
+        return 'datetime'
+    
+    # Check for Datetime with timezone info
+    if isinstance(dtype, pl.Datetime):
+        return 'datetime'
+    
+    # Boolean type
+    if dtype == pl.Boolean:
+        return 'boolean'
+    
+    # Other types
+    return 'other'
+
+
+def filter_columns_by_type(df: pl.DataFrame, columns: List[str], dtype: str) -> List[str]:
+    """
+    Filter columns by data type.
+    
+    Args:
+        df: DataFrame to filter columns from
+        columns: List of columns to filter
+        dtype: Type to filter by ('numeric', 'string', 'datetime', 'boolean')
+        
+    Returns:
+        List of columns matching the type
+        
+    Example:
+        numeric_cols = filter_columns_by_type(df, all_cols, 'numeric')
+    """
+    filtered = []
+    
+    for col in columns:
+        col_type = get_column_type(df, col)
+        if col_type == dtype:
+            filtered.append(col)
+    
+    return filtered