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.

• To read offline events from GstLAL, PyCBC, or bayestar-realize-coincs, use ligo.skymap.io.events.open. It can read GstLAL’s LIGO-LW XML or SQLite files and PyCBC’s HDF5 files produced by PyCBC.

• To read online events from GraceDB, use ligo.skymap.io.events.gracedb.open.

• To read events from any other source or format, write your own concrete event classes inheriting from the ligo.skymap.io.events.Event and ligo.skymap.io.events.SingleEvent base classes.

High-Level Openers

ligo.skymap.io.events.open(f, *args, **kwargs)

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)

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)

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)

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)

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

Bases: 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

Abstraction of a coincident trigger.

Attributes:

singleslist, tuple

Sequence of SingleEvent

template_argsdict

Dictionary of template parameters

class ligo.skymap.io.events.SingleEvent

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