lsurf 1.0.0__py3-none-any.whl

lsurf/analysis/sphere_viz.py

@@ -0,0 +1,1280 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Sphere Visualization - Mollweide Projections and Time Analysis
+
+Functions for visualizing ray patterns on spherical detection surfaces
+using Mollweide projections and time distribution analysis.
+"""
+
+import matplotlib.gridspec as gridspec
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.colors import LogNorm
+
+try:
+    from astropy import units as u
+    from astropy_healpix import HEALPix
+
+    HAS_HEALPIX = True
+except ImportError:
+    HAS_HEALPIX = False
+
+
+def plot_mollweide_intensity(
+    healpix_data,
+    output_path: str | None = None,
+    log_scale: bool = True,
+    cmap: str = "hot",
+    title: str | None = None,
+    show_aggregated: bool = False,
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot intensity distribution on Mollweide projection.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    output_path : str, optional
+        If provided, save figure to this path
+    log_scale : bool, optional
+        Use logarithmic color scale (default: True)
+    cmap : str, optional
+        Matplotlib colormap (default: 'hot')
+    title : str, optional
+        Figure title
+    show_aggregated : bool, optional
+        If True and aggregated data exists, show per-pixel aggregated intensities
+        If False, show individual ray scatter plot (default: False)
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    fig = plt.figure(figsize=(14, 7))
+    ax = fig.add_subplot(111, projection="mollweide")
+
+    if show_aggregated and healpix_data.aggregated is not None:
+        # Plot aggregated per-pixel data
+        pixel_ids = healpix_data.aggregated["pixel_ids"]
+        intensity_sum = healpix_data.aggregated["intensity_sum"]
+
+        # Get pixel centers
+        hp = HEALPix(nside=healpix_data.nside, order="ring", frame=None)
+        lon, lat = hp.healpix_to_lonlat(pixel_ids)
+
+        # Convert to radians and wrap longitude
+        lon_rad = lon.to(u.rad).value
+        lat_rad = lat.to(u.rad).value
+
+        # Wrap longitude to [-π, π] for Mollweide
+        lon_rad = np.where(lon_rad > np.pi, lon_rad - 2 * np.pi, lon_rad)
+
+        # Plot
+        if log_scale and np.any(intensity_sum > 0):
+            norm = LogNorm(
+                vmin=intensity_sum[intensity_sum > 0].min(), vmax=intensity_sum.max()
+            )
+            scatter = ax.scatter(
+                lon_rad, lat_rad, c=intensity_sum, cmap=cmap, s=5, alpha=0.8, norm=norm
+            )
+        else:
+            scatter = ax.scatter(
+                lon_rad, lat_rad, c=intensity_sum, cmap=cmap, s=5, alpha=0.8
+            )
+
+        cbar_label = "Summed Intensity per Pixel"
+
+    else:
+        # Plot individual rays
+        lon_rad = healpix_data.lon.copy()
+        lat_rad = healpix_data.lat.copy()
+        intensities = healpix_data.intensities
+
+        # Wrap longitude to [-π, π]
+        lon_rad = np.where(lon_rad > np.pi, lon_rad - 2 * np.pi, lon_rad)
+
+        # Plot
+        if log_scale and np.any(intensities > 0):
+            norm = LogNorm(
+                vmin=intensities[intensities > 0].min(), vmax=intensities.max()
+            )
+            scatter = ax.scatter(
+                lon_rad, lat_rad, c=intensities, cmap=cmap, s=2, alpha=0.6, norm=norm
+            )
+        else:
+            scatter = ax.scatter(
+                lon_rad, lat_rad, c=intensities, cmap=cmap, s=2, alpha=0.6
+            )
+
+        cbar_label = "Ray Intensity"
+
+    # Colorbar
+    cbar = plt.colorbar(scatter, ax=ax, pad=0.1, shrink=0.8)
+    if log_scale:
+        cbar_label += " (log scale)"
+    cbar.set_label(cbar_label, fontsize=12)
+
+    # Labels
+    ax.set_xlabel("Azimuth (longitude)", fontsize=12)
+    ax.set_ylabel("Elevation (latitude)", fontsize=12)
+
+    if title is None:
+        title = f"Intensity Distribution on Detection Sphere (N={healpix_data.num_rays:,} rays)"
+    ax.set_title(title, fontsize=14, pad=20)
+
+    ax.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_mollweide_time(
+    healpix_data,
+    output_path: str | None = None,
+    cmap: str = "viridis",
+    title: str | None = None,
+    show_aggregated: bool = False,
+    time_units: str = "us",
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot arrival time distribution on Mollweide projection.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    output_path : str, optional
+        If provided, save figure to this path
+    cmap : str, optional
+        Matplotlib colormap (default: 'viridis')
+    title : str, optional
+        Figure title
+    show_aggregated : bool, optional
+        If True, show per-pixel weighted mean time (default: False)
+    time_units : str, optional
+        Time units for display: 'us', 'ns', 's' (default: 'us')
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    # Convert time units
+    unit_scales = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    unit_labels = {"s": "s", "ms": "ms", "us": "μs", "ns": "ns"}
+    scale = unit_scales.get(time_units, 1e6)
+    label = unit_labels.get(time_units, "μs")
+
+    fig = plt.figure(figsize=(14, 7))
+    ax = fig.add_subplot(111, projection="mollweide")
+
+    if show_aggregated and healpix_data.aggregated is not None:
+        # Plot aggregated weighted mean time
+        pixel_ids = healpix_data.aggregated["pixel_ids"]
+        times = healpix_data.aggregated["time_weighted_mean"] * scale
+
+        # Get pixel centers
+        hp = HEALPix(nside=healpix_data.nside, order="ring", frame=None)
+        lon, lat = hp.healpix_to_lonlat(pixel_ids)
+
+        lon_rad = lon.to(u.rad).value
+        lat_rad = lat.to(u.rad).value
+        lon_rad = np.where(lon_rad > np.pi, lon_rad - 2 * np.pi, lon_rad)
+
+        scatter = ax.scatter(lon_rad, lat_rad, c=times, cmap=cmap, s=5, alpha=0.8)
+        cbar_label = f"Intensity-weighted Mean Time ({label})"
+
+    else:
+        # Plot individual ray times
+        lon_rad = healpix_data.lon.copy()
+        lat_rad = healpix_data.lat.copy()
+        times = healpix_data.times * scale
+
+        lon_rad = np.where(lon_rad > np.pi, lon_rad - 2 * np.pi, lon_rad)
+
+        scatter = ax.scatter(lon_rad, lat_rad, c=times, cmap=cmap, s=2, alpha=0.6)
+        cbar_label = f"Arrival Time ({label})"
+
+    # Colorbar
+    cbar = plt.colorbar(scatter, ax=ax, pad=0.1, shrink=0.8)
+    cbar.set_label(cbar_label, fontsize=12)
+
+    # Labels
+    ax.set_xlabel("Azimuth (longitude)", fontsize=12)
+    ax.set_ylabel("Elevation (latitude)", fontsize=12)
+
+    if title is None:
+        title = "Arrival Time Distribution on Detection Sphere"
+    ax.set_title(title, fontsize=14, pad=20)
+
+    ax.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_time_distributions(
+    healpix_data,
+    peak_mask: np.ndarray | None = None,
+    time_stats: dict | None = None,
+    peak_stats: dict | None = None,
+    output_path: str | None = None,
+    time_units: str = "us",
+    bins: int = 100,
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot arrival time distributions comparing all rays vs peak region.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    peak_mask : ndarray, optional
+        Boolean mask for rays in peak region
+    time_stats : dict, optional
+        Statistics for all rays
+    peak_stats : dict, optional
+        Statistics for peak region rays
+    output_path : str, optional
+        If provided, save figure to this path
+    time_units : str, optional
+        Time units: 'us', 'ns', 's' (default: 'us')
+    bins : int, optional
+        Number of histogram bins (default: 100)
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    unit_scales = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    unit_labels = {"s": "s", "ms": "ms", "us": "μs", "ns": "ns"}
+    scale = unit_scales.get(time_units, 1e6)
+    label = unit_labels.get(time_units, "μs")
+
+    fig = plt.figure(figsize=(16, 10))
+    gs = gridspec.GridSpec(2, 2, figure=fig, hspace=0.3, wspace=0.3)
+
+    # All times
+    all_times = healpix_data.times * scale
+    all_intensities = healpix_data.intensities
+
+    # Peak times (if mask provided)
+    if peak_mask is not None and np.any(peak_mask):
+        peak_times = healpix_data.times[peak_mask] * scale
+        peak_intensities = healpix_data.intensities[peak_mask]
+        has_peak = True
+    else:
+        has_peak = False
+
+    # =========================================================================
+    # 1. All rays histogram (intensity-weighted)
+    # =========================================================================
+    ax1 = fig.add_subplot(gs[0, 0])
+    ax1.hist(
+        all_times,
+        bins=bins,
+        weights=all_intensities,
+        color="steelblue",
+        alpha=0.7,
+        edgecolor="black",
+    )
+    ax1.set_xlabel(f"Arrival Time ({label})", fontsize=11)
+    ax1.set_ylabel("Intensity-weighted Count", fontsize=11)
+    ax1.set_title("All Rays - Time Distribution", fontsize=12)
+    ax1.grid(True, alpha=0.3)
+
+    if time_stats:
+        stats_text = f"Mean: {time_stats['mean_time']*scale:.2f} {label}\n"
+        stats_text += f"Std: {time_stats['std_time']*scale:.2f} {label}\n"
+        stats_text += f"FWHM: {time_stats['fwhm_time']*scale:.2f} {label}"
+        ax1.text(
+            0.02,
+            0.98,
+            stats_text,
+            transform=ax1.transAxes,
+            verticalalignment="top",
+            fontsize=9,
+            bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.5},
+        )
+
+    # =========================================================================
+    # 2. Peak region histogram (if available)
+    # =========================================================================
+    ax2 = fig.add_subplot(gs[0, 1])
+    if has_peak:
+        ax2.hist(
+            peak_times,
+            bins=bins,
+            weights=peak_intensities,
+            color="coral",
+            alpha=0.7,
+            edgecolor="black",
+        )
+        ax2.set_xlabel(f"Arrival Time ({label})", fontsize=11)
+        ax2.set_ylabel("Intensity-weighted Count", fontsize=11)
+        ax2.set_title("Peak Region - Time Distribution", fontsize=12)
+        ax2.grid(True, alpha=0.3)
+
+        if peak_stats:
+            stats_text = f"Mean: {peak_stats['mean_time']*scale:.2f} {label}\n"
+            stats_text += f"Std: {peak_stats['std_time']*scale:.2f} {label}\n"
+            stats_text += f"FWHM: {peak_stats['fwhm_time']*scale:.2f} {label}"
+            ax2.text(
+                0.02,
+                0.98,
+                stats_text,
+                transform=ax2.transAxes,
+                verticalalignment="top",
+                fontsize=9,
+                bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.5},
+            )
+    else:
+        ax2.text(
+            0.5,
+            0.5,
+            "No peak region defined",
+            transform=ax2.transAxes,
+            ha="center",
+            va="center",
+            fontsize=12,
+        )
+        ax2.set_title("Peak Region - Time Distribution", fontsize=12)
+
+    # =========================================================================
+    # 3. Comparison overlay
+    # =========================================================================
+    ax3 = fig.add_subplot(gs[1, 0])
+    ax3.hist(
+        all_times,
+        bins=bins,
+        weights=all_intensities,
+        color="steelblue",
+        alpha=0.5,
+        label="All rays",
+        edgecolor="black",
+    )
+    if has_peak:
+        ax3.hist(
+            peak_times,
+            bins=bins,
+            weights=peak_intensities,
+            color="coral",
+            alpha=0.5,
+            label="Peak region",
+            edgecolor="black",
+        )
+    ax3.set_xlabel(f"Arrival Time ({label})", fontsize=11)
+    ax3.set_ylabel("Intensity-weighted Count", fontsize=11)
+    ax3.set_title("Comparison: All vs Peak Region", fontsize=12)
+    ax3.legend(fontsize=10)
+    ax3.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 4. Statistics summary
+    # =========================================================================
+    ax4 = fig.add_subplot(gs[1, 1])
+    ax4.axis("off")
+
+    summary_text = "Time Distribution Statistics\n"
+    summary_text += "=" * 50 + "\n\n"
+
+    if time_stats:
+        summary_text += f"ALL RAYS (N={time_stats['num_rays']:,})\n"
+        summary_text += "-" * 50 + "\n"
+        summary_text += (
+            f"Mean time:     {time_stats['mean_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Median time:   {time_stats['median_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Std deviation: {time_stats['std_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"FWHM:          {time_stats['fwhm_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Time span:     {time_stats['time_span']*scale:>10.2f} {label}\n"
+        )
+        summary_text += f"Weighted mean: {time_stats['weighted_mean_time']*scale:>10.2f} {label}\n\n"
+
+    if peak_stats and has_peak:
+        summary_text += f"PEAK REGION (N={peak_stats['num_rays']:,})\n"
+        summary_text += "-" * 50 + "\n"
+        summary_text += (
+            f"Mean time:     {peak_stats['mean_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Median time:   {peak_stats['median_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Std deviation: {peak_stats['std_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"FWHM:          {peak_stats['fwhm_time']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Time span:     {peak_stats['time_span']*scale:>10.2f} {label}\n"
+        )
+        summary_text += (
+            f"Weighted mean: {peak_stats['weighted_mean_time']*scale:>10.2f} {label}\n"
+        )
+
+    ax4.text(
+        0.1,
+        0.9,
+        summary_text,
+        transform=ax4.transAxes,
+        verticalalignment="top",
+        fontsize=10,
+        fontfamily="monospace",
+        bbox={"boxstyle": "round", "facecolor": "lightblue", "alpha": 0.3},
+    )
+
+    plt.suptitle("Arrival Time Analysis", fontsize=14, y=0.98)
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_combined_analysis(
+    healpix_data,
+    peak_mask: np.ndarray | None = None,
+    time_stats: dict | None = None,
+    peak_stats: dict | None = None,
+    output_path: str | None = None,
+    log_scale: bool = True,
+    time_units: str = "us",
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Create comprehensive multi-panel analysis figure.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    peak_mask : ndarray, optional
+        Boolean mask for peak region rays
+    time_stats : dict, optional
+        Statistics for all rays
+    peak_stats : dict, optional
+        Statistics for peak region
+    output_path : str, optional
+        If provided, save figure to this path
+    log_scale : bool, optional
+        Use log scale for intensity (default: True)
+    time_units : str, optional
+        Time units (default: 'us')
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    unit_scales = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    unit_labels = {"s": "s", "ms": "ms", "us": "μs", "ns": "ns"}
+    scale = unit_scales.get(time_units, 1e6)
+    label = unit_labels.get(time_units, "μs")
+
+    fig = plt.figure(figsize=(18, 12))
+    gs = gridspec.GridSpec(
+        3, 2, figure=fig, hspace=0.35, wspace=0.25, height_ratios=[1.2, 1, 1]
+    )
+
+    # =========================================================================
+    # 1. Intensity map (Mollweide)
+    # =========================================================================
+    ax1 = fig.add_subplot(gs[0, :], projection="mollweide")
+
+    lon_rad = healpix_data.lon.copy()
+    lat_rad = healpix_data.lat.copy()
+    intensities = healpix_data.intensities
+
+    lon_rad = np.where(lon_rad > np.pi, lon_rad - 2 * np.pi, lon_rad)
+
+    if log_scale and np.any(intensities > 0):
+        norm = LogNorm(vmin=intensities[intensities > 0].min(), vmax=intensities.max())
+        scatter1 = ax1.scatter(
+            lon_rad, lat_rad, c=intensities, cmap="hot", s=2, alpha=0.6, norm=norm
+        )
+        cbar_label = "Ray Intensity (log scale)"
+    else:
+        scatter1 = ax1.scatter(
+            lon_rad, lat_rad, c=intensities, cmap="hot", s=2, alpha=0.6
+        )
+        cbar_label = "Ray Intensity"
+
+    cbar1 = plt.colorbar(scatter1, ax=ax1, pad=0.05, shrink=0.6, aspect=20)
+    cbar1.set_label(cbar_label, fontsize=10)
+
+    ax1.set_xlabel("Azimuth", fontsize=11)
+    ax1.set_ylabel("Elevation", fontsize=11)
+    ax1.set_title(
+        f"Intensity Distribution (N={healpix_data.num_rays:,} rays)",
+        fontsize=12,
+        pad=15,
+    )
+    ax1.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 2. Time map (Mollweide)
+    # =========================================================================
+    ax2 = fig.add_subplot(gs[1, :], projection="mollweide")
+
+    times = healpix_data.times * scale
+    scatter2 = ax2.scatter(lon_rad, lat_rad, c=times, cmap="viridis", s=2, alpha=0.6)
+
+    cbar2 = plt.colorbar(scatter2, ax=ax2, pad=0.05, shrink=0.6, aspect=20)
+    cbar2.set_label(f"Arrival Time ({label})", fontsize=10)
+
+    ax2.set_xlabel("Azimuth", fontsize=11)
+    ax2.set_ylabel("Elevation", fontsize=11)
+    ax2.set_title("Arrival Time Distribution", fontsize=12, pad=15)
+    ax2.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 3. Time histogram - All rays
+    # =========================================================================
+    ax3 = fig.add_subplot(gs[2, 0])
+
+    all_times = healpix_data.times * scale
+    all_intensities = healpix_data.intensities
+
+    ax3.hist(
+        all_times,
+        bins=80,
+        weights=all_intensities,
+        color="steelblue",
+        alpha=0.7,
+        edgecolor="black",
+    )
+    ax3.set_xlabel(f"Arrival Time ({label})", fontsize=10)
+    ax3.set_ylabel("Intensity-weighted Count", fontsize=10)
+    ax3.set_title("All Rays - Time Distribution", fontsize=11)
+    ax3.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 4. Time histogram - Peak region
+    # =========================================================================
+    ax4 = fig.add_subplot(gs[2, 1])
+
+    if peak_mask is not None and np.any(peak_mask):
+        peak_times = healpix_data.times[peak_mask] * scale
+        peak_intensities = healpix_data.intensities[peak_mask]
+
+        ax4.hist(
+            peak_times,
+            bins=80,
+            weights=peak_intensities,
+            color="coral",
+            alpha=0.7,
+            edgecolor="black",
+        )
+        ax4.set_xlabel(f"Arrival Time ({label})", fontsize=10)
+        ax4.set_ylabel("Intensity-weighted Count", fontsize=10)
+        ax4.set_title("Peak Region - Time Distribution", fontsize=11)
+        ax4.grid(True, alpha=0.3)
+
+        if peak_stats:
+            stats_text = f"N={peak_stats['num_rays']:,}\n"
+            stats_text += f"Mean: {peak_stats['mean_time']*scale:.2f} {label}\n"
+            stats_text += f"FWHM: {peak_stats['fwhm_time']*scale:.2f} {label}"
+            ax4.text(
+                0.98,
+                0.98,
+                stats_text,
+                transform=ax4.transAxes,
+                verticalalignment="top",
+                horizontalalignment="right",
+                fontsize=9,
+                bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.5},
+            )
+    else:
+        ax4.text(
+            0.5,
+            0.5,
+            "No peak region defined",
+            transform=ax4.transAxes,
+            ha="center",
+            va="center",
+            fontsize=11,
+        )
+        ax4.set_title("Peak Region - Time Distribution", fontsize=11)
+
+    plt.suptitle("Sphere Intersection Pattern Analysis", fontsize=16, y=0.995)
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_2d_intensity(
+    healpix_data,
+    output_path: str | None = None,
+    log_scale: bool = True,
+    cmap: str = "hot",
+    title: str | None = None,
+    plot_type: str = "profile",
+    gridsize: int = 50,
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot intensity distribution vs elevation angle (1D profile).
+
+    Shows intensity as a function of elevation angle, suitable for
+    tightly clustered ray patterns.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    output_path : str, optional
+        If provided, save figure to this path
+    log_scale : bool, optional
+        Use logarithmic y-axis scale (default: True)
+    cmap : str, optional
+        Matplotlib colormap (default: 'hot')
+    title : str, optional
+        Figure title
+    plot_type : str, optional
+        'profile' for elevation profile, 'hexbin' for 2D, 'scatter' for 2D scatter (default: 'profile')
+    gridsize : int, optional
+        Number of bins for elevation profile (default: 50)
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    fig, ax = plt.subplots(figsize=(12, 8))
+
+    # Convert to degrees for easier reading
+    elevation_deg = np.degrees(healpix_data.lat)
+    intensities = healpix_data.intensities
+
+    if plot_type == "profile":
+        # 1D profile: elevation angle vs intensity
+        # Bin by elevation and sum intensities
+        hist, bin_edges = np.histogram(
+            elevation_deg, bins=gridsize, weights=intensities
+        )
+        bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
+
+        ax.plot(bin_centers, hist, "o-", color="steelblue", linewidth=2, markersize=4)
+        ax.fill_between(bin_centers, 0, hist, alpha=0.3, color="steelblue")
+
+        ax.set_xlabel("Elevation (degrees)", fontsize=12)
+        ax.set_ylabel("Intensity", fontsize=12)
+
+        if log_scale and np.any(hist > 0):
+            ax.set_yscale("log")
+
+        ax.grid(True, alpha=0.3)
+
+    else:
+        # Fall back to 2D plots
+        azimuth_deg = np.degrees(healpix_data.lon)
+
+        if plot_type == "hexbin":
+            # Hexagonal binning
+            if log_scale and np.any(intensities > 0):
+                hb = ax.hexbin(
+                    azimuth_deg,
+                    elevation_deg,
+                    C=intensities,
+                    gridsize=gridsize,
+                    cmap=cmap,
+                    reduce_C_function=np.sum,
+                    norm=LogNorm(
+                        vmin=intensities[intensities > 0].min(),
+                        vmax=intensities.max(),
+                    ),
+                    mincnt=1,
+                )
+            else:
+                hb = ax.hexbin(
+                    azimuth_deg,
+                    elevation_deg,
+                    C=intensities,
+                    gridsize=gridsize,
+                    cmap=cmap,
+                    reduce_C_function=np.sum,
+                    mincnt=1,
+                )
+
+            cbar = plt.colorbar(hb, ax=ax)
+            cbar_label = "Summed Intensity per Bin"
+            if log_scale:
+                cbar_label += " (log scale)"
+            cbar.set_label(cbar_label, fontsize=12)
+
+            ax.set_xlabel("Azimuth (degrees)", fontsize=12)
+            ax.set_ylabel("Elevation (degrees)", fontsize=12)
+
+        else:
+            # Scatter plot
+            if log_scale and np.any(intensities > 0):
+                norm = LogNorm(
+                    vmin=intensities[intensities > 0].min(), vmax=intensities.max()
+                )
+                scatter = ax.scatter(
+                    azimuth_deg,
+                    elevation_deg,
+                    c=intensities,
+                    cmap=cmap,
+                    s=5,
+                    alpha=0.6,
+                    norm=norm,
+                )
+            else:
+                scatter = ax.scatter(
+                    azimuth_deg,
+                    elevation_deg,
+                    c=intensities,
+                    cmap=cmap,
+                    s=5,
+                    alpha=0.6,
+                )
+
+            cbar = plt.colorbar(scatter, ax=ax)
+            cbar_label = "Ray Intensity"
+            if log_scale:
+                cbar_label += " (log scale)"
+            cbar.set_label(cbar_label, fontsize=12)
+
+            ax.set_xlabel("Azimuth (degrees)", fontsize=12)
+            ax.set_ylabel("Elevation (degrees)", fontsize=12)
+
+    if title is None:
+        title = f"Intensity Distribution (N={healpix_data.num_rays:,} rays)"
+    ax.set_title(title, fontsize=14)
+
+    plt.tight_layout()
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_viewing_angle_intensity(
+    healpix_data,
+    output_path: str | None = None,
+    log_scale: bool = True,
+    title: str | None = None,
+    gridsize: int = 50,
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot intensity vs viewing angle from horizontal at (0,0,0).
+
+    Shows intensity as a function of viewing angle from horizontal plane
+    at the origin (Earth surface reference point). This is the geometric
+    angle to the intersection point, not the ray direction angle.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data with viewing_angle attribute
+    output_path : str, optional
+        If provided, save figure to this path
+    log_scale : bool, optional
+        Use logarithmic y-axis scale (default: True)
+    title : str, optional
+        Figure title
+    gridsize : int, optional
+        Number of bins for angle profile (default: 50)
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    if healpix_data.viewing_angle is None:
+        raise ValueError("HEALPixData does not have viewing_angle computed")
+
+    fig, ax = plt.subplots(figsize=(12, 8))
+
+    # Convert to degrees for easier reading
+    viewing_angle_deg = np.degrees(healpix_data.viewing_angle)
+    intensities = healpix_data.intensities
+
+    # Bin by viewing angle and sum intensities
+    hist, bin_edges = np.histogram(
+        viewing_angle_deg, bins=gridsize, weights=intensities
+    )
+    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
+
+    ax.plot(bin_centers, hist, "o-", color="steelblue", linewidth=2, markersize=4)
+    ax.fill_between(bin_centers, 0, hist, alpha=0.3, color="steelblue")
+
+    ax.set_xlabel("Viewing Angle from Horizontal (degrees)", fontsize=12)
+    ax.set_ylabel("Intensity (W)", fontsize=12)
+
+    if log_scale and np.any(hist > 0):
+        ax.set_yscale("log")
+
+    ax.grid(True, alpha=0.3)
+
+    if title is None:
+        title = f"Intensity vs Viewing Angle (N={healpix_data.num_rays:,} rays)"
+    ax.set_title(title, fontsize=14)
+
+    plt.tight_layout()
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_ray_direction_intensity(
+    healpix_data,
+    output_path: str | None = None,
+    log_scale: bool = True,
+    title: str | None = None,
+    gridsize: int = 50,
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot intensity vs ray direction elevation angle.
+
+    Shows intensity as a function of the elevation angle of the ray
+    direction vectors themselves (angle above horizontal).
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data with ray_elevation attribute
+    output_path : str, optional
+        If provided, save figure to this path
+    log_scale : bool, optional
+        Use logarithmic y-axis scale (default: True)
+    title : str, optional
+        Figure title
+    gridsize : int, optional
+        Number of bins for angle profile (default: 50)
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    if healpix_data.ray_elevation is None:
+        raise ValueError("HEALPixData does not have ray_elevation computed")
+
+    fig, ax = plt.subplots(figsize=(12, 8))
+
+    # Convert to degrees for easier reading
+    ray_elevation_deg = np.degrees(healpix_data.ray_elevation)
+    intensities = healpix_data.intensities
+
+    # Bin by ray direction elevation and sum intensities
+    hist, bin_edges = np.histogram(
+        ray_elevation_deg, bins=gridsize, weights=intensities
+    )
+    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
+
+    ax.plot(bin_centers, hist, "o-", color="darkgreen", linewidth=2, markersize=4)
+    ax.fill_between(bin_centers, 0, hist, alpha=0.3, color="darkgreen")
+
+    ax.set_xlabel("Ray Direction Elevation from Horizontal (degrees)", fontsize=12)
+    ax.set_ylabel("Intensity (W)", fontsize=12)
+
+    if log_scale and np.any(hist > 0):
+        ax.set_yscale("log")
+
+    ax.grid(True, alpha=0.3)
+
+    if title is None:
+        title = f"Intensity vs Ray Direction Angle (N={healpix_data.num_rays:,} rays)"
+    ax.set_title(title, fontsize=14)
+
+    plt.tight_layout()
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_2d_time(
+    healpix_data,
+    output_path: str | None = None,
+    cmap: str = "viridis",
+    title: str | None = None,
+    plot_type: str = "hexbin",
+    gridsize: int = 50,
+    time_units: str = "us",
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Plot arrival time distribution as simple 2D plot (azimuth vs elevation).
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    output_path : str, optional
+        If provided, save figure to this path
+    cmap : str, optional
+        Matplotlib colormap (default: 'viridis')
+    title : str, optional
+        Figure title
+    plot_type : str, optional
+        'hexbin' for hexagonal binning, 'scatter' for scatter plot (default: 'hexbin')
+    gridsize : int, optional
+        Grid size for hexbin (default: 50)
+    time_units : str, optional
+        Time units: 'us', 'ns', 's' (default: 'us')
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    unit_scales = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    unit_labels = {"s": "s", "ms": "ms", "us": "μs", "ns": "ns"}
+    scale = unit_scales.get(time_units, 1e6)
+    label = unit_labels.get(time_units, "μs")
+
+    fig, ax = plt.subplots(figsize=(12, 8))
+
+    # Convert to degrees
+    azimuth_deg = np.degrees(healpix_data.lon)
+    elevation_deg = np.degrees(healpix_data.lat)
+    times = healpix_data.times * scale
+
+    if plot_type == "hexbin":
+        # Hexagonal binning with intensity-weighted mean time
+        hb = ax.hexbin(
+            azimuth_deg,
+            elevation_deg,
+            C=times,
+            gridsize=gridsize,
+            cmap=cmap,
+            reduce_C_function=np.mean,
+            mincnt=1,
+        )
+        cbar_label = f"Mean Arrival Time ({label})"
+    else:
+        # Scatter plot
+        scatter = ax.scatter(
+            azimuth_deg, elevation_deg, c=times, cmap=cmap, s=5, alpha=0.6
+        )
+        hb = scatter
+        cbar_label = f"Arrival Time ({label})"
+
+    cbar = plt.colorbar(hb, ax=ax)
+    cbar.set_label(cbar_label, fontsize=12)
+
+    ax.set_xlabel("Azimuth (degrees)", fontsize=12)
+    ax.set_ylabel("Elevation (degrees)", fontsize=12)
+
+    if title is None:
+        title = f"Arrival Time Distribution (N={healpix_data.num_rays:,} rays)"
+    ax.set_title(title, fontsize=14)
+
+    ax.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig
+
+
+def plot_2d_combined(
+    healpix_data,
+    peak_mask: np.ndarray | None = None,
+    time_stats: dict | None = None,
+    peak_stats: dict | None = None,
+    output_path: str | None = None,
+    log_scale: bool = True,
+    time_units: str = "us",
+    plot_type: str = "hexbin",
+    gridsize: int = 50,
+    dpi: int = 150,
+) -> plt.Figure:
+    """
+    Create 2D combined analysis figure (simpler than Mollweide for localized patterns).
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    peak_mask : ndarray, optional
+        Boolean mask for peak region rays
+    time_stats : dict, optional
+        Statistics for all rays
+    peak_stats : dict, optional
+        Statistics for peak region
+    output_path : str, optional
+        If provided, save figure to this path
+    log_scale : bool, optional
+        Use log scale for intensity (default: True)
+    time_units : str, optional
+        Time units (default: 'us')
+    plot_type : str, optional
+        'hexbin' or 'scatter' (default: 'hexbin')
+    gridsize : int, optional
+        Grid size for hexbin (default: 50)
+    dpi : int, optional
+        Figure resolution (default: 150)
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure object
+    """
+    unit_scales = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    unit_labels = {"s": "s", "ms": "ms", "us": "μs", "ns": "ns"}
+    scale = unit_scales.get(time_units, 1e6)
+    label = unit_labels.get(time_units, "μs")
+
+    fig = plt.figure(figsize=(16, 10))
+    gs = gridspec.GridSpec(2, 2, figure=fig, hspace=0.3, wspace=0.3)
+
+    # Convert to degrees
+    azimuth_deg = np.degrees(healpix_data.lon)
+    elevation_deg = np.degrees(healpix_data.lat)
+    intensities = healpix_data.intensities
+    times = healpix_data.times * scale
+
+    # =========================================================================
+    # 1. Intensity map (2D)
+    # =========================================================================
+    ax1 = fig.add_subplot(gs[0, 0])
+
+    if plot_type == "hexbin":
+        if log_scale and np.any(intensities > 0):
+            hb1 = ax1.hexbin(
+                azimuth_deg,
+                elevation_deg,
+                C=intensities,
+                gridsize=gridsize,
+                cmap="hot",
+                reduce_C_function=np.sum,
+                norm=LogNorm(
+                    vmin=intensities[intensities > 0].min(), vmax=intensities.max()
+                ),
+                mincnt=1,
+            )
+        else:
+            hb1 = ax1.hexbin(
+                azimuth_deg,
+                elevation_deg,
+                C=intensities,
+                gridsize=gridsize,
+                cmap="hot",
+                reduce_C_function=np.sum,
+                mincnt=1,
+            )
+        cbar1 = plt.colorbar(hb1, ax=ax1)
+        cbar_label = "Summed Intensity"
+    else:
+        if log_scale and np.any(intensities > 0):
+            norm = LogNorm(
+                vmin=intensities[intensities > 0].min(), vmax=intensities.max()
+            )
+            sc1 = ax1.scatter(
+                azimuth_deg,
+                elevation_deg,
+                c=intensities,
+                cmap="hot",
+                s=2,
+                alpha=0.6,
+                norm=norm,
+            )
+        else:
+            sc1 = ax1.scatter(
+                azimuth_deg, elevation_deg, c=intensities, cmap="hot", s=2, alpha=0.6
+            )
+        cbar1 = plt.colorbar(sc1, ax=ax1)
+        cbar_label = "Intensity"
+
+    if log_scale:
+        cbar_label += " (log)"
+    cbar1.set_label(cbar_label, fontsize=10)
+
+    ax1.set_xlabel("Azimuth (°)", fontsize=11)
+    ax1.set_ylabel("Elevation (°)", fontsize=11)
+    ax1.set_title(f"Intensity Distribution (N={healpix_data.num_rays:,})", fontsize=12)
+    ax1.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 2. Time map (2D)
+    # =========================================================================
+    ax2 = fig.add_subplot(gs[0, 1])
+
+    if plot_type == "hexbin":
+        hb2 = ax2.hexbin(
+            azimuth_deg,
+            elevation_deg,
+            C=times,
+            gridsize=gridsize,
+            cmap="viridis",
+            reduce_C_function=np.mean,
+            mincnt=1,
+        )
+    else:
+        hb2 = ax2.scatter(
+            azimuth_deg, elevation_deg, c=times, cmap="viridis", s=2, alpha=0.6
+        )
+
+    cbar2 = plt.colorbar(hb2, ax=ax2)
+    cbar2.set_label(f"Arrival Time ({label})", fontsize=10)
+
+    ax2.set_xlabel("Azimuth (°)", fontsize=11)
+    ax2.set_ylabel("Elevation (°)", fontsize=11)
+    ax2.set_title("Arrival Time Distribution", fontsize=12)
+    ax2.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 3. Time histogram - All rays
+    # =========================================================================
+    ax3 = fig.add_subplot(gs[1, 0])
+
+    ax3.hist(
+        times,
+        bins=80,
+        weights=intensities,
+        color="steelblue",
+        alpha=0.7,
+        edgecolor="black",
+    )
+    ax3.set_xlabel(f"Arrival Time ({label})", fontsize=10)
+    ax3.set_ylabel("Intensity-weighted Count", fontsize=10)
+    ax3.set_title("All Rays - Time Distribution", fontsize=11)
+    ax3.grid(True, alpha=0.3)
+
+    # =========================================================================
+    # 4. Time histogram - Peak region
+    # =========================================================================
+    ax4 = fig.add_subplot(gs[1, 1])
+
+    if peak_mask is not None and np.any(peak_mask):
+        peak_times = healpix_data.times[peak_mask] * scale
+        peak_intensities = healpix_data.intensities[peak_mask]
+
+        ax4.hist(
+            peak_times,
+            bins=80,
+            weights=peak_intensities,
+            color="coral",
+            alpha=0.7,
+            edgecolor="black",
+        )
+        ax4.set_xlabel(f"Arrival Time ({label})", fontsize=10)
+        ax4.set_ylabel("Intensity-weighted Count", fontsize=10)
+        ax4.set_title("Peak Region - Time Distribution", fontsize=11)
+        ax4.grid(True, alpha=0.3)
+
+        if peak_stats:
+            stats_text = f"N={peak_stats['num_rays']:,}\n"
+            stats_text += f"Mean: {peak_stats['mean_time']*scale:.2f} {label}\n"
+            stats_text += f"FWHM: {peak_stats['fwhm_time']*scale:.2f} {label}"
+            ax4.text(
+                0.98,
+                0.98,
+                stats_text,
+                transform=ax4.transAxes,
+                verticalalignment="top",
+                horizontalalignment="right",
+                fontsize=9,
+                bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.5},
+            )
+    else:
+        ax4.text(
+            0.5,
+            0.5,
+            "No peak region defined",
+            transform=ax4.transAxes,
+            ha="center",
+            va="center",
+            fontsize=11,
+        )
+        ax4.set_title("Peak Region - Time Distribution", fontsize=11)
+
+    plt.suptitle("Sphere Intersection Pattern - 2D Analysis", fontsize=14, y=0.995)
+
+    if output_path:
+        plt.savefig(output_path, dpi=dpi, bbox_inches="tight")
+        print(f"Saved: {output_path}")
+
+    return fig