Alert Contents

Public LIGO/Virgo/KAGRA alerts are distributed using NASA’s General Coordinates Network (GCN, https://gcn.nasa.gov) and Scalable Cyberinfrastructure to support Multi-Messenger Astrophysics (SCiMMA, https://scimma.org). There are two types of alerts:

Notices are machine-readable packets. They are available as JSON, Avro, VOEvent XML, and several other legacy formats. See the Sample Code section for instructions on receiving notices, which are available via Kafka and VOEvent brokers.

Warning

The JSON, Avro, and VOEvent formats are fully supported, but the legacy text, binary, and email formats are not.

The VOEvent XML alerts are official data products of LIGO/Virgo/KAGRA. GCN produces several other legacy formats from them, in particular a text-based “full format” and binary format. LIGO/Virgo/KAGRA performs only limited quality control of the legacy formats.

GCN Circulars are short human-readable astronomical bulletins. They are written in a certain well-established format and style. You can subscribe to GCN Circulars to receive and post them by email, or you can view them in the public GCN Circulars archive.

Notice Types

For each event, there are up to five kinds of Notices:

An Early Warning Notice may be issued for CBC events up to tens of seconds before merger. The candidate must have passed some automated data quality checks, but it may later be retracted after human vetting. There is no accompanying GCN Circular at this stage. Early Warning alerts are an experimental feature in O3. Early Warning alerts are only possible for exceptionally loud and nearby CBC events, and are expected to be rare.

A Preliminary Notice is issued automatically within minutes after a gravitational-wave candidate is detected. Like an Early Warning Notice, the candidate must have passed automated data quality checks, but it may later be retracted, and there is no accompanying GCN Circular.

An Initial Notice is issued after human vetting (see Candidate Vetting). If the signal does not pass human vetting (e.g., it is a glitch), then instead of an initial alert there will be a retraction. The initial alert is also accompanied by a GCN Circular, which should be considered as the first formal publication of the candidate and can be cited as such.

An Update Notice is issued whenever further analysis leads to improved estimates of the sky localization, significance, or classification. There may be multiple updates for a given event, and updates may be issued hours, days, or even weeks after the event.

Lastly, a Retraction Notice is issued if the candidate is rejected as a result of vetting by human instrument scientists and data analysts. A retraction indicates that the candidate has been withdrawn because it is probably not astrophysical.

All types of Notices except for Retraction notices contain the following information, which are described in further detail below:

Of the above fields, Retraction notices provide only the name.

Initial and Update notices are accompanied by human-readable GCN Circulars, which restate all of the above information and also may include a data quality assessment.

Notice Formats

Notices essentially come in two different formats: a format that is distributed over Kafka and a different format that is distributed using VOEvent brokers. These two formats contain the same information about the candidate but contain different metadata and follow different schema.

Kafka Notice (GCN, SCiMMA)

Public LIGO/Virgo/KAGRA notices distributed over Kafka as either JSON or Avro follow the format of the table below. The event field will be null in retraction notices; the external_coinc field will only be non-null in the event of a coincidence between a gravitational-wave candidate and an alert from a third party.

Important

The sky map field stores the raw byte-string representation of the sky localization file (described below) in Avro notices, but stores the Base64 encoded byte-string representation in JSON notices.

alert_type

{EARLYWARNING,PRELIMINARY,INITIAL,UPDATE,RETRACTION}

time_created

Time notice was created (UTC, ISO-8601) 2018-11-01T22:34:20Z

superevent_id

GraceDB ID: [{T,M}]SYYMMDDabc. Example: MS181101abc

event

time

Time of event (UTC, ISO-8601), e.g. 2018-11-01T22:22:46.654Z

far

Estimated FAR in Hz

instruments

List of detectors, e.g. ['H1', 'L1','V1'] whose data have been used by the online pipeline that has produced the preferred event for that particular superevent

skymap

The contents of a sky map in a multi-order FITS format as a Base64-encoded string.

search

{AllSky, AllSkyLong, BBH, EarlyWarning, HighMass, IMBH, MDC}

group

CBC

Burst

pipeline

{gstlal,MBTAOnline,pycbc,spiir}

{CWB,oLIB}

event.properties

HasNS, HasRemnant, HasMassGap

Probability, under the assumption that the source is not noise, that at least one of the compact objects was a neutron star, that the system ejected a non-zero amount of neutron star matter, and that at least one of the compact objects has mass in the range 3-5 solar masses, respectively

N/A

event.classification

BNS, NSBH, BBH, Noise

Probability that the source is a BNS, NSBH, BBH, or Terrestrial (i.e, noise) respectively

N/A

external_coinc

gcn_notice_id

{583417860, 583327924}

ivorn

External IVORN identification field

observatory

{Fermi,Swift}

search

{GRB,SubGRB}

time_difference

Time between source and external event in seconds

time_coincidence_far

Estimated coincidence false alarm rate in Hz using timing

time_sky_position_coincidence_far

Estimated coincidence false alarm rate in Hz using timing and sky position

combined_skymap

The contents of a sky map produced by combining the GW skymap and the external coincidence skymap in a multi-order FITS format as a Base64-encoded string.

VOEvent Notice (GCN Classic)

The table below is a representation of the contents of a LIGO/Virgo/KAGRA GCN Notice.

Root

IVORN

ivo://gwnet/LVC#[{T,M}]SYYMMDDabc-{1,2,3}-{EarlyWarning,Preliminary,Initial,Update,Retraction}

Role

{observation,test}

Who

Date

Time sent (UTC, ISO-8601), e.g. 2018-11-01T22:34:49

Author

LIGO Scientific Collaboration, Virgo Collaboration, and KAGRA Collaboration

What

GraceID

GraceDB ID: [{T,M}]SYYMMDDabc. Example: MS181101abc

Packet Type

GCN Notice type: {Preliminary,Initial,Update,Retraction}

Notice Type

Numerical equivalent of GCN Notice type: {150,151,152,164}

FAR

Estimated FAR in Hz

Sky Map

Versioned URL of HEALPix FITS sky localization file in the format https://gracedb.ligo.org/api/superevents/[{T,M}]SYYMMDDabc/files/{bayestar,LALInference,cWB}.multiorder.fits,[0-8]. Example: https://gracedb.ligo.org/api/superevents/S190901ap/files/bayestar.multiorder.fits,0

Group

CBC

Burst

Pipeline

{gstlal,MBTA,pycbc,spiir}

{CWB,oLIB}

CentralFreq

N/A

Central frequency in Hz

Duration

Duration of burst in s

BNS, NSBH, BBH, Noise

Probability that the source is a BNS, NSBH, BBH, or Terrestrial (i.e, noise) respectively

N/A

HasNS, HasRemnant, HasMassGap

Probability, under the assumption that the source is not noise, that at least one of the compact objects was a neutron star, that the system ejected a non-zero amount of neutron star matter, and that at least one of the compact objects has mass in the range 3-5 solar masses, respectively

WhereWhen

Time of signal (UTC, ISO-8601), e.g. 2018-11-01T22:22:46.654437

How

List of detectors, e.g. H1: LIGO Hanford 4 km gravitational wave detector, L1: LIGO Livingston 4 km gravitational wave detector and V1: Virgo 3 km gravitational wave detector K1: KAGRA 3 km gravitational wave detector whose data have been used by the online pipeline that has produced the preferred event for that particular superevent

In the event of a coincidence between a gravitational-wave candidate and an alert from a third party (e.g. a gamma-ray burst or neutrino trigger), the following fields will also be present:

External GCN Notice ID

{583417860, 583327924}

External IVORN

External IVORN identification field

External Observatory

{Fermi,Swift}

External Search

{GRB,SubGRB}

Time Coincidence FAR

Estimated coincidence false alarm rate in Hz using timing

Time and Sky Position Coincidence FAR

Estimated coincidence false alarm rate in Hz using timing and sky position

Joint Skymap Fits

URL of combined GW-External HEALPix FITS sky localization file

Time Difference

Time between source and external event in seconds

Notice Contents

Name

The name of an event is its GraceDB ID (sometimes called the superevent ID), a uniquely assigned identifier such as MS181101abc. A GraceDB ID has three parts:

  • Prefix: S for normal candidates and MS or TS for mock or test events respectively. The S stands for superevent.

  • Date: The six-digit UTC date of the event consisting of a two-digit year, month, and day of month.

  • Suffix: A lowercase alphabetic string that is incremented automatically (a, b, …, z, aa, ab, … az, ba, etc.) whenever a candidate on a given date is added to GraceDB.

Significance

The significance of the event is quantified by its false alarm rate: the expected rate of events from the pipeline that produced the preferred event with equal or higher ranking statistics, in the absence of any astrophysical signal (see false alarm rate (FAR)).

Sky Localization

The sky localization consists of the posterior probability distribution of the source’s sky position and (for CBC events only) luminosity distance. The Classic GCN Notice and Circular will provide a URL for the sky localization file stored in GraceDB, notices delivered over Kafka will provide byte-string representations of the localization file content. Avro notices will provide the raw bytes, JSON notices will provide base64 encoded bytes. The sky localization is saved in a FITS file as a HEALPix [1] all-sky image. See our sample code for instructions on working with sky localization files.

The sky map URL will generally be of the form https://gracedb.ligo.org/api/superevents/sid/files/method.multiorder.fits,v, where sid is the superevent ID, method is the sky localization algorithm (usually bayestar, LALInference, or cWB), and v is an integer that uniquely identifies different versions of the localization. The version number is automatically assigned by GraceDB, starting from 0, and increments for each file of the same name. For example, the first FITS file with the name bayestar.multiorder.fits becomes bayestar.multiorder.fits,0, then the next one is bayestar.multiorder.fits,1, and so on. The filename without the version suffix, such as bayestar.multiorder.fits, always points to the most recent version.

Important

We generally provide localizations in two HEALPix formats, distinguished by file extension:

*.multiorder.fits

A new variant of the HEALPix format that is designed to overcome limitations of the *.fits.gz format for well-localized events from three-detector operations and future gravitational-wave facilities (see rationale in LIGO-G1800186). It uses HEALPix explicit indexing and the NUNIQ numbering scheme, which is closely related to multi-order coverage (MOC) maps in Aladin. This is the new format that is used by the LIGO/Virgo/KAGRA low-latency alert pipeline. This is the primary and preferred format, and the only format that is explicitly listed in the GCN Notices and Circulars. See the section Working with Multi-Order Sky Maps for details.

*.fits.gz

A subset of the standard HEALPix-in-FITS format (see semi-official specifications from the HEALPix team and from the gamma-ray community) that is recognized by a wide variety of astronomical imaging programs including DS9 and Aladin. It uses HEALPix implicit indexing and the NESTED numbering scheme. See the section Working with Flat Resolution Sky Maps for details.

Both formats always use celestial (equatorial, J2000) coordinates.

Inference

The inference section is present for CBC events only. It has two parts:

Classification: Four numbers, summing to unity, giving probability that the source belongs to the following five mutually exclusive categories:

The figure below shows the extent of the three astrophysical categories (BNS, NSBH, and BBH) in terms of the component masses \(m_1\) and \(m_2\).

Note

By convention, the component masses are defined such that \(m_1 \geq m_2\), so that the primary compact object in the binary (i.e., component 1), is always more massive than the secondary compact object (i.e., component 2).

In the mass diagram below, the upper diagonal region \(m_1 < m_2\) is lightly shaded in order to indicate that the definitions of four mass classes (BNS, NSBH, BBH) are symmetric in \(m_1\) and \(m_2\).

(Source code)

Mass parameter space

Properties: Probabilities that the source has each of the following properties, assuming that it is not noise (e.g., assuming that it is a BNS, NSBH, or BBH merger):

  • HasNS: The mass of one or more of the binary’s two companion compact objects is consistent with a neutron star. Equivalently, the mass of the secondary or less massive compact object is consistent with a neutron star. The upper limit of the neutron star mass is marginalized over several neutron star equations of state (EOS).

  • HasRemnant: A non-zero amount of neutron star material remained outside the final remnant compact object (a necessary but not sufficient condition to produce certain kinds of electromagnetic emission such as a short GRB or a kilonova). Several neutron star EOSs are considered to compute the remnant mass and are marginalized over.

  • HasMassGap: The mass of one or more of the binary’s two companion object lies in the hypothetical “mass gap” between neutron stars and black holes, defined here as \(3 M_{\odot} \leq m \leq 5 M_{\odot}\).

All of the quantities in the Classification and Properties sections are model dependent to some extent: the Classification section takes into consideration prior knowledge of astrophysical compact binary merger rates from previous LIGO/Virgo/KAGRA observations, and both the Classification and Properties sections depend on details of neutron star physics (e.g. maximum NS mass, equation of state). See the earlier subsection of the Data Analysis section for implementation details.

Circular Contents

The following information will be present in the human-readable GCN Circulars.

Data Quality Assessment

Circulars may contain concise descriptions of any instrument or data quality issues that may affect the significance estimates or the GW parameter inferences. Unresolved data quality issues could mean that sky localization estimates may shift after they have been mitigated, but does not mean that they will. This is to be considered as advisory information.

Sky Localization Ellipse

Generally, GW sky localizations are irregularly shaped. However, for particularly accurately localized events, the sky localization region can be well described by an ellipse. When the area of the 90% ellipse is less than 1.35 times the area of the smallest possible 90% credible region, the GCN Circular will provide a 90% containment ellipse. For details of the ellipse fitting algorithm, see ligo.skymap.postprocess.ellipse.

The ellipse is described in the format of a DS9 region string. Many tools can read DS9 region strings, including DS9, Aladin, astropy-regions, and pyregion. The region string contains the right ascension, declination, semi-major axis, semi-minor axis, position angle of the semi-minor axis). Here is an example:

