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

significant

true if trials factor × FAR < 1/month for CBC events, otherwise false

true if trials factor × FAR < 1/year for burst events, otherwise false

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,BBH,EarlyWarning,MDC,SSM}

AllSky

group

CBC

Burst

pipeline

{gstlal,MBTA,pycbc,spiir,CWB}

{CWB,oLIB,MLy}

duration

N/A

time interval for which the signal is detected (above noise)

central_frequency

estimation of the frequency of the signal’s main component

event.properties

HasNS, HasRemnant, HasMassGap, HasSSM

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, that at least one of the compact objects has mass in the range 3-5 solar masses, and that at least one of the compact objects has mass less than 1 solar mass, 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

For example: 583417860

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

Significant

1 if trials factor × FAR < 1/month for CBC events, otherwise 0

1 if trials factor × FAR < 1/year for burst events, otherwise 0

Sky Map

Versioned URL of HEALPix FITS sky localization file in the format https://gracedb.ligo.org/api/superevents/[{T,M}]SYYMMDDabc/files/{bayestar,bilby,cWB,MLy}.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}

{CWB,oLIB,MLy}

central_frequency

N/A

estimation of the frequency of the signal’s main component

duration

time interval for which the signal is detected (above noise)

BNS, NSBH, BBH, Noise

Probability that the source is a BNS, NSBH, BBH, or Terrestrial (i.e, noise) respectively. N/A for SSM searches.

N/A

HasNS, HasRemnant, HasMassGap, HasSSM

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, and that at least one of the compact objects has mass less than 1 solar mass, 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,INTEGRAL,AGILE,SNEWS}

External Search

{GRB,SubGRB,SubGRBTargeted,Supernova}

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 [3] 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, bilby, cWB or MLy), 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: Available only for events generated by modeled searches for stellar mass CBC and not for SSM CBC searches. Four numbers, summing to unity, giving the probability that the source belongs to the following four mutually exclusive categories:

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

Note

By convention, the component masses are defined such that m1≥m2, 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 m1<m2 is lightly shaded in order to indicate that the definitions of four mass classes (BNS, NSBH, BBH) are symmetric in m1 and m2.

(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 SSM, 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. For stellar mass events, the upper limit of the neutron star mass is marginalized over several neutron star equations of state (EOS). For SSM events, the neutron star is defined as a compact object in the mass range of 1M⊙≤m≤3M⊙

  • 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. This property is present only for stellar mass search alerts and not for SSM search alerts.

  • 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 3M⊙≤m≤5M⊙.

  • HasSSM: The mass of one or more of the binary’s two component objects is less than 1M⊙. This property is present only for SSM search alerts and not for stellar mass search alerts.

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="int" name="Significant" ucd="meta.number" value="1">
      <Description>Indicates that this event is a significant alert if 1, no if 0</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>

Public Annotations

This section summarizes additional information regarding GW candidates that is available on GraceDB in GW candidate event annotations, but not in GCN Notices or Circulars.

Per-Pipeline Event Information

We provide supplementary information on the detection of a GW candidate in multiple pipelines in the per-pipeline event information table.

GWSkyNet Classification

GWSkyNet is a machine learning classifier that produces a GWSkyNet score for multi-detector CBC event candidates. For a multi-detector CBC candidate, the values provided on GraceDB are the following:

  • GWSkyNet score: A measure of GWSkyNet’s confidence that an event candidate belongs to the noise or signal class. A GWSkyNet score of 0 is consistent with noise, and 1 is consistent with a signal. The score is produced using the sky localization information and the metadata encoded in FITS files associated with the event [1]. This allows GWSkyNet to evaluate an event from a different perspective from the search pipelines, using a common, standardized end product generated by BAYESTAR [4] [5].

  • GWSkyNet False Alarm Probability: The corresponding GWSkyNet FAP. The GWSkyNet FAP measures the fraction of noise events at or above a candidate’s GWSkyNet score. This empirical measurement is derived from GWSkyNet’s performance on known LIGO-Virgo detector glitches and simulated gravitational wave signals, as described in the GWSkyNet output guide [2].

  • GWSkyNet False Negative Probability: The corresponding GWSkyNet FNP. The GWSkyNet FNP measures the fraction of astrophysical events at or below a candidate’s GWSkyNet score. This empirical measurement is derived from GWSkyNet’s performance on known LIGO-Virgo detector glitches and simulated gravitational wave signals, as described in the GWSkyNet output guide [2].

GWSkyNet classification is not available for single-detector CBC candidates.