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

isgri/__init__.py

@@ -0,0 +1 @@
+from .__version__ import __version__

isgri/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

isgri/catalog/__init__.py

@@ -0,0 +1,3 @@
+from .scwquery import ScwQuery
+
+__all__ = ["ScwQuery"]

isgri/catalog/builder.py

@@ -0,0 +1,90 @@
+from isgri.utils import LightCurve, QualityMetrics
+import numpy as np
+import os, subprocess
+from typing import Optional
+from joblib import Parallel, delayed  # type: ignore
+import multiprocessing
+
+
+class CatalogBuilder:
+    def __init__(
+        self,
+        archive_path: str,
+        catalog_path: str,
+        lightcurve_cache: Optional[str] = None,
+        n_cores: Optional[int] = None,
+    ):
+        self.archive_path = archive_path
+        self.catalog_path = catalog_path
+        self.lightcurve_cache = lightcurve_cache
+        self.n_cores = n_cores if n_cores is not None else multiprocessing.cpu_count()
+        self.catalog = self._load_catalog()
+
+    def _load_catalog(self):
+        if not os.path.exists(self.catalog_path):
+            empty_structure = CatalogStructure.get_empty_structure()
+            return empty_structure
+        else:
+            catalog = CatalogStructure.load_from_fits(self.catalog_path)
+            return catalog
+
+    def _process_scw(self, path) -> tuple[dict, list]:
+        lc = LightCurve.load_data(path)
+
+        time, full_counts = lc.rebin(1, emin=15, emax=1000, local_time=False)
+        _, module_counts = lc.rebin_by_modules(1, emin=15, emax=1000, local_time=False)
+        module_counts.insert(0, full_counts)
+        module_counts = np.array(module_counts)
+        quality = QualityMetrics.compute(lc)
+        quality.module_data = {"time": time, "counts": module_counts[1:]}
+        raw_chisq = quality.raw_chi_squared()
+        clipped_chisq = quality.sigma_clip_chi_squared()
+        gti_chisq = quality.gti_chi_squared()
+
+        # cnames = [
+        #     ("REVOL", int),
+        #     ("SWID", "S12"),
+        #     ("TSTART", float),
+        #     ("TSTOP", float),
+        #     ("TELAPSE", float),
+        #     ("RA_SCX", float),
+        #     ("DEC_SCX", float),
+        #     ("RA_SCZ", float),
+        #     ("DEC_SCZ", float),
+        #     ("NoEVTS", int),
+        #     ("LCs", np.ndarray),
+        #     ("GTIs", np.ndarray),
+        #     ("CHI", float),
+        #     ("CUT_CHI", float),
+        #     ("GTI_CHI", float),
+        # ]
+        table_data = {
+            "REVOL": lc.metadata["REVOL"],
+            "SWID": lc.metadata["SWID"],
+            "TSTART": lc.metadata["TSTART"],
+            "TSTOP": lc.metadata["TSTOP"],
+            "ONTIME": lc.metadata["TELAPSE"],
+            "RA_SCX": lc.metadata["RA_SCX"],
+            "DEC_SCX": lc.metadata["DEC_SCX"],
+            "RA_SCZ": lc.metadata["RA_SCZ"],
+            "DEC_SCZ": lc.metadata["DEC_SCZ"],
+            "NoEVTS": len(lc.time),
+            "CHI": raw_chisq,
+            "CUT_CHI": clipped_chisq,
+            "GTI_CHI": gti_chisq,
+        }
+        array_data = [lc.metadata["SWID"], time, module_counts, lc.gti]
+        return table_data, array_data
+
+    def _process_rev(self, rev_paths: list[str]) -> tuple[list[dict], list[list]]:
+        data = Parallel(n_jobs=self.n_cores, backend="multiprocessing")(
+            delayed(self._process_scw)(path) for path in rev_paths
+        )
+        table_data_list, array_data_list = zip(*data)
+        return table_data_list, array_data_list
+
+    def _find_scws(self) -> tuple[np.ndarray[str], np.ndarray[str]]:
+        # Find all SCW files in the archive
+        scws_files = subprocess.run(
+            ["find", "-L", self.archive_path, "-name", "isgri_events.fits.gz"], capture_output=True, text=True
+        )

isgri/catalog/scwquery.py

