additory 0.1.0a1__py3-none-any.whl

additory/augment/list_registry.py

@@ -0,0 +1,177 @@
+"""
+List Registry Manager for Data Augmentation
+
+Manages user-registered lists and provides access to built-in lists.
+
+List Resolution Order:
+    1. User-registered lists (highest priority)
+    2. Built-in lists
+    3. Error if not found
+"""
+
+from typing import List, Optional, Dict, Any
+
+from additory.common.exceptions import ValidationError
+from additory.augment.builtin_lists import BUILTIN_LISTS, list_builtin_names
+
+
+# Global registry for user-registered lists
+_USER_LISTS: Dict[str, List[Any]] = {}
+
+
+def register_list(name: str, values: List[Any]) -> None:
+    """
+    Register a custom list for use in augmentation strategies.
+    
+    User-registered lists take priority over built-in lists with the same name.
+    
+    Args:
+        name: List name (e.g., "my_custom_list")
+        values: List of values
+    
+    Raises:
+        ValidationError: If parameters are invalid
+    
+    Examples:
+        >>> add.register_list("custom_statuses", ["New", "Processing", "Done"])
+        >>> add.register_list("banks", ["My Bank", "Your Bank"])  # Overrides built-in
+    """
+    if not isinstance(name, str) or not name.strip():
+        raise ValidationError("List name must be a non-empty string")
+    
+    if not isinstance(values, list):
+        raise ValidationError("Values must be a list")
+    
+    if len(values) == 0:
+        raise ValidationError("List must contain at least one value")
+    
+    # Store in user registry
+    _USER_LISTS[name] = values
+
+
+def get_list(name: str) -> List[Any]:
+    """
+    Get a list by name (user-registered or built-in).
+    
+    Resolution order:
+        1. User-registered lists
+        2. Built-in lists
+        3. Raise error if not found
+    
+    Args:
+        name: List name
+    
+    Returns:
+        List of values
+    
+    Raises:
+        ValidationError: If list not found
+    """
+    # Check user-registered lists first
+    if name in _USER_LISTS:
+        return _USER_LISTS[name]
+    
+    # Check built-in lists
+    if name in BUILTIN_LISTS:
+        return BUILTIN_LISTS[name]
+    
+    # Not found
+    raise ValidationError(
+        f"List '{name}' not found. "
+        f"Use add.list_available() to see available lists or "
+        f"add.register_list('{name}', [...]) to create it."
+    )
+
+
+def list_exists(name: str) -> bool:
+    """
+    Check if a list exists (user-registered or built-in).
+    
+    Args:
+        name: List name
+    
+    Returns:
+        True if list exists, False otherwise
+    """
+    return name in _USER_LISTS or name in BUILTIN_LISTS
+
+
+def list_available() -> Dict[str, int]:
+    """
+    Get all available lists with their sizes.
+    
+    Returns:
+        Dictionary mapping list names to their sizes
+        Format: {"list_name": count, ...}
+    
+    Examples:
+        >>> lists = add.list_available()
+        >>> print(lists)
+        {'first_names': 200, 'banks': 120, 'my_custom_list': 5, ...}
+    """
+    result = {}
+    
+    # Add built-in lists
+    for name, values in BUILTIN_LISTS.items():
+        result[name] = len(values)
+    
+    # Add user-registered lists (may override built-in counts)
+    for name, values in _USER_LISTS.items():
+        result[name] = len(values)
+    
+    return result
+
+
+def list_show(name: str) -> List[Any]:
+    """
+    Show the contents of a list.
+    
+    Args:
+        name: List name
+    
+    Returns:
+        List of values
+    
+    Raises:
+        ValidationError: If list not found
+    
+    Examples:
+        >>> add.list_show("statuses")
+        ['Active', 'Inactive', 'Pending', 'Completed', ...]
+    """
+    return get_list(name)
+
+
+def list_remove(name: str) -> bool:
+    """
+    Remove a user-registered list.
+    
+    Note: Cannot remove built-in lists. If a user-registered list
+    overrides a built-in list, removing it will restore the built-in.
+    
+    Args:
+        name: List name
+    
+    Returns:
+        True if list was removed, False if not found
+    
+    Examples:
+        >>> add.register_list("temp_list", ["a", "b"])
+        >>> add.list_remove("temp_list")
+        True
+        >>> add.list_remove("temp_list")
+        False
+    """
+    if name in _USER_LISTS:
+        del _USER_LISTS[name]
+        return True
+    return False
+
+
+def clear_user_lists() -> None:
+    """
+    Clear all user-registered lists.
+    
+    Built-in lists are not affected.
+    """
+    _USER_LISTS.clear()

additory/augment/smote.py

