isgri 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

isgri/utils/lightcurve.py

@@ -1,5 +1,36 @@
+"""
+ISGRI Light Curve Analysis
+===========================
+
+Tools for working with INTEGRAL/ISGRI event data and creating light curves.
+
+Classes
+-------
+LightCurve : Main light curve class
+
+Examples
+--------
+>>> from isgri.utils import LightCurve
+>>>
+>>> # Load events with PIF weighting
+>>> lc = LightCurve.load_data(
+...     events_path="events.fits",
+...     pif_path="model.fits",
+...     pif_threshold=0.5
+... )
+>>>
+>>> # Create 1-second binned light curve
+>>> time, counts = lc.rebin(binsize=1.0, emin=20, emax=100)
+>>>
+>>> # Analyze by detector module
+>>> times, module_lcs = lc.rebin_by_modules(1.0, 20, 100)
+"""
+
 from astropy.io import fits
 import numpy as np
+from numpy.typing import NDArray
+from typing import Optional, Union, Tuple, List
+from pathlib import Path
 import os
 from .file_loaders import load_isgri_events, load_isgri_pif, default_pif_metadata, merge_metadata
 from .pif import DETZ_BOUNDS, DETY_BOUNDS
@@ -7,54 +38,112 @@ from .pif import DETZ_BOUNDS, DETY_BOUNDS
 
 class LightCurve:
     """
-    A class for working with ISGRI events. Works fully with and without ISGRI model file (PIF file).
-
-    Attributes:
-        time (ndarray): The IJD time values of the events.
-        energies (ndarray): The energy values of the events in keV.
-        gtis (ndarray): The Good Time Intervals (GTIs) of the events.
-        t0 (float): The first time of the events (IJD).
-        local_time (ndarray): The local time values of the events (seconds from t0).
-        dety (ndarray): The Y detector coordinates.
-        detz (ndarray): The Z detector coordinates.
-        pif (ndarray): The PIF values of the events.
-        metadata (dict): Event metadata including SWID, source info, etc.
-
-    Methods:
-        load_data: Loads the light curve data from events and PIF files.
-        rebin: Rebins the light curve with specified bin size and energy range.
-        rebin_by_modules: Rebins the light curve for all 8 detector modules.
-        cts: Calculates the counts in specified time and energy range.
-        ijd2loc: Converts IJD time to local time (seconds from t0).
-        loc2ijd: Converts local time to IJD time.
+    ISGRI light curve analysis class.
+
+    Handles event data with optional detector response (PIF) weighting.
+    Provides rebinning, module-level analysis, and time conversions.
+
+    Parameters
+    ----------
+    time : ndarray
+        IJD time values of events
+    energies : ndarray
+        Energy values in keV
+    gtis : ndarray
+        Good Time Intervals (start, stop) in IJD
+    dety : ndarray
+        Y detector coordinates (mm)
+    detz : ndarray
+        Z detector coordinates (mm)
+    weights : ndarray
+        PIF weight for each event (1.0 if no PIF)
+    metadata : dict
+        Event metadata (SWID, source info, etc.)
+
+    Attributes
+    ----------
+    t0 : float
+        Reference time (first event time in IJD)
+    local_time : ndarray
+        Time relative to t0 in seconds
+
+    Examples
+    --------
+    >>> lc = LightCurve.load_data("events.fits", pif_path="model.fits")
+    >>> time, counts = lc.rebin(binsize=1.0, emin=20, emax=100)
+    >>> print(f"Total counts: {counts.sum()}")
+
+    >>> # Module-by-module analysis
+    >>> times, module_counts = lc.rebin_by_modules(1.0, 20, 100)
+    >>> print(f"Module 3 counts: {module_counts[3].sum()}")
+
+    See Also
+    --------
+    load_data : Load events from FITS files
+    rebin : Rebin light curve
+    rebin_by_modules : Rebin by detector module
     """
 
