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

isgri/utils/time_conversion.py

@@ -1,39 +1,210 @@
-from astropy.time import Time
-
-
-def ijd2utc(t):
-    """
-    Converts IJD (INTEGRAL Julian Date) time to UTC ISO format.
-
-    Args:
-        t (float or ndarray): IJD time value(s).
-
-    Returns:
-        str or ndarray: UTC time in ISO format (YYYY-MM-DD HH:MM:SS.sss).
-
-    Examples:
-        >>> ijd2utc(0.0)
-        '1999-12-31 23:58:55.817'
-        >>> ijd2utc(1000.5)
-        '2002-09-27 11:58:55.816'
-    """
-    return Time(t + 51544, format="mjd", scale="tt").utc.iso
-
-
-def utc2ijd(t):
-    """
-    Converts UTC ISO format time to IJD (INTEGRAL Julian Date).
-
-    Args:
-        t (str or ndarray): UTC time in ISO format (YYYY-MM-DD HH:MM:SS).
-
-    Returns:
-        float or ndarray: IJD time value(s).
-
-    Examples:
-        >>> utc2ijd('1999-12-31 23:58:55.817')
-        0.0
-        >>> utc2ijd('2002-09-27 00:00:00')
-        1000.0
-    """
-    return Time(t, format="iso", scale="utc").tt.mjd - 51544
+"""
+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(ijd_time: Union[float, NDArray[np.float64]]) -> Union[str, NDArray[np.str_]]:
+    """
+    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'
+
+    >>> ijd2utc(1000.5)
+    '2002-09-27 11:58:55.816'
+
+    >>> # Array conversion
+    >>> ijds = np.array([0.0, 1000.0, 2000.0])
+    >>> utcs = ijd2utc(ijds)
+    >>> print(utcs[0])
+    1999-12-31 23: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)
+    """
+    mjd = ijd_time + INTEGRAL_EPOCH_MJD
+    t = Time(mjd, format="mjd", scale="tt")
+    return t.utc.iso
+
+
+def utc2ijd(utc_time: Union[str, NDArray[np.str_]]) -> Union[float, NDArray[np.float64]]:
+    """
+    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)
+
+    Examples
+    --------
+    >>> mjd2ijd(51544.0)
+    0.0
+
+    >>> mjd2ijd(55197.5)
+    3653.5
+
+    See Also
+    --------
+    ijd2mjd : Inverse conversion
+    """
+    return mjd_time - INTEGRAL_EPOCH_MJD

isgri-0.5.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: isgri
+Version: 0.5.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: click
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Requires-Dist: tomli-w
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# ISGRI
+
+Python toolkit for INTEGRAL/ISGRI data analysis.
+
+## Features
+
+### Command Line Interface
+Query catalogs directly from the terminal:
+- Filter by time, position, quality, revolution
+- Export results to FITS/CSV
+- List SWIDs for batch processing
+
+### 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 to/from UTC)
+
+
+## Installation
+
+```bash
+pip install isgri
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Configure default paths (once)
+isgri config-set --catalog ~/data/scw_catalog.fits
+
+# Query by time range
+isgri query --tstart 2010-01-01 --tstop 2010-12-31
+
+# Query Crab with quality cut
+isgri query --ra 83.63 --dec 22.01 --max-chi 2.0 --fov full
+
+# Get list of SWIDs for processing
+isgri query --tstart 3000 --tstop 3100 --list-swids > swids.txt
+
+# Export results
+isgri query --tstart 3000 --tstop 3100 --output results.fits
+```
+
+### 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}")
+```
+
+## Configuration
+
+ISGRI stores configuration in default config folder for each system (see: platformdirs package)
+
+```bash
+# View current config
+isgri config
+
+# Set paths
+isgri config-set --archive /path/to/archive --catalog /path/to/catalog.fits
+```
+
+Config can also be used in Python:
+
+```python
+from isgri.config import get_config
+
+cfg = get_config()
+print(cfg.archive_path)
+print(cfg.catalog_path)
+```
+
+Local config file `isgri_config.toml` in current directory overrides global config.
+
+
+## Documentation
+
+- **CLI Reference**: Run `isgri --help` or `isgri <command> --help`
+- **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
+├── config.py         # Configuration management
+└── cli.py            # Command line interface
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- astropy
+- numpy

isgri-0.5.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+isgri/__init__.py,sha256=V2hnOxXKcjMiusdGP8sOAR4QsBlWHQ0pZZMN2Cean6o,38
+isgri/__version__.py,sha256=pVYhOkVS5PHJd_cIEx6PTaY6VggXFTC3pqWdf0I8zao,21
+isgri/cli.py,sha256=ESrhtFCo-VEYuC3y4CL9Hv2Mdr6MVESCkRZ0N6kLgKs,7211
+isgri/config.py,sha256=i1ibczZsmgqELv4ik2h2nWLnHyl68_5KGsz5Ec8Uf4E,4365
+isgri/catalog/__init__.py,sha256=CT9Zd1WISpv7kowf3bqagKewZ8SjLr1rZzVSFkwEj3o,58
+isgri/catalog/builder.py,sha256=C1M1rBXOWyRE85Nru1Dl9pq6FbmyUEl63v-4cbV57y8,3493
+isgri/catalog/scwquery.py,sha256=KKsiAXkJHsm2WlQjYRN-knzHBhIJVCaM4jUAh_FaBYs,17603
+isgri/catalog/wcs.py,sha256=mD6bZxiBxKYpuYCl8f2tSCc8uuWFzMRL2jf5SuFAhfg,5562
+isgri/utils/__init__.py,sha256=H83Al7urc6LNW5KUzUBRdtRBUTahiZmkehKFiK90RrU,183
+isgri/utils/file_loaders.py,sha256=g-LUfYw35hPePlFeicymaL-NbZXzZWfNmM127XJjCKY,12497
+isgri/utils/lightcurve.py,sha256=Pjys-eIyKShDKHqFpGa9SZ0Dzz7LiLIwBpUkp_6s41g,14133
+isgri/utils/pif.py,sha256=LixlkShy1j_ymfdJLyCV8zl0EeHgfVDVjddSex18GLQ,8648
+isgri/utils/quality.py,sha256=Na-sNEX1E4xWQJx0FYe9vbOAgPrTcLohHeUAnmlKYSw,13348
+isgri/utils/time_conversion.py,sha256=MNPVjrsrmwRDbCWmqdWN0xRs8PtHkFGli-H2cYwF9Ns,5204
+isgri-0.5.0.dist-info/METADATA,sha256=uc6rHgLYHLqZxiNm2MlXQAlLKDTKgCXt-PEsRyqHZAU,4019
+isgri-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+isgri-0.5.0.dist-info/entry_points.txt,sha256=ZziremOhrp8Lrk9Znu5L1lo7FmkrtMf6FDo8r1900Zc,41
+isgri-0.5.0.dist-info/licenses/LICENSE,sha256=Q8oxmHR1cSnEXSHCjY3qeXMtupZI_1ZQZ1MBt4oeANE,1102
+isgri-0.5.0.dist-info/RECORD,,

isgri-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+isgri = isgri.cli:main

isgri-0.3.0.dist-info/METADATA

@@ -1,66 +0,0 @@
-Metadata-Version: 2.4
-Name: isgri
-Version: 0.3.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 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.3.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=TZGXnao6hQ2STlI8S8JIfaldPAfdMORQJ0IH_rilFu4,7930
-isgri/utils/time_conversion.py,sha256=47aTXn6cvi-LjOptDY2W-rjeF_PjthZer61VIsJqsro,908
-isgri-0.3.0.dist-info/METADATA,sha256=MofiJhRbXTPhMNOQAtOSc4QmsYEIm8ckXayvr2LTIMQ,1767
-isgri-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-isgri-0.3.0.dist-info/licenses/LICENSE,sha256=Q8oxmHR1cSnEXSHCjY3qeXMtupZI_1ZQZ1MBt4oeANE,1102
-isgri-0.3.0.dist-info/RECORD,,