Data Models

What characterizes an event?

The different types of events in GraceDB are distinguished by the following parameters:

Group: the working group responsible for finding the candidate
- values: CBC, Burst, Detchar, External, Test
Pipeline: the data analysis software tool used make the detection
- values: CWB2G, spiir, HardwareInjection, X, Q, Omega, Ringdown, Fermi, Swift, CWB, SNEWS, oLIB, pycbc, INTEGRAL, AGILE, gstlal, MLy, MBTAOnline, MBTA, CHIME, PyGRB, aframe, SVOM, IceCube
Search: the search activity which led to the detection
- values: AllSky, LowMass, HighMass, GRB, Supernova, MDC, LowMassSim, AllSkyLong, O2VirgoTest, BBH, IMBH, SubGRB, EarlyWarning, SubGRBTargeted, SSM, FRB, LensingSubthreshold, VTInjection, HEN

An individual “event stream” is specified by setting the values of these three parameters. For example, choosing Group=CBC, Pipeline=gstlal, and Search=LowMass selects the event stream consisting of low-mass inspiral events detected by the gstlal pipeline from the CBC group. This framework was chosen in order avoid situations where events from different sources would overlap in searches and alerts.

Base event model

In addition to the three parameters described above, there are additional common attributes for all events. These are:

submitter: the user who submitted the event
created: the time at which the event was created
instruments: the interferometers involved in the detection
far: the false alarm rate in Hz
gpstime: the time at which the event occurred (a.k.a. “Event time”)
reporting_latency: defined as the time difference between when an event lands on GraceDB (created) and the reported gpstime (in seconds)
superevent: the superevent_id of the event’ parent superevent, if applicable
superevent_neighbours: superevents currently in GraceDB whose t_0 is within a set time window of the event’s gpstime (currently ± 100s). Value is a dictionary, whose key is the superevent_id and value is the superevent dictionary

The base event class was created with GW events in mind, so not all of the fields will be applicable for any given event. For example, instruments and far do not apply to a Swift GRB event.

Event subclasses

Most events also have pipeline-specific attributes, and these are reflected in event subclasses. For example, the gstlal pipeline produces an estimate for the chirp mass, which is represented in the CoincInspiral event subclass.

Serialized events

Event objects are serialized into JSON format in responses from the API and in igwn-alert messages. Here, we show some examples for the different event subclasses.

CBC pipelines (gstlal, spiir, PyCBC, MBTAOnline)