icrs; ellipse(03h08m25s, -45d08m14s, 9d, 3d, 112d)

Not Included in Alerts

The alerts will not contain quantitative estimates of intrinsic properties such as masses and spins, nor contain information on the GW strain or reconstructed waveforms. After final analysis, those data products are released through the Gravitational Wave Open Science Center.

Notice Examples

Kafka

Below are examples of GCN notices to illustrate the formatting of the Notices. The skymap and combined_skymap fields has been truncated for display purposes, though links to the full files for both formats can be found in the SCiMMA and GCN sample code sections. Recall that SCiMMA notices follow the same schema as GCN notices, however the skymap and combined_skymap fields in SCiMMA notices contain raw bytes while the skymap and combined_skymap fields in GCN notices is base64 encoded.

{
    "alert_type": "EARLYWARNING",
    "time_created": "2018-11-01T22:34:20Z",
    "superevent_id": "MS181101ab",
    "urls": {
        "gracedb": "https://example.org/superevents/MS181101ab/view/"
    },
    "event": {
        "time": "2018-11-01T22:22:46.654Z",
        "far": 9.11069936486e-14,
        "significant": true,
        "instruments": [
            "H1",
            "L1",
            "V1"
        ],
        "group": "CBC",
        "pipeline": "gstlal",
        "search": "MDC",
        "properties": {
            "HasNS": 0.95,
            "HasRemnant": 0.91,
            "HasMassGap": 0.01
        },
        "classification": {
            "BNS": 0.95,
            "NSBH": 0.01,
            "BBH": 0.03,
            "Terrestrial": 0.01
        },
        "duration": null,
        "central_frequency": null,
        "skymap": "U0lNUExFICA9ICAgICAgICAgICAgICAgICAgICBUIC8gY29uZm..."
    },
    "external_coinc": null
}