-    def __init__(self, time, energies, gtis, dety, detz, weights, metadata):
+    time: NDArray[np.float64]
+    energies: NDArray[np.float64]
+    gtis: NDArray[np.float64]
+    t0: float
+    local_time: NDArray[np.float64]
+    dety: NDArray[np.float64]
+    detz: NDArray[np.float64]
+    weights: NDArray[np.float64]
+    metadata: dict
+
+    def __init__(
+        self,
+        time: NDArray[np.float64],
+        energies: NDArray[np.float64],
+        gtis: NDArray[np.float64],
+        dety: NDArray[np.float64],
+        detz: NDArray[np.float64],
+        weights: NDArray[np.float64],
+        metadata: dict,
+    ) -> None:
         """
         Initialize LightCurve instance.
 
-        Args:
-            time (ndarray): IJD time values.
-            energies (ndarray): Energy values in keV.
-            gtis (ndarray): Good Time Intervals.
-            dety (ndarray): Y detector coordinates.
-            detz (ndarray): Z detector coordinates.
-            pif (ndarray): PIF mask values.
-            metadata (dict): Event metadata.
+        Parameters
+        ----------
+        time : ndarray
+            IJD time values
+        energies : ndarray
+            Energy values in keV
+        gtis : ndarray
+            Good Time Intervals
+        dety : ndarray
+            Y detector coordinates
+        detz : ndarray
+            Z detector coordinates
+        weights : ndarray
+            PIF weights for each event
+        metadata : dict
+            Event metadata
         """
         self.time = time
         self.energies = energies
         self.gtis = gtis
         self.t0 = time[0]
         self.local_time = (time - self.t0) * 86400
-
         self.dety = dety
         self.detz = detz
         self.weights = weights
         self.metadata = metadata
 
     @classmethod
-    def load_data(cls, events_path=None, pif_path=None, scw=None, source=None, pif_threshold=0.5, pif_extension=-1):
+    def load_data(
+        cls,
+        events_path: Optional[Union[str, Path]] = None,
+        pif_path: Optional[Union[str, Path]] = None,
+        scw: Optional[str] = None,
+        source: Optional[str] = None,
+        pif_threshold: float = 0.5,
+        pif_extension: int = -1,
+    ) -> "LightCurve":
         """
         Loads the events from the given events file and PIF file (optional).
 
@@ -71,6 +160,9 @@ class LightCurve:
         """
         events, gtis, metadata = load_isgri_events(events_path)
         if pif_path:
+            if pif_threshold < 0 or pif_threshold > 1:
+                raise ValueError(f"pif_threshold must be in [0, 1], got {pif_threshold}")
+            
             events, weights, metadata_pif = load_isgri_pif(pif_path, events, pif_threshold, pif_extension)
         else:
             weights = np.ones(len(events))
@@ -82,7 +174,14 @@ class LightCurve:
         dety, detz = events["DETY"], events["DETZ"]
         return cls(time, energies, gtis, dety, detz, weights, metadata)
 
-    def rebin(self, binsize, emin, emax, local_time=True, custom_mask=None):
+    def rebin(
+        self,
+        binsize: Union[float, NDArray[np.float64], List[float]],
+        emin: float,
+        emax: float,
+        local_time: bool = True,
+        custom_mask: Optional[NDArray[np.bool_]] = None,
+    ) -> Tuple[NDArray[np.float64], NDArray[np.float64]]:
         """
         Rebins the events with the specified bin size and energy range.
 
@@ -103,8 +202,20 @@ class LightCurve:
             >>> time, counts = lc.rebin(binsize=1.0, emin=30, emax=300)
             >>> time, counts = lc.rebin(binsize=[0, 1, 2, 5, 10], emin=50, emax=200)
         """
+        # Validate inputs
         if emin >= emax:
