oscura 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

oscura/visualization/annotations.py

@@ -1,371 +0,0 @@
-"""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
-
-from oscura.utils.geometry import generate_leader_line
-
-
-@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 and limit annotations
-    visible_annots = _filter_by_viewport(annotations, viewport)
-    visible_annots = _apply_density_limit(visible_annots, density_limit)
-
-    # Initialize placement
-    placed = _initialize_placements(visible_annots)
-
-    # Resolve collisions
-    _resolve_collisions(placed, collision_threshold, max_iterations)
-
-    # Add leader lines where needed
-    _add_leader_lines(placed, leader_threshold=30.0)
-
-    return placed
-
-
-def _filter_by_viewport(
-    annotations: list[Annotation],
-    viewport: tuple[float, float] | None,
-) -> list[Annotation]:
-    """Filter annotations by viewport range."""
-    if viewport is None:
-        return annotations
-
-    x_min, x_max = viewport
-    return [a for a in annotations if x_min <= a.x <= x_max]
-
-
-def _apply_density_limit(
-    annotations: list[Annotation],
-    density_limit: int,
-) -> list[Annotation]:
-    """Apply density limiting by keeping top priority annotations."""
-    if len(annotations) <= density_limit:
-        return annotations
-
-    sorted_annots = sorted(annotations, key=lambda a: a.priority, reverse=True)
-    return sorted_annots[:density_limit]
-
-
-def _initialize_placements(annotations: list[Annotation]) -> list[PlacedAnnotation]:
-    """Initialize placed annotations at anchor points."""
-    return [
-        PlacedAnnotation(
-            annotation=annot,
-            display_x=annot.x,
-            display_y=annot.y,
-            visible=True,
-            needs_leader=False,
-        )
-        for annot in annotations
-    ]
-
-
-def _resolve_collisions(
-    placed: list[PlacedAnnotation],
-    collision_threshold: float,
-    max_iterations: int,
-) -> None:
-    """Resolve collisions using iterative adjustment."""
-    for _iteration in range(max_iterations):
-        moved = False
-
-        for i in range(len(placed)):
-            for j in range(i + 1, len(placed)):
-                if _check_collision(placed[i], placed[j], collision_threshold):
-                    # Move 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
-
-        if not moved:
-            break
-
-
-def _add_leader_lines(placed: list[PlacedAnnotation], leader_threshold: float) -> None:
-    """Add leader lines for displaced annotations."""
-    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),
-            )
-
-
-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 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

@@ -1,305 +0,0 @@
-"""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",
-]