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

isgri/catalog/wcs.py

@@ -1,190 +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)
+"""
+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()