{
  "submitter": "albert.einstein@LIGO.ORG",
  "created": "2022-03-16 16:24:22 UTC",
  "group": "CBC",
  "graceid": "G194533",
  "pipeline": "gstlal",
  "gpstime": 1331483080.381693,
  "instruments": "H1,L1",
  "nevents": 2,
  "offline": true,
  "search": "AllSky",
  "far": 9.838364843405464e-07,
  "far_is_upper_limit": false,
  "likelihood": 7.102756279364618,
  "labels": [],
  "extra_attributes": {
    "CoincInspiral": {
      "ifos": "H1,L1",
      "end_time": 1331483080,
      "end_time_ns": 381693272,
      "mass": 33.25822162628174,
      "mchirp": 8.482876777648926,
      "minimum_duration": 10.69916749000549,
      "snr": 8.132830463379912,
      "false_alarm_rate": 1.0,
      "combined_far": 9.838364843405464e-07
    },
    "SingleInspiral": [
      {
        "alpha5": 0.0,
        "Gamma9": 0.0,
        "alpha3": 0.0,
        "chi": 0.0,
        "Gamma3": 0.0,
        "mass2": 3.8596239,
        "psi3": 0.0,
        "bank_chisq_dof": 0,
        "alpha4": 0.0,
        "spin1x": 0.0,
        "tau5": 0.0,
        "cont_chisq_dof": 0,
        "tau0": 13.399828,
        "spin2z": -0.7718026,
        "chisq": 0.84257615,
        "ttotal": 0.0,
        "Gamma5": 0.0,
        "Gamma2": 0.0,
        "Gamma7": 0.0,
        "ifo": "H1",
        "tau3": 2.0797865,
        "coa_phase": 1.0123366,
        "template_duration": 16.54621628092527,
        "bank_chisq": 4.4854383,
        "event_duration": 0.0,
        "sigmasq": 94135947.51864928,
        "Gamma4": 0.0,
        "Gamma6": 0.0,
        "mtotal": 33.258221,
        "tau4": 0.0,
        "psi0": 0.0,
        "impulse_time": 0,
        "alpha6": 0.0,
        "spin2x": 0.0,
        "cont_chisq": 0.0,
        "end_time_ns": 296526746,
        "mchirp": 8.4828768,
        "alpha": 0.0,
        "mass1": 29.398598,
        "impulse_time_ns": 0,
        "spin1y": 0.0,
        "Gamma8": 0.0,
        "spin2y": 0.0,
        "spin1z": -0.023584178,
        "channel": "GDS-CALIB_STRAIN_CLEAN",
        "end_time": 1269006850,
        "eta": 0.10258257,
        "kappa": 0.0,
        "search": "",
        "amplitude": 0.0,
        "snr": 4.4854383,
        "alpha2": 0.0,
        "beta": 0.0,
        "rsqveto_duration": 0.0,
        "alpha1": 0.0,
        "chisq_dof": 1,
        "end_time_gmst": 46546.36006766932,
        "f_final": 1024.0,
        "Gamma0": 8754102.0,
        "tau2": 0.0,
        "Gamma1": 682.0
      },
      {
        "alpha5": 0.0,
        "Gamma9": 0.0,
        "alpha3": 0.0,
        "chi": 0.0,
        "Gamma3": 0.0,
        "mass2": 3.8596239,
        "psi3": 0.0,
        "bank_chisq_dof": 0,
        "alpha4": 0.0,
        "spin1x": 0.0,
        "tau5": 0.0,
        "cont_chisq_dof": 0,
        "tau0": 13.399828,
        "spin2z": -0.7718026,
        "chisq": 0.80979407,
        "ttotal": 0.0,
        "Gamma5": 0.0,
        "Gamma2": 0.0,
        "Gamma7": 0.0,
        "ifo": "L1",
        "tau3": 2.0797865,
        "coa_phase": -2.6118183,
        "template_duration": 16.54621628092527,
        "bank_chisq": 6.7840824,
        "event_duration": 0.0,
        "sigmasq": 147851034.091153,
        "Gamma4": 0.0,
        "Gamma6": 0.0,
        "mtotal": 33.258221,
        "tau4": 0.0,
        "psi0": 0.0,
        "impulse_time": 0,
        "alpha6": 0.0,
        "spin2x": 0.0,
        "cont_chisq": 0.0,
        "end_time_ns": 300832569,
        "mchirp": 8.4828768,
        "alpha": 0.0,
        "mass1": 29.398598,
        "impulse_time_ns": 0,
        "spin1y": 0.0,
        "Gamma8": 0.0,
        "spin2y": 0.0,
        "spin1z": -0.023584178,
        "channel": "GDS-CALIB_STRAIN_CLEAN",
        "end_time": 1269006850,
        "eta": 0.10258257,
        "kappa": 0.0,
        "search": "",
        "amplitude": 0.0,
        "snr": 6.7840824,
        "alpha2": 0.0,
        "beta": 0.0,
        "rsqveto_duration": 0.0,
        "alpha1": 0.0,
        "chisq_dof": 1,
        "end_time_gmst": 46546.36006798331,
        "f_final": 1024.0,
        "Gamma0": 8754102.0,
        "tau2": 0.0,
        "Gamma1": 682.0
      }
    ]
  },
  "superevent": null,
  "superevent_neighbours": {
    "S220316o": {
        "... S220316o dict excluded for clarity ..."
  },
  "links": {
    "neighbors": "https://gracedb-test.ligo.org/api/events/G194533/neighbors/",
    "log": "https://gracedb-test.ligo.org/api/events/G194533/log/",
    "emobservations": "https://gracedb-test.ligo.org/api/events/G194533/emobservation/",
    "files": "https://gracedb-test.ligo.org/api/events/G194533/files/",
    "labels": "https://gracedb-test.ligo.org/api/events/G194533/labels/",
    "self": "https://gracedb-test.ligo.org/api/events/G194533",
    "tags": "https://gracedb-test.ligo.org/api/events/G194533/tag/"
  }
}

CWB

{
    "graceid": "G194536",
    "gpstime": 1042312876.509,
    "pipeline": "CWB",
    "labels": [],
    "group": "Burst",
    "extra_attributes": {
        "MultiBurst": {
            "central_freq": 1392.169556,
            "false_alarm_rate": null,
            "confidence": null,
            "start_time_ns": 500000000,
            "start_time": 1042312876,
            "ligo_angle_sig": null,
            "bandwidth": 256.0,
            "single_ifo_times": "1042312876.5073,1042312876.5090",
            "snr": 7.298671111921677,
            "ligo_angle": null,
            "amplitude": 5.017162,
            "ligo_axis_ra": 201.224625,
            "duration": 0.023438,
            "ligo_axis_dec": 69.422546,
            "peak_time_ns": null,
            "peak_time": null,
            "ifos": "H1,L1"
        }
    },
    "links": {
        "neighbors": "https://gracedb-test.ligo.org/api/events/G194536/neighbors/",
        "files": "https://gracedb-test.ligo.org/api/events/G194536/files/",
        "log": "https://gracedb-test.ligo.org/api/events/G194536/log/",
        "tags": "https://gracedb-test.ligo.org/api/events/G194536/tag/",
        "self": "https://gracedb-test.ligo.org/api/events/G194536",
        "labels": "https://gracedb-test.ligo.org/api/events/G194536/labels/",
        "emobservations": "https://gracedb-test.ligo.org/api/events/G194536/emobservation/"
    },
    "created": "2022-03-16 18:18:52 UTC",
    "far": 0.00019265,
    "instruments": "H1,L1",
    "warnings": [],
    "search": "AllSky",
    "nevents": null,
    "superevent": null,
    "submitter": "albert.einstein@LIGO.ORG",
    "superevent_neighbours": {},
    "offline": false,
    "likelihood": 53.2706,
    "far_is_upper_limit": false
}

oLIB

{
    "graceid": "G194537",
    "gpstime": 1216336200.66,
    "pipeline": "oLIB",
    "labels": [],
    "group": "Burst",
    "extra_attributes": {
        "LalInferenceBurst": {
            "omicron_snr_H1": 4.98,
            "omicron_snr_L1": 4.99,
            "hrss_mean": 8.12e-23,
            "frequency_median": 718.03,
            "hrss_median": 2.19e-23,
            "omicron_snr_network": 6.91,
            "quality_mean": 15.2,
            "bsn": 7.19,
            "frequency_mean": 721.23,
            "quality_median": 15.1,
            "omicron_snr_V1": null,
            "bci": 1.111
        }
    },
    "links": {
        "neighbors": "https://gracedb-test.ligo.org/api/events/G194537/neighbors/",
        "files": "https://gracedb-test.ligo.org/api/events/G194537/files/",
        "log": "https://gracedb-test.ligo.org/api/events/G194537/log/",
        "tags": "https://gracedb-test.ligo.org/api/events/G194537/tag/",
        "self": "https://gracedb-test.ligo.org/api/events/G194537",
        "labels": "https://gracedb-test.ligo.org/api/events/G194537/labels/",
        "emobservations": "https://gracedb-test.ligo.org/api/events/G194537/emobservation/"
    },
    "created": "2022-03-16 18:21:37 UTC",
    "far": 7.22e-06,
    "instruments": "H1,L1",
    "warnings": [],
    "search": "AllSky",
    "nevents": 1,
    "superevent": null,
    "submitter": "albert.einstein@LIGO.ORG",
    "superevent_neighbours": {},
    "offline": false,
    "likelihood": null,
    "far_is_upper_limit": false
}

Machine Learning (MLy, aframe)

{
    "submitter": "alan.turing@ligo.org",
    "created": "2024-02-20 16:41:20 UTC",
    "group": "Burst",
    "graceid": "G648217",
    "pipeline": "MLy",
    "gpstime": 1392456472.379048,
    "reporting_latency": 26026.564137,
    "instruments": "H1,L1",
    "nevents": null,
    "offline": false,
    "search": "AllSky",
    "far": 5.855080848625316e-05,
    "far_is_upper_limit": false,
    "likelihood": null,
    "labels": [],
    "extra_attributes": {
        "MLyBurst": {
            "bandwidth": 64.0,
            "central_freq": 309.246308659392,
            "central_time": 1392456472.379048,
            "duration": 0.1875,
            "SNR": 6.015912207824155,
            "detection_statistic": null,
            "scores": {
                "coherency": 0.0799756646156311,
                "coincidence": 0.2124568223953247,
                "combined": 0.016991375573191192
            }
        }
    },
    "superevent": null,
    "superevent_neighbours": {},
    "links": {
        "neighbors": "https://gracedb-test.ligo.org/api/events/G648217/neighbors/",
        "log": "https://gracedb-test.ligo.org/api/events/G648217/log/",
        "emobservations": "https://gracedb-test.ligo.org/api/events/G648217/emobservation/",
        "files": "https://gracedb-test.ligo.org/api/events/G648217/files/",
        "labels": "https://gracedb-test.ligo.org/api/events/G648217/labels/",
        "self": "https://gracedb-test.ligo.org/api/events/G648217",
        "tags": "https://gracedb-test.ligo.org/api/events/G648217/tag/"
    }
}

External (GRB)

{
    "graceid": "E194539",
    "gpstime": 1238065339.32,
    "pipeline": "Fermi",
    "labels": [],
    "group": "External",
    "extra_attributes": {
        "GRB": {
            "author_ivorn": "ivo://nasa.gsfc.tan/gcn",
            "dec": -67.8274,
            "designation": null,
            "redshift": null,
            "how_description": "Fermi Satellite, GBM Instrument",
            "coord_system": "UTC-FK5-GEO",
            "trigger_id": "123456789",
            "error_radius": 8.8374,
            "how_reference_url": "http://gcn.gsfc.nasa.gov/fermi.html",
            "ra": 345.99,
            "ivorn": "fake_ivorn",
            "trigger_duration": null,
            "author_shortname": "Fermi (via VO-GCN)",
            "T90": null,
            "observatory_location_id": "GEOLUN"
        }
    },
    "links": {
        "neighbors": "https://gracedb-test.ligo.org/api/events/E194539/neighbors/",
        "files": "https://gracedb-test.ligo.org/api/events/E194539/files/",
        "log": "https://gracedb-test.ligo.org/api/events/E194539/log/",
        "tags": "https://gracedb-test.ligo.org/api/events/E194539/tag/",
        "self": "https://gracedb-test.ligo.org/api/events/E194539",
        "labels": "https://gracedb-test.ligo.org/api/events/E194539/labels/",
        "emobservations": "https://gracedb-test.ligo.org/api/events/E194539/emobservation/"
    },
    "created": "2022-03-16 18:25:37 UTC",
    "far": null,
    "instruments": "",
    "warnings": [],
    "search": null,
    "nevents": null,
    "superevent": null,
    "submitter": "enrico.fermi@LIGO.ORG",
    "superevent_neighbours": {},
    "offline": false,
    "likelihood": null,
    "far_is_upper_limit": false
}

External (Neutrino)

{
    "warnings": [],
    "submitter": "wolfgang.pauli@ligo.org",
    "created": "2024-03-01 20:18:46 UTC",
    "group": "External",
    "graceid": "E653136",
    "pipeline": "IceCube",
    "gpstime": 1384986914.64,
    "reporting_latency": 8372630.079705,
    "instruments": "",
    "nevents": null,
    "offline": false,
    "search": "HEN",
    "far": 4.667681380010147e-09,
    "far_is_upper_limit": false,
    "likelihood": null,
    "labels": [],
    "extra_attributes": {
        "NeutrinoEvent": {
            "ivorn": "ivo://nasa.gsfc.gcn/AMON#ICECUBE_GOLD_Event2023-11-25T22:34:56.64_24_138599_039138591_0",
            "coord_system": "UTC-FK5-GEO",
            "ra": 176.2601,
            "dec": 52.6366,
            "error_radius": 0.7792,
            "far_ne": 0.1472,
            "far_unit": "yr^-1",
            "signalness": 0.6312,
            "energy": 191.7344,
            "src_error_90": 0.7792,
            "src_error_50": 0.3035,
            "amon_id": 13859939138591,
            "run_id": 138599,
            "event_id": 39138591,
            "stream": 24
        }
    },
    "superevent": null,
    "superevent_neighbours": {},
    "links": {
        "neighbors": "https://gracedb-test.ligo.org/api/events/E653136/neighbors/",
        "log": "https://gracedb-test.ligo.org/api/events/E653136/log/",
        "emobservations": "https://gracedb-test.ligo.org/api/events/E653136/emobservation/",
        "files": "https://gracedb-test.ligo.org/api/events/E653136/files/",
        "labels": "https://gracedb-test.ligo.org/api/events/E653136/labels/",
        "self": "https://gracedb-test.ligo.org/api/events/E653136",
        "tags": "https://gracedb-test.ligo.org/api/events/E653136/tag/"
    }
}

Superevents

What is a superevent?

In reality, what we called “events” above might be better characterized as “triggers”, since different analysis pipelines may detect the same physical GW event and submit it to GraceDB. In order to collect the information about a single physical event in one place, reduce the amount of follow-up processing needed, and issue alerts about only one GraceDB entry per physical event, we have created the “superevent” data model.

A downstream process separate from GraceDB listens for event creations, analyzes their attributes, and determines how to aggregate events into superevents.

Data model

The main attributes of the superevent data model are:

superevent_id: a unique date-based ID (Example: S180912b; more information below in Date-based IDs)
gw_id: a unique date-based ID only assigned to superevents which are confirmed GWs (Example: GW180915BC; more information below in Date-based IDs)
category: superevent category (Production, Test, or MDC); more information below in Categories
gw_events: list of graceids corresponding to Event objects which are part of this superevent and were submitted by GW analysis pipelines
preferred_event: the graceid of the superevent’s preferred event
preferred_event_data: the event dictionary of the superevent preferred event
em_events: list of graceids corresponding to Event objects which are part of this superevent and are in the “External” group (i.e., were observed by electromagnetic or neutrino telescopes)
created: time at which the superevent was created
submitter: user who created the superevent
t_start: time corresponding to start of window for grouping events into this superevent
t_end: time corresponding to end of window for grouping events into this superevent
t_0: best estimate of time at which the GW event occurred

Serialized superevent

Here is an example of a superevent which has been serialized into a JSON:

{
  "superevent_id": "S220316r",
  "gw_id": null,
  "category": "Production",
  "created": "2022-03-16 18:30:10 UTC",
  "submitter": "albert.einstein@LIGO.ORG",
  "preferred_event": "G194542",
  "em_type": null,
  "t_start": 1331490616.298529,
  "t_0": 1331490617.298529,
  "t_end": 1331490618.89512,
  "gw_events": [
    "G194543",
    "G194542",
    "G194541",
    "G194540"
  ],
  "em_events": [],
  "far": 9.652186314922026e-07,
  "time_coinc_far": null,
  "space_coinc_far": null,
  "labels": [],
  "links": {
    "events": "https://gracedb-test.ligo.org/api/superevents/S220316r/events/",
    "labels": "https://gracedb-test.ligo.org/api/superevents/S220316r/labels/",
    "logs": "https://gracedb-test.ligo.org/api/superevents/S220316r/logs/",
    "files": "https://gracedb-test.ligo.org/api/superevents/S220316r/files/",
    "self": "https://gracedb-test.ligo.org/api/superevents/S220316r/",
    "voevents": "https://gracedb-test.ligo.org/api/superevents/S220316r/voevents/",
    "emobservations": "https://gracedb-test.ligo.org/api/superevents/S220316r/emobservations/"
  },
  "preferred_event_data": {
    "submitter": "albert.einstein@LIGO.ORG",
    "created": "2022-03-16 18:30:00 UTC",
    "group": "CBC",
    "graceid": "G194542",
    "pipeline": "gstlal",
    "gpstime": 1331490617.298529,
    "instruments": "H1,L1",
    "nevents": 2,
    "offline": true,
    "search": "AllSky",
    "far": 9.652186314922026e-07,
    "far_is_upper_limit": false,
    "likelihood": 7.102756279364618,
    "labels": [
      "SKYMAP_READY",
      "PASTRO_READY"
    ],
    "extra_attributes": {},
    "superevent": "S220316r",
    "superevent_neighbours": {
      "S220316r": {
        "superevent_id": "S220316r",
        "gw_events": [
          "G194543",
          "G194542",
          "G194541",
          "G194540"
        ],
        "preferred_event": "G194542",
        "preferred_event_data": {
          "submitter": "albert.einstein@LIGO.ORG",
          "created": "2022-03-16 18:30:00 UTC",
          "group": "CBC",
          "graceid": "G194542",
          "pipeline": "gstlal",
          "gpstime": 1331490617.298529,
          "instruments": "H1,L1",
          "nevents": 2,
          "offline": true,
          "search": "AllSky",
          "far": 9.652186314922026e-07,
          "far_is_upper_limit": false,
          "likelihood": 7.102756279364618,
          "labels": [
            "SKYMAP_READY",
            "PASTRO_READY"
          ],
          "extra_attributes": {}
        },
        "far": 9.652186314922026e-07,
        "t_start": 1331490616.298529,
        "t_0": 1331490617.298529,
        "t_end": 1331490618.89512
      }
    },
    "links": {
      "neighbors": "https://gracedb-test.ligo.org/api/events/G194542/neighbors/",
      "log": "https://gracedb-test.ligo.org/api/events/G194542/log/",
      "emobservations": "https://gracedb-test.ligo.org/api/events/G194542/emobservation/",
      "files": "https://gracedb-test.ligo.org/api/events/G194542/files/",
      "labels": "https://gracedb-test.ligo.org/api/events/G194542/labels/",
      "self": "https://gracedb-test.ligo.org/api/events/G194542",
      "tags": "https://gracedb-test.ligo.org/api/events/G194542/tag/"
    }
  }
}

Categories

There are three categories of superevents:

Production: “real” superevents which correspond to potential GW events
Test: used for generic testing superevent creation, annotation, etc.
MDC: generated as part of the mock data challenge (MDC), which comprises a constant stream of events which are sent to GraceDB for testing by internal and LV-EM users

Each category of superevent may only contain events of the corresponding type; i.e., Production superevents may only contain production (G, E, and H-type) events, Test superevents may only contain test (T-type) events, and MDC superevents may only contain MDC (M-type) events.

Letter suffixes for superevent date-based IDs are also calculated independently for each superevent category (see Date-based IDs).

Date-based IDs

We generate IDs for superevents based on the date of their occurrence, at the time of creation. These IDs have three parts:

Prefix
Six digit (YYMMDD) date string
Letter suffix

A few examples are:

S180920abc
TS180717b
GW170817A

Prefix

The prefix is determined by the superevent’s “status” (is it marked as a “confirmed GW” or not) and its category. A superevent’s category will never change, but its status can, resulting in a prefix change. When this happens, the superevent will be accessible (via URLs, the API, searches, etc.) by both its old and new IDs.

Category	Not a confirmed GW	Confirmed GW
`Production`	S	GW
`Test`	TS	TGW
`MDC`	MS	MGW

Date string

The date string is determined by the superevent’s value for t_0 at creation. This is converted from GPS to UTC time and turned into a YYMMDD string. Note that a superevent’s t_0 value may change as additional events are added to it, but this will not change the date string in the superevent’s ID.

Because these date strings are only 6 digits, they are degenerate over a period of 100 years. We currently define this period to run from 1980-01-01 00:00:00 UTC to 2079-12-31 23:59:59 UTC.

If GraceDB is still around at that point, we will probably have to switch to four-digit years.

Letter suffix

The letter suffix is determined by the chronological ordering of superevents observed on a given date by creation time in GraceDB, not by the occurence time of the actual GW event. This is because a unique ID must be determined at creation time and it is not realistic to recalculate it every time a new superevent is created.

The letter suffix just corresponds to the superevent’s number within this chronological ordering. To be explicit: 1 = a, 2 = b, 27 = aa, and so on.

This suffix is calculated independently for each category of superevent. This means that the first Production superevent for a given date will have a suffix of a, and so will the first Test superevent for that date. In this case, ID uniqueness is preserved by the fact that these categories have different prefixes.

When a superevent is confirmed as a GW, a new letter suffix is determined based on how many superevents for the same date have already been confirmed as a GW. Again, this is dependent on the chronological ordering of the time at which this confirmation action takes place, and not by the occurrence time of the actual GW event. Uppercase letters are used for suffixes for confirmed GWs.

Example scenario

Here’s a hypothetical series of superevent creations occurring on March 31, 2018:

A Production superevent is created at 12:00:00 UTC with a t_0 corresponding to 11:30:00 UTC
Another Production superevent is created at 12:05:00 with a t_0 corresponding to 11:00:00 UTC
A Test superevent is created at 12:10:00 with a t_0 corresponding to 12:05:00 UTC
A third Production superevent is created at 12:15:00 with a t_0 corresponding to 10:00:00 UTC

The resulting set of superevent IDs will be:

Creation time (UTC)	`t_0` (UTC)	Category	Superevent ID
12:00:00	11:30:00	`Production`	`S180331a`
12:05:00	11:00:00	`Production`	`S180331b`
12:10:00	12:05:00	`Test`	`TS180331a`
12:15:00	10:00:00	`Production`	`S180331c`

Now let’s say S180331b is confirmed as a GW at 13:00:00 UTC and S180331a is confirmed as a GW at 13:05:00 UTC. This would result in the following superevent IDs:

Creation time (UTC)	`t_0` (UTC)	Category	Superevent ID
12:00:00	11:30:00	`Production`	`GW180331B`
12:05:00	11:00:00	`Production`	`GW180331A`
12:10:00	12:05:00	`Test`	`TS180331a`
12:15:00	10:00:00	`Production`	`S180331c`

Note that the “upgraded” superevents would still be accessible through the web interface, API calls, searches, etc. by either of their IDs.

Annotations

Annotations are pieces of information about an event or superevent that that are added after the event or superevent is created. They are often the results of followup processes, but are sometimes also provided by the same data analysis pipeline that initially generated the event. The most common type of annotation is an log message with the following fields:

submitter: the user who created the log message
created: the time at which the log message was created
filename: the name of the attached file (if applicable)
file_version: the specific version of the file for this message
comment: the log message text

If the uploaded file is an image, it is displayed along with the comment in the GraceDB event or superevent page. Log messages can also be tagged in order to give other users an idea of the thematic category to which the message belongs. Users can invent arbitrary tags, but the following set have a special status, as they affect the display of information in the event page (i.e., they are “blessed”):

analyst_comments: Analyst Comments
em_follow: EM Followup
psd: Noise Curves
data_quality: Data Quality
sky_loc: Sky Localization
background: Background Information
ext_coinc: External Coincidence
strain: Strain Data
tfplots: Time-Frequency Info
pe: Parameter Estimation
sig_info: Significance Info
audio: Sound Files

Other types of annotations are labels, VOEvent objects, EM observation records, and signoffs.

Serialized annotations

Here we show some examples of annotations which have ben serialized into JSON format. These annotations are basically identical whether they are attached to an event or superevent, and these examples show some of each case.

Log

{
    "N": 1,
    "comment": "Initial data upload",
    "created": "2018-09-19 18:29:01 UTC",
    "file": "https://gracedb.ligo.org/api/events/T0140/files/upload.data.gz,0",
    "file_version": 0,
    "filename": "upload_data.gz",
    "issuer": "albert.einstein@LIGO.ORG",
    "self": "https://gracedb.ligo.org/api/events/T0140/logs/1/",
    "tag_names": ["em_follow", "sky_loc"]
}

Label

{
    "created": "2018-09-19 18:29:24 UTC", 
    "creator": "albert.einstein@LIGO.ORG", 
    "name": "DQV", 
    "self": "https://gracedb.ligo.org/api/events/T0140/labels/DQV"
}

Signoff

{
    "comment": "Everything looks good",
    "instrument": "",
    "self": "https://gracedb.ligo.org/api/superevents/TGW800106H/signoffs/ADV/",
    "signoff_type": "ADV",
    "status": "OK",
    "submitter": "albert.einstein@LIGO.ORG"
}

Notes: - status: can be “OK” or “NO” - signoff_type: can be “ADV” (EM advocate) or “OP” (instrument control room operator) - instrument: two-letter instrument code, like “H1”, “L1”, “V1”, etc. For advocate signoffs, this is an empty string.

EMObservation

{
    "N": 1, 
    "comment": "message", 
    "created": "2018-09-19 18:28:57 UTC", 
    "dec": 6.5, 
    "decWidth": 3.6999999999999993, 
    "footprint_count": 4, 
    "footprints": [
        {
            "N": 4, 
            "dec": 8.0, 
            "decWidth": 0.7, 
            "exposure_time": 1, 
            "ra": 4.0, 
            "raWidth": 0.5, 
            "start_time": "2018-09-19 13:29:00 UTC"
        }, 
        {
            "N": 3, 
            "dec": 7.0, 
            "decWidth": 0.7, 
            "exposure_time": 1, 
            "ra": 3.0, 
            "raWidth": 0.5, 
            "start_time": "2018-09-19 13:28:59 UTC"
        }, 
        {
            "N": 2, 
            "dec": 6.0, 
            "decWidth": 0.7, 
            "exposure_time": 1, 
            "ra": 2.0, 
            "raWidth": 0.5, 
            "start_time": "2018-09-19 13:28:58 UTC"
        }, 
        {
            "N": 1, 
            "dec": 5.0, 
            "decWidth": 0.7, 
            "exposure_time": 1, 
            "ra": 1.0, 
            "raWidth": 0.5, 
            "start_time": "2018-09-19 13:28:57 UTC"
        }
    ], 
    "group": "ARI LJMU", 
    "ra": 2.5, 
    "raWidth": 3.5, 
    "submitter": "albert.einstein@LIGO.ORG"
}

VOEvent

{
    "N": 1,
    "created": "2018-09-19 18:29:08 UTC",
    "file_version": 0,
    "filename": "TGW800106H-1-Preliminary.xml",
    "issuer": "albert.einstein@LIGO.ORG",
    "ivorn": "ivo://gwnet/gcn_sender#TGW800106H-1-Preliminary",
    "links": {
        "file": "https://gracedb.ligo.org/api/superevents/TGW800106H/files/TGW800106H-1-Preliminary.xml,0",
        "self": "https://gracedb.ligo.org/api/superevents/TGW800106H/voevents/1/"
    },
    "voevent_type": "PR"
}