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
andligo.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
, orhdf.open
, as appropriate.- Returns:
- ligo.skymap.io.events.gracedb.open(graceids, client=None)¶
Read events from GraceDB.
- Parameters:
- graceidslist
List of GraceDB ID strings.
- client
ligo.gracedb.rest.GraceDb
, optional Client object
- Returns:
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.
- *fileslist of str, file-like object, or
- Returns:
- 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_def
ligo.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 filef
are searched.
- fstr, file-like object, or
- Returns:
- 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.
- fstr, file-like object, or
- Returns:
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]¶
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[source]¶
Abstraction of a coincident trigger.
- Attributes:
- singleslist, tuple
Sequence of
SingleEvent
- template_argsdict
Dictionary of template parameters
- class ligo.skymap.io.events.SingleEvent[source]¶
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
- psd
REAL8FrequencySeries
Power spectral density
- snr_series
COMPLEX8TimeSeries
SNR time series