GCN Classic

Below are examples of VOEvent notices.

<?xml version='1.0' encoding='UTF-8'?>
<voe:VOEvent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:voe="http://www.ivoa.net/xml/VOEvent/v2.0" xsi:schemaLocation="http://www.ivoa.net/xml/VOEvent/v2.0 http://www.ivoa.net/xml/VOEvent/VOEvent-v2.0.xsd" version="2.0" role="test" ivorn="ivo://gwnet/LVC#MS181101ab-1-EarlyWarning">
  <Who>
    <Date>2018-11-01T22:34:20Z</Date>
    <Author>
      <contactName>LIGO Scientific Collaboration, Virgo Collaboration, and KAGRA Collaboration</contactName>
    </Author>
  </Who>
  <What>
    <Param dataType="int" name="Packet_Type" value="163">
      <Description>The Notice Type number is assigned/used within GCN, eg type=163 is an LVC_EARLY_WARNING notice</Description>
    </Param>
    <Param dataType="int" name="internal" value="0">
      <Description>Indicates whether this event should be distributed to LSC/Virgo/KAGRA members only</Description>
    </Param>
    <Param dataType="int" name="Pkt_Ser_Num" value="1">
      <Description>A number that increments by 1 each time a new revision is issued for this event</Description>
    </Param>
    <Param dataType="string" name="GraceID" ucd="meta.id" value="MS181101ab">
      <Description>Identifier in GraceDB</Description>
    </Param>
    <Param dataType="string" name="AlertType" ucd="meta.version" value="EarlyWarning">
      <Description>VOEvent alert type</Description>
    </Param>
    <Param dataType="int" name="HardwareInj" ucd="meta.number" value="0">
      <Description>Indicates that this event is a hardware injection if 1, no if 0</Description>
    </Param>
    <Param dataType="int" name="OpenAlert" ucd="meta.number" value="1">
      <Description>Indicates that this event is an open alert if 1, no if 0</Description>
    </Param>
    <Param dataType="string" name="EventPage" ucd="meta.ref.url" value="https://example.org/superevents/MS181101ab/view/">
      <Description>Web page for evolving status of this GW candidate</Description>
    </Param>
    <Param dataType="string" name="Instruments" ucd="meta.code" value="H1,L1,V1">
      <Description>List of instruments used in analysis to identify this event</Description>
    </Param>
    <Param dataType="float" name="FAR" ucd="arith.rate;stat.falsealarm" unit="Hz" value="9.11069936486e-14">
      <Description>False alarm rate for GW candidates with this strength or greater</Description>
    </Param>
    <Param dataType="string" name="Group" ucd="meta.code" value="CBC">
      <Description>Data analysis working group</Description>
    </Param>
    <Param dataType="string" name="Pipeline" ucd="meta.code" value="gstlal">
      <Description>Low-latency data analysis pipeline</Description>
    </Param>
    <Param dataType="string" name="Search" ucd="meta.code" value="MDC">
      <Description>Specific low-latency search</Description>
    </Param>
    <Group name="GW_SKYMAP" type="GW_SKYMAP">
      <Param dataType="string" name="skymap_fits" ucd="meta.ref.url" value="https://emfollow.docs.ligo.org/userguide/_static/bayestar.multiorder.fits,0">
        <Description>Sky Map FITS</Description>
      </Param>
    </Group>
    <Group name="Classification" type="Classification">
      <Param dataType="float" name="BNS" ucd="stat.probability" value="0.95">
        <Description>Probability that the source is a binary neutron star merger (both objects lighter than 3 solar masses)</Description>
      </Param>
      <Param dataType="float" name="NSBH" ucd="stat.probability" value="0.01">
        <Description>Probability that the source is a neutron star-black hole merger (secondary lighter than 3 solar masses)</Description>
      </Param>
      <Param dataType="float" name="BBH" ucd="stat.probability" value="0.03">
        <Description>Probability that the source is a binary black hole merger (both objects heavier than 3 solar masses)</Description>
      </Param>
      <Param dataType="float" name="Terrestrial" ucd="stat.probability" value="0.01">
        <Description>Probability that the source is terrestrial (i.e., a background noise fluctuation or a glitch)</Description>
      </Param>
      <Description>Source classification: binary neutron star (BNS), neutron star-black hole (NSBH), binary black hole (BBH), or terrestrial (noise)</Description>
    </Group>
    <Group name="Properties" type="Properties">
      <Param dataType="float" name="HasNS" ucd="stat.probability" value="0.95">
        <Description>Probability that at least one object in the binary has a mass that is less than 3 solar masses</Description>
      </Param>
      <Param dataType="float" name="HasRemnant" ucd="stat.probability" value="0.91">
        <Description>Probability that a nonzero mass was ejected outside the central remnant object</Description>
      </Param>
      <Param dataType="float" name="HasMassGap" ucd="stat.probability" value="0.01">
        <Description>Probability that at least one object in the binary has a mass between 3 and 5 solar masses</Description>
      </Param>
      <Description>Qualitative properties of the source, conditioned on the assumption that the signal is an astrophysical compact binary merger</Description>
    </Group>
  </What>
  <WhereWhen>
    <ObsDataLocation>
      <ObservatoryLocation id="LIGO Virgo KAGRA"/>
      <ObservationLocation>
        <AstroCoordSystem id="UTC-FK5-GEO"/>
        <AstroCoords coord_system_id="UTC-FK5-GEO">
          <Time unit="s">
            <TimeInstant>
              <ISOTime>2018-11-01T22:22:46.654437Z</ISOTime>
            </TimeInstant>
          </Time>
        </AstroCoords>
      </ObservationLocation>
    </ObsDataLocation>
  </WhereWhen>
  <Description>Early warning report of a candidate gravitational wave event</Description>
  <How>
    <Description>Candidate gravitational wave event identified by low-latency analysis</Description>
    <Description>H1: LIGO Hanford 4 km gravitational wave detector</Description>
    <Description>L1: LIGO Livingston 4 km gravitational wave detector</Description>
    <Description>V1: Virgo 3 km gravitational wave detector</Description>
    <Description>K1: KAGRA 3 km gravitational wave detector</Description>
  </How>
</voe:VOEvent>