photo-stack-finder 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

utils/plot_helpers.py

@@ -1,123 +1,123 @@
-"""Plotting utilities for benchmark analysis and visualization.
-
-This module provides standardized plotting functions that encapsulate
-matplotlib configuration and boilerplate, ensuring consistent visualization
-across the codebase.
-
-All functions save plots directly to files rather than displaying them,
-making them suitable for automated analysis pipelines.
-"""
-
-from pathlib import Path
-
-import matplotlib.pyplot as plt
-import numpy as np
-import pandas as pd
-from numpy.typing import NDArray
-
-
-def save_histogram_comparison(
-    pos_data: NDArray[np.float64],
-    neg_data: NDArray[np.float64],
-    threshold: float,
-    method_name: str,
-    output_path: Path,
-) -> None:
-    """Generate and save a histogram comparing similar/dissimilar distributions.
-
-    Creates overlaid histograms showing the distribution of scores for
-    similar pairs (pos_data) and dissimilar pairs (neg_data), with a
-    vertical line indicating the decision threshold.
-
-    Args:
-        pos_data: Scores for similar pairs (positive class)
-        neg_data: Scores for dissimilar pairs (negative class)
-        threshold: Decision threshold to display as vertical line
-        method_name: Name of the comparison method (for plot title)
-        output_path: Path where the plot should be saved
-
-    Note:
-        Uses 50 bins and 50% transparency for overlapping histograms.
-        The plot is saved and closed automatically.
-    """
-    plt.figure(figsize=(10, 6))
-    plt.hist(pos_data, bins=50, alpha=0.5, label="Similar", color="green")
-    plt.hist(neg_data, bins=50, alpha=0.5, label="Dissimilar", color="red")
-    plt.axvline(threshold, color="black", linestyle="--", label="Threshold")
-    plt.xlabel("Score")
-    plt.ylabel("Frequency")
-    plt.title(f"{method_name} - Score Distribution")
-    plt.legend()
-    plt.tight_layout()
-    plt.savefig(output_path)
-    plt.close()
-
-
-def save_correlation_heatmap(
-    corr_matrix: pd.DataFrame,
-    output_path: Path,
-) -> None:
-    """Generate and save a correlation heatmap for method comparison.
-
-    Creates a heatmap showing correlation coefficients between different
-    comparison methods, using a diverging colormap centered at zero.
-
-    Args:
-        corr_matrix: Square correlation matrix (DataFrame with method names as index/columns)
-        output_path: Path where the plot should be saved
-
-    Note:
-        Uses 'coolwarm' colormap with values clamped to [-1, 1] range.
-        Correlation values are annotated on the heatmap.
-    """
-    plt.figure(figsize=(12, 10))
-    plt.imshow(corr_matrix, cmap="coolwarm", vmin=-1, vmax=1, aspect="auto")
-    plt.colorbar(label="Correlation")
-    plt.xticks(range(len(corr_matrix.columns)), list(corr_matrix.columns), rotation=90)
-    plt.yticks(range(len(corr_matrix.index)), list(corr_matrix.index))
-    plt.title("Method Correlation Matrix")
-
-    # Annotate correlation values
-    for i in range(len(corr_matrix.index)):
-        for j in range(len(corr_matrix.columns)):
-            value = corr_matrix.iloc[i, j]
-            plt.text(j, i, f"{value:.2f}", ha="center", va="center", color="black")
-
-    plt.tight_layout()
-    plt.savefig(output_path)
-    plt.close()
-
-
-def save_pca_scatter(
-    x_pca: NDArray[np.float64],
-    y_true: NDArray[np.int_],
-    explained_variance: list[float],
-    output_path: Path,
-) -> None:
-    """Generate and save a PCA scatter plot with class coloring.
-
-    Creates a 2D scatter plot of the first two principal components,
-    with points colored by their true class labels.
-
-    Args:
-        x_pca: PCA-transformed coordinates (n_samples x n_components, uses first 2)
-        y_true: True class labels (0 for dissimilar, 1 for similar)
-        explained_variance: Variance explained by each principal component (uses first 2)
-        output_path: Path where the plot should be saved
-
-    Note:
-        Axis labels include the percentage of variance explained.
-        Similar pairs are shown in green, dissimilar in red.
-    """
-    plt.figure(figsize=(10, 8))
-    for label, color, name in [(1, "green", "Similar"), (0, "red", "Dissimilar")]:
-        mask = y_true == label
-        plt.scatter(x_pca[mask, 0], x_pca[mask, 1], c=color, label=name, alpha=0.5)
-
-    plt.xlabel(f"PC1 ({explained_variance[0]:.1%} variance)")
-    plt.ylabel(f"PC2 ({explained_variance[1]:.1%} variance)")
-    plt.title("PCA: Method Scores by True Label")
-    plt.legend()
-    plt.tight_layout()
-    plt.savefig(output_path)
-    plt.close()
+"""Plotting utilities for benchmark analysis and visualization.
+
+This module provides standardized plotting functions that encapsulate
+matplotlib configuration and boilerplate, ensuring consistent visualization
+across the codebase.
+
+All functions save plots directly to files rather than displaying them,
+making them suitable for automated analysis pipelines.
+"""
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from numpy.typing import NDArray
+
+
+def save_histogram_comparison(
+    pos_data: NDArray[np.float64],
+    neg_data: NDArray[np.float64],
+    threshold: float,
+    method_name: str,
+    output_path: Path,
+) -> None:
+    """Generate and save a histogram comparing similar/dissimilar distributions.
+
+    Creates overlaid histograms showing the distribution of scores for
+    similar pairs (pos_data) and dissimilar pairs (neg_data), with a
+    vertical line indicating the decision threshold.
+
+    Args:
+        pos_data: Scores for similar pairs (positive class)
+        neg_data: Scores for dissimilar pairs (negative class)
+        threshold: Decision threshold to display as vertical line
+        method_name: Name of the comparison method (for plot title)
+        output_path: Path where the plot should be saved
+
+    Note:
+        Uses 50 bins and 50% transparency for overlapping histograms.
+        The plot is saved and closed automatically.
+    """
+    plt.figure(figsize=(10, 6))
+    plt.hist(pos_data, bins=50, alpha=0.5, label="Similar", color="green")
+    plt.hist(neg_data, bins=50, alpha=0.5, label="Dissimilar", color="red")
+    plt.axvline(threshold, color="black", linestyle="--", label="Threshold")
+    plt.xlabel("Score")
+    plt.ylabel("Frequency")
+    plt.title(f"{method_name} - Score Distribution")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(output_path)
+    plt.close()
+
+
+def save_correlation_heatmap(
+    corr_matrix: pd.DataFrame,
+    output_path: Path,
+) -> None:
+    """Generate and save a correlation heatmap for method comparison.
+
+    Creates a heatmap showing correlation coefficients between different
+    comparison methods, using a diverging colormap centered at zero.
+
+    Args:
+        corr_matrix: Square correlation matrix (DataFrame with method names as index/columns)
+        output_path: Path where the plot should be saved
+
+    Note:
+        Uses 'coolwarm' colormap with values clamped to [-1, 1] range.
+        Correlation values are annotated on the heatmap.
+    """
+    plt.figure(figsize=(12, 10))
+    plt.imshow(corr_matrix, cmap="coolwarm", vmin=-1, vmax=1, aspect="auto")
+    plt.colorbar(label="Correlation")
+    plt.xticks(range(len(corr_matrix.columns)), list(corr_matrix.columns), rotation=90)
+    plt.yticks(range(len(corr_matrix.index)), list(corr_matrix.index))
+    plt.title("Method Correlation Matrix")
+
+    # Annotate correlation values
+    for i in range(len(corr_matrix.index)):
+        for j in range(len(corr_matrix.columns)):
+            value = corr_matrix.iloc[i, j]
+            plt.text(j, i, f"{value:.2f}", ha="center", va="center", color="black")
+
+    plt.tight_layout()
+    plt.savefig(output_path)
+    plt.close()
+
+
+def save_pca_scatter(
+    x_pca: NDArray[np.float64],
+    y_true: NDArray[np.int_],
+    explained_variance: list[float],
+    output_path: Path,
+) -> None:
+    """Generate and save a PCA scatter plot with class coloring.
+
+    Creates a 2D scatter plot of the first two principal components,
+    with points colored by their true class labels.
+
+    Args:
+        x_pca: PCA-transformed coordinates (n_samples x n_components, uses first 2)
+        y_true: True class labels (0 for dissimilar, 1 for similar)
+        explained_variance: Variance explained by each principal component (uses first 2)
+        output_path: Path where the plot should be saved
+
+    Note:
+        Axis labels include the percentage of variance explained.
+        Similar pairs are shown in green, dissimilar in red.
+    """
+    plt.figure(figsize=(10, 8))
+    for label, color, name in [(1, "green", "Similar"), (0, "red", "Dissimilar")]:
+        mask = y_true == label
+        plt.scatter(x_pca[mask, 0], x_pca[mask, 1], c=color, label=name, alpha=0.5)
+
+    plt.xlabel(f"PC1 ({explained_variance[0]:.1%} variance)")
+    plt.ylabel(f"PC2 ({explained_variance[1]:.1%} variance)")
+    plt.title("PCA: Method Scores by True Label")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(output_path)
+    plt.close()

