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

isgri/catalog/wcs.py

@@ -0,0 +1,190 @@
+"""
+WCS coordinate transformations for celestial coordinates.
+
+Implements spherical coordinate rotations following Calabretta & Greisen (2002),
+"Representations of celestial coordinates in FITS", A&A 395, 1077-1122.
+https://doi.org/10.1051/0004-6361:20021327
+"""
+
+from typing import Union
+import numpy.typing as npt
+import numpy as np
+
+
+def spherical_to_cartesian(lon, lat):
+    """
+    Convert spherical coordinates to Cartesian unit vectors.
+
+    Args:
+        lon: Longitude in degrees
+        lat: Latitude in degrees
+
+    Returns:
+        tuple: (x, y, z) Cartesian coordinates on unit sphere
+    """
+    lon_rad = np.radians(lon)
+    lat_rad = np.radians(lat)
+
+    cos_lat = np.cos(lat_rad)
+    x = cos_lat * np.cos(lon_rad)
+    y = cos_lat * np.sin(lon_rad)
+    z = np.sin(lat_rad)
+
+    return x, y, z
+
+
+def cartesian_to_spherical(x, y, z):
+    """
+    Convert Cartesian unit vectors to spherical coordinates.
+
+    Args:
+        x, y, z: Cartesian coordinates
+
+    Returns:
+        tuple: (lon, lat) in degrees
+    """
+    # Clamp z to valid range for arcsin
+    z = np.clip(z, -1.0, 1.0)
+
+    lat = np.degrees(np.arcsin(z))
+    lon = np.degrees(np.arctan2(y, x))
+
+    return lon, lat
+
+
+def rotation_matrix(alpha_p, delta_p, phi_p=np.pi):
+    """
+    Compute rotation matrix for coordinate transformation.
+
+    Following Calabretta & Greisen (2002), equations (5) and (7).
+    Assumes theta_0 = 90° (most common case).
+
+    Args:
+        alpha_p: Reference point RA in radians
+        delta_p: Reference point Dec in radians
+        phi_p: Native longitude of celestial pole (default: π for standard orientation)
+
+    Returns:
+        ndarray: 3x3 rotation matrix
+    """
+    sa = np.sin(alpha_p)
+    ca = np.cos(alpha_p)
+    sd = np.sin(delta_p)
+    cd = np.cos(delta_p)
+    sp = np.sin(phi_p)
+    cp = np.cos(phi_p)
+
+    # Rotation matrix from Calabretta & Greisen (2002), eq. (5)
+    R = np.array(
+        [
+            [-sa * sp - ca * cp * sd, ca * sp - sa * cp * sd, cp * cd],
+            [sa * cp - ca * sp * sd, -ca * cp - sa * sp * sd, sp * cd],
+            [ca * cd, sa * cd, sd],
+        ]
+    )
+
+    return R
+
+
+def celestial_to_native(lon, lat, crval, longpole=180.0):
+    """
+    Transform from celestial (RA/Dec) to native spherical coordinates.
+
+    Args:
+        lon: Celestial longitude (RA) in degrees
+        lat: Celestial latitude (Dec) in degrees
+        crval: Reference point [RA, Dec] in degrees
+        longpole: Native longitude of celestial north pole (default: 180°)
+
+    Returns:
+        tuple: (phi, theta) native coordinates in degrees
+    """
+    alpha_p = np.radians(crval[0])
+    delta_p = np.radians(crval[1])
+    phi_p = np.radians(longpole)
+
+    x, y, z = spherical_to_cartesian(lon, lat)
+
+    R = rotation_matrix(alpha_p, delta_p, phi_p)
+    x_rot = R[0, 0] * x + R[0, 1] * y + R[0, 2] * z
+    y_rot = R[1, 0] * x + R[1, 1] * y + R[1, 2] * z
+    z_rot = R[2, 0] * x + R[2, 1] * y + R[2, 2] * z
+
+    phi, theta = cartesian_to_spherical(x_rot, y_rot, z_rot)
+
+    return phi, theta
+
+
+def native_to_celestial(phi, theta, crval, longpole=180.0):
+    """
+    Transform from native spherical to celestial (RA/Dec) coordinates.
+
+    Args:
+        phi: Native longitude in degrees
+        theta: Native latitude in degrees
+        crval: Reference point [RA, Dec] in degrees
+        longpole: Native longitude of celestial north pole (default: 180°)
+
+    Returns:
+        tuple: (lon, lat) celestial coordinates in degrees
+    """
+    alpha_p = np.radians(crval[0])
+    delta_p = np.radians(crval[1])
+    phi_p = np.radians(longpole)
+
+    x, y, z = spherical_to_cartesian(phi, theta)
+
+    R = rotation_matrix(alpha_p, delta_p, phi_p).T  # Transpose for inverse rotation
+    x_rot = R[0, 0] * x + R[0, 1] * y + R[0, 2] * z
+    y_rot = R[1, 0] * x + R[1, 1] * y + R[1, 2] * z
+    z_rot = R[2, 0] * x + R[2, 1] * y + R[2, 2] * z
+
+    lon, lat = cartesian_to_spherical(x_rot, y_rot, z_rot)
+
+    return lon, lat
+
+
+def compute_detector_offset(
+    src_ra: Union[float, npt.ArrayLike],
+    src_dec: Union[float, npt.ArrayLike],
+    pointing_ra: float,
+    pointing_dec: float,
+    z_ra: float,
+    z_dec: float,
+) -> tuple[Union[float, np.ndarray], Union[float, np.ndarray]]:
+    """
+    Compute source offset in INTEGRAL detector coordinates.
+
+    Args:
+        src_ra: Source RA in degrees
+        src_dec: Source Dec in degrees
+        pointing_ra: Pointing axis RA in degrees
+        pointing_dec: Pointing axis Dec in degrees
+        z_ra: Z-axis RA in degrees
+        z_dec: Z-axis Dec in degrees
+
+    Returns:
+        tuple: (y_offset, z_offset) in degrees (absolute values)
+    """
+    # Transform Z-axis to native coordinates to get roll angle
+    scZ_phi, _ = celestial_to_native(z_ra, z_dec, [pointing_ra, pointing_dec])
+    roll = scZ_phi - 180.0
+
+    # Transform source to native coordinates
+    phi, theta = celestial_to_native(src_ra, src_dec, [pointing_ra, pointing_dec])
+
+    # Convert to detector coordinates
+    # theta is elevation from pointing axis
+    theta = 90.0 - theta
+
+    # phi is azimuth, correct for roll
+    phi = phi + 90.0 - roll
+
+    # Project onto detector Y and Z axes
+    theta_rad = np.radians(theta)
+    phi_rad = np.radians(phi)
+
+    y = np.degrees(np.arctan(np.tan(theta_rad) * np.cos(phi_rad)))
+    z = np.degrees(np.arctan(np.tan(theta_rad) * np.sin(phi_rad)))
+
+    return np.abs(y), np.abs(z)