@@ -0,0 +1,320 @@
+"""
+SMOTE (Synthetic Minority Over-sampling Technique) for Data Augmentation
+
+Provides imbalanced data handling strategies:
+- SMOTE: Generate synthetic samples for minority class
+- Balance: Balance class distribution
+- Oversample: Simple oversampling with variation
+"""
+
+from typing import List, Optional, Dict, Any, Tuple
+import warnings
+
+import numpy as np
+
+from additory.common.exceptions import ValidationError, AugmentError
+
+
+def calculate_distances(point: np.ndarray, data: np.ndarray) -> np.ndarray:
+    """
+    Calculate Euclidean distances from point to all points in data.
+    
+    Args:
+        point: Single data point (1D array)
+        data: Array of data points (2D array)
+        
+    Returns:
+        Array of distances
+    """
+    return np.sqrt(np.sum((data - point) ** 2, axis=1))
+
+
+def find_k_nearest_neighbors(
+    point_idx: int,
+    data: np.ndarray,
+    k: int = 5
+) -> np.ndarray:
+    """
+    Find k nearest neighbors of a point.
+    
+    Args:
+        point_idx: Index of the point
+        data: Array of all data points
+        k: Number of neighbors to find
+        
+    Returns:
+        Array of indices of k nearest neighbors
+    """
+    point = data[point_idx]
+    distances = calculate_distances(point, data)
+    
+    # Exclude the point itself
+    distances[point_idx] = np.inf
+    
+    # Get k nearest
+    nearest_indices = np.argsort(distances)[:k]
+    
+    return nearest_indices
+
+
+def generate_synthetic_sample(
+    point: np.ndarray,
+    neighbor: np.ndarray,
+    seed: Optional[int] = None
+) -> np.ndarray:
+    """
+    Generate synthetic sample between point and neighbor.
+    
+    Uses linear interpolation with random weight.
+    
+    Args:
+        point: Original data point
+        neighbor: Neighbor data point
+        seed: Random seed
+        
+    Returns:
+        Synthetic sample
+    """
+    if seed is not None:
+        np.random.seed(seed)
+    
+    # Random weight between 0 and 1
+    weight = np.random.random()
+    
+    # Linear interpolation
+    synthetic = point + weight * (neighbor - point)
+    
+    return synthetic
+
+
+def smote_generate(
+    data: np.ndarray,
+    n_samples: int,
+    k_neighbors: int = 5,
+    seed: Optional[int] = None
+) -> np.ndarray:
+    """
+    Generate synthetic samples using SMOTE algorithm.
+    
+    SMOTE creates synthetic samples by:
+    1. For each sample, find k nearest neighbors
+    2. Randomly select one neighbor
+    3. Create synthetic sample along line between sample and neighbor
+    
+    Args:
+        data: Original data (2D array: samples x features)
+        n_samples: Number of synthetic samples to generate
+        k_neighbors: Number of nearest neighbors to consider
+        seed: Random seed for reproducibility
+        
+    Returns:
+        Array of synthetic samples
+        
+    Raises:
+        ValidationError: If parameters invalid
+    """
+    n_original, n_features = data.shape
+    
+    # Validate parameters
+    if n_samples <= 0:
+        raise ValidationError(f"n_samples must be positive, got {n_samples}")
+    
+    if k_neighbors <= 0:
+        raise ValidationError(f"k_neighbors must be positive, got {k_neighbors}")
+    
+    if k_neighbors >= n_original:
+        warnings.warn(
+            f"k_neighbors ({k_neighbors}) >= number of samples ({n_original}). "
+            f"Using k_neighbors={n_original - 1}"
+        )
+        k_neighbors = n_original - 1
+    
+    if n_original < 2:
+        raise ValidationError(
+            f"Need at least 2 samples for SMOTE, got {n_original}"
+        )
+    
+    # Set seed for reproducibility
+    if seed is not None:
+        np.random.seed(seed)
+    
+    # Generate synthetic samples
+    synthetic_samples = []
+    
+    for i in range(n_samples):
+        # Randomly select a sample
+        sample_idx = np.random.randint(0, n_original)
+        sample = data[sample_idx]
+        
+        # Find k nearest neighbors
+        neighbor_indices = find_k_nearest_neighbors(sample_idx, data, k_neighbors)
+        
+        # Randomly select one neighbor
+        neighbor_idx = np.random.choice(neighbor_indices)
+        neighbor = data[neighbor_idx]
+        
+        # Generate synthetic sample
+        synthetic = generate_synthetic_sample(sample, neighbor, seed=None)
+        synthetic_samples.append(synthetic)
+    
+    return np.array(synthetic_samples)
+
+
+def apply_smote_strategy(
+    df_polars,
+    columns: List[str],
+    n_rows: int,
+    k_neighbors: int = 5,
+    seed: Optional[int] = None
+) -> Dict[str, List[float]]:
+    """
+    Apply SMOTE to generate synthetic rows for specified columns.
+    
+    Args:
+        df_polars: Input Polars DataFrame
+        columns: List of column names to use for SMOTE
+        n_rows: Number of synthetic rows to generate
+        k_neighbors: Number of nearest neighbors
+        seed: Random seed for reproducibility
+        
+    Returns:
+        Dictionary mapping column names to generated values
+        
+    Raises:
+        ValidationError: If columns invalid or insufficient data
+    """
+    # Validate columns exist
+    for col in columns:
+        if col not in df_polars.columns:
+            raise ValidationError(f"Column '{col}' not found in DataFrame")
+    
+    # Extract data for specified columns
+    data_list = []
+    for col in columns:
+        col_data = df_polars[col].to_numpy()
+        
+        # Check if numeric
+        if not np.issubdtype(col_data.dtype, np.number):
+            raise ValidationError(
+                f"SMOTE requires numeric columns. Column '{col}' is not numeric."
+            )
+        
+        # Check for nulls
+        if np.any(np.isnan(col_data)):
+            raise ValidationError(
+                f"SMOTE requires non-null values. Column '{col}' contains nulls."
+            )
+        
+        data_list.append(col_data)
+    
+    # Stack into 2D array (samples x features)
+    data = np.column_stack(data_list)
+    
+    # Generate synthetic samples
+    synthetic_data = smote_generate(data, n_rows, k_neighbors, seed)
+    
+    # Split back into columns
+    result = {}
+    for i, col in enumerate(columns):
+        result[col] = synthetic_data[:, i].tolist()
+    
+    return result
+
+
+def balance_classes(
+    df_polars,
+    class_column: str,
+    target_ratio: float = 1.0,
+    method: str = "smote",
+    k_neighbors: int = 5,
+    seed: Optional[int] = None
+) -> Tuple[int, str]:
+    """
+    Calculate how many samples needed to balance classes.
+    
+    Args:
+        df_polars: Input Polars DataFrame
+        class_column: Column containing class labels
+        target_ratio: Target ratio of minority to majority class (default: 1.0 for perfect balance)
+        method: Balancing method ('smote' or 'oversample')
+        k_neighbors: Number of neighbors for SMOTE
+        seed: Random seed
+        
+    Returns:
+        Tuple of (n_samples_needed, minority_class)
+        
+    Raises:
+        ValidationError: If class column invalid
+    """
+    # Validate class column
+    if class_column not in df_polars.columns:
+        raise ValidationError(f"Class column '{class_column}' not found in DataFrame")
+    
+    # Get class counts
+    class_counts = df_polars[class_column].value_counts()
+    
+    if len(class_counts) < 2:
+        raise ValidationError(
+            f"Need at least 2 classes for balancing, found {len(class_counts)}"
+        )
+    
+    # Find minority and majority classes
+    class_counts_dict = dict(zip(
+        class_counts[class_column].to_list(),
+        class_counts['counts'].to_list()
+    ))
+    
+    minority_class = min(class_counts_dict, key=class_counts_dict.get)
+    majority_class = max(class_counts_dict, key=class_counts_dict.get)
+    
+    minority_count = class_counts_dict[minority_class]
+    majority_count = class_counts_dict[majority_class]
+    
+    # Calculate target count for minority class
+    target_count = int(majority_count * target_ratio)
+    
+    # Calculate how many samples needed
+    n_samples_needed = max(0, target_count - minority_count)
+    
+    return n_samples_needed, minority_class
+
+
+def generate_smote_values(
+    df_polars,
+    columns: List[str],
+    n_rows: int,
+    k_neighbors: int = 5,
+    seed: Optional[int] = None,
+    **params
+) -> Dict[str, List[Any]]:
+    """
+    Main SMOTE generation function.
+    
+    Args:
+        df_polars: Input Polars DataFrame
+        columns: Columns to use for SMOTE (numeric only)
+        n_rows: Number of synthetic rows to generate
+        k_neighbors: Number of nearest neighbors (default: 5)
+        seed: Random seed for reproducibility
+        **params: Additional parameters (reserved for future use)
+        
+    Returns:
+        Dictionary mapping column names to generated values
+        
+    Raises:
+        ValidationError: If parameters invalid
+        AugmentError: If generation fails
+    """
+    try:
+        return apply_smote_strategy(
+            df_polars,
+            columns,
+            n_rows,
+            k_neighbors,
+            seed
+        )
+    
+    except Exception as e:
+        if isinstance(e, (ValidationError, AugmentError)):
+            raise
+        raise AugmentError(f"SMOTE generation failed: {e}")