-            raise ValueError("emin must be less than emax")
+            raise ValueError(f"emin ({emin}) must be less than emax ({emax})")
+
+        if emin < 0:
+            raise ValueError(f"emin must be non-negative, got {emin}")
+
+        if isinstance(binsize, (int, float)) and binsize <= 0:
+            raise ValueError(f"binsize must be positive, got {binsize}")
+
+        if custom_mask is not None and len(custom_mask) != len(self.time):
+            raise ValueError(
+                f"custom_mask length ({len(custom_mask)}) must match " f"number of events ({len(self.time)})"
+            )
 
         # Select time axis
         time = self.local_time if local_time else self.time
@@ -124,7 +235,13 @@ class LightCurve:
 
         return time_centers, counts
 
-    def _create_bins(self, binsize, time, t0, local_time):
+    def _create_bins(
+        self,
+        binsize: Union[float, NDArray[np.float64], List[float]],
+        time: NDArray[np.float64],
+        t0: float,
+        local_time: bool,
+    ) -> Tuple[NDArray[np.float64], float]:
         """
         Create time bins for rebinning.
 
@@ -148,7 +265,12 @@ class LightCurve:
 
         return bins, binsize_actual
 
-    def _create_event_mask(self, emin, emax, custom_mask=None):
+    def _create_event_mask(
+        self,
+        emin: float,
+        emax: float,
+        custom_mask: Optional[NDArray[np.bool_]] = None,
+    ) -> NDArray[np.bool_]:
         """
         Create combined event filter mask.
 
@@ -169,7 +291,14 @@ class LightCurve:
 
         return mask
 
-    def rebin_by_modules(self, binsize, emin, emax, local_time=True, custom_mask=None):
+    def rebin_by_modules(
+        self,
+        binsize: float,
+        emin: float,
+        emax: float,
+        local_time: bool = True,
+        custom_mask: Optional[NDArray[np.bool_]] = None,
+    ) -> Tuple[NDArray[np.float64], List[NDArray[np.float64]]]:
         """
         Rebins the events by all 8 detector modules with the specified bin size and energy range.
 
@@ -222,7 +351,14 @@ class LightCurve:
 
         return times, counts
 
-    def cts(self, t1, t2, emin, emax, local_time=True, bkg=False):
+    def cts(
+        self,
+        t1: float,
+        t2: float,
+        emin: float,
+        emax: float,
+        local_time: bool = True,
+    ) -> float:
         """
         Calculates the counts in the specified time and energy range.
 
@@ -232,7 +368,6 @@ class LightCurve:
             emin (float): The minimum energy value in keV.
             emax (float): The maximum energy value in keV.
             local_time (bool, optional): If True, uses local time. Defaults to True.
-            bkg (bool, optional): Reserved for future background subtraction. Defaults to False.
 
         Returns:
             float: The total counts in the specified range.
@@ -240,7 +375,7 @@ class LightCurve:
         time = self.local_time if local_time else self.time
         return np.sum(self.weights[(time >= t1) & (time < t2) & (self.energies >= emin) & (self.energies < emax)])
 
-    def ijd2loc(self, ijd_time):
+    def ijd2loc(self, ijd_time: Union[float, NDArray[np.float64]]) -> Union[float, NDArray[np.float64]]:
         """
         Converts IJD (INTEGRAL Julian Date) time to local time.
 
@@ -252,7 +387,7 @@ class LightCurve:
         """
         return (ijd_time - self.t0) * 86400
 
-    def loc2ijd(self, evt_time):
+    def loc2ijd(self, evt_time: Union[float, NDArray[np.float64]]) -> Union[float, NDArray[np.float64]]:
         """
         Converts local time to IJD (INTEGRAL Julian Date) time.
 
@@ -263,3 +398,12 @@ class LightCurve:
             float or ndarray: The IJD time value(s).
         """
         return evt_time / 86400 + self.t0
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"LightCurve(n_events={len(self.time)}, "
+            f"time_range=({self.time[0]:.3f}, {self.time[-1]:.3f}) IJD, "
+            f"energy_range=({self.energies.min():.1f}, {self.energies.max():.1f}) keV, "
+            f"scw={self.metadata.get('SWID', 'Unknown')})"
+        )