@@ -0,0 +1,524 @@
+from astropy.table import Table
+from astropy.coordinates import SkyCoord
+from astropy.time import Time
+from astropy import units as u
+import numpy as np
+from pathlib import Path
+from typing import Optional, Union, Literal
+from dataclasses import dataclass
+from isgri.utils import ijd2utc, utc2ijd
+from .wcs import compute_detector_offset
+from ..config import Config
+
+
+@dataclass
+class Filter:
+    """Filter with mask and parameters"""
+
+    name: str
+    mask: np.ndarray
+    params: dict
+
+
+class ScwQuery:
+    """
+    Query interface for INTEGRAL SCW catalog.
+
+    Parameters
+    ----------
+    catalog_path : str or Path
+        Path to SCW catalog FITS file
+
+    Examples
+    --------
+    >>> query = ScwQuery("data/scw_catalog.fits")
+    >>> results = query.time(tstart=3000).quality(max_chi=2.0).get()
+    >>>
+    >>> # FOV-based filtering
+    >>> results = query.position(ra=83.63, dec=22.01, fov_mode="full").get()
+
+    See Also
+    --------
+    time : Filter by time range
+    quality : Filter by data quality
+    position : Filter by sky position
+    revolution : Filter by revolution number
+    """
+
+    ISGRI_FULLY_CODED = 4.0  # half-width in degrees (8x8 total)
+    ISGRI_DETECTOR_EDGE = 14.5  # half-width in degrees (29x29 total)
+
+    def __init__(self, catalog_path: Optional[Union[str, Path]] = None):
+        if catalog_path is None:
+            cfg = Config()
+            catalog_path = cfg.catalog_path
+            if catalog_path is None:
+                raise ValueError("No catalog_path provided and no catalog_path in config")
+
+        self.catalog_path = Path(catalog_path)
+        self._catalog: Optional[Table] = None
+        self._mask: Optional[np.ndarray] = None
+        self._filters: list[Filter] = []
+
+    @property
+    def catalog(self) -> Table:
+        """Lazy load catalog from FITS file"""
+        if self._catalog is None:
+            if not self.catalog_path.exists():
+                raise FileNotFoundError(f"Catalog not found: {self.catalog_path}")
+            self._catalog = Table.read(self.catalog_path)
+            self._validate_catalog()
+        return self._catalog
+
+    def _validate_catalog(self):
+        """Check required columns exist"""
+        required = ["SWID", "TSTART", "TSTOP", "RA_SCX", "DEC_SCX", "RA_SCZ", "DEC_SCZ", "CHI"]
+        missing = [col for col in required if col not in self._catalog.colnames]
+        if missing:
+            raise ValueError(f"Catalog missing required columns: {missing}")
+
+    @property
+    def mask(self) -> np.ndarray:
+        """Initialize mask if needed"""
+        if self._mask is None:
+            self._mask = np.ones(len(self.catalog), dtype=bool)
+        return self._mask
+
+    def time(
+        self, tstart: Optional[Union[float, str]] = None, tstop: Optional[Union[float, str]] = None
+    ) -> "ScwQuery":
+        """
+        Filter by time range.
+
+        Parameters
+        ----------
+        tstart : float or str, optional
+            Start time in IJD (float) or ISO format (str)
+        tstop : float or str, optional
+            Stop time in IJD (float) or ISO format (str)
+
+        Returns
+        -------
+        ScwQuery
+            Self for method chaining
+
+        Examples
+        --------
+        >>> query.time(tstart="2010-01-01", tstop="2010-12-31")
+        >>> query.time(tstart=3000.0)  # IJD format
+        >>> query.time(tstop="2015-01-01")  # Only upper bound
+        """
+        mask = np.ones(len(self.catalog), dtype=bool)
+
+        if tstart is not None:
+            tstart_ijd = self._parse_time(tstart)
+            mask &= self.catalog["TSTOP"] >= tstart_ijd
+
+        if tstop is not None:
+            tstop_ijd = self._parse_time(tstop)
+            mask &= self.catalog["TSTART"] <= tstop_ijd
+
+        self._add_filter(Filter(name="time", mask=mask, params={"tstart": tstart, "tstop": tstop}))
+        return self
+
+    def quality(self, max_chi: Optional[float] = None, chi_type: str = "CHI") -> "ScwQuery":
+        """
+        Filter by quality metric (lower chi-squared means better quality).
+
+        Parameters
+        ----------
+        max_chi : float, optional
+            Maximum chi-squared value to accept
+        chi_type : str, default "CHI"
+            Column name: "CHI", "CUT_CHI", or "GTI_CHI"
+
+        Returns
+        -------
+        ScwQuery
+            Self for method chaining
+
+        Examples
+        --------
+        >>> query.quality(max_chi=2.0)  # High quality data
+        >>> query.quality(max_chi=5.0, chi_type="CUT_CHI")  # Alternative metric
+
+        """
+        if chi_type not in self.catalog.colnames:
+            raise ValueError(f"Column {chi_type} not found in catalog")
+
+        mask = np.ones(len(self.catalog), dtype=bool)
+
+        if max_chi is not None:
+            if max_chi <= 0:
+                raise ValueError("max_chi must be positive")
+            mask &= self.catalog[chi_type] <= max_chi
+
+        self._add_filter(Filter(name="quality", mask=mask, params={"max_chi": max_chi, "chi_type": chi_type}))
+        return self
+
+    def position(
+        self,
+        ra: Optional[Union[float, str]] = None,
+        dec: Optional[Union[float, str]] = None,
+        radius: Optional[float] = None,
+        target: Optional[SkyCoord] = None,
+        fov_mode: Optional[Literal["full", "any"]] = None,
+        max_offset: Optional[float] = None,
+    ) -> "ScwQuery":
+        """
+        Filter by sky position using angular separation or FOV constraints.
+
+        Parameters
+        ----------
+        ra : float or str, optional
+            Right ascension in degrees or HMS format
+        dec : float or str, optional
+            Declination in degrees or DMS format
+        radius : float, optional
+            Angular separation radius in degrees (simple cone search)
+        target : SkyCoord, optional
+            Target position as SkyCoord (alternative to ra/dec)
+        fov_mode : {'full', 'any'}, optional
+            FOV filtering mode using detector coordinates:
+            - 'full': fully coded FOV (both |Y| and |Z| <= 4 deg)
+            - 'any': detector FOV (both |Y| and |Z| <= 14.5 deg)
+        max_offset : float, optional
+            Custom maximum offset in degrees (uses max of |Y|, |Z|)
+
+        Returns
+        -------
+        ScwQuery
+            Self for method chaining
+
+        Notes
+        -----
+        When fov_mode or max_offset is specified, uses compute_detector_offset() to calculate
+        detector Y/Z offsets from pointing center. Otherwise uses simple angular
+        separation from X-axis pointing.
+
+        Examples
+        --------
+        >>> query.position(ra=83.63, dec=22.01, radius=5.0)
+        >>> query.position(ra=83.63, dec=22.01, fov_mode="full")
+        >>> query.position(ra="05h34m31s", dec="+22d00m52s", fov_mode="any")
+        """
+        if target is None:
+            if ra is None or dec is None:
+                return self
+            target = self._parse_position(ra, dec)
+
+        if isinstance(ra, (int, float)) and not (0 <= ra < 360):
+            raise ValueError(f"RA must be in [0, 360), got {ra}")
+
+        if isinstance(dec, (int, float)) and not (-90 <= dec <= 90):
+            raise ValueError(f"Dec must be in [-90, 90], got {dec}")
+
+        if radius is not None and radius <= 0:
+            raise ValueError("radius must be positive")
+
+        if fov_mode is not None and fov_mode not in ["full", "any"]:
+            raise ValueError(f"Invalid fov_mode: {fov_mode}. Use 'full' or 'any'")
+
+        mask = np.ones(len(self.catalog), dtype=bool)
+
+        if fov_mode is not None or max_offset is not None:
+            y_off, z_off, max_off = self._compute_detector_offsets(target)
+
+            if fov_mode == "full":
+                mask &= (np.abs(y_off) <= self.ISGRI_FULLY_CODED) & (np.abs(z_off) <= self.ISGRI_FULLY_CODED)
+                filter_params = {
+                    "ra": target.ra.deg,
+                    "dec": target.dec.deg,
+                    "fov_mode": "full",
+                    "max_offset": self.ISGRI_FULLY_CODED,
+                    "y_offset": y_off,
+                    "z_offset": z_off,
+                    "max_offset_actual": max_off,
+                }
+
+            elif fov_mode == "any":
+                mask &= (np.abs(y_off) <= self.ISGRI_DETECTOR_EDGE) & (np.abs(z_off) <= self.ISGRI_DETECTOR_EDGE)
+                filter_params = {
+                    "ra": target.ra.deg,
+                    "dec": target.dec.deg,
+                    "fov_mode": "any",
+                    "max_offset": self.ISGRI_DETECTOR_EDGE,
+                    "y_offset": y_off,
+                    "z_offset": z_off,
+                    "max_offset_actual": max_off,
+                }
+
+            elif max_offset is not None:
+                mask &= max_off <= max_offset
+                filter_params = {
+                    "ra": target.ra.deg,
+                    "dec": target.dec.deg,
+                    "fov_mode": "custom",
+                    "max_offset": max_offset,
+                    "y_offset": y_off,
+                    "z_offset": z_off,
+                    "max_offset_actual": max_off,
+                }
+
+        else:
+            pointings_x = SkyCoord(self.catalog["RA_SCX"], self.catalog["DEC_SCX"], unit="deg")
+            separations = target.separation(pointings_x).deg
+
+            if radius is not None:
+                if radius <= 0:
+                    raise ValueError("radius must be positive")
+                mask &= separations <= radius
+
+            filter_params = {
+                "ra": target.ra.deg,
+                "dec": target.dec.deg,
+                "radius": radius,
+                "separations": separations,
+            }
+
+        self._add_filter(Filter(name="position", mask=mask, params=filter_params))
+        return self
+
+    def revolution(self, revolutions: Union[int, str, list[Union[int, str]]]) -> "ScwQuery":
+        """
+        Filter by revolution number(s).
+
+        Parameters
+        ----------
+        revolutions : int, str, or list
+            Revolution number(s) as integer (255), 4-digit string ("0255"),
+            or list of mixed types
+
+        Returns
+        -------
+        ScwQuery
+            Self for method chaining
+
+        Examples
+        --------
+        >>> query.revolution(255)
+        >>> query.revolution("0255")
+        >>> query.revolution([255, "0256", 300])
+        """
+        if not isinstance(revolutions, list):
+            revolutions = [revolutions]
+
+        rev_ints = []
+        for rev in revolutions:
+            if isinstance(rev, int):
+                rev_ints.append(rev)
+            elif isinstance(rev, str):
+                if len(rev) != 4:
+                    raise ValueError(f"Revolution string must be 4 digits: '{rev}'")
+                try:
+                    rev_ints.append(int(rev))
+                except ValueError:
+                    raise ValueError(f"Invalid revolution string: '{rev}'")
+            else:
+                raise TypeError(f"Revolution must be int or str, got {type(rev)}")
+
+        mask = np.isin(self.catalog["REVOL"], rev_ints)
+        self._add_filter(Filter(name="revolution", mask=mask, params={"revolutions": rev_ints}))
+        return self
+
+    def get(self) -> Table:
+        """
+        Apply all filters and return filtered catalog.
+
+        Returns
+        -------
+        Table
+            Filtered catalog as astropy Table
+
+        Notes
+        -----
+        This is typically the final call in a filter chain:
+
+        Examples
+        --------
+        >>> results = query.time(tstart=3000).quality(max_chi=2.0).get()
+        >>> print(len(results))
+        """
+        combined_mask = self.mask.copy()
+        for filt in self._filters:
+            combined_mask &= filt.mask
+        return self.catalog[combined_mask]
+
+    def count(self) -> int:
+        """
+        Count SCWs matching current filters.
+
+        Returns
+        -------
+        int
+            Number of matching SCWs
+
+        Examples
+        --------
+        >>> query.time(tstart=3000).count()
+        150
+        >>> # Faster than len(query.get()) for large catalogs
+        """
+        return len(self.get())
+
+    def reset(self) -> "ScwQuery":
+        """
+        Clear all filters and reset to full catalog.
+
+        Returns
+        -------
+        ScwQuery
+            Self for method chaining
+
+        Examples
+        --------
+        >>> query.time(tstart=3000).get()  # First query
+        >>> query.reset()  # Clear filters
+        >>> query.quality(max_chi=2.0).get()  # New query
+        """
+        self._filters.clear()
+        self._mask = None
+        return self
+
+    def _compute_detector_offsets(self, target: SkyCoord) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Compute detector Y/Z offsets using compute_detector_offset.
+
+        Parameters
+        ----------
+        target : SkyCoord
+            Target sky position
+
+        Returns
+        -------
+        y_offset : ndarray
+            Y-axis offsets in degrees
+        z_offset : ndarray
+            Z-axis offsets in degrees
+        max_offset : ndarray
+            Maximum of |Y| and |Z| offsets
+        """
+        y_off, z_off = compute_detector_offset(
+            target.ra.deg,
+            target.dec.deg,
+            self.catalog["RA_SCX"],
+            self.catalog["DEC_SCX"],
+            self.catalog["RA_SCZ"],
+            self.catalog["DEC_SCZ"],
+        )
+        max_off = np.maximum(np.abs(y_off), np.abs(z_off))
+        return y_off, z_off, max_off
+
+    def _add_filter(self, filter: Filter):
+        """Replace existing filter with same name or add new filter"""
+        self._filters = [f for f in self._filters if f.name != filter.name]
+        self._filters.append(filter)
+
+    def _parse_time(self, time: Union[float, str]) -> float:
+        """
+        Parse time to IJD format.
+
+        Parameters
+        ----------
+        time : float or str
+            Time as IJD (< 51544), MJD (>= 51544), or ISO string
+
+        Returns
+        -------
+        float
+            Time in IJD format
+        """
+        if isinstance(time, (int, float)):
+            return time if time < 51544 else time - 51544
+        if isinstance(time, str):
+            return utc2ijd(time)
+        raise TypeError(f"Invalid time type: {type(time)}")
+
+    def _parse_position(self, ra: Union[float, str], dec: Union[float, str]) -> SkyCoord:
+        """
+        Parse coordinates to SkyCoord.
+
+        Parameters
+        ----------
+        ra : float or str
+            Right ascension as degrees or HMS string
+        dec : float or str
+            Declination as degrees or DMS string
+
+        Returns
+        -------
+        SkyCoord
+            Parsed coordinate
+        """
+        if isinstance(ra, (int, float)) and isinstance(dec, (int, float)):
+            return SkyCoord(ra, dec, unit="deg")
+
+        if isinstance(ra, str) and isinstance(dec, str):
+            try:
+                return SkyCoord(ra, dec, unit=(u.hourangle, u.deg))
+            except:
+                try:
+                    return SkyCoord(ra, dec, unit="deg")
+                except Exception as e:
+                    raise ValueError(f"Could not parse position: {ra}, {dec}") from e
+
+        raise TypeError(f"Invalid position types: {type(ra)}, {type(dec)}")
+
+    @property
+    def filters_summary(self) -> dict:
+        """
+        Get summary of applied filters.
+
+        Returns
+        -------
+        dict
+            Dictionary mapping filter names to their parameters
+        """
+        return {f.name: f.params for f in self._filters}
+
+    def get_offsets(self, ra: Union[float, str], dec: Union[float, str]) -> Table:
+        """
+        Get filtered catalog with detector offsets computed.
+
+        Parameters
+        ----------
+        ra : float or str
+            Right ascension
+        dec : float or str
+            Declination
+
+        Returns
+        -------
+        Table
+            Filtered catalog with Y_OFFSET, Z_OFFSET, MAX_OFFSET columns added
+
+        Examples
+        --------
+        >>> results = query.time(tstart=3000).get_offsets(ra=83.63, dec=22.01)
+        >>> fully_coded = results[results['MAX_OFFSET'] <= 4.0]
+        """
+        target = self._parse_position(ra, dec)
+        y_off, z_off, max_off = self._compute_detector_offsets(target)
+
+        result = self.get()
+        combined_mask = self._get_combined_mask()
+        result["Y_OFFSET"] = y_off[combined_mask]
+        result["Z_OFFSET"] = z_off[combined_mask]
+        result["MAX_OFFSET"] = max_off[combined_mask]
+        return result
+
+    def _get_combined_mask(self) -> np.ndarray:
+        """Get combined mask from all active filters"""
+        combined_mask = self.mask.copy()
+        for filt in self._filters:
+            combined_mask &= filt.mask
+        return combined_mask
+
+    def __repr__(self) -> str:
+        n_total = len(self.catalog)
+        n_selected = self.count()
+        return (
+            f"ScwQuery(catalog={self.catalog_path.name}, "
+            f"total={n_total}, selected={n_selected}, "
+            f"filters={list(self.filters_summary.keys())})"
+        )