deepextractor.data.omicron
==========================

.. py:module:: deepextractor.data.omicron

.. autoapi-nested-parse::

   Omicron glitch-trigger utilities.

   !! DISCLAIMER !!
   fetch_omicron_triggers() relies on gwtrigfind locating Omicron output files on
   the local filesystem.  These files are only present on the computing clusters
   co-located with each LIGO detector site:

       L1 (Livingston)  →  LLO cluster  (ldas-pcdev*.ligo-la.caltech.edu)
       H1 (Hanford)     →  LHO cluster  (ldas-pcdev*.ligo-wa.caltech.edu)

   Do NOT run trigger-fetching code on CIT, LDAS, or any off-site cluster — it
   will fail to locate trigger files and raise RuntimeError.







Module Contents
---------------

.. py:data:: logger

.. py:data:: O1_START
   :value: 1126051217


.. py:data:: O1_END
   :value: 1137254417


.. py:data:: O2_START
   :value: 1164556817


.. py:data:: O2_END
   :value: 1187733618


.. py:data:: O3A_START
   :value: 1238166018


.. py:data:: O3A_END
   :value: 1253977218


.. py:data:: O3B_START
   :value: 1256655618


.. py:data:: O3B_END
   :value: 1269363618


.. py:data:: O4A_START
   :value: 1368975618


.. py:data:: O4A_END
   :value: 1389398418


.. py:data:: O4B_START
   :value: 1396742418


.. py:data:: O4B_END
   :value: 1413331218


.. py:data:: RUN_PERIODS
   :type:  dict[str, tuple[int, int]]

.. py:function:: find_clean_gaps(peak_times: numpy.ndarray, durations: numpy.ndarray, run_start: int | float, run_end: int | float, trigger_buffer: float = 0.5) -> list[tuple[float, float]]

   Return trigger-free time intervals within a GPS span.

   Builds excluded windows from each trigger's peak time and duration, merges
   overlapping exclusions, then returns their complement within
   ``[run_start, run_end)``.

   :param peak_times: Omicron trigger peak times (GPS seconds).
   :param durations: Trigger durations (seconds), matched 1-to-1 with peak_times.
   :param run_start: GPS start of the observing run (inclusive).
   :param run_end: GPS end of the observing run (exclusive).
   :param trigger_buffer: Extra padding (seconds) on each side of every trigger
                          beyond the raw duration.  Accounts for ring-down and edge effects.

   :returns: List of ``(gap_start, gap_end)`` tuples (GPS seconds), sorted by start
             time, all within ``[run_start, run_end)``.


.. py:function:: fetch_omicron_triggers(ifo: str, gps_start: int, gps_end: int, channel: str | None = None) -> dict[str, numpy.ndarray]

   Return Omicron trigger parameters for a GPS interval.

   :param ifo: Detector prefix — ``"L1"`` or ``"H1"``.
   :param gps_start: GPS start time (inclusive).
   :param gps_end: GPS end time (exclusive).
   :param channel: Full channel name, e.g. ``"L1:GDS-CALIB_STRAIN"``.
                   Defaults to the standard strain channel for *ifo*.

   :returns:   - ``peak_time``: GPS time of peak SNR
               - ``tstart``:    GPS start of the Omicron Q-tile
               - ``tend``:      GPS end of the Omicron Q-tile
               - ``duration``:  tend - tstart (tile width in seconds)
   :rtype: Dict with 1-D float64 arrays per trigger

   :raises ValueError: If *ifo* is unrecognised and *channel* is not given.
   :raises RuntimeError: If no trigger files are found.  Usually means the script
       is not running on the correct site cluster.


.. py:function:: save_omicron_triggers(triggers: dict[str, numpy.ndarray], prefix: str, output_dir: str | pathlib.Path = '.') -> None

   Save trigger arrays to ``<output_dir>/<prefix>_triggers.npz``.

   :param triggers: Dict returned by fetch_omicron_triggers (peak_time, tstart,
                    tend, duration).
   :param prefix: Filename stem, e.g. ``"l1_o3a"``.
   :param output_dir: Destination directory (created if absent).