oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/visualization/annotations.py

@@ -0,0 +1,374 @@
+"""Enhanced annotation placement with collision detection.
+
+This module provides intelligent annotation placement with collision avoidance,
+priority-based positioning, and dynamic hiding at different zoom levels.
+
+
+Example:
+    >>> from oscura.visualization.annotations import place_annotations
+    >>> placed = place_annotations(annotations, viewport=(0, 10), density_limit=20)
+
+References:
+    - Force-directed graph layout (Fruchterman-Reingold)
+    - Greedy placement with priority
+    - Leader line routing algorithms
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class Annotation:
+    """Annotation specification with position and metadata.
+
+    Attributes:
+        text: Annotation text
+        x: X coordinate in data units
+        y: Y coordinate in data units
+        bbox_width: Bounding box width in pixels
+        bbox_height: Bounding box height in pixels
+        priority: Priority for placement (0-1, higher is more important)
+        anchor: Preferred anchor position
+        metadata: Additional metadata
+    """
+
+    text: str
+    x: float
+    y: float
+    bbox_width: float = 60.0
+    bbox_height: float = 20.0
+    priority: float = 0.5
+    anchor: str = "auto"
+    metadata: dict | None = None  # type: ignore[type-arg]
+
+    def __post_init__(self):  # type: ignore[no-untyped-def]
+        if self.metadata is None:
+            self.metadata = {}
+
+
+@dataclass
+class PlacedAnnotation:
+    """Annotation with optimized placement and leader line.
+
+    Attributes:
+        annotation: Original annotation
+        display_x: Optimized X position in data units
+        display_y: Optimized Y position in data units
+        visible: Whether annotation is visible at current zoom
+        needs_leader: Whether a leader line is needed
+        leader_points: Points for leader line (if needed)
+    """
+
+    annotation: Annotation
+    display_x: float
+    display_y: float
+    visible: bool = True
+    needs_leader: bool = False
+    leader_points: list[tuple[float, float]] | None = None
+
+
+def place_annotations(
+    annotations: list[Annotation],
+    *,
+    viewport: tuple[float, float] | None = None,
+    density_limit: int = 20,
+    collision_threshold: float = 5.0,
+    max_iterations: int = 50,
+) -> list[PlacedAnnotation]:
+    """Place annotations with collision detection and density limiting.
+
+    Enhanced version with viewport-aware density limiting and dynamic hiding.
+
+    Args:
+        annotations: List of annotations to place.
+        viewport: Viewport range (x_min, x_max) for density calculation (None = all visible).
+        density_limit: Maximum annotations per viewport.
+        collision_threshold: Minimum spacing in pixels.
+        max_iterations: Maximum iterations for collision resolution.
+
+    Returns:
+        List of PlacedAnnotation with optimized positions.
+
+    Example:
+        >>> annots = [
+        ...     Annotation("Peak", 5.0, 1.0, priority=0.9),
+        ...     Annotation("Min", 3.0, -0.5, priority=0.7),
+        ... ]
+        >>> placed = place_annotations(annots, density_limit=10)
+
+    References:
+        VIS-016: Annotation Placement Intelligence (enhanced)
+    """
+    if len(annotations) == 0:
+        return []
+
+    # Filter by viewport if specified
+    if viewport is not None:
+        x_min, x_max = viewport
+        visible_annots = [a for a in annotations if x_min <= a.x <= x_max]
+    else:
+        visible_annots = annotations
+
+    # Apply density limiting - keep only top priority annotations
+    if len(visible_annots) > density_limit:
+        # Sort by priority (descending)
+        sorted_annots = sorted(
+            visible_annots,
+            key=lambda a: a.priority,
+            reverse=True,
+        )
+        visible_annots = sorted_annots[:density_limit]
+
+    # Initialize placed annotations at anchor points
+    placed = []
+    for annot in visible_annots:
+        placed.append(
+            PlacedAnnotation(
+                annotation=annot,
+                display_x=annot.x,
+                display_y=annot.y,
+                visible=True,
+                needs_leader=False,
+            )
+        )
+
+    # Resolve collisions using iterative adjustment
+    for _iteration in range(max_iterations):
+        moved = False
+
+        # Check all pairs for collisions
+        for i in range(len(placed)):
+            for j in range(i + 1, len(placed)):
+                if _check_collision(placed[i], placed[j], collision_threshold):
+                    # Resolve collision by moving lower-priority annotation
+                    if placed[i].annotation.priority >= placed[j].annotation.priority:
+                        moved = _move_annotation(placed[j], placed[i], collision_threshold) or moved
+                    else:
+                        moved = _move_annotation(placed[i], placed[j], collision_threshold) or moved
+
+        # Converged if nothing moved
+        if not moved:
+            break
+
+    # Determine which annotations need leader lines
+    leader_threshold = 30.0  # pixels
+
+    for p in placed:
+        dx = abs(p.display_x - p.annotation.x)
+        dy = abs(p.display_y - p.annotation.y)
+        displacement = np.sqrt(dx**2 + dy**2)
+
+        if displacement > leader_threshold:
+            p.needs_leader = True
+            p.leader_points = _generate_leader_line(
+                (p.annotation.x, p.annotation.y),
+                (p.display_x, p.display_y),
+            )
+
+    return placed
+
+
+def _check_collision(
+    p1: PlacedAnnotation,
+    p2: PlacedAnnotation,
+    threshold: float,
+) -> bool:
+    """Check if two annotations collide.
+
+    Args:
+        p1: First annotation
+        p2: Second annotation
+        threshold: Minimum spacing threshold
+
+    Returns:
+        True if annotations collide
+    """
+    # Bounding box collision detection
+    dx = abs(p2.display_x - p1.display_x)
+    dy = abs(p2.display_y - p1.display_y)
+
+    # Minimum separation (sum of half-widths + threshold)
+    min_dx = (p1.annotation.bbox_width + p2.annotation.bbox_width) / 2 + threshold
+    min_dy = (p1.annotation.bbox_height + p2.annotation.bbox_height) / 2 + threshold
+
+    return dx < min_dx and dy < min_dy
+
+
+def _move_annotation(
+    to_move: PlacedAnnotation,
+    fixed: PlacedAnnotation,
+    threshold: float,
+) -> bool:
+    """Move annotation away from collision.
+
+    Args:
+        to_move: Annotation to move
+        fixed: Fixed annotation to move away from
+        threshold: Minimum spacing
+
+    Returns:
+        True if annotation was moved
+    """
+    dx = to_move.display_x - fixed.display_x
+    dy = to_move.display_y - fixed.display_y
+
+    distance = np.sqrt(dx**2 + dy**2)
+
+    if distance < 1e-6:
+        # Randomize if overlapping exactly
+        dx = np.random.randn() * 10
+        dy = np.random.randn() * 10
+        distance = np.sqrt(dx**2 + dy**2)
+
+    # Required separation
+    min_dx = (to_move.annotation.bbox_width + fixed.annotation.bbox_width) / 2 + threshold
+    min_dy = (to_move.annotation.bbox_height + fixed.annotation.bbox_height) / 2 + threshold
+    min_dist = np.sqrt(min_dx**2 + min_dy**2)
+
+    # Move away if too close
+    if distance < min_dist:
+        # Move proportionally to required distance
+        scale = min_dist / distance
+        new_x = fixed.display_x + dx * scale
+        new_y = fixed.display_y + dy * scale
+
+        # Apply with damping to avoid oscillation
+        damping = 0.5
+        to_move.display_x += (new_x - to_move.display_x) * damping
+        to_move.display_y += (new_y - to_move.display_y) * damping
+
+        return True
+
+    return False
+
+
+def _generate_leader_line(
+    anchor: tuple[float, float],
+    label: tuple[float, float],
+) -> list[tuple[float, float]]:
+    """Generate orthogonal leader line from anchor to label.
+
+    Args:
+        anchor: Anchor point (x, y)
+        label: Label position (x, y)
+
+    Returns:
+        List of points for leader line
+    """
+    ax, ay = anchor
+    lx, ly = label
+
+    # L-shaped leader line
+    dx = abs(lx - ax)
+    dy = abs(ly - ay)
+
+    if dx > dy:
+        # Horizontal-first
+        mid = (lx, ay)
+    else:
+        # Vertical-first
+        mid = (ax, ly)
+
+    return [anchor, mid, label]
+
+
+def filter_by_zoom_level(
+    placed: list[PlacedAnnotation],
+    zoom_range: tuple[float, float],
+    *,
+    min_width_for_display: float = 0.1,
+) -> list[PlacedAnnotation]:
+    """Filter annotations based on zoom level.
+
+    Hide annotations when zoom range is too large for readability.
+
+    Args:
+        placed: List of placed annotations.
+        zoom_range: Current zoom range (x_min, x_max).
+        min_width_for_display: Minimum zoom width to display annotations.
+
+    Returns:
+        Filtered list with visibility updated.
+
+    Example:
+        >>> # Hide annotations when zoomed out too far
+        >>> filtered = filter_by_zoom_level(placed, (0, 1000), min_width_for_display=1.0)
+
+    References:
+        VIS-016: Annotation Placement Intelligence (dynamic hiding)
+    """
+    x_min, x_max = zoom_range
+    zoom_width = x_max - x_min
+
+    result = []
+    for p in placed:
+        # Update visibility based on zoom level
+        if zoom_width < min_width_for_display:
+            p.visible = True
+        else:
+            # Hide if outside viewport or too zoomed out
+            in_viewport = x_min <= p.annotation.x <= x_max
+            p.visible = in_viewport
+
+        result.append(p)
+
+    return result
+
+
+def create_priority_annotation(  # type: ignore[no-untyped-def]
+    text: str,
+    x: float,
+    y: float,
+    *,
+    importance: str = "normal",
+    **kwargs,
+) -> Annotation:
+    """Create annotation with priority based on importance level.
+
+    Args:
+        text: Annotation text.
+        x: X position in data units.
+        y: Y position in data units.
+        importance: Importance level ("critical", "high", "normal", "low").
+        **kwargs: Additional Annotation parameters.
+
+    Returns:
+        Annotation with appropriate priority.
+
+    Example:
+        >>> peak_annot = create_priority_annotation(
+        ...     "Critical Peak", 5.0, 1.0, importance="critical"
+        ... )
+
+    References:
+        VIS-016: Annotation Placement Intelligence (priority-based positioning)
+    """
+    priority_map = {
+        "critical": 1.0,
+        "high": 0.8,
+        "normal": 0.5,
+        "low": 0.2,
+    }
+
+    priority = priority_map.get(importance, 0.5)
+
+    return Annotation(
+        text=text,
+        x=x,
+        y=y,
+        priority=priority,
+        **kwargs,
+    )
+
+
+__all__ = [
+    "Annotation",
+    "PlacedAnnotation",
+    "create_priority_annotation",
+    "filter_by_zoom_level",
+    "place_annotations",
+]

oscura/visualization/axis_scaling.py

@@ -0,0 +1,305 @@
+"""Intelligent axis scaling and range optimization.
+
+This module provides enhanced Y-axis scaling with nice number rounding,
+outlier exclusion, and per-channel scaling for multi-channel plots.
+
+
+Example:
+    >>> from oscura.visualization.axis_scaling import calculate_axis_limits
+    >>> y_min, y_max = calculate_axis_limits(signal, nice_numbers=True)
+
+References:
+    - Wilkinson's tick placement algorithm
+    - Percentile-based outlier detection
+    - IEEE publication best practices
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def calculate_axis_limits(
+    data: NDArray[np.float64],
+    *,
+    nice_numbers: bool = True,
+    outlier_percentile: float = 1.0,
+    margin_percent: float = 5.0,
+    symmetric: bool = False,
+    zero_centered: bool = False,
+) -> tuple[float, float]:
+    """Calculate optimal axis limits with nice number rounding.
+
+    Enhanced version with nice number rounding for publication-quality plots.
+
+    Args:
+        data: Signal data array.
+        nice_numbers: Round limits to nice numbers (1, 2, 5 × 10^n).  # noqa: RUF002
+        outlier_percentile: Percentile for outlier exclusion (default 1% each side).
+        margin_percent: Margin as percentage of data range (default 5%).
+        symmetric: Use symmetric range ±max for bipolar signals.
+        zero_centered: Force zero to be centered in range.
+
+    Returns:
+        Tuple of (y_min, y_max) with nice rounded values.
+
+    Raises:
+        ValueError: If data is empty or all NaN.
+
+    Example:
+        >>> signal = np.array([1.234, 5.678, 9.012])
+        >>> y_min, y_max = calculate_axis_limits(signal, nice_numbers=True)
+        >>> # Returns nice values like (0.0, 10.0) instead of (1.234, 9.012)
+
+    References:
+        VIS-013: Auto Y-Axis Range Optimization
+        Wilkinson (1999): The Grammar of Graphics
+    """
+    if len(data) == 0:
+        raise ValueError("Data array is empty")
+
+    # Remove NaN values
+    clean_data = data[~np.isnan(data)]
+
+    if len(clean_data) == 0:
+        raise ValueError("Data contains only NaN values")
+
+    # Exclude outliers using percentiles
+    lower_pct = outlier_percentile
+    upper_pct = 100.0 - outlier_percentile
+
+    data_min = np.percentile(clean_data, lower_pct)
+    data_max = np.percentile(clean_data, upper_pct)
+    data_range = data_max - data_min
+
+    # Apply margin
+    margin = margin_percent / 100.0
+    margin_value = data_range * margin
+
+    if symmetric:
+        # Symmetric range: ±max
+        max_abs = max(abs(data_min), abs(data_max))
+        y_min = -(max_abs + margin_value)
+        y_max = max_abs + margin_value
+    elif zero_centered:
+        # Force zero to be centered
+        max_extent = max(abs(data_min), abs(data_max)) + margin_value
+        y_min = -max_extent
+        y_max = max_extent
+    else:
+        # Asymmetric range
+        y_min = data_min - margin_value
+        y_max = data_max + margin_value
+
+    # Round to nice numbers if requested
+    if nice_numbers:
+        y_min = _round_to_nice_number(y_min, direction="down")
+        y_max = _round_to_nice_number(y_max, direction="up")
+
+    return (float(y_min), float(y_max))
+
+
+def calculate_multi_channel_limits(  # type: ignore[no-untyped-def]
+    channels: list[NDArray[np.float64]],
+    *,
+    mode: Literal["per_channel", "common", "grouped"] = "per_channel",
+    nice_numbers: bool = True,
+    **kwargs,
+) -> list[tuple[float, float]]:
+    """Calculate axis limits for multiple channels.
+
+    Args:
+        channels: List of channel data arrays.
+        mode: Scaling mode:
+            - "per_channel": Independent ranges per channel
+            - "common": Single range for all channels
+            - "grouped": Group similar ranges
+        nice_numbers: Round to nice numbers.
+        **kwargs: Additional arguments passed to calculate_axis_limits.
+
+    Returns:
+        List of (y_min, y_max) tuples, one per channel.
+
+    Raises:
+        ValueError: If unknown mode specified.
+
+    Example:
+        >>> ch1 = np.array([0, 1, 2])
+        >>> ch2 = np.array([0, 10, 20])
+        >>> limits = calculate_multi_channel_limits([ch1, ch2], mode="per_channel")
+
+    References:
+        VIS-013: Auto Y-Axis Range Optimization (per-channel scaling)
+        VIS-015: Multi-Channel Stack Optimization
+    """
+    if len(channels) == 0:
+        return []
+
+    if mode == "per_channel":
+        # Independent ranges
+        return [calculate_axis_limits(ch, nice_numbers=nice_numbers, **kwargs) for ch in channels]
+
+    elif mode == "common":
+        # Single range for all channels
+        all_data = np.concatenate([ch for ch in channels if len(ch) > 0])
+        if len(all_data) == 0:
+            return [(0.0, 1.0)] * len(channels)
+
+        common_limits = calculate_axis_limits(all_data, nice_numbers=nice_numbers, **kwargs)
+        return [common_limits] * len(channels)
+
+    elif mode == "grouped":
+        # Group channels with similar ranges
+        # First calculate individual ranges
+        individual_limits = [
+            calculate_axis_limits(ch, nice_numbers=False, **kwargs) for ch in channels
+        ]
+
+        # Simple grouping: group by order of magnitude
+        grouped_limits = []
+        for y_min, y_max in individual_limits:
+            range_mag = np.log10(max(abs(y_max - y_min), 1e-10))
+            # Round to nearest integer magnitude
+            group_mag = int(np.round(range_mag))
+
+            # Use 10^group_mag as the range scale
+            scale = 10.0**group_mag
+
+            # Round to this scale
+            grouped_min = np.floor(y_min / scale) * scale
+            grouped_max = np.ceil(y_max / scale) * scale
+
+            if nice_numbers:
+                grouped_min = _round_to_nice_number(grouped_min, direction="down")
+                grouped_max = _round_to_nice_number(grouped_max, direction="up")
+
+            grouped_limits.append((float(grouped_min), float(grouped_max)))
+
+        return grouped_limits
+
+    else:
+        raise ValueError(f"Unknown mode: {mode}")
+
+
+def _round_to_nice_number(
+    value: float,
+    *,
+    direction: Literal["up", "down", "nearest"] = "nearest",
+) -> float:
+    """Round value to nice number (1, 2, 5 × 10^n).  # noqa: RUF002
+
+    Args:
+        value: Value to round.
+        direction: Rounding direction ("up", "down", "nearest").
+
+    Returns:
+        Rounded nice number.
+
+    Example:
+        >>> _round_to_nice_number(3.7, direction="up")
+        5.0
+        >>> _round_to_nice_number(3.7, direction="down")
+        2.0
+        >>> _round_to_nice_number(0.037, direction="up")
+        0.05
+    """
+    if value == 0:
+        return 0.0
+
+    # Determine sign
+    sign = 1 if value >= 0 else -1
+    abs_value = abs(value)
+
+    # Find exponent
+    exponent = np.floor(np.log10(abs_value))
+    mantissa = abs_value / (10**exponent)
+
+    # Round mantissa to nice fraction (1, 2, 5)
+    nice_fractions = [1.0, 2.0, 5.0, 10.0]
+
+    if direction == "up":
+        # Find smallest nice fraction >= mantissa
+        nice_mantissa = next((f for f in nice_fractions if f >= mantissa), 10.0)
+    elif direction == "down":
+        # Find largest nice fraction <= mantissa
+        nice_mantissa = 1.0
+        for f in nice_fractions:
+            if f <= mantissa:
+                nice_mantissa = f
+            else:
+                break
+    else:  # nearest
+        # Find closest nice fraction
+        distances = [abs(f - mantissa) for f in nice_fractions]
+        min_idx = np.argmin(distances)
+        nice_mantissa = nice_fractions[min_idx]
+
+    # Handle mantissa = 10 case (move to next exponent)
+    if nice_mantissa >= 10.0:
+        nice_mantissa = 1.0
+        exponent += 1
+
+    return sign * nice_mantissa * (10**exponent)  # type: ignore[no-any-return]
+
+
+def suggest_tick_spacing(
+    y_min: float,
+    y_max: float,
+    *,
+    target_ticks: int = 5,
+    minor_ticks: bool = True,
+) -> tuple[float, float]:
+    """Suggest tick spacing for axis.
+
+    Args:
+        y_min: Minimum axis value.
+        y_max: Maximum axis value.
+        target_ticks: Target number of major ticks.
+        minor_ticks: Generate minor tick spacing.
+
+    Returns:
+        Tuple of (major_spacing, minor_spacing).
+
+    Example:
+        >>> major, minor = suggest_tick_spacing(0, 10, target_ticks=5)
+        >>> # Returns (2.0, 0.5) for nice tick marks at 0, 2, 4, 6, 8, 10
+
+    References:
+        VIS-019: Grid Auto-Spacing
+    """
+    axis_range = y_max - y_min
+
+    if axis_range <= 0:
+        return (1.0, 0.2)
+
+    # Calculate rough spacing
+    rough_spacing = axis_range / target_ticks
+
+    # Round to nice number
+    major_spacing = _round_to_nice_number(rough_spacing, direction="nearest")
+
+    # Minor spacing: 1/5 of major for most cases
+    if minor_ticks:
+        # Use 1/5 for multiples of 5, 1/4 for multiples of 2, 1/2 otherwise
+        if major_spacing % 5 == 0:
+            minor_spacing = major_spacing / 5
+        elif major_spacing % 2 == 0:
+            minor_spacing = major_spacing / 4
+        else:
+            minor_spacing = major_spacing / 2
+    else:
+        minor_spacing = major_spacing
+
+    return (float(major_spacing), float(minor_spacing))
+
+
+__all__ = [
+    "calculate_axis_limits",
+    "calculate_multi_channel_limits",
+    "suggest_tick_spacing",
+]