A look inside a VOEvent

As we’ve discussed, VOEvents are designed to be readable both by machines and by humans. Let’s start by looking at a real live VOEvent by eye and picking out the important characteristics. Here’s one:

<?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://org.hotwired/exciting_events#123">
  <Who>
    <AuthorIVORN>ivo://hotwired.org</AuthorIVORN>
    <Date>1970-01-01T00:00:00</Date>
    <Author>
      <title>Hotwired VOEvent Tutorial</title>
    </Author>
  </Who>
  <What>
    <Group name="source_flux">
      <Param dataType="float" name="peak_flux" ucd="em.radio.100-200MHz"
             unit="Janskys" value="0.0015">
        <Description>Peak Flux</Description>
      </Param>
      <Param dataType="float" name="int_flux" ucd="em.radio.100-200MHz"
             unit="Janskys" value="2.0e-3">
        <Description>Integrated Flux</Description>
      </Param>
    </Group>
  </What>
  <WhereWhen>
    <ObsDataLocation>
      <ObservatoryLocation id="GEOSURFACE"/>
      <ObservationLocation>
        <AstroCoordSystem id="UTC-FK5-GEO"/>
        <AstroCoords coord_system_id="UTC-FK5-GEO">
          <Time unit="s">
            <TimeInstant>
              <ISOTime>1970-01-01T00:00:00</ISOTime>
            </TimeInstant>
          </Time>
          <Position2D unit="deg">
            <Name1>RA</Name1>
            <Name2>Dec</Name2>
            <Value2>
              <C1>123.5</C1>
              <C2>45</C2>
            </Value2>
            <Error2Radius>0.1</Error2Radius>
          </Position2D>
        </AstroCoords>
      </ObservationLocation>
    </ObsDataLocation>
  </WhereWhen>
  <How>
    <Description>JDS spied with his little eye</Description>
  </How>
  <Why importance="0.5">
    <Inference probability="0.1" relation="identified">
      <Name>GRB121212A</Name>
      <Concept>process.variation.burst;em.radio</Concept>
    </Inference>
  </Why>
  <Citations>
    <EventIVORN cite="followup">ivo://org.hotwired/exciting_events#1</EventIVORN>
  </Citations>
</voe:VOEvent>

The first thing to realise is that it’s not important to understand all the details. There’s a lot of “boilerplate” markup language which isn’t necessary to getting a good overview of what’s going on here. However, it should be pretty easy to tease out a few salient points.

Overall structure

The first thing that should be immediately obvious are the blocks referring to the who, what, where & when, how, and why that we previously discussed.

The Who block in lines 8 to 14 tells us that this event was generated back in 1970 by an author who was eagerly anticipating this tutorial session. What that author observed is described by lines 15 through 26 it was a radio source, for which we provide peak and integrated flux densities in Janskys at a frequency between 100 and 200 MHz. WhereWhen (lines 27–50) tells us that the observation was made at an observatory on the Earth’s surface, and provides an RA and dec with association uncertainties. How just provides a free-form text description of how the observation was made, and Why identifies this with a GRB taking place in 2012 (nearly 43 years after this observation was made—not bad!).

Event roles

While, in general, we’re going to avoid considering the subtleties of the markup, there are a few features it’s worth pointing out. First, right up the top of the event we have the string:

role="test"

This is important. It serves as notice to recipients that the event does not describe an actual astronomical event. If you are experimenting with VOEvent, you should always use the test role, even if you don’t intend for your events to be published: if one should leak of your sandbox, it could be horribly expensive if somebody mistakes it for a notice of a genuine transient and triggers their multi-hundred-million-dollar followup facility.

That said, there are three other possible roles we should mention. observation is the obvious one: it’s reporting the results of a particular observation. utility is informing the recipient about details of the observing system; for example, a change in configuration. Finally, prediction indicates that the author is indulging in a little fortune telling.

IVORNs and identifiers

Next, let’s talk about IVORNs, or “IVOA Resource Names”. IVORNs provide unique identifiers for entities known to the virtual observatory, where “entity” is quite broadly defined. In particular, here we provide an identifier both for the author of the event:

<AuthorIVORN>ivo://org.hotwired</AuthorIVORN>

and for the event itself:

ivo://org.hotwired/exciting_events#123

First, consider the identity of the author: org.hotwired. In formal IVOA terms, this should be a “naming authority” which has the right to create IVOA-compliant identifers for the resources it creates. In practice, the necessary registration material to make this worthwhile for VOEvents isn’t yet in place, so we’ll improvise: choose a string which you are confident will usefully identify you (or your facility) to the recipient, and which is unlikely to clash with anybody else issuing VOEvents. Using a straightforward internet host (DNS) name (like hotwired.org) is discouraged (folks might try to resolve it through the normal internet systems, which will fail), but reversing it to create something which is uniquely tied to a given organization but which can’t be confused with a regular host name should work, and that’s exactly what we’ve done here.

Now, look at the identity of the event itself. This is particularly worth noting, as the VOEvent standard assigns specific meanings to each part. In this case, we are considering event number 123 published to the exciting_events stream by org.hotwired. In general, we expect events to be grouped into streams in this way, where a stream represents a specific source of events—a given instrument or a particular way of processing the data, say. A single naming authority could manage multiple streams (so we could imagine org.hotwired also publishing to the tedious_events stream).

We can refer to other events by specifying their IVORN. For example, this event specifies:

<Citations>
  <EventIVORN cite="followup">ivo://org.hotwired/exciting_events#1</EventIVORN>
</Citations>

This means that this VOEvent is reporting a follow-up to a previous observation, which was described by event 1 in the same stream. As well as followup, it is also possible for the current event to use supersedes to provide a corrected version of a previous event, or retraction to withdraw it altogether. Ultimately, an event aggregation service could group together VOEvents which cite each other to build up a full description of a particular astronomical event.

At time of writing, there is no central body for VOEvents which creates naming authorities or enforces standards on IVORNs. For now, you’re simply encouraged to structure your IVORNS following the above guidelines. Longer term, work is ongoing to integrate the VOEvent system with the wider VOEvent “registry” system, which will help ensure standards are enforced and provide mechanisms to look up details of particular authors, available event streams, and the events themselves.

Unified Content Descriptors

Depending on the source of the event, it might be “obvious” to the human that “peak flux” measured in Janskys likely refers to some sort of electromagnetic radiation. However, the computer which might be automatically processing and making decisions based on this VOEvent needs all the help it can get. To that end, we can annotate the event with Unified Content Descriptors, or UCDs (Derriere et al, 2005). For example, we write

ucd="em.radio.100-200MHz"

to indicate the type of measurement that peak_flux and int_flux refer to. A very similar idea applies to the scientific inference:

<Concept>process.variation.burst;em.radio</Concept>