additory 0.1.0a2__py3-none-any.whl → 0.1.0a3__py3-none-any.whl

additory/synthetic/column_name_resolver.py

@@ -0,0 +1,149 @@
+"""
+Column Name Resolver for Linked Lists
+
+Resolves column names for linked lists using priority order:
+1. Column_Names row (explicit names)
+2. Underscore parsing from list name
+3. Fallback to {strategy_key}_1, {strategy_key}_2, etc.
+"""
+
+from typing import List, Optional
+import warnings
+
+
+def parse_column_names_from_underscores(list_name: str) -> Optional[List[str]]:
+    """
+    Parse column names from list name using underscore delimiters.
+    
+    Args:
+        list_name: Name of the list variable (e.g., "AE_CM_SEV")
+        
+    Returns:
+        List of column names, or None if no underscores found
+        
+    Examples:
+        >>> parse_column_names_from_underscores("AE_CM_SEV")
+        ['AE', 'CM', 'SEV']
+        
+        >>> parse_column_names_from_underscores("adverse_event_medication")
+        ['adverse', 'event', 'medication']
+        
+        >>> parse_column_names_from_underscores("adverseconmed")
+        None
+    """
+    if '_' not in list_name:
+        return None
+    
+    parts = list_name.split('_')
+    
+    # Filter out empty parts
+    column_names = [part for part in parts if part]
+    
+    if not column_names:
+        return None
+    
+    return column_names
+
+
+def generate_fallback_column_names(strategy_key: str, num_columns: int) -> List[str]:
+    """
+    Generate fallback column names when no other naming strategy works.
+    
+    Format: {strategy_key}_1, {strategy_key}_2, etc.
+    
+    Args:
+        strategy_key: Key from strategy dict (e.g., "col1")
+        num_columns: Number of columns to generate names for
+        
+    Returns:
+        List of column names
+        
+    Examples:
+        >>> generate_fallback_column_names("col1", 3)
+        ['col1_1', 'col1_2', 'col1_3']
+        
+        >>> generate_fallback_column_names("adverse_events", 2)
+        ['adverse_events_1', 'adverse_events_2']
+    """
+    return [f"{strategy_key}_{i+1}" for i in range(num_columns)]
+
+
+def resolve_column_names(
+    list_name: str,
+    strategy_key: str,
+    num_columns: int,
+    explicit_names: Optional[List[str]] = None
+) -> List[str]:
+    """
+    Resolve column names using priority order.
+    
+    Priority:
+    1. explicit_names (from Column_Names row)
+    2. Underscore parsing from list_name
+    3. Fallback to {strategy_key}_1, {strategy_key}_2, etc.
+    
+    Args:
+        list_name: Name of the list variable
+        strategy_key: Key from strategy dict
+        num_columns: Number of columns to generate
+        explicit_names: Explicit column names from Column_Names row (optional)
+        
+    Returns:
+        List of column names
+        
+    Raises:
+        ValueError: If explicit_names count doesn't match num_columns
+        
+    Examples:
+        >>> # Priority 1: Explicit names
+        >>> resolve_column_names("AE_CM", "col1", 2, ["adverse_event", "medication"])
+        ['adverse_event', 'medication']
+        
+        >>> # Priority 2: Underscore parsing
+        >>> resolve_column_names("AE_CM_SEV", "col1", 3)
+        ['AE', 'CM', 'SEV']
+        
+        >>> # Priority 3: Fallback
+        >>> resolve_column_names("adverseconmed", "col1", 2)
+        ['col1_1', 'col1_2']
+    """
+    # Priority 1: Explicit names from Column_Names row
+    if explicit_names is not None:
+        if len(explicit_names) != num_columns:
+            raise ValueError(
+                f"Column_Names row has {len(explicit_names)} names but "
+                f"linked list generates {num_columns} columns. They must match."
+            )
+        return explicit_names
+    
+    # Priority 2: Underscore parsing
+    parsed_names = parse_column_names_from_underscores(list_name)
+    if parsed_names is not None:
+        if len(parsed_names) == num_columns:
+            return parsed_names
+        else:
+            # Underscore count doesn't match - fall through to fallback
+            warnings.warn(
+                f"List name '{list_name}' has {len(parsed_names)} underscore-separated "
+                f"parts but generates {num_columns} columns. "
+                f"Using fallback naming: {strategy_key}_1, {strategy_key}_2, etc.\n"
+                f"Suggestion: Use a list name with {num_columns-1} underscores, "
+                f"or add a Column_Names row for explicit naming.",
+                UserWarning
+            )
+    else:
+        # No underscores - emit warning
+        warnings.warn(
+            f"List name '{list_name}' has no underscores. "
+            f"Using fallback naming: {strategy_key}_1, {strategy_key}_2, etc.\n"
+            f"Suggestion: Use underscore-delimited naming (e.g., 'AE_CM_SEV') "
+            f"or add a Column_Names row:\n"
+            f"  {list_name} = [\n"
+            f"      ['Column_Names:[col1,col2,col3]'],\n"
+            f"      ['primary', ['attr1'], ['attr2']]\n"
+            f"  ]",
+            UserWarning
+        )
+    
+    # Priority 3: Fallback
+    return generate_fallback_column_names(strategy_key, num_columns)