isgri/cli.py

@@ -0,0 +1,224 @@
+import click
+from pathlib import Path
+from .catalog import ScwQuery
+from .__version__ import __version__
+from .config import Config
+
+
+@click.group()
+@click.version_option(version=__version__)
+def main():
+    """ISGRI - INTEGRAL/ISGRI data analysis toolkit."""
+    pass
+
+
+def parse_time(time_str):
+    """
+    Parse time string as IJD float or ISO date string.
+
+    Parameters
+    ----------
+    time_str : str or None
+        Time as "YYYY-MM-DD" or IJD number
+
+    Returns
+    -------
+    float or str or None
+        Parsed time value
+    """
+    if time_str is None:
+        return None
+
+    try:
+        return float(time_str)
+    except ValueError:
+        return time_str
+
+
+@main.command()
+@click.option("--catalog", type=click.Path(), help="Path to catalog FITS file. If not provided, uses config value.")
+@click.option("--tstart", help="Start time (YYYY-MM-DD or IJD)")
+@click.option("--tstop", help="Stop time (YYYY-MM-DD or IJD)")
+@click.option("--ra", type=float, help="Right ascension (degrees)")
+@click.option("--dec", type=float, help="Declination (degrees)")
+@click.option("--fov", type=click.Choice(["full", "any"]), default="any", help="Field of view mode")
+@click.option("--max-chi", type=float, help="Maximum chi-squared value")
+@click.option("--chi-type", type=click.Choice(["RAW", "CUT", "GTI"]), default="CUT", help="Type of chi-squared value")
+@click.option("--revolution", "-r", help="Revolution number")
+@click.option("--output", "-o", type=click.Path(), help="Output file (.fits or .csv)")
+@click.option("--list-swids", is_flag=True, help="Only output SWID list")
+@click.option("--count", is_flag=True, help="Only show count")
+def query(catalog, tstart, tstop, ra, dec, fov, max_chi, chi_type, revolution, output, list_swids, count):
+    """
+    Query INTEGRAL science window catalog.
+
+    If no catalog path is provided, uses the default from configuration.
+    Multiple filters can be combined.
+
+    Examples:
+        Query by time range (IJD):
+
+            isgri query --tstart 3000 --tstop 3100
+
+        Query by time range (ISO date):
+
+            isgri query --tstart 2010-01-01 --tstop 2010-12-31
+
+        Query by sky position:
+
+            isgri query --ra 83.63 --dec 22.01 --fov full
+
+        Query with quality cut:
+
+            isgri query --max-chi 2.0 --chi-type CUT
+
+        Save results to file:
+
+            isgri query --tstart 3000 --tstop 3100 --output results.fits
+
+        Get only SWID list:
+
+            isgri query --tstart 3000 --tstop 3100 --list-swids
+
+        Count matching science windows:
+
+            isgri query --ra 83.63 --dec 22.01 --count
+    """
+    try:
+        # Load catalog
+        q = ScwQuery(catalog)
+        initial_count = len(q.catalog)
+
+        # Parse times (handle both IJD and ISO)
+        tstart = parse_time(tstart)
+        tstop = parse_time(tstop)
+
+        # Apply filters
+        if tstart or tstop:
+            q = q.time(tstart=tstart, tstop=tstop)
+
+        if ra is not None and dec is not None:
+            q = q.position(ra=ra, dec=dec, fov_mode=fov)
+
+        if max_chi is not None:
+            q = q.quality(max_chi=max_chi, chi_type=chi_type)
+
+        if revolution:
+            q = q.revolution(revolution)
+
+        results = q.get()
+
+        if count:
+            click.echo(len(results))
+
+        elif list_swids:
+            for swid in results["SWID"]:
+                click.echo(swid)
+
+        elif output:
+            if output.endswith(".csv"):
+                results.write(output, format="ascii.csv", overwrite=True)
+            else:
+                results.write(output, format="fits", overwrite=True)
+            click.echo(f"Saved {len(results)} SCWs to {output}")
+
+        else:
+            click.echo(f"Found {len(results)}/{initial_count} SCWs")
+            if len(results) > 0:
+                display_cols = ["SWID", "TSTART", "TSTOP", "RA_SCX", "DEC_SCX"]
+                chi_col = f"{chi_type}_CHI" if chi_type != "RAW" else "CHI"
+                if chi_col in results.colnames:
+                    display_cols.append(chi_col)
+                click.echo(results[display_cols][:10])
+                if len(results) > 10:
+                    click.echo(f"... and {len(results) - 10} more")
+
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@main.command()
+def config():
+    """
+    Show current configuration.
+
+    Displays paths to config file, archive directory, and catalog file,
+    along with their existence status.
+    """
+    cfg = Config()
+
+    click.echo(f"Config file: {cfg.path}")
+    click.echo(f"  Exists: {cfg.path.exists()}")
+    click.echo()
+
+    archive = cfg.archive_path
+    click.echo(f"Archive path: {archive if archive else '(not set)'}")
+    if archive:
+        click.echo(f"  Exists: {archive.exists()}")
+
+    try:
+        catalog = cfg.catalog_path
+        click.echo(f"Catalog path: {catalog if catalog else '(not set)'}")
+        if catalog:
+            click.echo(f"  Exists: {catalog.exists()}")
+    except FileNotFoundError as e:
+        click.echo(f"Catalog path: (configured but file not found)")
+        click.echo(f"  Error: {e}")
+
+
+@main.command()
+@click.option("--archive", type=click.Path(), help="INTEGRAL archive directory path")
+@click.option("--catalog", type=click.Path(), help="Catalog FITS file path")
+def config_set(archive, catalog):
+    """
+    Set configuration values.
+
+    Set default paths for archive directory and/or catalog file.
+    Paths are expanded (~ becomes home directory) and resolved to absolute paths.
+    Warns if path doesn't exist but allows setting anyway.
+
+    Examples:
+
+        Set archive path:
+
+            isgri config-set --archive /anita/archivio/
+
+        Set catalog path:
+
+            isgri config-set --catalog ~/data/scw_catalog.fits
+
+        Set both at once:
+
+            isgri config-set --archive /anita/archivio/ --catalog ~/data/scw_catalog.fits
+    """
+    if not archive and not catalog:
+        click.echo("Error: Specify at least one option (--archive or --catalog)", err=True)
+        raise click.Abort()
+
+    cfg = Config()
+
+    if archive:
+        archive_path = Path(archive).expanduser().resolve()
+        if not archive_path.exists():
+            click.echo(f"Warning: Archive path does not exist: {archive_path}", err=True)
+            if not click.confirm("Set anyway?"):
+                raise click.Abort()
+        cfg.set(archive_path=archive_path)
+        click.echo(f"✓ Archive path set to: {archive_path}")
+
+    if catalog:
+        catalog_path = Path(catalog).expanduser().resolve()
+        if not catalog_path.exists():
+            click.echo(f"Warning: Catalog file does not exist: {catalog_path}", err=True)
+            if not click.confirm("Set anyway?"):
+                raise click.Abort()
+        cfg.set(catalog_path=catalog_path)
+        click.echo(f"✓ Catalog path set to: {catalog_path}")
+
+    click.echo()
+    click.echo(f"Configuration saved to: {cfg.path}")
+
+
+if __name__ == "__main__":
+    main()

