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

isgri/utils/time_conversion.py

@@ -1,39 +1,210 @@
+"""
+Time Conversion Utilities for INTEGRAL
+=======================================
+
+Convert between INTEGRAL Julian Date (IJD) and other time formats.
+
+INTEGRAL uses IJD as its standard time format:
+- IJD 0.0 = 2000-01-01 00:00:00 TT (Terrestrial Time)
+- IJD = MJD - 51544.0
+- IJD uses TT time scale (atomic time)
+
+Functions
+---------
+ijd2utc : Convert IJD to UTC ISO format
+utc2ijd : Convert UTC ISO format to IJD
+ijd2mjd : Convert IJD to Modified Julian Date
+mjd2ijd : Convert Modified Julian Date to IJD
+
+Examples
+--------
+>>> from isgri.utils import ijd2utc, utc2ijd
+>>>
+>>> # Convert IJD to readable format
+>>> utc_str = ijd2utc(3000.5)
+>>> print(utc_str)
+2008-03-17 11:58:55.816
+>>>
+>>> # Round trip conversion
+>>> ijd = utc2ijd("2010-01-01 12:00:00")
+>>> print(f"IJD: {ijd:.3f}")
+IJD: 3653.500
+
+Notes
+-----
+- IJD uses TT (Terrestrial Time) scale for consistency with spacecraft clock
+- UTC conversions account for leap seconds automatically
+- Precision: ~1 microsecond for typical astronomical observations
+"""
+
 from astropy.time import Time
+from typing import Union
+import numpy as np
+from numpy.typing import NDArray
+
+# INTEGRAL epoch: MJD 51544.0 = 2000-01-01 00:00:00 TT
+INTEGRAL_EPOCH_MJD = 51544.0
 
 
-def ijd2utc(t):
+def ijd2utc(ijd_time: Union[float, NDArray[np.float64]]) -> Union[str, NDArray[np.str_]]:
     """
-    Converts IJD (INTEGRAL Julian Date) time to UTC ISO format.
+    Convert IJD (INTEGRAL Julian Date) to UTC ISO format.
+
+    Parameters
+    ----------
+    ijd_time : float or ndarray
+        IJD time value(s). Can be scalar or array.
+
+    Returns
+    -------
+    utc_str : str or ndarray of str
+        UTC time in ISO format 'YYYY-MM-DD HH:MM:SS.sss'
+        Scalar if input is scalar, array if input is array.
+
+    Examples
+    --------
+    >>> ijd2utc(0.0)
+    '1999-12-31 23:58:55.816'
 
-    Args:
-        t (float or ndarray): IJD time value(s).
+    >>> ijd2utc(1000.5)
+    '2002-09-27 11:58:55.816'
 
-    Returns:
-        str or ndarray: UTC time in ISO format (YYYY-MM-DD HH:MM:SS.sss).
+    >>> # Array conversion
+    >>> ijds = np.array([0.0, 1000.0, 2000.0])
+    >>> utcs = ijd2utc(ijds)
+    >>> print(utcs[0])
+    1999-12-31 23:58:55.816
 
-    Examples:
-        >>> ijd2utc(0.0)
-        '1999-12-31 23:58:55.817'
-        >>> ijd2utc(1000.5)
-        '2002-09-27 11:58:55.816'
+    See Also
+    --------
+    utc2ijd : Inverse conversion (UTC to IJD)
+    ijd2mjd : Convert IJD to MJD
+
+    Notes
+    -----
+    - IJD 0.0 corresponds to 2000-01-01 00:00:00 TT
+    - Accounts for leap seconds via UTC scale
+    - Output precision is milliseconds (3 decimal places)
     """