additory/{augment → synthetic}/distributions.py

@@ -1,5 +1,5 @@
 """
-Distribution Strategies for Data Augmentation
+Distribution Strategies for Synthetic Data Generation
 
 DEPRECATED: This module has been moved to additory.common.distributions
 Please update your imports to use additory.common.distributions instead.
@@ -11,7 +11,7 @@ import warnings
 
 # Issue deprecation warning
 warnings.warn(
-    "additory.augment.distributions is deprecated. "
+    "additory.synthetic.distributions is deprecated. "
     "Please use additory.common.distributions instead. "
     "This module will be removed in a future version.",
     DeprecationWarning,

additory/{augment → synthetic}/forecast.py

@@ -1,5 +1,5 @@
 """
-Forecast Strategies for Data Augmentation
+Forecast Strategies for Synthetic Data Generation
 
 Provides time series forecasting capabilities:
 - Linear trend forecasting

additory/synthetic/linked_list_parser.py

@@ -0,0 +1,415 @@
+"""
+Linked List Parser for Synthetic Data Generation
+
+Parses linked lists with optional special rows:
+- Column_Names:[name1,name2,name3] - Explicit column names
+- Regex:[pattern1], Regex:[pattern2], ... - Regex patterns for testing
+
+Generates cartesian product of primary key pattern:
+[primary_key, [attr1_values], [attr2_values], ...]
+"""
+
+from itertools import product
+from typing import List, Tuple, Optional, Dict, Any
+import re
+import random
+import string
+
+from additory.common.exceptions import ValidationError
+
+
+def parse_column_names_row(row: List[str]) -> Optional[List[str]]:
+    """
+    Parse Column_Names row to extract explicit column names.
+    
+    Format: ["Column_Names:[name1,name2,name3]"]
+    
+    Args:
+        row: First element should start with "Column_Names:"
+        
+    Returns:
+        List of column names, or None if not a Column_Names row
+        
+    Examples:
+        >>> parse_column_names_row(["Column_Names:[AE,CM,SEV]"])
+        ['AE', 'CM', 'SEV']
+        
+        >>> parse_column_names_row(["Column_Names:[adverse_event,medication]"])
+        ['adverse_event', 'medication']
+    """
+    if not row or not isinstance(row[0], str):
+        return None
+    
+    first_elem = row[0].strip()
+    if not first_elem.startswith("Column_Names:"):
+        return None
+    
+    # Extract content between brackets: "Column_Names:[AE,CM,SEV]" -> "AE,CM,SEV"
+    match = re.search(r'Column_Names:\[([^\]]+)\]', first_elem)
+    if not match:
+        raise ValidationError(
+            f"Invalid Column_Names format: '{first_elem}'. "
+            "Expected format: 'Column_Names:[name1,name2,name3]'"
+        )
+    
+    names_str = match.group(1)
+    column_names = [name.strip() for name in names_str.split(',')]
+    
+    if not column_names or any(not name for name in column_names):
+        raise ValidationError(
+            f"Column names cannot be empty. Got: {column_names}"
+        )
+    
+    return column_names
+
+
+def parse_regex_row(row: List[str]) -> Optional[List[str]]:
+    """
+    Parse Regex row to extract regex patterns.
+    
+    Format: ["Regex:[A-Z]{3,10}", "Regex:[A-Za-z0-9]{8,50}", ...]
+    
+    Args:
+        row: List where elements may start with "Regex:"
+        
+    Returns:
+        List of regex patterns (without "Regex:" prefix), or None if not a Regex row
+        
+    Examples:
+        >>> parse_regex_row(["Regex:[A-Z]{3,10}", "Regex:[A-Za-z0-9]{8,50}"])
+        ['[A-Z]{3,10}', '[A-Za-z0-9]{8,50}']
+        
+        >>> parse_regex_row(["Headache", ["Aspirin"]])
+        None
+    """
+    if not row or not isinstance(row[0], str):
+        return None
+    
+    first_elem = row[0].strip()
+    if not first_elem.startswith("Regex:"):
+        return None
+    
+    # Extract patterns from all elements
+    patterns = []
+    for elem in row:
+        if isinstance(elem, str) and elem.strip().startswith("Regex:"):
+            pattern = elem.strip()[6:]  # Remove "Regex:" prefix
+            patterns.append(pattern)
+        else:
+            # Mixed row: some regex, some not
+            patterns.append(str(elem))
+    
+    return patterns
+
+
+def generate_from_regex(pattern: str, seed: Optional[int] = None) -> str:
+    """
+    Generate a string matching the regex pattern (simplified).
+    
+    Supports basic patterns:
+    - [A-Z]{n,m} - Uppercase letters
+    - [a-z]{n,m} - Lowercase letters
+    - [0-9]{n,m} or \\d{n,m} - Digits
+    - [A-Za-z0-9]{n,m} - Alphanumeric
+    
+    Args:
+        pattern: Regex pattern
+        seed: Random seed for reproducibility
+        
+    Returns:
+        Generated string matching pattern
+        
+    Examples:
+        >>> generate_from_regex('[A-Z]{3,10}', seed=42)
+        'ABCDEFGHIJ'
+        
+        >>> generate_from_regex('[0-9]{1,3}', seed=42)
+        '999'
+    """
+    if seed is not None:
+        random.seed(seed)
+    
+    # Parse pattern: [charset]{min,max}
+    match = re.match(r'\[([^\]]+)\]\{(\d+),(\d+)\}', pattern)
+    if not match:
+        # Fallback: return pattern as-is with marker
+        return f"REGEX_{pattern[:10]}"
+    
+    charset_def = match.group(1)
+    min_len = int(match.group(2))
+    max_len = int(match.group(3))
+    
+    # Determine character set
+    if charset_def == 'A-Z':
+        charset = string.ascii_uppercase
+    elif charset_def == 'a-z':
+        charset = string.ascii_lowercase
+    elif charset_def in ['0-9', '\\d']:
+        charset = string.digits
+    elif charset_def == 'A-Za-z':
+        charset = string.ascii_letters
+    elif charset_def == 'A-Za-z0-9':
+        charset = string.ascii_letters + string.digits
+    else:
+        # Fallback
+        charset = string.ascii_letters + string.digits
+    
+    # Generate max length string (for edge case testing)
+    length = max_len
+    return ''.join(random.choice(charset) for _ in range(length))
+
+
+def parse_data_rows(rows: List[List]) -> List[Tuple]:
+    """
+    Parse data rows in primary key format and generate cartesian product.
+    
+    Format: [primary_key, [attr1_values], [attr2_values], ...]
+    
+    Args:
+        rows: List of data rows
+        
+    Returns:
+        List of tuples representing all valid combinations
+        
+    Raises:
+        ValidationError: If row format is invalid
+        
+    Examples:
+        >>> rows = [
+        ...     ["Headache", ["Aspirin", "Ibuprofen"], ["mild", "moderate"]],
+        ...     ["Nausea", ["Ondansetron"], ["severe"]]
+        ... ]
+        >>> combinations = parse_data_rows(rows)
+        >>> len(combinations)
+        5
+        >>> combinations[0]
+        ('Headache', 'Aspirin', 'mild')
+    """
+    if not rows:
+        raise ValidationError("No data rows found in linked list")
+    
+    combinations = []
+    expected_length = None
+    
+    for i, row in enumerate(rows):
+        if not isinstance(row, list):
+            raise ValidationError(
+                f"Row {i+1} is not a list. Expected format: "
+                "[primary_key, [attr1_values], [attr2_values], ...]"
+            )
+        
+        if len(row) < 1:
+            raise ValidationError(f"Row {i+1} is empty")
+        
+        # Validate structure consistency (strict validation for MVP)
+        if expected_length is None:
+            expected_length = len(row)
+        elif len(row) != expected_length:
+            raise ValidationError(
+                f"Row {i+1} has {len(row)} elements, expected {expected_length}. "
+                "All data rows must have the same structure.\n"
+                f"Row {i+1}: {row}\n"
+                "Expected format: [primary_key, [attr1_values], [attr2_values], ...]"
+            )
+        
+        # Extract primary key and attribute lists
+        primary_key = row[0]
+        attribute_lists = row[1:]
+        
+        # Validate attribute lists
+        for j, attr_list in enumerate(attribute_lists):
+            if not isinstance(attr_list, list):
+                raise ValidationError(
+                    f"Row {i+1}, attribute {j+1} is not a list. "
+                    f"Got: {type(attr_list).__name__}. "
+                    "Expected format: [primary_key, [attr1_values], [attr2_values], ...]"
+                )
+            if len(attr_list) == 0:
+                raise ValidationError(
+                    f"Row {i+1}, attribute {j+1} is an empty list"
+                )
+        
+        # Generate cartesian product for this row
+        if attribute_lists:
+            for combination in product(*attribute_lists):
+                combinations.append((primary_key, *combination))
+        else:
+            # Only primary key, no attributes
+            combinations.append((primary_key,))
+    
+    return combinations
+
+
+def parse_linked_list(data: List) -> Dict[str, Any]:
+    """
+    Parse linked list with optional special rows.
+    
+    Special rows (order-independent):
+    - Column_Names:[name1,name2,name3]
+    - Regex:[pattern1], Regex:[pattern2], ...
+    
+    Args:
+        data: Linked list data
+        
+    Returns:
+        Dictionary with:
+        - column_names: List of column names (or None)
+        - has_regex: Boolean indicating if regex row present
+        - regex_patterns: List of regex patterns (or None)
+        - combinations: List of tuples (cartesian product)
+        - num_columns: Number of columns to generate
+        
+    Raises:
+        ValidationError: If format is invalid
+        
+    Examples:
+        >>> data = [
+        ...     ["Column_Names:[AE,CM,SEV]"],
+        ...     ["Regex:[A-Z]{3,10}", "Regex:[A-Za-z0-9]{8,50}", "Regex:[0-9]{1,3}"],
+        ...     ["Headache", ["Aspirin"], ["mild"]]
+        ... ]
+        >>> result = parse_linked_list(data)
+        >>> result['column_names']
+        ['AE', 'CM', 'SEV']
+        >>> result['has_regex']
+        True
+        >>> len(result['combinations'])
+        1
+    """
+    if not data or not isinstance(data, list):
+        raise ValidationError(
+            "Linked list must be a non-empty list. "
+            "Expected format: [[primary_key, [attr1_values], ...], ...]"
+        )
+    
+    column_names = None
+    has_regex = False
+    regex_patterns = None
+    data_rows = []
+    
+    # Parse rows
+    for row in data:
+        if not isinstance(row, list):
+            raise ValidationError(
+                f"Each row must be a list. Got: {type(row).__name__}"
+            )
+        
+        # Check for Column_Names row
+        col_names = parse_column_names_row(row)
+        if col_names is not None:
+            if column_names is not None:
+                raise ValidationError(
+                    "Multiple Column_Names rows found. Only one is allowed."
+                )
+            column_names = col_names
+            continue
+        
+        # Check for Regex row
+        patterns = parse_regex_row(row)
+        if patterns is not None:
+            if has_regex:
+                raise ValidationError(
+                    "Multiple Regex rows found. Only one is allowed."
+                )
+            has_regex = True
+            regex_patterns = patterns
+            continue
+        
+        # Regular data row
+        data_rows.append(row)
+    
+    # Parse data rows to generate combinations
+    if not data_rows and not has_regex:
+        raise ValidationError(
+            "No data rows found. Linked list must contain at least one data row "
+            "or a Regex row."
+        )
+    
+    # Generate combinations from data rows
+    combinations = []
+    if data_rows:
+        combinations = parse_data_rows(data_rows)
+    
+    # Determine number of columns
+    if combinations:
+        num_columns = len(combinations[0])
+    elif regex_patterns:
+        num_columns = len(regex_patterns)
+    else:
+        raise ValidationError("Cannot determine number of columns")
+    
+    # Validate column names count if provided
+    if column_names and len(column_names) != num_columns:
+        raise ValidationError(
+            f"Column_Names row has {len(column_names)} names but data has "
+            f"{num_columns} columns. They must match."
+        )
+    
+    return {
+        'column_names': column_names,
+        'has_regex': has_regex,
+        'regex_patterns': regex_patterns,
+        'combinations': combinations,
+        'num_columns': num_columns
+    }
+
+
+def generate_linked_list_data(
+    parsed_data: Dict[str, Any],
+    n_rows: int,
+    seed: Optional[int] = None
+) -> List[Tuple]:
+    """
+    Generate data rows from parsed linked list.
+    
+    Handles three scenarios:
+    1. Both regex + data: First row regex, rest from combinations
+    2. Regex only: All rows regex
+    3. Data only: All rows from combinations
+    
+    Args:
+        parsed_data: Output from parse_linked_list()
+        n_rows: Number of rows to generate
+        seed: Random seed for reproducibility
+        
+    Returns:
+        List of tuples (one per row)
+        
+    Examples:
+        >>> parsed = parse_linked_list([["Headache", ["Aspirin"], ["mild"]]])
+        >>> rows = generate_linked_list_data(parsed, n_rows=3, seed=42)
+        >>> len(rows)
+        3
+        >>> rows[0]
+        ('Headache', 'Aspirin', 'mild')
+    """
+    if seed is not None:
+        random.seed(seed)
+    
+    has_regex = parsed_data['has_regex']
+    regex_patterns = parsed_data['regex_patterns']
+    combinations = parsed_data['combinations']
+    
+    results = []
+    
+    # Scenario 1 & 2: Regex present
+    if has_regex:
+        # Generate first row from regex
+        regex_row = tuple(generate_from_regex(pattern, seed) for pattern in regex_patterns)
+        results.append(regex_row)
+        n_rows -= 1
+        
+        # Scenario 2: Regex only (no combinations)
+        if not combinations:
+            # Generate all remaining rows from regex
+            for _ in range(n_rows):
+                regex_row = tuple(generate_from_regex(pattern, seed) for pattern in regex_patterns)
+                results.append(regex_row)
+            return results
+    
+    # Scenario 1 & 3: Sample from combinations
+    if combinations:
+        for _ in range(n_rows):
+            results.append(random.choice(combinations))
+    
+    return results