Event Candidate I/O (ligo.skymap.io.events)

This module provides a high-level interface for reading event records from LIGO/Virgo/KAGRA search pipelines.

High-Level Openers

ligo.skymap.io.events.open(f, *args, **kwargs) [edit on github]

Read events from LIGO-LW XML, LIGO-LW SQlite, or HDF5 files. The format is determined automatically using the file(1) command, and then the file is opened using ligolw.open, sqlite.open, or hdf.open, as appropriate.

Returns
EventSource
ligo.skymap.io.events.gracedb.open(graceids, client=None) [edit on github]

Read events from GraceDB.

Parameters
graceidslist

List of GraceDB ID strings.

clientligo.gracedb.rest.GraceDb, optional

Client object

Returns
EventSource

Openers for Specific Formats

ligo.skymap.io.events.hdf.open(*files, **kwargs) [edit on github]

Read events from PyCBC-style HDF5 files.

Parameters
*fileslist of str, file-like object, or h5py.File objects

The PyCBC coinc, bank, psds, and triggers files, in any order.

Returns
EventSource
ligo.skymap.io.events.ligolw.open(f, psd_file=None, coinc_def=<ligo.lw.lsctables.CoincDef object>, fallbackpath=None, **kwargs) [edit on github]

Read events from LIGO-LW XML files.

Parameters
fstr, file-like object, or ligo.lw.ligolw.Document

The name of the file, or the file object, or the XML document object, containing the trigger tables.

psd_filestr, file-like object, or ligo.lw.ligolw.Document

The name of the file, or the file object, or the XML document object, containing the PSDs. If not supplied, then PSDs will be read automatically from any files mentioned in --reference-psd command line arguments stored in the ProcessParams table.

coinc_defligo.lw.lsctables.CoincDef, optional

An optional coinc definer to limit which events are read.

fallbackpathstr, optional

A directory to search for PSD files whose --reference-psd command line arguments have relative paths. By default, the current working directory and the directory containing file f are searched.

Returns
EventSource
ligo.skymap.io.events.sqlite.open(f, *args, **kwargs) [edit on github]

Read events from LIGO-LW SQLite files.

Parameters
fstr, file-like object, or sqlite3.Connection instance

The SQLite database.

Returns
EventSource

Abstract Base Classes

To implement your own event format, write your own concrete classes using Event and SingleEvent as base classes. Here is an example of a concrete class that produces events populated with random values:

from lal import CreateREAL8FrequencySeries
from lalsimulation import SimNoisePSD, SimNoisePSDaLIGOZeroDetHighPowerPtr
from ligo.skymap.io.events import Event, SingleEvent
import numpy as np

class RandomEvent(Event):

    def __init__(self):
        self._singles = [RandomSingleEvent('H1'), RandomSingleEvent('L1')]
        self._template_args = {'mass1': np.random.uniform(1.0, 3.0),
                               'mass1': np.random.uniform(1.0, 3.0)}

    @property
    def singles(self):
        return self._singles

    @property
    def template_args(self):
        return self._template_args


class RandomSingleEvent(SingleEvent):

    def __init__(self, detector):
        self._detector = detector
        self._snr = np.random.uniform(1, 10)
        self._phase = np.random.uniform(-np.pi, np.pi)
        self._time = np.random.uniform(1e9, 1.1e9)
        self._psd = CreateREAL8FrequencySeries(name=None, epoch=None, f0=0.0,
                                               deltaF=1.0, sampleUnits=None,
                                               length=16384)
        SimNoisePSD(psd=self._psd, flow=10.0,
                    psdfunc=SimNoisePSDaLIGOZeroDetHighPowerPtr)
        self._psd.data.data[self._psd.data.data == 0] = np.inf

    @property
    def detector(self):
        return self._detector

    @property
    def snr(self):
        return self._snr

    @property
    def phase(self):
        return self._phase

    @property
    def time(self):
        return self._time

    @property
    def zerolag_time(self):
        return self._time

    @property
    def psd(self):
        return self._psd


np.random.seed(0)
event = RandomEvent()
print(event)
# output:
# <RandomEvent(singles=[<RandomSingleEvent(detector='H1',
# snr=5.939321535345923, phase=1.3520746650524709, time=1060276337.6071644)>,
# <RandomSingleEvent(detector='L1', snr=5.903948646972072,
# phase=-0.47969104306747123, time=1064589411.3066657)>])>
class ligo.skymap.io.events.EventSource[source] [edit on github]

Bases: collections.abc.Mapping

Abstraction of a source of coincident events.

This is a mapping from event IDs (which may be any hashable type, but are generally integers or strings) to instances of Event.

class ligo.skymap.io.events.Event[source] [edit on github]

Abstraction of a coincident trigger.

Attributes
singleslist, tuple

Sequence of SingleEvent

template_argsdict

Dictionary of template parameters

class ligo.skymap.io.events.SingleEvent[source] [edit on github]

Abstraction of a single-detector trigger.

Attributes
detectorstr

Instrument name (e.g. ‘H1’)

snrfloat

Signal to noise ratio

phasefloat

Phase on arrival

timefloat

GPS time on arrival

zerolag_timefloat

GPS time on arrival in zero-lag data, without time slides applied

psdREAL8FrequencySeries

Power spectral density

snr_seriesCOMPLEX8TimeSeries

SNR time series