-    return Time(t + 51544, format="mjd", scale="tt").utc.iso
+    mjd = ijd_time + INTEGRAL_EPOCH_MJD
+    t = Time(mjd, format="mjd", scale="tt")
+    return t.utc.iso
 
 
-def utc2ijd(t):
+def utc2ijd(utc_time: Union[str, NDArray[np.str_]]) -> Union[float, NDArray[np.float64]]:
     """
-    Converts UTC ISO format time to IJD (INTEGRAL Julian Date).
+    Convert UTC ISO format to IJD (INTEGRAL Julian Date).
+
+    Parameters
+    ----------
+    utc_time : str or ndarray of str
+        UTC time in ISO format. Accepts:
+        - 'YYYY-MM-DD HH:MM:SS' (space separator)
+        - 'YYYY-MM-DDTHH:MM:SS' (T separator)
+        - Can include fractional seconds
+
+    Returns
+    -------
+    ijd_time : float or ndarray
+        IJD time value(s)
+
+    Examples
+    --------
+    >>> utc2ijd('1999-12-31 23:58:55.816')
+    0.0
+
+    >>> utc2ijd('2002-09-27 00:00:00')
+    1000.0
+
+    >>> # ISO 8601 format (with T separator)
+    >>> utc2ijd('2010-01-01T12:00:00')
+    3653.5
+
+    >>> # Array conversion
+    >>> utcs = ['2000-01-01 00:00:00', '2000-01-02 00:00:00']
+    >>> ijds = utc2ijd(utcs)
+    >>> print(ijds)
+    [0.00074287 1.00074287]
+
+    See Also
+    --------
+    ijd2utc : Inverse conversion (IJD to UTC)
+    mjd2ijd : Convert MJD to IJD
+
+    Notes
+    -----
+    - Automatically handles both space and T separators
+    - Accounts for leap seconds
+    - Returns TT (Terrestrial Time) scale
+    """
+    # Handle T separator in ISO 8601 format
+    if isinstance(utc_time, str):
+        utc_time = utc_time.replace("T", " ")
+    elif isinstance(utc_time, np.ndarray):
+        # Vectorized string replacement for arrays
+        utc_time = np.char.replace(utc_time, "T", " ")
+
+    t = Time(utc_time, format="iso", scale="utc")
+    return t.tt.mjd - INTEGRAL_EPOCH_MJD
+
+
+def ijd2mjd(ijd_time: Union[float, NDArray[np.float64]]) -> Union[float, NDArray[np.float64]]:
+    """
+    Convert IJD to Modified Julian Date (MJD).
+
+    Simple offset: MJD = IJD + 51544.0
+
+    Parameters
+    ----------
+    ijd_time : float or ndarray
+        IJD time value(s)
+
+    Returns
+    -------
+    mjd_time : float or ndarray
+        MJD time value(s)
+
+    Examples
+    --------
+    >>> ijd2mjd(0.0)
+    51544.0
+
+    >>> ijd2mjd(3653.5)
+    55197.5
+
+    See Also
+    --------
+    mjd2ijd : Inverse conversion
+    """
+    return ijd_time + INTEGRAL_EPOCH_MJD
+
+
+def mjd2ijd(mjd_time: Union[float, NDArray[np.float64]]) -> Union[float, NDArray[np.float64]]:
+    """
+    Convert Modified Julian Date (MJD) to IJD.
+
+    Simple offset: IJD = MJD - 51544.0
+
+    Parameters
+    ----------
+    mjd_time : float or ndarray
+        MJD time value(s)
+
+    Returns
+    -------
+    ijd_time : float or ndarray
+        IJD time value(s)
 
-    Args:
-        t (str or ndarray): UTC time in ISO format (YYYY-MM-DD HH:MM:SS).
+    Examples
+    --------
+    >>> mjd2ijd(51544.0)
+    0.0
 
-    Returns:
-        float or ndarray: IJD time value(s).
+    >>> mjd2ijd(55197.5)
+    3653.5
 
-    Examples:
-        >>> utc2ijd('1999-12-31 23:58:55.817')
-        0.0
-        >>> utc2ijd('2002-09-27 00:00:00')
-        1000.0
+    See Also
+    --------
+    ijd2mjd : Inverse conversion
     """
-    return Time(t, format="iso", scale="utc").tt.mjd - 51544
+    return mjd_time - INTEGRAL_EPOCH_MJD