utils/ports.py

@@ -1,136 +1,136 @@
-"""Port-based pipeline connectivity inspired by SystemC/Verilog.
-
-This module provides typed input/output ports for pipeline stages, enabling:
-- Type-safe connections between stages
-- Dependency tracking through timestamps
-- Decoupling stages from each other and from storage details
-
-Architecture:
-- InputPort: Typed input on a stage (like sc_in<T> in SystemC)
-- OutputPort: Typed output on a stage (like sc_out<T> in SystemC)
-- Ports connect stages without exposing cache paths or implementation
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TypeVar
-
-from .base_ports import BaseInputPort, BaseOutputPort, StageProtocol
-
-T = TypeVar("T")
-
-
-class OutputPort[T](BaseOutputPort):
-    """Typed output port on a pipeline stage.
-
-    An output port provides read access to a stage's output data.
-    Multiple consumers can read from the same output port.
-
-    The port uses a getter callback provided by the stage to access data.
-    The port itself has no storage - it delegates to the stage's getter.
-
-    Type parameter T specifies the data type this port produces,
-    enabling compile-time type checking of connections.
-
-    Analogous to: sc_out<T> in SystemC, output wire in Verilog
-    """
-
-    def __init__(
-        self,
-        owner: StageProtocol,
-        getter: Callable[[], T],
-    ):
-        """Initialize output port.
-
-        Args:
-            owner: The stage that produces this output (used for timestamps)
-            getter: Callable that returns the output data when called.
-                    Typically a lambda like: lambda: self.result
-                    or lambda: self.result['bins'] for partial data.
-                    The getter is called each time read() is invoked.
-
-        Example:
-            # Simple case - return entire result
-            self.output_o = OutputPort(self, lambda: self.result)
-
-            # Multiple ports exposing different parts
-            self.bins_o = OutputPort(self, lambda: self.sha_bins)
-            self.forest_o = OutputPort(self, lambda: self.forest)
-        """
-        super().__init__(owner)
-        self.getter = getter
-
-    def read(self) -> T:
-        """Read output data from owning stage.
-
-        Calls the getter callback to retrieve the current output data.
-
-        Returns:
-            Output data of type T
-
-        Raises:
-            Exception: If getter fails (e.g., stage hasn't run yet)
-        """
-        return self.getter()
-
-
-class InputPort[T](BaseInputPort):
-    """Typed input port on a pipeline stage.
-
-    An input port represents a dependency on another stage's output.
-    It provides read access to upstream data without knowing which
-    stage produces it or where it's stored.
-
-    The port must be bound to an OutputPort before use. The binding
-    enforces type compatibility through Generic[T].
-
-    Type parameter T specifies the data type this port consumes,
-    matching the OutputPort[T] it connects to.
-
-    Analogous to: sc_in<T> in SystemC, input wire in Verilog
-    """
-
-    def __init__(self, name: str):
-        """Initialize input port.
-
-        Args:
-            name: Descriptive name for this input (e.g., "sha_bins", "forest")
-        """
-        super().__init__(name)
-        self._source: OutputPort[T] | None = None
-
-    def bind(self, source: OutputPort[T]) -> None:
-        """Bind this input to an output port.
-
-        This connects the input to its data source. The Generic[T] type
-        parameter ensures type compatibility at compile time.
-
-        Args:
-            source: The output port to read from
-
-        Example:
-            stage.forest_input.bind(prev_stage.forest_output)
-        """
-        self._source = source
-
-    def read(self) -> T:
-        """Read data from connected output port.
-
-        Returns:
-            Data of type T from the bound output port
-
-        Raises:
-            RuntimeError: If port is not bound to a source
-        """
-        if self._source is None:
-            raise RuntimeError(f"Input port '{self.name}' is not bound to any source")
-        return self._source.read()
-
-    def is_bound(self) -> bool:
-        """Check if this input is connected to a source.
-
-        Returns:
-            True if bind() has been called, False otherwise
-        """
-        return self._source is not None
+"""Port-based pipeline connectivity inspired by SystemC/Verilog.
+
+This module provides typed input/output ports for pipeline stages, enabling:
+- Type-safe connections between stages
+- Dependency tracking through timestamps
+- Decoupling stages from each other and from storage details
+
+Architecture:
+- InputPort: Typed input on a stage (like sc_in<T> in SystemC)
+- OutputPort: Typed output on a stage (like sc_out<T> in SystemC)
+- Ports connect stages without exposing cache paths or implementation
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from .base_ports import BaseInputPort, BaseOutputPort, StageProtocol
+
+T = TypeVar("T")
+
+
+class OutputPort[T](BaseOutputPort):
+    """Typed output port on a pipeline stage.
+
+    An output port provides read access to a stage's output data.
+    Multiple consumers can read from the same output port.
+
+    The port uses a getter callback provided by the stage to access data.
+    The port itself has no storage - it delegates to the stage's getter.
+
+    Type parameter T specifies the data type this port produces,
+    enabling compile-time type checking of connections.
+
+    Analogous to: sc_out<T> in SystemC, output wire in Verilog
+    """
+
+    def __init__(
+        self,
+        owner: StageProtocol,
+        getter: Callable[[], T],
+    ):
+        """Initialize output port.
+
+        Args:
+            owner: The stage that produces this output (used for timestamps)
+            getter: Callable that returns the output data when called.
+                    Typically a lambda like: lambda: self.result
+                    or lambda: self.result['bins'] for partial data.
+                    The getter is called each time read() is invoked.
+
+        Example:
+            # Simple case - return entire result
+            self.output_o = OutputPort(self, lambda: self.result)
+
+            # Multiple ports exposing different parts
+            self.bins_o = OutputPort(self, lambda: self.sha_bins)
+            self.forest_o = OutputPort(self, lambda: self.forest)
+        """
+        super().__init__(owner)
+        self.getter = getter
+
+    def read(self) -> T:
+        """Read output data from owning stage.
+
+        Calls the getter callback to retrieve the current output data.
+
+        Returns:
+            Output data of type T
+
+        Raises:
+            Exception: If getter fails (e.g., stage hasn't run yet)
+        """
+        return self.getter()
+
+
+class InputPort[T](BaseInputPort):
+    """Typed input port on a pipeline stage.
+
+    An input port represents a dependency on another stage's output.
+    It provides read access to upstream data without knowing which
+    stage produces it or where it's stored.
+
+    The port must be bound to an OutputPort before use. The binding
+    enforces type compatibility through Generic[T].
+
+    Type parameter T specifies the data type this port consumes,
+    matching the OutputPort[T] it connects to.
+
+    Analogous to: sc_in<T> in SystemC, input wire in Verilog
+    """
+
+    def __init__(self, name: str):
+        """Initialize input port.
+
+        Args:
+            name: Descriptive name for this input (e.g., "sha_bins", "forest")
+        """
+        super().__init__(name)
+        self._source: OutputPort[T] | None = None
+
+    def bind(self, source: OutputPort[T]) -> None:
+        """Bind this input to an output port.
+
+        This connects the input to its data source. The Generic[T] type
+        parameter ensures type compatibility at compile time.
+
+        Args:
+            source: The output port to read from
+
+        Example:
+            stage.forest_input.bind(prev_stage.forest_output)
+        """
+        self._source = source
+
+    def read(self) -> T:
+        """Read data from connected output port.
+
+        Returns:
+            Data of type T from the bound output port
+
+        Raises:
+            RuntimeError: If port is not bound to a source
+        """
+        if self._source is None:
+            raise RuntimeError(f"Input port '{self.name}' is not bound to any source")
+        return self._source.read()
+
+    def is_bound(self) -> bool:
+        """Check if this input is connected to a source.
+
+        Returns:
+            True if bind() has been called, False otherwise
+        """
+        return self._source is not None