lsurf 1.0.0__py3-none-any.whl

lsurf/analysis/healpix_utils.py

@@ -0,0 +1,418 @@
+# 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.
+
+"""
+HEALPix Utilities for Sphere Pattern Analysis
+
+Functions for converting recorded ray data to HEALPix representation
+and aggregating statistics per pixel.
+"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+try:
+    from astropy import units as u
+    from astropy_healpix import HEALPix
+
+    HAS_HEALPIX = True
+except ImportError:
+    HAS_HEALPIX = False
+
+
+class HEALPixData:
+    """
+    Container for HEALPix-mapped ray data.
+
+    Attributes
+    ----------
+    nside : int
+        HEALPix resolution parameter
+    npix : int
+        Total number of HEALPix pixels
+    pixel_indices : ndarray
+        HEALPix pixel index for each ray
+    lon : ndarray
+        Longitude (azimuth) for each ray in radians
+    lat : ndarray
+        Latitude (elevation) for each ray in radians
+    intensities : ndarray
+        Intensity for each ray
+    times : ndarray
+        Arrival time for each ray (seconds)
+    generations : ndarray
+        Generation (bounce count) for each ray
+    viewing_angle : ndarray or None
+        Viewing angle from horizontal at (0,0,0) in radians
+    ray_elevation : ndarray or None
+        Ray direction elevation angle from horizontal in radians
+    ray_azimuth : ndarray or None
+        Ray direction azimuth angle in radians
+    aggregated : dict or None
+        Aggregated statistics per pixel (if computed)
+    """
+
+    def __init__(
+        self,
+        nside: int,
+        pixel_indices: NDArray[np.int64],
+        lon: NDArray[np.float64],
+        lat: NDArray[np.float64],
+        intensities: NDArray[np.float32],
+        times: NDArray[np.float32],
+        generations: NDArray[np.int32],
+        viewing_angle: NDArray[np.float32] | None = None,
+        ray_elevation: NDArray[np.float32] | None = None,
+        ray_azimuth: NDArray[np.float32] | None = None,
+    ):
+        self.nside = nside
+        self.npix = 12 * nside**2
+        self.pixel_indices = pixel_indices
+        self.lon = lon
+        self.lat = lat
+        self.intensities = intensities
+        self.times = times
+        self.generations = generations
+        self.viewing_angle = viewing_angle
+        self.ray_elevation = ray_elevation
+        self.ray_azimuth = ray_azimuth
+        self.aggregated = None
+
+    @property
+    def num_rays(self) -> int:
+        """Number of recorded rays."""
+        return len(self.pixel_indices)
+
+
+def rays_to_healpix(
+    recorded_rays,
+    nside: int = 128,
+) -> HEALPixData:
+    """
+    Convert recorded rays to HEALPix pixel representation.
+
+    Parameters
+    ----------
+    recorded_rays : RecordedRays
+        Recorded ray data from detection sphere
+    nside : int, optional
+        HEALPix resolution parameter (default: 128)
+        Higher values give finer resolution
+        nside=64 → ~3,400 pixels
+        nside=128 → ~13,000 pixels
+        nside=256 → ~50,000 pixels
+
+    Returns
+    -------
+    HEALPixData
+        HEALPix-mapped ray data
+
+    Raises
+    ------
+    ImportError
+        If astropy-healpix is not installed
+    """
+    if not HAS_HEALPIX:
+        raise ImportError(
+            "astropy-healpix is required. Install with: pip install astropy-healpix"
+        )
+
+    # Compute angular coordinates
+    angular = recorded_rays.compute_angular_coordinates()
+
+    # Extract azimuth (longitude) and elevation (latitude)
+    # azimuth: 0 to 2π
+    # elevation: -π/2 to π/2 (horizon at 0)
+    azimuth = angular["azimuth"]  # radians
+    elevation = angular["elevation"]  # radians
+
+    # Create HEALPix object
+    hp = HEALPix(nside=nside, order="ring", frame=None)
+
+    # Convert to astropy units
+    lon = azimuth * u.rad
+    lat = elevation * u.rad
+
+    # Get HEALPix pixel indices
+    pixel_indices = hp.lonlat_to_healpix(lon, lat)
+
+    # Compute viewing angle from horizontal at (0,0,0)
+    viewing_angle = recorded_rays.compute_viewing_angle_from_origin()
+
+    # Compute ray direction angles
+    ray_dir_angles = recorded_rays.compute_ray_direction_angles()
+
+    return HEALPixData(
+        nside=nside,
+        pixel_indices=pixel_indices,
+        lon=azimuth,
+        lat=elevation,
+        intensities=recorded_rays.intensities,
+        times=recorded_rays.times,
+        generations=recorded_rays.generations,
+        viewing_angle=viewing_angle,
+        ray_elevation=ray_dir_angles["elevation"],
+        ray_azimuth=ray_dir_angles["azimuth"],
+    )
+
+
+def aggregate_healpix_data(
+    healpix_data: HEALPixData,
+) -> dict[str, NDArray]:
+    """
+    Aggregate ray properties per HEALPix pixel.
+
+    Computes per-pixel statistics:
+    - Total intensity (sum)
+    - Mean arrival time (intensity-weighted)
+    - Ray count
+    - Mean generation
+    - Intensity standard deviation
+    - Time standard deviation
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+
+    Returns
+    -------
+    dict
+        Dictionary with aggregated arrays for each occupied pixel:
+        - 'pixel_ids': Array of pixel indices with data
+        - 'intensity_sum': Total intensity per pixel
+        - 'intensity_mean': Mean intensity per pixel
+        - 'time_weighted_mean': Intensity-weighted mean time
+        - 'time_mean': Arithmetic mean time
+        - 'time_std': Standard deviation of arrival time
+        - 'ray_count': Number of rays per pixel
+        - 'generation_mean': Mean generation per pixel
+    """
+    # Get unique pixel indices
+    unique_pixels = np.unique(healpix_data.pixel_indices)
+    n_pixels = len(unique_pixels)
+
+    # Initialize aggregated arrays
+    intensity_sum = np.zeros(n_pixels, dtype=np.float64)
+    intensity_mean = np.zeros(n_pixels, dtype=np.float64)
+    time_weighted_mean = np.zeros(n_pixels, dtype=np.float64)
+    time_mean = np.zeros(n_pixels, dtype=np.float64)
+    time_std = np.zeros(n_pixels, dtype=np.float64)
+    ray_count = np.zeros(n_pixels, dtype=np.int32)
+    generation_mean = np.zeros(n_pixels, dtype=np.float64)
+
+    # Aggregate per pixel
+    for i, pixel_id in enumerate(unique_pixels):
+        mask = healpix_data.pixel_indices == pixel_id
+
+        # Intensities in this pixel
+        pixel_intensities = healpix_data.intensities[mask]
+        pixel_times = healpix_data.times[mask]
+        pixel_generations = healpix_data.generations[mask]
+
+        # Sum and count
+        intensity_sum[i] = np.sum(pixel_intensities)
+        ray_count[i] = np.sum(mask)
+        intensity_mean[i] = np.mean(pixel_intensities)
+
+        # Intensity-weighted mean time
+        total_intensity = intensity_sum[i]
+        if total_intensity > 0:
+            time_weighted_mean[i] = (
+                np.sum(pixel_times * pixel_intensities) / total_intensity
+            )
+        else:
+            time_weighted_mean[i] = np.mean(pixel_times)
+
+        # Arithmetic mean time and std
+        time_mean[i] = np.mean(pixel_times)
+        time_std[i] = np.std(pixel_times) if len(pixel_times) > 1 else 0.0
+
+        # Mean generation
+        generation_mean[i] = np.mean(pixel_generations)
+
+    aggregated = {
+        "pixel_ids": unique_pixels,
+        "intensity_sum": intensity_sum,
+        "intensity_mean": intensity_mean,
+        "time_weighted_mean": time_weighted_mean,
+        "time_mean": time_mean,
+        "time_std": time_std,
+        "ray_count": ray_count,
+        "generation_mean": generation_mean,
+    }
+
+    # Store in HEALPixData object
+    healpix_data.aggregated = aggregated
+
+    return aggregated
+
+
+def identify_peak_region(
+    healpix_data: HEALPixData,
+    threshold_percentile: float = 90.0,
+) -> tuple[NDArray[np.int64], NDArray[np.bool_]]:
+    """
+    Identify pixels in the peak intensity region.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix data with aggregated statistics
+    threshold_percentile : float, optional
+        Percentile threshold for peak region (default: 90.0)
+        90.0 means top 10% of pixels by intensity
+
+    Returns
+    -------
+    peak_pixel_ids : ndarray
+        Pixel IDs in the peak region
+    peak_mask : ndarray
+        Boolean mask for rays in peak region
+
+    Raises
+    ------
+    ValueError
+        If aggregated data not computed
+    """
+    if healpix_data.aggregated is None:
+        raise ValueError("Must call aggregate_healpix_data() first")
+
+    # Get intensity sum per pixel
+    intensity_sum = healpix_data.aggregated["intensity_sum"]
+    pixel_ids = healpix_data.aggregated["pixel_ids"]
+
+    # Find threshold
+    threshold = np.percentile(intensity_sum, threshold_percentile)
+
+    # Identify peak pixels
+    peak_pixel_mask = intensity_sum >= threshold
+    peak_pixel_ids = pixel_ids[peak_pixel_mask]
+
+    # Create mask for individual rays in peak region
+    peak_ray_mask = np.isin(healpix_data.pixel_indices, peak_pixel_ids)
+
+    return peak_pixel_ids, peak_ray_mask
+
+
+def compute_time_statistics(
+    healpix_data: HEALPixData,
+    peak_mask: NDArray[np.bool_] | None = None,
+) -> dict[str, float]:
+    """
+    Compute arrival time statistics.
+
+    Parameters
+    ----------
+    healpix_data : HEALPixData
+        HEALPix-mapped ray data
+    peak_mask : ndarray, optional
+        Boolean mask to select rays in peak region
+        If None, uses all rays
+
+    Returns
+    -------
+    dict
+        Statistics including:
+        - 'mean_time': Mean arrival time (s)
+        - 'median_time': Median arrival time (s)
+        - 'std_time': Standard deviation (s)
+        - 'min_time': Minimum time (s)
+        - 'max_time': Maximum time (s)
+        - 'time_span': max - min (s)
+        - 'weighted_mean_time': Intensity-weighted mean (s)
+        - 'fwhm_time': Full width at half maximum (s)
+        - 'num_rays': Number of rays included
+    """
+    if peak_mask is None:
+        times = healpix_data.times
+        intensities = healpix_data.intensities
+    else:
+        times = healpix_data.times[peak_mask]
+        intensities = healpix_data.intensities[peak_mask]
+
+    if len(times) == 0:
+        return {
+            "mean_time": 0.0,
+            "median_time": 0.0,
+            "std_time": 0.0,
+            "min_time": 0.0,
+            "max_time": 0.0,
+            "time_span": 0.0,
+            "weighted_mean_time": 0.0,
+            "fwhm_time": 0.0,
+            "num_rays": 0,
+        }
+
+    # Basic statistics
+    mean_time = np.mean(times)
+    median_time = np.median(times)
+    std_time = np.std(times)
+    min_time = np.min(times)
+    max_time = np.max(times)
+    time_span = max_time - min_time
+
+    # Intensity-weighted mean
+    total_intensity = np.sum(intensities)
+    if total_intensity > 0:
+        weighted_mean_time = np.sum(times * intensities) / total_intensity
+    else:
+        weighted_mean_time = mean_time
+
+    # Estimate FWHM from histogram
+    hist, bin_edges = np.histogram(times, bins=100, weights=intensities)
+    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
+
+    peak_idx = np.argmax(hist)
+    peak_value = hist[peak_idx]
+    half_max = peak_value / 2
+
+    # Find indices where histogram > half max
+    above_half = hist >= half_max
+    if np.any(above_half):
+        indices = np.where(above_half)[0]
+        fwhm_time = bin_centers[indices[-1]] - bin_centers[indices[0]]
+    else:
+        fwhm_time = std_time * 2.355  # Gaussian approximation
+
+    return {
+        "mean_time": float(mean_time),
+        "median_time": float(median_time),
+        "std_time": float(std_time),
+        "min_time": float(min_time),
+        "max_time": float(max_time),
+        "time_span": float(time_span),
+        "weighted_mean_time": float(weighted_mean_time),
+        "fwhm_time": float(fwhm_time),
+        "num_rays": int(len(times)),
+    }