isgri/utils/pif.py

@@ -1,41 +1,286 @@
+"""
+ISGRI Detector Pixel Illumination Fraction (PIF) Tools
+========================================================
+
+Functions for working with ISGRI detector response maps (PIF files).
+PIF values indicate what fraction of source flux reaches each detector pixel,
+accounting for shadowing by the coded mask.
+
+PIF values range from 0 (fully shadowed) to 1 (fully illuminated).
+
+Functions
+---------
+select_isgri_module : Get detector coordinate bounds for a module
+apply_pif_mask : Filter events by PIF threshold
+coding_fraction : Calculate coded fraction for source position
+estimate_active_modules : Determine which modules have significant PIF coverage
+
+Examples
+--------
+>>> import numpy as np
+>>> from astropy.table import Table
+>>>
+>>> # Load PIF and events
+>>> pif_file = np.random.rand(134, 130)  # Mock PIF
+>>> events = Table({'DETZ': [10, 20], 'DETY': [15, 25]})
+>>>
+>>> # Apply PIF weighting
+>>> filtered_events, weights = apply_pif_mask(pif_file, events, pif_threshold=0.5)
+>>>
+>>> # Check which modules are active
+>>> active = estimate_active_modules(pif_file)
+>>> print(f"Active modules: {np.where(active)[0]}")
+"""
+
 import numpy as np
+from numpy.typing import NDArray
+from typing import Tuple
+from astropy.table import Table
+
+# ISGRI detector module boundaries (mm coordinates)
+# 8 modules total: 4 rows × 2 columns
+# Z-axis (rows): 4 modules 
+# Y-axis (cols): 2 modules
+DETZ_BOUNDS = [0, 32, 66, 100, 134]  # 5 boundaries for 4 rows
+DETY_BOUNDS = [0, 64, 130]  # 3 boundaries for 2 columns
+
+
+def select_isgri_module(module_no: int) -> Tuple[int, int, int, int]:
+    """
+    Get detector coordinate bounds for specified module.
+
+    ISGRI has 8 modules arranged in 4 rows × 2 columns:
+
+    Module layout:
+        [0] [1]
+        [2] [3]
+        [4] [5]
+        [6] [7]
+
+    Parameters
+    ----------
+    module_no : int
+        Module number (0-7)
+
+    Returns
+    -------
+    z1, z2, y1, y2 : int
+        Detector coordinate bounds (DETZ min/max, DETY min/max)
+
+    Raises
+    ------
+    ValueError
+        If module_no not in range [0, 7]
 
-DETZ_BOUNDS, DETY_BOUNDS = [0, 32, 66, 100, 134], [0, 64, 130]  # Detector module boundaries
+    Examples
+    --------
+    >>> z1, z2, y1, y2 = select_isgri_module(0)
+    >>> print(f"Module 0: DETZ=[{z1},{z2}], DETY=[{y1},{y2}]")
+    Module 0: DETZ=[0,32], DETY=[0,64]
 
+    >>> # Module 3 is bottom-right
+    >>> select_isgri_module(3)
+    (66, 100, 64, 130)
+    """
+    if not (0 <= module_no <= 7):
+        raise ValueError(f"module_no must be in [0, 7], got {module_no}")
 
-def select_isgri_module(module_no):
-    col = 0 if module_no % 2 == 0 else 1
-    row = module_no // 2
-    x1, x2 = DETZ_BOUNDS[row], DETZ_BOUNDS[row + 1]
+    col = module_no % 2  # 0=left, 1=right
+    row = module_no // 2  # 0-3 from top to bottom
+
+    z1, z2 = DETZ_BOUNDS[row], DETZ_BOUNDS[row + 1]
     y1, y2 = DETY_BOUNDS[col], DETY_BOUNDS[col + 1]
-    return x1, x2, y1, y2
 