isgri-0.4.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: isgri
+Version: 0.4.0
+Summary: Python package for INTEGRAL IBIS/ISGRI lightcurve analysis
+Author: Dominik Patryk Pacholski
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: astropy
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# ISGRI
+
+Python toolkit for INTEGRAL/ISGRI data analysis.
+
+## Features
+
+### 📊 SCW Catalog Query
+Query INTEGRAL Science Window catalogs with a fluent Python API:
+- Filter by time, position, quality, revolution
+- Calculate detector offsets
+- Export results to FITS/CSV
+
+### 💡 Light Curve Analysis
+Extract and analyze ISGRI light curves:
+- Event loading with PIF weighting
+- Custom time binning
+- Module-by-module analysis
+- Quality metrics (chi-squared tests)
+- Time conversions (IJD ↔ UTC)
+
+
+## Installation
+
+```bash
+pip install isgri
+```
+
+## Quick Start
+
+### Query SCW Catalog
+
+```python
+from isgri.catalog import ScwQuery
+
+# Load catalog
+cat = ScwQuery("path_to_catalog.fits")
+
+# Find Crab observations in 2010 with good quality
+results = (cat
+    .time(tstart="2010-01-01", tstop="2010-12-31")
+    .quality(max_chi=2.0)
+    .position(ra=83.63, dec=22.01, fov_mode="full")
+    .get()
+)
+
+print(f"Found {len(results)} observations")
+```
+
+### Analyze Light Curves
+
+```python
+from isgri.utils import LightCurve, QualityMetrics
+
+# Load events with PIF weighting
+lc = LightCurve.load_data(
+    events_path="isgri_events.fits",
+    pif_path="source_model.fits",
+    pif_threshold=0.5
+)
+
+# Create 1-second binned light curve
+time, counts = lc.rebin(binsize=1.0, emin=20, emax=100)
+
+# Compute quality metrics
+qm = QualityMetrics(lc, binsize=1.0, emin=20, emax=100)
+chi = qm.raw_chi_squared()
+print(f"Chisq/dof = {chi:.2f}")
+```
+
+## Documentation
+
+- **Catalog Tutorial**: [scwquery_walkthrough.ipynb](https://github.com/dominp/isgri/blob/main/demo/scwquery_walkthrough.ipynb)
+- **Light Curve Tutorial**: [lightcurve_walkthrough.ipynb](https://github.com/dominp/isgri/blob/main/demo/lightcurve_walkthrough.ipynb)
+- **API Reference**: Use `help()` in Python or see docstrings
+
+## Project Structure
+
+```
+isgri/
+├── catalog/          # SCW catalog query tools
+│   ├── scwquery.py   # Main query interface
+│   └── wcs.py        # Coordinate transformations
+└── utils/            # Light curve analysis utilities
+    ├── lightcurve.py # Light curve class
+    ├── quality.py    # Quality metrics
+    ├── pif.py        # PIF tools
+    ├── file_loaders.py
+    └── time_conversion.py
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- astropy
+- numpy

isgri-0.4.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+isgri/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+isgri/catalog/__init__.py,sha256=5GTSWfc32HA8z9Q-6taYxPpQi8vTlFfqXUbdJVPITvE,55
+isgri/catalog/scwquery.py,sha256=QAZhbbrXOoTghYXotQxZODGNFFIp9XLv_lZ1nwyYBY8,16821
+isgri/catalog/wcs.py,sha256=KJfIpo-sMVLUBfkv6CGUyTfaBXWpfDQPJEvVhXne-48,5372
+isgri/utils/__init__.py,sha256=H83Al7urc6LNW5KUzUBRdtRBUTahiZmkehKFiK90RrU,183
+isgri/utils/file_loaders.py,sha256=_1KBqxUnQUXs1fD4GSP7-nDsYi9HblpNFkKyG2037To,12000
+isgri/utils/lightcurve.py,sha256=yQMk4H9k7zZ8JvrtPQF6_mZVbk5_MIq_zMOT3lyKZgw,13724
+isgri/utils/pif.py,sha256=UsLKNaso4h-ztkaUotm-XSePx7ZJDQlz3vRKDOaoxfA,8362
+isgri/utils/quality.py,sha256=FKCvvDQ_Ys6zm-nKvwHt8_Mz58XFEWvj7keCHf_4sc0,12959
+isgri/utils/time_conversion.py,sha256=RU9NQtPAWZI-HQf5SS1fMCvsozrgBAApIGp8xIxBc2I,4994
+isgri-0.4.0.dist-info/METADATA,sha256=A2d8vquGiiGsfEkUXjfcbgz5O2v7cJsiHkgV9x-jS5k,2583
+isgri-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+isgri-0.4.0.dist-info/licenses/LICENSE,sha256=Q8oxmHR1cSnEXSHCjY3qeXMtupZI_1ZQZ1MBt4oeANE,1102
+isgri-0.4.0.dist-info/RECORD,,

isgri-0.2.0.dist-info/METADATA

@@ -1,66 +0,0 @@
-Metadata-Version: 2.4
-Name: isgri
-Version: 0.2.0
-Summary: Python package for INTEGRAL IBIS/ISGRI lightcurve analysis
-Author: Dominik Patryk Pacholski
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: astropy>=7.2.0
-Requires-Dist: numpy>=2.3.5
-Description-Content-Type: text/markdown
-
-# isgri
-
-Python package for ISGRI (INTEGRAL Soft Gamma-Ray Imager) lightcurve analysis.
-
-## Installation
-
-```bash
-pip install isgri
-```
-
-Or from source:
-```bash
-git clone https://github.com/dominp/isgri.git
-cd isgri
-pip install -e .
-```
-
-## Quick Start
-
-```python
-from isgri.utils import LightCurve, QualityMetrics
-
-# Load data
-lc = LightCurve.load_data(
-    events_path='/path/to/isgri_events.fits',
-    pif_path='/path/to/source_model.fits'
-)
-
-# Create lightcurve
-time, counts = lc.rebin(binsize=1.0, emin=30, emax=300)
-
-# Create lightcurve per each module
-times, module_counts = lc.rebin_by_modules(binsize=1.0, emin=30, emax=300)
-
-# Compute quality metrics
-qm = QualityMetrics(lc, binsize=1.0, emin=30, emax=300)
-chi = qm.raw_chi_squared()
-```
-
-**About PIF files:** PIF (Pixel Illumination Fraction) files contain per-pixel sensitivity maps generated by OSA task `ii_pif`. They weight events based on source position to improve signal-to-noise ratio. Using PIF files is recommended but optional.
-
-## Features
-
-- Load ISGRI events and PIF files
-- Rebin lightcurves with custom binning
-- Module-by-module analysis (8 detector modules)
-- Quality metrics (chi-squared variability tests)
-- Time conversions (IJD ↔ UTC)
-- Custom event filtering
-
-## Documentation
-
-- **Tutorial**: - **Tutorial**: See [demo notebook](https://github.com/dominp/isgri/blob/main/demo/lightcurve_walkthrough.ipynb) on GitHub
-- **API docs**: All functions have docstrings - use `help(LightCurve)`

isgri-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-isgri/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-isgri/utils/__init__.py,sha256=H83Al7urc6LNW5KUzUBRdtRBUTahiZmkehKFiK90RrU,183
-isgri/utils/file_loaders.py,sha256=HBQ-n-jFhcP1cxykemBFYTZ72ydJNQrZMUQTeZ2dSnw,5509
-isgri/utils/lightcurve.py,sha256=VGRWcpOMnh8Rrbo-EETKAevhYYBZe55IuRQOw_cIfvY,10243
-isgri/utils/pif.py,sha256=oxndfoZp-y9FO_TXcCP3dmesvh-sC7hAy2u_1YwGitw,1317
-isgri/utils/quality.py,sha256=vNOkIFOkOTP1FAy_1-t5Xvi38gp6UNgXJN3T-DtM8es,7209
-isgri/utils/time_conversion.py,sha256=47aTXn6cvi-LjOptDY2W-rjeF_PjthZer61VIsJqsro,908
-isgri-0.2.0.dist-info/METADATA,sha256=n3Wxho_x45DSjVi1QQs3eTVmU9_HP1sLsuXFttTMns0,1781
-isgri-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-isgri-0.2.0.dist-info/licenses/LICENSE,sha256=Q8oxmHR1cSnEXSHCjY3qeXMtupZI_1ZQZ1MBt4oeANE,1102
-isgri-0.2.0.dist-info/RECORD,,