isgri/config.py

@@ -0,0 +1,151 @@
+import sys
+from pathlib import Path
+from typing import Optional
+from platformdirs import user_config_dir
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+
+class Config:
+    """
+    Configuration manager for ISGRI.
+
+    Manages paths to archive directory and catalog. Config is stored
+    in platform-specific location (~/.config/isgri/config.toml on Linux).
+    Falls back to local isgri_config.toml if global config doesn't exist.
+
+    Parameters
+    ----------
+    path : Path, optional
+        Custom config file path. If not provided, uses platform default.
+
+    Attributes
+    ----------
+    path : Path
+        Path to config file
+    archive_path : Path or None
+        Path to INTEGRAL archive directory
+    catalog_path : Path or None
+        Path to catalog FITS file (validated on access)
+    """
+
+    DEFAULT_PATH = Path(user_config_dir("isgri")) / "config.toml"
+
+    def __init__(self, path: Optional[Path] = None):
+        self.path = path or self.DEFAULT_PATH
+        self._config = None
+
+    @property
+    def config(self) -> dict:
+        """
+        Load and return config dictionary.
+
+        Returns
+        -------
+        dict
+            Configuration dictionary
+        """
+        if self._config is not None:
+            return self._config
+
+        if self.path.exists():
+            path = self.path
+        elif self.path == self.DEFAULT_PATH and Path("isgri_config.toml").exists():
+            print("Config file not found at default path, using local isgri_config.toml instead.", file=sys.stderr)
+            path = Path("isgri_config.toml")
+        else:
+            self._config = {}
+            return self._config
+
+        with open(path, "rb") as f:
+            self._config = tomllib.load(f)
+
+        return self._config
+
+    @property
+    def archive_path(self) -> Optional[Path]:
+        """
+        Get archive directory path from config.
+
+        Returns
+        -------
+        Path or None
+            Path to archive directory. No validation performed.
+        """
+        path_str = self.config.get("archive_path")
+        if path_str:
+            return Path(path_str)
+        return None
+
+    @property
+    def catalog_path(self) -> Optional[Path]:
+        """
+        Get catalog path from config.
+
+        Returns
+        -------
+        Path or None
+            Path to catalog FITS file
+
+        Raises
+        ------
+        FileNotFoundError
+            If configured path doesn't exist
+        """
+        path_str = self.config.get("catalog_path")
+        if not path_str:
+            return None
+        path = Path(path_str)
+        if not path.exists():
+            raise FileNotFoundError(f"Catalog path does not exist: {path}")
+        return path
+
+    def save(self):
+        """Save current config to file."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.path, "wb") as f:
+            tomli_w.dump(self._config or {}, f)
+
+    def create_new(self, archive_path: Optional[Path] = None, catalog_path: Optional[Path] = None):
+        """
+        Create new config file with given paths.
+
+        Parameters
+        ----------
+        archive_path : Path, optional
+            Path to archive directory
+        catalog_path : Path, optional
+            Path to catalog FITS file
+        """
+        self._config = {}
+        if archive_path:
+            self._config["archive_path"] = str(archive_path)
+        if catalog_path:
+            self._config["catalog_path"] = str(catalog_path)
+        self.save()
+
+    def set(self, archive_path: Optional[Path] = None, catalog_path: Optional[Path] = None):
+        """
+        Update config paths and save.
+
+        Parameters
+        ----------
+        archive_path : Path, optional
+            New archive directory path
+        catalog_path : Path, optional
+            New catalog path
+        """
+        if archive_path:
+            self.config["archive_path"] = str(archive_path)
+        if catalog_path:
+            self.config["catalog_path"] = str(catalog_path)
+
+        self.save()
+
+    def __repr__(self):
+        return f"Config(path={self.path}, archive={self.archive_path}, catalog={self.catalog_path})"