+    return z1, z2, y1, y2
+
+
+def apply_pif_mask(
+    pif_file: NDArray[np.float64],
+    events: Table,
+    pif_threshold: float = 0.5,
+) -> Tuple[Table, NDArray[np.float64]]:
+    """
+    Filter events by PIF threshold and return PIF weights.
+
+    Events with PIF < threshold are removed. Remaining events are
+    weighted by their PIF values for response correction.
+
+    Parameters
+    ----------
+    pif_file : ndarray, shape (134, 130)
+        2D PIF array (DETZ x DETY coordinates)
+    events : Table
+        Event table with 'DETZ' and 'DETY' columns
+    pif_threshold : float, default 0.5
+        Minimum PIF value to keep event (0.0-1.0)
+
+    Returns
+    -------
+    filtered_events : Table
+        Events with PIF >= threshold
+    pif_weights : ndarray
+        PIF value for each filtered event
+
+    Raises
+    ------
+    ValueError
+        If pif_threshold not in [0, 1]
+        If events missing 'DETZ' or 'DETY' columns
+        If PIF dimensions don't match expected (134, 130)
 
-def apply_pif_mask(pif_file, events, pif_threshold=0.5):
+    Examples
+    --------
+    >>> pif = np.random.rand(134, 130)
+    >>> events = Table({'DETZ': [10, 20, 30], 'DETY': [15, 25, 35]})
+    >>>
+    >>> # Keep only well-illuminated events
+    >>> filtered, weights = apply_pif_mask(pif, events, pif_threshold=0.7)
+    >>> print(f"Kept {len(filtered)}/{len(events)} events")
+    >>> print(f"Mean weight: {weights.mean():.3f}")
+    """
+    # Validate inputs
+    if not (0 <= pif_threshold <= 1):
+        raise ValueError(f"pif_threshold must be in [0, 1], got {pif_threshold}")
+
+    if pif_file.shape != (134, 130):
+        raise ValueError(f"PIF file must have shape (134, 130), got {pif_file.shape}")
+
+    if "DETZ" not in events.colnames or "DETY" not in events.colnames:
+        raise ValueError("Events table must have 'DETZ' and 'DETY' columns")
+
+    # Create mask for events above threshold
     pif_filter = pif_file > pif_threshold
