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

additory/synthetic/smote.py

@@ -1,320 +0,0 @@
-"""
-SMOTE (Synthetic Minority Over-sampling Technique) for Synthetic Data Generation
-
-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}")