oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/visualization/layout.py

@@ -21,6 +21,8 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
+from oscura.utils.geometry import generate_leader_line
+
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
@@ -165,53 +167,19 @@ def layout_stacked_channels(
     )
 
 
-def optimize_annotation_placement(
+def _initialize_placed_annotations(
     annotations: list[Annotation],
-    *,
-    display_width: float = 800.0,
-    display_height: float = 600.0,
-    max_iterations: int = 100,
-    repulsion_strength: float = 10.0,
-    min_spacing: float = 5.0,
 ) -> list[PlacedAnnotation]:
-    """Optimize annotation placement with collision avoidance.
-
-    Uses force-directed layout algorithm to separate overlapping labels
-    with repulsive forces. Generates leader lines when labels must be
-    displaced from anchor points.
+    """Initialize placed annotations at anchor points.
 
     Args:
         annotations: List of annotations to place.
-        display_width: Display area width in pixels.
-        display_height: Display area height in pixels.
-        max_iterations: Maximum iterations for force-directed layout.
-        repulsion_strength: Strength of repulsive force between overlapping labels.
-        min_spacing: Minimum spacing between annotations in pixels.
 
     Returns:
-        List of PlacedAnnotation with optimized positions.
-
-    Raises:
-        ValueError: If annotations list is empty.
-
-    Example:
-        >>> annots = [Annotation("Peak", 0.5, 1.0, priority=0.9)]
-        >>> placed = optimize_annotation_placement(annots)
-        >>> print(f"Needs leader: {placed[0].needs_leader}")
-
-    References:
-        VIS-016: Annotation Placement Intelligence
-        Force-directed graph layout (Fruchterman-Reingold)
+        List of PlacedAnnotation initially at anchor points.
     """
-    if len(annotations) == 0:
-        raise ValueError("annotations list cannot be empty")
-
-    # Convert annotations to display coordinates
-    # For now, assume data coordinates are normalized to display units
     placed = []
-
     for annot in annotations:
-        # Initial placement at anchor point
         placed.append(
             PlacedAnnotation(
                 annotation=annot,
@@ -221,84 +189,126 @@ def optimize_annotation_placement(
                 leader_points=None,
             )
         )
+    return placed
 
-    # Apply force-directed layout to resolve overlaps
-    for _iteration in range(max_iterations):
-        moved = False
-
-        # Calculate forces between all pairs
-        for i in range(len(placed)):
-            fx = 0.0
-            fy = 0.0
-
-            for j in range(len(placed)):
-                if i == j:
-                    continue
-
-                # Check for bounding box overlap
-                dx = placed[j].display_x - placed[i].display_x
-                dy = placed[j].display_y - placed[i].display_y
-
-                # Bounding box sizes
-                w1 = placed[i].annotation.bbox_width
-                h1 = placed[i].annotation.bbox_height
-                w2 = placed[j].annotation.bbox_width
-                h2 = placed[j].annotation.bbox_height
-
-                # Minimum separation (sum of half-widths + spacing)
-                min_dx = (w1 + w2) / 2 + min_spacing
-                min_dy = (h1 + h2) / 2 + min_spacing
-
-                # Check if overlapping
-                if abs(dx) < min_dx and abs(dy) < min_dy:
-                    # Calculate repulsive force
-                    distance = np.sqrt(dx**2 + dy**2)
-                    if distance < 1e-6:
-                        # Avoid division by zero
-                        distance = 1e-6
-                        dx = np.random.randn() * 0.1
-                        dy = np.random.randn() * 0.1
-
-                    # Repulsion inversely proportional to distance
-                    force = repulsion_strength / distance
-
-                    # Apply force in direction away from overlap
-                    fx -= force * dx / distance
-                    fy -= force * dy / distance
-
-            # Apply forces with damping (priority affects inertia)
-            damping = 0.5
-            priority_factor = 1.0 - placed[i].annotation.priority
-
-            # Higher priority annotations move less
-            step_size = damping * priority_factor
-
-            new_x = placed[i].display_x + fx * step_size
-            new_y = placed[i].display_y + fy * step_size
-
-            # Clamp to display bounds
-            new_x = np.clip(new_x, 0, display_width)
-            new_y = np.clip(new_y, 0, display_height)
-
-            # Update if moved significantly
-            if abs(new_x - placed[i].display_x) > 0.1 or abs(new_y - placed[i].display_y) > 0.1:
-                placed[i] = PlacedAnnotation(
-                    annotation=placed[i].annotation,
-                    display_x=new_x,
-                    display_y=new_y,
-                    needs_leader=False,
-                    leader_points=None,
+
+def _calculate_repulsive_force(
+    placed_i: PlacedAnnotation,
+    placed_j: PlacedAnnotation,
+    min_spacing: float,
+    repulsion_strength: float,
+) -> tuple[float, float]:
+    """Calculate repulsive force between two annotations.
+
+    Args:
+        placed_i: First annotation.
+        placed_j: Second annotation.
+        min_spacing: Minimum spacing in pixels.
+        repulsion_strength: Repulsive force strength.
+
+    Returns:
+        Tuple of (fx, fy) force components.
+    """
+    # Check for bounding box overlap
+    dx = placed_j.display_x - placed_i.display_x
+    dy = placed_j.display_y - placed_i.display_y
+
+    # Bounding box sizes
+    w1 = placed_i.annotation.bbox_width
+    h1 = placed_i.annotation.bbox_height
+    w2 = placed_j.annotation.bbox_width
+    h2 = placed_j.annotation.bbox_height
+
+    # Minimum separation (sum of half-widths + spacing)
+    min_dx = (w1 + w2) / 2 + min_spacing
+    min_dy = (h1 + h2) / 2 + min_spacing
+
+    # Check if overlapping
+    if abs(dx) < min_dx and abs(dy) < min_dy:
+        # Calculate repulsive force
+        distance = np.sqrt(dx**2 + dy**2)
+        if distance < 1e-6:
+            # Avoid division by zero
+            distance = 1e-6
+            dx = np.random.randn() * 0.1
+            dy = np.random.randn() * 0.1
+
+        # Repulsion inversely proportional to distance
+        force = repulsion_strength / distance
+
+        # Return force in direction away from overlap
+        return -force * dx / distance, -force * dy / distance
+
+    return 0.0, 0.0
+
+
+def _apply_force_iteration(
+    placed: list[PlacedAnnotation],
+    display_width: float,
+    display_height: float,
+    min_spacing: float,
+    repulsion_strength: float,
+) -> bool:
+    """Apply one iteration of force-directed layout.
+
+    Args:
+        placed: List of placed annotations to update.
+        display_width: Display width for clamping.
+        display_height: Display height for clamping.
+        min_spacing: Minimum spacing in pixels.
+        repulsion_strength: Repulsive force strength.
+
+    Returns:
+        True if any annotation moved significantly.
+    """
+    moved = False
+
+    for i in range(len(placed)):
+        fx = 0.0
+        fy = 0.0
+
+        # Calculate forces from all other annotations
+        for j in range(len(placed)):
+            if i != j:
+                force_x, force_y = _calculate_repulsive_force(
+                    placed[i], placed[j], min_spacing, repulsion_strength
                 )
-                moved = True
+                fx += force_x
+                fy += force_y
 
-        # Converged if nothing moved
-        if not moved:
-            break
+        # Apply forces with damping (priority affects inertia)
+        damping = 0.5
+        priority_factor = 1.0 - placed[i].annotation.priority
+        step_size = damping * priority_factor
 
-    # Determine which annotations need leader lines
-    # (displaced beyond threshold from original position)
-    leader_threshold = 20.0  # pixels
+        new_x = placed[i].display_x + fx * step_size
+        new_y = placed[i].display_y + fy * step_size
 
+        # Clamp to display bounds
+        new_x = np.clip(new_x, 0, display_width)
+        new_y = np.clip(new_y, 0, display_height)
+
+        # Update if moved significantly
+        if abs(new_x - placed[i].display_x) > 0.1 or abs(new_y - placed[i].display_y) > 0.1:
+            placed[i] = PlacedAnnotation(
+                annotation=placed[i].annotation,
+                display_x=new_x,
+                display_y=new_y,
+                needs_leader=False,
+                leader_points=None,
+            )
+            moved = True
+
+    return moved
+
+
+def _add_leader_lines(placed: list[PlacedAnnotation], leader_threshold: float = 20.0) -> None:
+    """Add leader lines to annotations displaced from anchor points.
+
+    Args:
+        placed: List of placed annotations to update in-place.
+        leader_threshold: Displacement threshold for leader line in pixels.
+    """
     for i, p in enumerate(placed):
         anchor_x = p.annotation.x
         anchor_y = p.annotation.y
@@ -307,7 +317,7 @@ def optimize_annotation_placement(
 
         if displacement > leader_threshold:
             # Generate simple orthogonal leader line
-            leader_points = _generate_leader_line(
+            leader_points = generate_leader_line(
                 (anchor_x, anchor_y),
                 (p.display_x, p.display_y),
             )
@@ -320,40 +330,65 @@ def optimize_annotation_placement(
                 leader_points=leader_points,
             )
 
-    return placed
 
+def optimize_annotation_placement(
+    annotations: list[Annotation],
+    *,
+    display_width: float = 800.0,
+    display_height: float = 600.0,
+    max_iterations: int = 100,
+    repulsion_strength: float = 10.0,
+    min_spacing: float = 5.0,
+) -> list[PlacedAnnotation]:
+    """Optimize annotation placement with collision avoidance.
 
-def _generate_leader_line(
-    anchor: tuple[float, float],
-    label: tuple[float, float],
-) -> list[tuple[float, float]]:
-    """Generate orthogonal leader line from anchor to label.
+    Uses force-directed layout algorithm to separate overlapping labels
+    with repulsive forces. Generates leader lines when labels must be
+    displaced from anchor points.
 
     Args:
-        anchor: Anchor point (x, y)
-        label: Label position (x, y)
+        annotations: List of annotations to place.
+        display_width: Display area width in pixels.
+        display_height: Display area height in pixels.
+        max_iterations: Maximum iterations for force-directed layout.
+        repulsion_strength: Strength of repulsive force between overlapping labels.
+        min_spacing: Minimum spacing between annotations in pixels.
 
     Returns:
-        List of points for leader line
+        List of PlacedAnnotation with optimized positions.
+
+    Raises:
+        ValueError: If annotations list is empty.
+
+    Example:
+        >>> annots = [Annotation("Peak", 0.5, 1.0, priority=0.9)]
+        >>> placed = optimize_annotation_placement(annots)
+        >>> print(f"Needs leader: {placed[0].needs_leader}")
+
+    References:
+        VIS-016: Annotation Placement Intelligence
+        Force-directed graph layout (Fruchterman-Reingold)
     """
-    ax, ay = anchor
-    lx, ly = label
+    if len(annotations) == 0:
+        raise ValueError("annotations list cannot be empty")
 
-    # Simple L-shaped leader: anchor -> midpoint -> label
-    # Choose horizontal-then-vertical or vertical-then-horizontal
-    # based on which dimension has larger displacement
+    # Data preparation - initialize at anchor points
+    placed = _initialize_placed_annotations(annotations)
 
-    dx = abs(lx - ax)
-    dy = abs(ly - ay)
+    # Force-directed layout iterations
+    for _iteration in range(max_iterations):
+        moved = _apply_force_iteration(
+            placed, display_width, display_height, min_spacing, repulsion_strength
+        )
+
+        # Converged if nothing moved
+        if not moved:
+            break
 
-    if dx > dy:
-        # Horizontal-first
-        mid = (lx, ay)
-    else:
-        # Vertical-first
-        mid = (ax, ly)
+    # Annotation - add leader lines for displaced annotations
+    _add_leader_lines(placed, leader_threshold=20.0)
 
-    return [anchor, mid, label]
+    return placed
 
 
 __all__ = [

oscura/visualization/optimization.py

@@ -65,37 +65,64 @@ def calculate_optimal_y_range(
     References:
         VIS-013: Auto Y-Axis Range Optimization
     """
+    clean_data = _validate_and_clean_data(data)
+    filtered_data = _filter_outliers(clean_data, outlier_threshold)
+    _check_clipping(clean_data, filtered_data, clip_warning_threshold)
+
+    # Calculate data range
+    data_min, data_max = float(np.min(filtered_data)), float(np.max(filtered_data))
+    margin = _select_smart_margin(len(filtered_data), margin_percent)
+
+    # Apply range mode
+    if symmetric:
+        return _symmetric_range(data_min, data_max, margin)
+    else:
+        return _asymmetric_range(data_min, data_max, margin)
+
+
+def _validate_and_clean_data(data: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Validate data and remove NaN values."""
     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")
 
-    # Use percentile-based outlier detection (1st-99th percentile default)
-    # This corresponds to approximately 3-sigma for normal distributions
-    lower_percentile = 0.5
-    upper_percentile = 99.5
+    return clean_data
 
-    # Calculate robust statistics using percentiles
-    np.percentile(clean_data, lower_percentile)
-    np.percentile(clean_data, upper_percentile)
 
-    # Filter outliers beyond threshold sigma
-    median = np.median(clean_data)
-    mad = np.median(np.abs(clean_data - median))
+def _filter_outliers(data: NDArray[np.float64], outlier_threshold: float) -> NDArray[np.float64]:
+    """Filter outliers using robust MAD-based z-scores.
+
+    Falls back to standard deviation when MAD = 0 (highly concentrated data).
+    """
+    median = np.median(data)
+    mad = np.median(np.abs(data - median))
     robust_std = 1.4826 * mad  # MAD to std conversion
 
     if robust_std > 0:
-        z_scores = np.abs(clean_data - median) / robust_std
-        inlier_mask = z_scores <= outlier_threshold
-        filtered_data = clean_data[inlier_mask]
-    else:
-        filtered_data = clean_data
-
-    # Detect clipping
+        z_scores = np.abs(data - median) / robust_std
+        filtered: NDArray[np.float64] = data[z_scores <= outlier_threshold]
+        return filtered
+
+    # Fallback to standard deviation when MAD = 0
+    mean = np.mean(data)
+    std = np.std(data)
+    if std > 0:
+        z_scores = np.abs(data - mean) / std
+        filtered = data[z_scores <= outlier_threshold]
+        return filtered
+
+    return data
+
+
+def _check_clipping(
+    clean_data: NDArray[np.float64],
+    filtered_data: NDArray[np.float64],
+    clip_warning_threshold: float,
+) -> None:
+    """Check and warn if too many samples are clipped."""
     clipped_fraction = 1.0 - (len(filtered_data) / len(clean_data))
     if clipped_fraction > clip_warning_threshold:
         import warnings
@@ -107,34 +134,49 @@ def calculate_optimal_y_range(
             stacklevel=2,
         )
 
-    # Calculate data range
-    data_min = np.min(filtered_data)
-    data_max = np.max(filtered_data)
-    data_range = data_max - data_min
 
-    # Smart margin selection based on data density
-    if len(filtered_data) > 10000:
-        # Dense data: smaller margin (2%)
-        margin = 0.02
-    elif len(filtered_data) < 100:
-        # Sparse data: larger margin (10%)
-        margin = 0.10
-    else:
-        # Default margin (5%)
-        margin = margin_percent / 100.0
+def _select_smart_margin(n_samples: int, margin_percent: float) -> float:
+    """Select margin based on data density.
 
-    # Apply symmetric range mode for bipolar signals
-    if symmetric:
-        max_abs = max(abs(data_min), abs(data_max))
-        margin_value = max_abs * margin
-        y_min = -(max_abs + margin_value)
-        y_max = max_abs + margin_value
-    else:
-        margin_value = data_range * margin
-        y_min = data_min - margin_value
-        y_max = data_max + margin_value
+    Only applies smart margin when using default value (5.0%).
+    Otherwise respects user's explicit margin_percent.
+    """
+    # Always respect explicit user values (non-default)
+    if margin_percent != 5.0:
+        return margin_percent / 100.0
+
+    # Apply smart margin only for default value
+    if n_samples > 10000:
+        return 0.02  # Dense data: smaller margin
+    elif n_samples < 100:
+        return 0.10  # Sparse data: larger margin
+    return margin_percent / 100.0
+
+
+def _symmetric_range(data_min: float, data_max: float, margin: float) -> tuple[float, float]:
+    """Calculate symmetric range for bipolar signals."""
+    max_abs = max(abs(data_min), abs(data_max))
+
+    # Handle constant data
+    if max_abs == 0:
+        return (-0.5, 0.5)  # Default range for constant zero
 
-    return (float(y_min), float(y_max))
+    margin_value = max_abs * margin
+    return (-(max_abs + margin_value), max_abs + margin_value)
+
+
+def _asymmetric_range(data_min: float, data_max: float, margin: float) -> tuple[float, float]:
+    """Calculate asymmetric range."""
+    data_range = data_max - data_min
+
+    # Handle constant data (range = 0)
+    if data_range == 0:
+        # Add fixed margin for constant data
+        default_margin = 0.5 if data_min == 0 else abs(data_min) * 0.1
+        return (data_min - default_margin, data_max + default_margin)
+
+    margin_value = data_range * margin
+    return (data_min - margin_value, data_max + margin_value)
 
 
 def calculate_optimal_x_window(
@@ -188,8 +230,10 @@ def calculate_optimal_x_window(
     active_regions = rms > rms_threshold
 
     if not np.any(active_regions):
-        # No significant activity, return full range
-        return (float(time[0]), float(time[-1]))
+        # No significant activity, return padded full range
+        time_range = time[-1] - time[0]
+        padding = time_range * 0.05  # 5% padding on each side
+        return (float(time[0] - padding), float(time[-1] + padding))
 
     # Find first active region
     active_indices = np.where(active_regions)[0]
@@ -215,21 +259,29 @@ def calculate_optimal_x_window(
 
         if len(crossings) >= 4:
             # Estimate period from crossings (two crossings per cycle)
+            # crossings[::2] already gives full periods (every other crossing)
             periods = np.diff(crossings[::2])
             if len(periods) > 0:
                 median_period = np.median(periods)
-                samples_per_feature = int(median_period * 2)  # Full cycle
+                samples_per_feature = int(median_period)  # Already full cycle from [::2]
 
                 # Calculate window to show target_features
                 total_samples = samples_per_feature * target_features
+
+                # Respect decimation constraint
+                max_window_samples = int(screen_width * samples_per_pixel)
+                total_samples = min(total_samples, max_window_samples)
+
                 window_start = first_active
                 window_end = min(window_start + total_samples, len(time) - 1)
 
                 return (float(time[window_start]), float(time[window_end]))
 
-    # Fallback: zoom to first N% of active region
+    # Fallback: zoom to respect decimation threshold
+    # Limit window to screen_width * samples_per_pixel samples
+    max_window_samples = int(screen_width * samples_per_pixel)
     active_duration = len(active_indices)
-    zoom_samples = min(active_duration, screen_width * int(samples_per_pixel))
+    zoom_samples = min(active_duration, max_window_samples)
     window_end = min(first_active + zoom_samples, len(time) - 1)
 
     return (float(time[first_active]), float(time[window_end]))
@@ -650,7 +702,7 @@ def detect_interesting_regions(
     edge_threshold: float | None = None,
     glitch_sigma: float = 3.0,
     anomaly_threshold: float = 3.0,
-    min_region_samples: int = 10,
+    min_region_samples: int = 1,
     max_regions: int = 10,
 ) -> list[InterestingRegion]:
     """Detect interesting regions in a signal for automatic zoom/focus.
@@ -664,7 +716,7 @@ def detect_interesting_regions(
         edge_threshold: Edge detection threshold (default: auto from signal stddev)
         glitch_sigma: Sigma threshold for glitch detection (default: 3.0)
         anomaly_threshold: Threshold for anomaly detection in sigma (default: 3.0)
-        min_region_samples: Minimum samples per region (default: 10)
+        min_region_samples: Minimum samples per region (default: 1)
         max_regions: Maximum number of regions to return (default: 10)
 
     Returns:
@@ -691,7 +743,6 @@ def detect_interesting_regions(
         raise ValueError("min_region_samples must be >= 1")
 
     regions: list[InterestingRegion] = []
-    1.0 / sample_rate
 
     # 1. Edge detection using first derivative
     edges = _detect_edges(signal, sample_rate, edge_threshold)

oscura/visualization/palettes.py

@@ -303,7 +303,7 @@ def show_palette(
             ax.set_xticklabels(["0", "0.25", "0.5", "0.75", "1.0"])
             ax.set_title(f"Colormap: {name}")
         except ValueError:
-            raise ValueError(f"Unknown palette or colormap: {name}")  # noqa: B904
+            raise ValueError(f"Unknown palette or colormap: {name}")
 
     plt.tight_layout()