-    piffed_events = events[pif_filter[events["DETZ"], events["DETY"]]]
-    pif = pif_file[piffed_events["DETZ"], piffed_events["DETY"]]
-    return piffed_events, pif
+
+    # Get PIF values at event positions
+    event_pif = pif_file[events["DETZ"], events["DETY"]]
+
+    # Apply filter
+    mask = event_pif > pif_threshold
+    filtered_events = events[mask]
+    pif_weights = event_pif[mask]
+
+    return filtered_events, pif_weights
 
 
-def coding_fraction(pif_file, events):
-    pif_cod = pif_file == 1
-    pif_cod = events[pif_cod[events["DETZ"], events["DETY"]]]
-    cody = (np.max(pif_cod["DETY"]) - np.min(pif_cod["DETY"])) / 129
-    codz = (np.max(pif_cod["DETZ"]) - np.min(pif_cod["DETZ"])) / 133
-    pif_cod = codz * cody
-    return pif_cod
+def coding_fraction(
+    pif_file: NDArray[np.float64],
+    events: Table,
+) -> float:
+    """
+    Calculate fraction of detector that is fully coded.
 
+    Uses events with PIF=1.0 (fully illuminated) to estimate
+    the size of the fully coded field of view.
+
+    Parameters
+    ----------
+    pif_file : ndarray, shape (134, 130)
+        2D PIF array
+    events : Table
+        Event table with 'DETZ' and 'DETY' columns
+
+    Returns
+    -------
+    coding_fraction : float
+        Fraction of detector area that is fully coded (0.0-1.0)
+
+    Notes
+    -----
+    Fully coded region has PIF=1.0 for on-axis sources.
+    Partially coded region has 0 < PIF < 1.
+
+    Examples
+    --------
+    >>> pif = np.ones((134, 130))
+    >>> pif[50:80, 40:90] = 1.0  # Fully coded region
+    >>> events = Table({'DETZ': np.arange(134), 'DETY': np.arange(130)})
+    >>>
+    >>> frac = coding_fraction(pif, events)
+    >>> print(f"Coding fraction: {frac:.2%}")
+    """
+    if pif_file.shape != (134, 130):
+        raise ValueError(f"PIF must have shape (134, 130), got {pif_file.shape}")
+
+    if "DETZ" not in events.colnames or "DETY" not in events.colnames:
+        raise ValueError("Events must have 'DETZ' and 'DETY' columns")
+
+    # Find fully coded pixels (PIF = 1.0)
+    fully_coded = pif_file == 1.0
+
+    # Get events in fully coded region
+    coded_events = events[fully_coded[events["DETZ"], events["DETY"]]]
+
+    if len(coded_events) == 0:
+        return 0.0
+
+    # Calculate extent in Y and Z
+    dety_range = np.max(coded_events["DETY"]) - np.min(coded_events["DETY"])
+    detz_range = np.max(coded_events["DETZ"]) - np.min(coded_events["DETZ"])
+
+    # Normalize by detector size (Y: 0-129, Z: 0-133)
+    frac_y = dety_range / 129.0
+    frac_z = detz_range / 133.0
+
+    # Area fraction
+    coding_frac = frac_y * frac_z
+
+    return coding_frac
+
+
+def estimate_active_modules(
+    pif_file: NDArray[np.float64],
+    threshold: float = 0.2,
+) -> NDArray[np.bool_]:
+    """
+    Determine which detector modules have significant PIF coverage.
+
+    A module is considered active if more than `threshold` fraction
+    of its pixels have PIF > 0.01.
+
+    Parameters
+    ----------
+    pif_file : ndarray, shape (134, 130)
+        2D PIF array
+    threshold : float, default 0.2
+        Minimum fraction of illuminated pixels (0.0-1.0)
+
+    Returns
+    -------
+    active_modules : ndarray of bool, shape (8,)
+        True if module is active, False otherwise
+
+    Examples
+    --------
+    >>> pif = np.random.rand(134, 130)
+    >>> pif[:50, :] = 0  # Top modules dark
+    >>>
+    >>> active = estimate_active_modules(pif, threshold=0.2)
+    >>> print(f"Active modules: {np.where(active)[0]}")
+    Active modules: [2 3 4 5 6 7]
+
+    >>> # Get list of active module numbers
+    >>> active_list = np.where(active)[0].tolist()
+    """
+    if pif_file.shape != (134, 130):
+        raise ValueError(f"PIF must have shape (134, 130), got {pif_file.shape}")
+
+    if not (0 <= threshold <= 1):
+        raise ValueError(f"threshold must be in [0, 1], got {threshold}")
+
+    active_modules = np.zeros(8, dtype=bool)
 
-def estimate_active_modules(mask):
-    m, n = DETZ_BOUNDS, DETY_BOUNDS  # Separate modules
-    mods = []
     for module_no in range(8):
-        x1, x2, y1, y2 = select_isgri_module(module_no)
-        a = mask[x1:x2, y1:y2].flatten()
-        if len(a[a > 0.01]) / len(a) > 0.2:
-            mods.append(1)
-        else:
-            mods.append(0)
-    mods = np.array(mods)
-    return mods
+        z1, z2, y1, y2 = select_isgri_module(module_no)
+
+        # Get PIF values for this module
+        module_pif = pif_file[z1:z2, y1:y2].flatten()
+
+        # Count illuminated pixels (PIF > 0.01)
+        n_illuminated = np.sum(module_pif > 0.01)
+        n_total = len(module_pif)
+
+        # Check if fraction exceeds threshold
+        if n_illuminated / n_total > threshold:
+            active_modules[module_no] = True
+
+    return active_modules