From 22a155afb0f25c6a8f8951e1cb2f40ba08e68510 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Fri, 27 Sep 2024 16:26:53 +0200 Subject: [PATCH 1/3] [Whitespace only] remove trailing blanks --- Makefile | 2 +- VOEvent-v2.1.xsd | 2 +- VOEvent.tex | 1610 ++++++++++++++++++++-------------------- VOEventRegExt-v2.0.xsd | 4 +- 4 files changed, 809 insertions(+), 809 deletions(-) diff --git a/Makefile b/Makefile index 14dbd4f..88cf5d6 100644 --- a/Makefile +++ b/Makefile @@ -26,7 +26,7 @@ FIGURES = role_diagram.svg # List of PDF figures (figures that must be converted to pixel images to # work in web browsers). -VECTORFIGURES = +VECTORFIGURES = # Additional files to distribute (e.g., CSS, schema files, examples...) AUX_FILES = VOEvent-v2.1.xsd VOEventRegExt-v2.0.xsd resrec-sample.vor diff --git a/VOEvent-v2.1.xsd b/VOEvent-v2.1.xsd index 74405b6..2a3cb80 100644 --- a/VOEvent-v2.1.xsd +++ b/VOEvent-v2.1.xsd @@ -18,7 +18,7 @@ Revision 2.1 2020/05/05 BaptisteCecconi - added "coord_value" type introducing "ucd" and "unit" attributes for C1, C2 and C3 elements - added "error2" type, with "C1" and "C2" elements - added "error3" type, with "C1", "C2" and "C3" elements -- added "TimeFrameType" (taken from to STC-1.30) +- added "TimeFrameType" (taken from to STC-1.30) - added "SpaceFrameType" (taken from to STC-1.30) --> } and {\tt +external schemata such as the IVOA's Space-Time Coordinate (STC) metadata +specification \citep{2007ivoa.spec.1030R}. Some of the VOEvent structure is +provided by this document, for example the meaning of the {\tt } and {\tt } elements; however other structure is provided by the author of the event -stream, who might define, for example, what the {\tt } and {\tt -} parameters mean when supplied with one of those events. - -VOEvent is a pragmatic effort that crosses the boundary between the Virtual -Observatory and the larger astronomical community. The results of astronomical -observations using real telescopes will be expressed using the IVOA VOEvent -standard and disseminated by registries and brokers within and outside the VO. -Each event that survives rigorous filtering can then be passed to other -telescopes to acquire follow-up observations that will confirm (or deny) the -original hypothesis as to the classification of the object(s) or processes that -generated that particular VOEvent in the first place. This must happen quickly -(often within seconds of the original VOEvent) and must minimise unnecessary -expenditures of either real or virtual resources. - -VOEvent is \emph{transport neutral}, but deploying and operating a robust -general-purpose network of interoperating brokers has always been a -high-priority issue. Various special-purpose networks and prototype networks +stream, who might define, for example, what the {\tt } and {\tt +} parameters mean when supplied with one of those events. + +VOEvent is a pragmatic effort that crosses the boundary between the Virtual +Observatory and the larger astronomical community. The results of astronomical +observations using real telescopes will be expressed using the IVOA VOEvent +standard and disseminated by registries and brokers within and outside the VO. +Each event that survives rigorous filtering can then be passed to other +telescopes to acquire follow-up observations that will confirm (or deny) the +original hypothesis as to the classification of the object(s) or processes that +generated that particular VOEvent in the first place. This must happen quickly +(often within seconds of the original VOEvent) and must minimise unnecessary +expenditures of either real or virtual resources. + +VOEvent is \emph{transport neutral}, but deploying and operating a robust +general-purpose network of interoperating brokers has always been a +high-priority issue. Various special-purpose networks and prototype networks for the global VOEventNet have been deployed and operated. See references under -SkyAlert \citep{bib05} and Transport \citep{bib33} for two options. +SkyAlert \citep{bib05} and Transport \citep{bib33} for two options. Following the Abstract and Introduction, this document contains a discussion of appropriate VOEvent usage in \S\ref{sec:2}. Section \S\ref{sec:3} is the heart of the document, conveying the semantics of a VOEvent packet. Explicit examples -of VOEvent packets are in \S\ref{sec:4}, and linked references in \S\ref{sec:5}. +of VOEvent packets are in \S\ref{sec:4}, and linked references in \S\ref{sec:5}. \section{Usage} \label{sec:2} -This document defines the syntax and semantics of an alert packet known as -VOEvent \citep{2011ivoa.spec.0711S}. In this document, the word \emph{packet} -will refer to a single, syntactically complete, VOEvent alert or message, +This document defines the syntax and semantics of an alert packet known as +VOEvent \citep{2011ivoa.spec.0711S}. In this document, the word \emph{packet} +will refer to a single, syntactically complete, VOEvent alert or message, however transmitted or stored. The transmission of such a packet announces that -an astronomical ``event'' has occurred, or provides information contingent on a -previous VOEvent through a citation mechanism. The packet may include -information regarding the ``who, what, where, when \& how'' of the event, and -may express ``why'' hypotheses regarding the physical cause of the observed -event and the likelihood of each of these hypotheses. +an astronomical ``event'' has occurred, or provides information contingent on a +previous VOEvent through a citation mechanism. The packet may include +information regarding the ``who, what, where, when \& how'' of the event, and +may express ``why'' hypotheses regarding the physical cause of the observed +event and the likelihood of each of these hypotheses. \subsection{Publishing VOEvent Packets} \label{sec:2.1} -VOEvent packets express sky transient alerts. VOEvent users subscribe to the +VOEvent packets express sky transient alerts. VOEvent users subscribe to the types of alerts pertinent to their science goals. The following roles define the -interchange of VOEvent semantics: +interchange of VOEvent semantics: \begin{itemize} -\item An \emph{\bf Author} is anyone (or any organisation) creating scientific -content suitable for representation as a sky transient alert. An author will -typically register with the IVOA registry, so that the {\tt } element of -VOEvent packets can be small and reusable, expressing only the IVOA identifier -needed to retrieve the contact information for the author. An authoring -organisation or individual may often rely on autonomous systems to actually -create and transport the individual alert messages. -\item A \emph{\bf Publisher} receives alerts from one-or-more authors, and -assigns a unique identifier to each resulting packet. Either the author or the -publisher generates the actual XML syntax of the event, but the publisher is -responsible for the validity of the packet relative to the VOEvent schema. -Publishers will register with the IVOA registry as described below. -\item A \emph{\bf Repository} subscribes to (or is party to the original -creation of) one or more VOEvent streams, persists packets either permanently -or temporarily, and runs a service that allows clients to resolve identifiers -and apply complex queries to its holdings. A given packet had one Publisher but -may be held in more than one Repository. Public repositories will register with -the IVOA registry. -\item A \emph{\bf Subscriber} is any entity that receives VOEvent packets for -whatever purpose. Subscribers can find out how to get certain types of events -by consulting the lists of publishers and repositories in the IVOA registry. -A subscription is a filter on the stream of events from a publisher: the -subscriber is notified whenever certain criteria are met. For example, the -filter may involve the curation part of the event (\emph{e.g., ``all events -published by the Swift spacecraft''}), its location (\emph{``anything in -M31''}), or it may reference the detailed metadata of the event itself -(\emph{``whenever the cosmic ray energy is greater than 3 TeV''}). -\item A Broker or Relay, also sometimes known as a Filter, is any combination -of the atomic roles of Publisher, Repository, or Subscriber that also offers -arbitrary application-level functionality. See the IVOA VOEvent Transport Note -\citep{2011ivoa.spec.0711S} for further discussion. +\item An \emph{\bf Author} is anyone (or any organisation) creating scientific +content suitable for representation as a sky transient alert. An author will +typically register with the IVOA registry, so that the {\tt } element of +VOEvent packets can be small and reusable, expressing only the IVOA identifier +needed to retrieve the contact information for the author. An authoring +organisation or individual may often rely on autonomous systems to actually +create and transport the individual alert messages. +\item A \emph{\bf Publisher} receives alerts from one-or-more authors, and +assigns a unique identifier to each resulting packet. Either the author or the +publisher generates the actual XML syntax of the event, but the publisher is +responsible for the validity of the packet relative to the VOEvent schema. +Publishers will register with the IVOA registry as described below. +\item A \emph{\bf Repository} subscribes to (or is party to the original +creation of) one or more VOEvent streams, persists packets either permanently +or temporarily, and runs a service that allows clients to resolve identifiers +and apply complex queries to its holdings. A given packet had one Publisher but +may be held in more than one Repository. Public repositories will register with +the IVOA registry. +\item A \emph{\bf Subscriber} is any entity that receives VOEvent packets for +whatever purpose. Subscribers can find out how to get certain types of events +by consulting the lists of publishers and repositories in the IVOA registry. +A subscription is a filter on the stream of events from a publisher: the +subscriber is notified whenever certain criteria are met. For example, the +filter may involve the curation part of the event (\emph{e.g., ``all events +published by the Swift spacecraft''}), its location (\emph{``anything in +M31''}), or it may reference the detailed metadata of the event itself +(\emph{``whenever the cosmic ray energy is greater than 3 TeV''}). +\item A Broker or Relay, also sometimes known as a Filter, is any combination +of the atomic roles of Publisher, Repository, or Subscriber that also offers +arbitrary application-level functionality. See the IVOA VOEvent Transport Note +\citep{2011ivoa.spec.0711S} for further discussion. \end{itemize} \subsection{VO Identifiers (IVORNs)} \label{sec:2.2} -VOEvent benefits from the IVOA identifiers developed for the VO registry. Such +VOEvent benefits from the IVOA identifiers developed for the VO registry. Such an identifier is called an \emph{IVORN}, that is, an \emph{International Virtual -Observatory Resource Name}. It is required to begin with ``{\tt ivo://}'', and +Observatory Resource Name}. It is required to begin with ``{\tt ivo://}'', and will stand in for a particular packet. A \emph{registered} VOEvent packet is one that has a valid identifier --- meaning that a mechanism exists that can resolve -that identifier to the full VOEvent packet. VOEvent identifiers thus provide a -citation mechanism --- a way to express that one VOEvent packet is a -\emph{follow-up} in some fashion of a previous packet. For these reasons, -VOEvent packets will often contain VO identifiers \citep{2016ivoa.spec.0523D}. +that identifier to the full VOEvent packet. VOEvent identifiers thus provide a +citation mechanism --- a way to express that one VOEvent packet is a +\emph{follow-up} in some fashion of a previous packet. For these reasons, +VOEvent packets will often contain VO identifiers \citep{2016ivoa.spec.0523D}. These take the general form {\tt ivo://authorityID/resourceKey\#local\_ID}, and are references to metadata packets that may be found at a VO registry or VOEvent -repository. There are several types of metadata schema that the registry can +repository. There are several types of metadata schema that the registry can hold. For the purposes of VOEvent, the principal schemata are: \begin{itemize} -\item {\bf VOEvent}: the metadata packet for an alert resulting from the -observation of a transient celestial event. This schema is defined in this -document. -\item {\bf VOEventStreamRegExt}: the metadata packet for a stream of VOEvents, -including information about who is running it, the parameters that may be -included and their meaning. The VOEventStreamRegExt may also be shortened to -just `stream', they mean the same thing. -\item {\bf VOEventServerRegExt}: the metadata packet to describe a service that -provides VOEvents, which may be past events from a repository query service, or -may be events sent in near real-time from a subscription service. The server -definition includes the list of streams whose events are kept, the service -endpoint to query the repository, or the endpoint to resolve a VOEvent -identifier. -\item {\bf Author Organisation}: these metadata \citep{2007ivoa.spec.0302H} -describe an author, including contact information and a description of the -project. The VOEvent {\bf } element contains either a reference to an -author's IVORN or explicit contact information sufficient to describe the -author. +\item {\bf VOEvent}: the metadata packet for an alert resulting from the +observation of a transient celestial event. This schema is defined in this +document. +\item {\bf VOEventStreamRegExt}: the metadata packet for a stream of VOEvents, +including information about who is running it, the parameters that may be +included and their meaning. The VOEventStreamRegExt may also be shortened to +just `stream', they mean the same thing. +\item {\bf VOEventServerRegExt}: the metadata packet to describe a service that +provides VOEvents, which may be past events from a repository query service, or +may be events sent in near real-time from a subscription service. The server +definition includes the list of streams whose events are kept, the service +endpoint to query the repository, or the endpoint to resolve a VOEvent +identifier. +\item {\bf Author Organisation}: these metadata \citep{2007ivoa.spec.0302H} +describe an author, including contact information and a description of the +project. The VOEvent {\bf } element contains either a reference to an +author's IVORN or explicit contact information sufficient to describe the +author. \end{itemize} -When such an identifier is \emph{resolved}, it means that the VOEvent metadata -packet is obtained in exchange for the identifier. Such resolution happens +When such an identifier is \emph{resolved}, it means that the VOEvent metadata +packet is obtained in exchange for the identifier. Such resolution happens through the global, distributed IVOA registry in stages. The registry is queried -to locate a repository holding the relevant packet, and then the repository is -queried for the packet itself. The part of the IVORN before the ``{\tt\#}'' +to locate a repository holding the relevant packet, and then the repository is +queried for the packet itself. The part of the IVORN before the ``{\tt\#}'' symbol points to the \emph{VOEventStreamRegExt} of which the event is a member; the whole IVORN (that includes the {\tt local\_ID}) points to the event itself. Thus VOEvent identifiers serve two purposes; they contain a stream identifier, -then the ``{\tt\#}'' sign, then the local reference within that stream. +then the ``{\tt\#}'' sign, then the local reference within that stream. -This is a key point in understanding VOEvent identifiers: {\bf The Event -identifier also expresses the Stream identifier.} For example: +This is a key point in understanding VOEvent identifiers: {\bf The Event +identifier also expresses the Stream identifier.} For example: \begin{itemize} \item {\tt ivo://nvo.caltech/voeventnet/catot\#1004071150784109051}\\ This identifier points to a specific VOEvent (number {\tt 1004071150784109051}) -that is an instance of the stream called {\tt -ivo://nvo.caltech/voeventnet/catot}. However, this IVORN will not resolve from -the global VO registry, but only from a repository that has this stream of -events. +that is an instance of the stream called {\tt +ivo://nvo.caltech/voeventnet/catot}. However, this IVORN will not resolve from +the global VO registry, but only from a repository that has this stream of +events. \item {\tt ivo://nvo.caltech/voeventnet/catot}\\ -This Stream identifier can be looked up in any VO registry, returning a -description, who runs it, the names, semantics, and descriptions of the -parameters used in the events, how to subscribe, etc. In this case, the stream -represents optical transients from the CRTS survey. For resolving the event +This Stream identifier can be looked up in any VO registry, returning a +description, who runs it, the names, semantics, and descriptions of the +parameters used in the events, how to subscribe, etc. In this case, the stream +represents optical transients from the CRTS survey. For resolving the event itself, we want a repository that will have the event, so a query would be used -like this: ``\emph{Find repositories that keep the events from this Stream}'' +like this: ``\emph{Find repositories that keep the events from this Stream}'' \end{itemize} -The nature of a standard service to query VOEvent server records and the +The nature of a standard service to query VOEvent server records and the metadata necessary to describe a Stream remain under discussion in the VOEvent -Working Group. +Working Group. \subsection{Authentication and Authorisation} \label{sec:2.3} VOEvents provide a mechanism for alerting members of the astronomical community to time-critical celestial phenomena. As a result of such an alert, significant hardware, software and personnel assets of the community may be retargeted to -investigate those phenomena. The scientific and financial costs of such -retargeting may be large, but the potential scientific gains are larger. The +investigate those phenomena. The scientific and financial costs of such +retargeting may be large, but the potential scientific gains are larger. The success of VOEvent --- and of observations of astronomical transients in general ---- depends on minimising both intentional and unintentional noise/spam -associated with this communications channel. All of the familiar internet -security worries apply to VOEvents. A discussion of these issues is available -under Authentication \citep{bib34} from both the VOEvent standpoint and for -comparison, general XML signatures. +--- depends on minimising both intentional and unintentional noise/spam +associated with this communications channel. All of the familiar internet +security worries apply to VOEvents. A discussion of these issues is available +under Authentication \citep{bib34} from both the VOEvent standpoint and for +comparison, general XML signatures. \section{VOEvent Semantics} \label{sec:3} -A VOEvent packet provides a general purpose mechanism for representing -information about transient astronomical events. However, not all VO data are -suitable for expression using VOEvent. The VOEvent schema -\citep{2011ivoa.spec.0711S} is as simple as practical to allow the minimal -representation of scientifically meaningful, time critical, events. VOEvent -also borrows other standard VO and astronomical schema, specifically STC for -space-time coordinates. The usual IVOA standards such as registries and UCD -identifiers are used. VOEvent has a strong interest in the development of -complete and robust astronomical ontologies, but must rely on pragmatic and -immediately useful prototypes of planned facilities. - -By definition, a VOEvent packet contains a single XML {\tt } element. -If multiple {\tt } elements are jointly contained within a larger -document in some fashion, they should still be handled as separate alert -packets. A {\tt } element may contain at most one of each of the +A VOEvent packet provides a general purpose mechanism for representing +information about transient astronomical events. However, not all VO data are +suitable for expression using VOEvent. The VOEvent schema +\citep{2011ivoa.spec.0711S} is as simple as practical to allow the minimal +representation of scientifically meaningful, time critical, events. VOEvent +also borrows other standard VO and astronomical schema, specifically STC for +space-time coordinates. The usual IVOA standards such as registries and UCD +identifiers are used. VOEvent has a strong interest in the development of +complete and robust astronomical ontologies, but must rely on pragmatic and +immediately useful prototypes of planned facilities. + +By definition, a VOEvent packet contains a single XML {\tt } element. +If multiple {\tt } elements are jointly contained within a larger +document in some fashion, they should still be handled as separate alert +packets. A {\tt } element may contain at most one of each of the following optional sub-elements: \begin{itemize} -\item[\tt ] Identification of scientifically responsible Author (see +\item[\tt ] Identification of scientifically responsible Author (see \S\ref{sec:3.2}) -\item[\tt ] Event Characterisation modelled by the Author (see +\item[\tt ] Event Characterisation modelled by the Author (see \S\ref{sec:3.3}) \item[\tt ] Space-Time Coordinates of the event (see \S\ref{sec:3.4}) \item[\tt ] Instrument Configuration (see \S\ref{sec:3.5}) @@ -408,354 +408,354 @@ \section{VOEvent Semantics} \item[\tt ] External Content (see \S\ref{sec:3.9}) \end{itemize} -Only those elements required to convey the event being described need be -present; the ordering of elements is not formally constrained. The intent of -VOEvent is to describe a single astronomical transient event per packet. -Multiple events should be expressed using multiple packets. On the other hand, -complex observations may best be expressed using multiple follow-up packets or -via embedded {\tt } to external resources such as VOTables or RTML -documents. XML structures other than those listed in this document should be -used with care within a {\tt } element, but some applications may -require the freedom to reference schema outside the scope of this specification. -Section 4 contains examples of complete VOEvent packets. +Only those elements required to convey the event being described need be +present; the ordering of elements is not formally constrained. The intent of +VOEvent is to describe a single astronomical transient event per packet. +Multiple events should be expressed using multiple packets. On the other hand, +complex observations may best be expressed using multiple follow-up packets or +via embedded {\tt } to external resources such as VOTables or RTML +documents. XML structures other than those listed in this document should be +used with care within a {\tt } element, but some applications may +require the freedom to reference schema outside the scope of this specification. +Section 4 contains examples of complete VOEvent packets. \subsection{{\tt } --- identifiers, roles and versions} \label{sec:3.1} A {\tt } expresses the discovery of a sky transient event, located in a -region of space and time, observed by an instrument, and published by a person -or institution who may have developed a hypothesis about the underlying -classification of the event. +region of space and time, observed by an instrument, and published by a person +or institution who may have developed a hypothesis about the underlying +classification of the event. -The {\tt } element has three attributes: +The {\tt } element has three attributes: \noindent {\bf 3.1.1} {\tt ivorn} \label{sec:3.1.1} --- -Each VOEvent packet is required to have one-and-only-one identifier, expressed -with the {\tt ivorn} attribute. VOEvent identifiers are URIs -\citep{2016ivoa.spec.0523D}. As the issuance of duplicate identifiers would -diminish the trust placed in systems exchanging VOEvents, it is anticipated that -a number of VOEvent publishers will be founded to issue unique IVORNs from a -variety of useful and appropriate namespaces. The non-opaque URI identifier is -constructed systematically so that the identifier of a different resource, the -VOEventStreamRegExt, is deducible from the identifier of an event. The first -part is the identifier for the publisher, and the event identifier is built -from this, then a {\tt\#} symbol, then a local string that is meaningful only +Each VOEvent packet is required to have one-and-only-one identifier, expressed +with the {\tt ivorn} attribute. VOEvent identifiers are URIs +\citep{2016ivoa.spec.0523D}. As the issuance of duplicate identifiers would +diminish the trust placed in systems exchanging VOEvents, it is anticipated that +a number of VOEvent publishers will be founded to issue unique IVORNs from a +variety of useful and appropriate namespaces. The non-opaque URI identifier is +constructed systematically so that the identifier of a different resource, the +VOEventStreamRegExt, is deducible from the identifier of an event. The first +part is the identifier for the publisher, and the event identifier is built +from this, then a {\tt\#} symbol, then a local string that is meaningful only in the context of that publisher. \noindent {\bf 3.1.2} {\tt role} \label{sec:3.1.2} --- The optional {\tt role} attribute accepts the enumerated options: \begin{itemize} -\item The value ``\emph{observation}'' is the default if the role is missing; -this means that the packet describes an observation of the actual universe. -\item The value ``\emph{prediction}'' indicates that the VOEvent describes an -event of whatever description that has yet to occur when the packet is created. +\item The value ``\emph{observation}'' is the default if the role is missing; +this means that the packet describes an observation of the actual universe. +\item The value ``\emph{prediction}'' indicates that the VOEvent describes an +event of whatever description that has yet to occur when the packet is created. \item The value ``\emph{utility}'' means that the packet expresses nothing about -astrophysics, but rather information about the observing system. This could be -used, for example, for a satellite to express that it has changed its -configuration. -\item The value ``\emph{test}'' means that the packet does not describe actual +astrophysics, but rather information about the observing system. This could be +used, for example, for a satellite to express that it has changed its +configuration. +\item The value ``\emph{test}'' means that the packet does not describe actual astronomical events, but rather is part of a testing procedure of some kind. \end{itemize} -It is the responsibility of all who receive VOEvent packets to pay attention to -the {\tt role}, and to be quite sure of the difference between an actual event -and a test of the system or a prediction of an event that has yet to happen. +It is the responsibility of all who receive VOEvent packets to pay attention to +the {\tt role}, and to be quite sure of the difference between an actual event +and a test of the system or a prediction of an event that has yet to happen. -\noindent {\bf 3.1.3} {\tt version} \label{sec:3.1.3} --- -The {\tt version} attribute is required to be present and to equal "2.0" for -all VOEvent packets governed by this version of the standard. There is no -default value. +\noindent {\bf 3.1.3} {\tt version} \label{sec:3.1.3} --- +The {\tt version} attribute is required to be present and to equal "2.0" for +all VOEvent packets governed by this version of the standard. There is no +default value. -For example, a {\tt } packet resulting from Tycho Brahe's discovery of -a ``Stella Nova'' in Cassiopeia on 11 November 1572 might start: +For example, a {\tt } packet resulting from Tycho Brahe's discovery of +a ``Stella Nova'' in Cassiopeia on 11 November 1572 might start: \begin{lstlisting}[language=XML] - \end{lstlisting} -The {\tt xmlns} attribute refers to one-or-more standard XML namespace -declarations that may optionally help define the contents of a packet. +The {\tt xmlns} attribute refers to one-or-more standard XML namespace +declarations that may optionally help define the contents of a packet. \subsection{{\tt } --- Curation Metadata} \label{sec:3.2} -This element of a VOEvent packet is devoted to curation metadata: who is -responsible for the information content of the packet. Usage should be -compatible with section 3.2 of the IVOA Resource Metadata specification -\citep{2007ivoa.spec.0302H}. Typical curation content would include: +This element of a VOEvent packet is devoted to curation metadata: who is +responsible for the information content of the packet. Usage should be +compatible with section 3.2 of the IVOA Resource Metadata specification +\citep{2007ivoa.spec.0302H}. Typical curation content would include: \subsubsection{\tt } -Author information follows the IVOA curation information schema: the +Author information follows the IVOA curation information schema: the organisation responsible for the packet can have a title, short name or acronym, -and a logo. A contact person has a name, email, and phone number. Other -contributors can also be noted. +and a logo. A contact person has a name, email, and phone number. Other +contributors can also be noted. -An example of Author information might be: +An example of Author information might be: \begin{lstlisting}[language=XML] Rapid Telescope for Optical Response - Raptor - http://www.raptor.lanl.gov/images/RAPTOR_patchLarge.jpg - Robert White + Raptor + http://www.raptor.lanl.gov/images/RAPTOR_patchLarge.jpg + Robert White rwhite@lanl.gov +1 800 555 1212 - + \end{lstlisting} -Contributor information can be included using as many {\tt } -elements as necessary. The element value is the full name of the person or -organisation. Each element can have three optional attributes: an {\tt ivorn} -attribute to refer to the person's or organisation information in the VO -registry; an {\tt altIdentifier} attribute to refer to other identifier (such +Contributor information can be included using as many {\tt } +elements as necessary. The element value is the full name of the person or +organisation. Each element can have three optional attributes: an {\tt ivorn} +attribute to refer to the person's or organisation information in the VO +registry; an {\tt altIdentifier} attribute to refer to other identifier (such as an ORCID (Open Researcher and Contributor ID)\footnote{ -\url{https://orcid.org}} for persons, or a Research Organisation Registry -(ROR)\footnote{\url{https://ror.org}} identifier for institutions), in the form -of an URI; and a {\tt role} attribute. The {\tt role} attribute is an important -part of the contributor's metadata and allows proper attribution of work. We -propose to use here the list of \emph{contributorType} from the Datacite +\url{https://orcid.org}} for persons, or a Research Organisation Registry +(ROR)\footnote{\url{https://ror.org}} identifier for institutions), in the form +of an URI; and a {\tt role} attribute. The {\tt role} attribute is an important +part of the contributor's metadata and allows proper attribution of work. We +propose to use here the list of \emph{contributorType} from the Datacite Metadata Schema v4.3 \citep{https://doi.org/10.14454/7xq3-zf69}. \subsubsection{\tt } -As an alternative to quoting Author information over and over, this information -can be published to the VO registry, then referenced through an IVORN. The {\tt -} element contains the identifier of the organisation responsible -for making the VOEvent available. Event subscribers will often use this as their -primary filtering criterion. Many subscribers will only want events from a -particular publisher, or more precisely, from a specific content creator. In -general, {\tt } should be a VOResource identifier that resolves to -an organisation in the sense of \citep{2007ivoa.spec.0302H}. Publishers and -subscribers may use this VOResource to exchange curation metadata directly. +As an alternative to quoting Author information over and over, this information +can be published to the VO registry, then referenced through an IVORN. The {\tt +} element contains the identifier of the organisation responsible +for making the VOEvent available. Event subscribers will often use this as their +primary filtering criterion. Many subscribers will only want events from a +particular publisher, or more precisely, from a specific content creator. In +general, {\tt } should be a VOResource identifier that resolves to +an organisation in the sense of \citep{2007ivoa.spec.0302H}. Publishers and +subscribers may use this VOResource to exchange curation metadata directly. \subsubsection{\tt } -The {\tt } contains the date and time of the creation of the VOEvent -packet. The required format is a subset of ISO-8601 (\emph{e.g., {\tt -yyyy-mm-ddThh:mm:ss}}). The timescale --- for curation purposes only --- is -assumed to be Coordinated Universal Time (UTC). Discussions of date and time for -the expression of meaningful scientific coordinates may be found in -\citep{2007ivoa.spec.1030R} and \citep{bib26}. +The {\tt } contains the date and time of the creation of the VOEvent +packet. The required format is a subset of ISO-8601 (\emph{e.g., {\tt +yyyy-mm-ddThh:mm:ss}}). The timescale --- for curation purposes only --- is +assumed to be Coordinated Universal Time (UTC). Discussions of date and time for +the expression of meaningful scientific coordinates may be found in +\citep{2007ivoa.spec.1030R} and \citep{bib26}. -Minimal {\tt } usage might resemble: +Minimal {\tt } usage might resemble: \begin{lstlisting}[language=XML] ivo://uraniborg.hven/Tycho 1573-05-05T01:23:45Z - + \end{lstlisting} -Tycho first noted SN 1572 on 11 November of that year. The event was published -in Tycho's pamphlet \emph{De Stella Nova} by 5 May 1573, thus this later date is -placed in the curation metadata. More detailed curation metadata can be -retrieved directly from the publisher. +Tycho first noted SN 1572 on 11 November of that year. The event was published +in Tycho's pamphlet \emph{De Stella Nova} by 5 May 1573, thus this later date is +placed in the curation metadata. More detailed curation metadata can be +retrieved directly from the publisher. \subsection{{\tt } --- Event Characterisation} \label{sec:3.3} -The {\tt } and {\tt } elements work together to characterise the -nature of a VOEvent. That is: {\tt } has author-defined parameters about -what was measured directly, or other relevant information about the event, -versus {\tt } is a data model of fixed schema about the hypothesised -underlying cause or causes of the astrophysical event. - -In general, an observation is the association of one or more dependent variables -with zero or more independent variables. The {\tt } element, for -example, is often used to express the independent variables in an observation ---- where was the telescope pointed and when was the camera shutter opened. The -{\tt } element, on the other hand, is typically used to express the -dependent variables --- what was seen at that location at that time. - -A {\tt } element contains a list of {\tt } elements which may be -associated and labeled using {\tt } elements. It may also have one or -more elements, each of which can contain {\tt } and {\tt } -elements: these last define a whole column, or vector of data, rather than a -single primitive value as with . See \S\ref{sec:4} for an example of -usage. +The {\tt } and {\tt } elements work together to characterise the +nature of a VOEvent. That is: {\tt } has author-defined parameters about +what was measured directly, or other relevant information about the event, +versus {\tt } is a data model of fixed schema about the hypothesised +underlying cause or causes of the astrophysical event. + +In general, an observation is the association of one or more dependent variables +with zero or more independent variables. The {\tt } element, for +example, is often used to express the independent variables in an observation +--- where was the telescope pointed and when was the camera shutter opened. The +{\tt } element, on the other hand, is typically used to express the +dependent variables --- what was seen at that location at that time. + +A {\tt } element contains a list of {\tt } elements which may be +associated and labeled using {\tt } elements. It may also have one or +more
elements, each of which can contain {\tt } and {\tt } +elements: these last define a whole column, or vector of data, rather than a +single primitive value as with . See \S\ref{sec:4} for an example of +usage. \subsubsection{{\tt } --- Numbers and strings with semantics} %\addtocounter{subsubsection}{1} \label{sec:3.3.1} -{\tt } elements may be used to represent the values of arbitrarily named -quantities. Thus a publisher need not establish a fixed schema for all events +{\tt } elements may be used to represent the values of arbitrarily named +quantities. Thus a publisher need not establish a fixed schema for all events they issue. Unified Content Descriptors (UCDs) \citep{2018ivoa.spec.0527P}. %\citep{std:UCD} -may be used to clarify meaning. Usage of {\tt } and {\tt } is -similar to the VOTable specification, see \S4.9 of \citep{2019ivoa.spec.1021O}. +may be used to clarify meaning. Usage of {\tt } and {\tt } is +similar to the VOTable specification, see \S4.9 of \citep{2019ivoa.spec.1021O}. -A {\tt } may contain elements {\tt } and {\tt }. -Like most VOEvent elements, these can be used to give further descriptive -documentation about what this parameter means. The {\tt } may also -contain an element {\tt } for the value of the parameter, as an alternate -to the `value' attribute defined below: if both are present, the attribute takes -precedence over the element. This allows parameter values to include a richer -variety of text strings, to avoid strings being changed by Attribute-Value -normalisation\footnote{\url{https://www.w3.org/TR/REC-xml/\#AVNormalize}} that -is part of the XML specification. +A {\tt } may contain elements {\tt } and {\tt }. +Like most VOEvent elements, these can be used to give further descriptive +documentation about what this parameter means. The {\tt } may also +contain an element {\tt } for the value of the parameter, as an alternate +to the `value' attribute defined below: if both are present, the attribute takes +precedence over the element. This allows parameter values to include a richer +variety of text strings, to avoid strings being changed by Attribute-Value +normalisation\footnote{\url{https://www.w3.org/TR/REC-xml/\#AVNormalize}} that +is part of the XML specification. -The following attributes are supported for {\tt }: +The following attributes are supported for {\tt }: -\noindent {\bf3.3.1.1} {\tt name}\label{sec:3.3.1.1} --- A simple utilitarian -name. This name may or may not have significance to subscribing clients. +\noindent {\bf3.3.1.1} {\tt name}\label{sec:3.3.1.1} --- A simple utilitarian +name. This name may or may not have significance to subscribing clients. -\noindent {\bf3.3.1.2} {\tt value}\label{sec:3.3.1.2} --- A string representing -the value in question. No range or type checking of implied numbers is -performed. +\noindent {\bf3.3.1.2} {\tt value}\label{sec:3.3.1.2} --- A string representing +the value in question. No range or type checking of implied numbers is +performed. -\noindent {\bf3.3.1.3} {\tt unit}\label{sec:3.3.1.3} --- The unit for +\noindent {\bf3.3.1.3} {\tt unit}\label{sec:3.3.1.3} --- The unit for interpreting {\tt value}. See \S4.4 of \citep{2019ivoa.spec.1021O} %\citep{std:VOTABLE} which relies on VOUnits \citep{2014ivoa.spec.0523D}. -\noindent {\bf3.3.1.4} {\tt ucd}\label{sec:3.3.1.4} --- A UCD +\noindent {\bf3.3.1.4} {\tt ucd}\label{sec:3.3.1.4} --- A UCD \citep{2018ivoa.spec.0527P} -%\citep{std:UCD} -expression characterizing the nature of the {\tt }. +%\citep{std:UCD} +expression characterizing the nature of the {\tt }. -\noindent {\bf3.3.1.5} {\tt dataType}\label{sec:3.3.1.5} --- A string specifying -the data type of the {\tt }. Allowed values are ``string'', ``int'', or -``float'', with the default being ``string''. +\noindent {\bf3.3.1.5} {\tt dataType}\label{sec:3.3.1.5} --- A string specifying +the data type of the {\tt }. Allowed values are ``string'', ``int'', or +``float'', with the default being ``string''. \begin{itemize} -\item For {\tt dataType=float}, the value must contain a possibly signed decimal -or floating point number, possibly embedded in whitespace; it may also be -$\pm$nan or $\pm$inf. If the value cannot be parsed this way, for example null +\item For {\tt dataType=float}, the value must contain a possibly signed decimal +or floating point number, possibly embedded in whitespace; it may also be +$\pm$nan or $\pm$inf. If the value cannot be parsed this way, for example null string, it may return zero or NaN, but no exception should be thrown. -\item For {\tt dataType=int}, the value must contain a possibly signed decimal -number, possibly embedded in whitespace. Conversion of floating point numbers to -integers truncates (towards zero). If the value cannot be parsed this way, for +\item For {\tt dataType=int}, the value must contain a possibly signed decimal +number, possibly embedded in whitespace. Conversion of floating point numbers to +integers truncates (towards zero). If the value cannot be parsed this way, for example null string, it will return zero, and no exception should be thrown. \end{itemize} -\noindent {\bf3.3.1.6} {\tt utype}\label{sec:3.3.1.6} --- A {\tt utype} defines -this {\tt } as part of a larger data structure, such as one of the IVOA -standard data models. For more details, read the corresponding IVOA -page\footnote{\url{http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/Utypes}}. +\noindent {\bf3.3.1.6} {\tt utype}\label{sec:3.3.1.6} --- A {\tt utype} defines +this {\tt } as part of a larger data structure, such as one of the IVOA +standard data models. For more details, read the corresponding IVOA +page\footnote{\url{http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/Utypes}}. -For example, here are three values from a GCN \citep{bib04} notice: +For example, here are three values from a GCN \citep{bib04} notice: \begin{lstlisting}[language=XML] -TRIGGER_NUM = 114299 RATE_SIGNIF = 20.49 GRB_INTEN = 73288 +TRIGGER_NUM = 114299 RATE_SIGNIF = 20.49 GRB_INTEN = 73288 \end{lstlisting} -In VOEvent, these can be represented as: +In VOEvent, these can be represented as: \begin{lstlisting}[language=XML] Best significance after trying all algorithms - + \end{lstlisting} \subsubsection{{\tt } --- collection of related Params} \label{sec:3.3.2} -{\tt } provides a simple mechanism for associating several {\tt } -(and/or {\tt }) elements, for instance, an error with a measurement. -{\tt }s may NOT be nested. {\tt } elements may have a {\tt name} -attribute, and unlike VOTable usage, may also have a {\tt type} attribute: +{\tt } provides a simple mechanism for associating several {\tt } +(and/or {\tt }) elements, for instance, an error with a measurement. +{\tt }s may NOT be nested. {\tt } elements may have a {\tt name} +attribute, and unlike VOTable usage, may also have a {\tt type} attribute: -\noindent {\bf3.3.2.1} {\tt name}\label{sec:3.3.2.1} --- A simple name such as -in \S\ref{sec:3.3.1.1}. +\noindent {\bf3.3.2.1} {\tt name}\label{sec:3.3.2.1} --- A simple name such as +in \S\ref{sec:3.3.1.1}. -\noindent {\bf3.3.2.2} {\tt type}\label{sec:3.3.2.2} --- A string that can be -used to build data structures, for example a Group with type ``complex'' might -have Params called ``real'' and ``imag'' for the two components of a complex -number. +\noindent {\bf3.3.2.2} {\tt type}\label{sec:3.3.2.2} --- A string that can be +used to build data structures, for example a Group with type ``complex'' might +have Params called ``real'' and ``imag'' for the two components of a complex +number. -In a GCN notice, for example, we might see this line: +In a GCN notice, for example, we might see this line: \begin{lstlisting}[language=XML] -GRB_INTEN: 73288 [cnts] Peak=1310 [cnts/sec] +GRB_INTEN: 73288 [cnts] Peak=1310 [cnts/sec] \end{lstlisting} -which could be expressed with one Param with a Value element, and the other with -a Value attribute: +which could be expressed with one Param with a Value element, and the other with +a Value attribute: \begin{lstlisting}[language=XML] 73288 - - + \end{lstlisting} -Note also that there cannot be Groups within Groups: a Group may only contain -Params and not Groups or Tables; a Table may only contain Params and Fields and -not Groups or Tables. There are rules of uniqueness for Params, Groups, Fields -and Tables in VOEvent: +Note also that there cannot be Groups within Groups: a Group may only contain +Params and not Groups or Tables; a Table may only contain Params and Fields and +not Groups or Tables. There are rules of uniqueness for Params, Groups, Fields +and Tables in VOEvent: \begin{itemize} -\item Each Param and Field must have a name. A Group or Table without a name is -equivalent to having a name which is the null string. -\item Names must be unique within the set of those Params that are not in a +\item Each Param and Field must have a name. A Group or Table without a name is +equivalent to having a name which is the null string. +\item Names must be unique within the set of those Params that are not in a Group or Table. -\item Names must be unique for the set of Params and Fields within a given Group +\item Names must be unique for the set of Params and Fields within a given Group or Table. -\item Groups and Tables must have unique names: this means that only one Group +\item Groups and Tables must have unique names: this means that only one Group or Table can be nameless. \end{itemize} \subsubsection{{\tt
} --- simple tabular data} \label{sec:3.3.3} -This element is intended for a short and simple table, and re-uses the ideas and -syntax of the IVOA VOTable, but simplified and streamlined: this is appropriate -because complex tables can be written as full VOTable and linked from the -VOEvent. Specifically, these simplifications are: no support for hierarchy of -tables (RESOURCE); no internal references (FieldRef and ParamRef); no provision -for binary data, only XML; table cells can only be string, float, or int, in -place of the arrays of 12 possible types and extensions; no formatting -information contained in the Table, nor domain of the data (VALUES); no -referencing between cells; there is no INFO element. +This element is intended for a short and simple table, and re-uses the ideas and +syntax of the IVOA VOTable, but simplified and streamlined: this is appropriate +because complex tables can be written as full VOTable and linked from the +VOEvent. Specifically, these simplifications are: no support for hierarchy of +tables (RESOURCE); no internal references (FieldRef and ParamRef); no provision +for binary data, only XML; table cells can only be string, float, or int, in +place of the arrays of 12 possible types and extensions; no formatting +information contained in the Table, nor domain of the data (VALUES); no +referencing between cells; there is no INFO element. There are five elements defined in this subsection: Table, Field, Data, TR, TD. -A {\tt
} element can contain a sequence of {\tt } elements, one -for each column of the table, and {\tt } elements for scalar information -about the table. There is then a single {\tt } element that contains the -data of the table, which is represented as a sequence of table rows, which are -{\tt } elements, each containing a sequence of {\tt
} elements for the -table cells. For a full table, where every cell has a value, the number of {\tt -} elements in each row should be the same as the number of {\tt } -elements. There is then a 1-to-1 correspondence between them for each row. - -The Table can contain {\tt } and {\tt } elements to add -documentation; the {\tt } elements can also contain these. Thus the {\tt -} can contain, in order, an optional {\tt } and {\tt -}, then a sequence of one or more {\tt } elements, then a {\tt -} element. The {\tt } element can also contain optional {\tt -} and {\tt } and nothing else. The {\tt } element -can contain only {\tt } elements, each of which can contain only {\tt
} -elements. The following explains the attributes that are allowed for these five -elements. - -The following attributes are supported for {\tt }: - -\noindent {\bf3.3.3.1} {\tt name}\label{sec:3.3.3.1} --- A simple utilitarian -name that may be used for identification or presentation purposes. This name -may or may not have significance to subscribing clients. - -\noindent {\bf3.3.3.2} {\tt type}\label{sec:3.3.3.2} --- A string representing -the type of the Table, that consumers can use for presentation or parsing. For -example, a table of type ``spectralLines'' could mean to some community to -expect columns (i.e., the {\tt }s) named ``wavelength'', ``width'', -``name'' to define spectral lines. - -The {\tt } element defines the semantic nature of a Table column, and is -structured similarly to the {\tt } element of section \ref{sec:3.3.1}. -The following attributes are supported for {\tt }, similarly to the {\tt -} definition above: - -\noindent {\bf3.3.3.3} {\tt name}\label{sec:3.3.3.3} --- A simple utilitarian -name that may be used elsewhere in the packet. This name may or may not have -significance to subscribing clients. - -\noindent {\bf3.3.3.4} {\tt unit}\label{sec:3.3.3.4} --- The unit for -interpreting the values as given in the {\tt
} table cells. See \S4.4 of -\citep{2019ivoa.spec.1021O}, which relies on \citep{2014ivoa.spec.0523D}. - -\noindent {\bf3.3.3.5} {\tt ucd}\label{sec:3.3.3.5} --- A UCD -\citep{2018ivoa.spec.0527P} expression characterizing the nature of the data in -this table column. - -\noindent {\bf3.3.3.6} {\tt dataType}\label{sec:3.3.3.6} --- A string specifying -the data type of the table column. Allowed values are ``string'', ``int'', or +A {\tt } element can contain a sequence of {\tt } elements, one +for each column of the table, and {\tt } elements for scalar information +about the table. There is then a single {\tt } element that contains the +data of the table, which is represented as a sequence of table rows, which are +{\tt } elements, each containing a sequence of {\tt
} elements for the +table cells. For a full table, where every cell has a value, the number of {\tt +} elements in each row should be the same as the number of {\tt } +elements. There is then a 1-to-1 correspondence between them for each row. + +The Table can contain {\tt } and {\tt } elements to add +documentation; the {\tt } elements can also contain these. Thus the {\tt +} can contain, in order, an optional {\tt } and {\tt +}, then a sequence of one or more {\tt } elements, then a {\tt +} element. The {\tt } element can also contain optional {\tt +} and {\tt } and nothing else. The {\tt } element +can contain only {\tt } elements, each of which can contain only {\tt
} +elements. The following explains the attributes that are allowed for these five +elements. + +The following attributes are supported for {\tt }: + +\noindent {\bf3.3.3.1} {\tt name}\label{sec:3.3.3.1} --- A simple utilitarian +name that may be used for identification or presentation purposes. This name +may or may not have significance to subscribing clients. + +\noindent {\bf3.3.3.2} {\tt type}\label{sec:3.3.3.2} --- A string representing +the type of the Table, that consumers can use for presentation or parsing. For +example, a table of type ``spectralLines'' could mean to some community to +expect columns (i.e., the {\tt }s) named ``wavelength'', ``width'', +``name'' to define spectral lines. + +The {\tt } element defines the semantic nature of a Table column, and is +structured similarly to the {\tt } element of section \ref{sec:3.3.1}. +The following attributes are supported for {\tt }, similarly to the {\tt +} definition above: + +\noindent {\bf3.3.3.3} {\tt name}\label{sec:3.3.3.3} --- A simple utilitarian +name that may be used elsewhere in the packet. This name may or may not have +significance to subscribing clients. + +\noindent {\bf3.3.3.4} {\tt unit}\label{sec:3.3.3.4} --- The unit for +interpreting the values as given in the {\tt
} table cells. See \S4.4 of +\citep{2019ivoa.spec.1021O}, which relies on \citep{2014ivoa.spec.0523D}. + +\noindent {\bf3.3.3.5} {\tt ucd}\label{sec:3.3.3.5} --- A UCD +\citep{2018ivoa.spec.0527P} expression characterizing the nature of the data in +this table column. + +\noindent {\bf3.3.3.6} {\tt dataType}\label{sec:3.3.3.6} --- A string specifying +the data type of the table column. Allowed values are ``string'', ``int'', or ``float'', with the default being ``string''. - -\noindent {\bf3.3.3.7} {\tt utype}\label{sec:3.3.3.7} --- A utype (see \S4.6 of -\citep{2019ivoa.spec.1021O}) defines this {\tt } as part of a larger data -structure, such as one of the IVOA standard data models. - - The following is an example of a Table element. Note the {\tt dataType} - attribute that is used to interpret the values in the table cells. + +\noindent {\bf3.3.3.7} {\tt utype}\label{sec:3.3.3.7} --- A utype (see \S4.6 of +\citep{2019ivoa.spec.1021O}) defines this {\tt } as part of a larger data +structure, such as one of the IVOA standard data models. + + The following is an example of a Table element. Note the {\tt dataType} + attribute that is used to interpret the values in the table cells. \begin{lstlisting}[language=XML] Individual Moduli and Distances for NGC 0931 from NED @@ -771,31 +771,31 @@ \subsubsection{{\tt
} --- simple tabular data} -
33.710.4355.22009ApJS..182..474S
34.010.8063.31997ApJS..109..333W
+
\end{lstlisting} \subsection{{\tt } --- Space-Time Coordinates} \label{sec:3.4} -A VOEvent packet will typically include information about where in the sky and -when in time an event was detected, and from what location, along with spatial -and temporal coordinate systems and errors. If either the spatial or temporal -locators are absent, it is to be assumed that the information is either unknown -or irrelevant. VOEvent v2.0 uses the syntax of the IVOA Space-Time Coordinate -(STC) specification version 1.30 or later; the {\tt } element may -reference an STC \citep{2007ivoa.spec.1030R} {\tt } element to -provide a sky location and time for the event. VOEvent publishers should -construct expressions that concisely provide all information that is -scientifically significant to the event, and no more than that. See -\S\ref{sec:4} for an example of usage. - -STC expressions are used to locate the physical phenomena associated with a -VOEvent alert in both time and space as described below. The {\tt -} element is a combination of information describing the -location of an observation in the sky along with information describing the -location of the observatory from which that observation was made. Both the sky -and the observatory are in constant motion, and STC inextricably relates spatial -and temporal information. +A VOEvent packet will typically include information about where in the sky and +when in time an event was detected, and from what location, along with spatial +and temporal coordinate systems and errors. If either the spatial or temporal +locators are absent, it is to be assumed that the information is either unknown +or irrelevant. VOEvent v2.0 uses the syntax of the IVOA Space-Time Coordinate +(STC) specification version 1.30 or later; the {\tt } element may +reference an STC \citep{2007ivoa.spec.1030R} {\tt } element to +provide a sky location and time for the event. VOEvent publishers should +construct expressions that concisely provide all information that is +scientifically significant to the event, and no more than that. See +\S\ref{sec:4} for an example of usage. + +STC expressions are used to locate the physical phenomena associated with a +VOEvent alert in both time and space as described below. The {\tt +} element is a combination of information describing the +location of an observation in the sky along with information describing the +location of the observatory from which that observation was made. Both the sky +and the observatory are in constant motion, and STC inextricably relates spatial +and temporal information. \begin{lstlisting}[language=XML] @@ -810,11 +810,11 @@ \subsubsection{ObservationLocation} \label{sec:3.4.1} The {\tt } defines the location of the event, whereas -the {\tt } specifies the location of the observatory, -for which that event location is valid. It should contain a link to a -coordinate system, {\tt }, as well as the actual coordinates -of the event, {\tt }, containing a reference back to the -coordinate system specification. For example: +the {\tt } specifies the location of the observatory, +for which that event location is valid. It should contain a link to a +coordinate system, {\tt }, as well as the actual coordinates +of the event, {\tt }, containing a reference back to the +coordinate system specification. For example: \begin{lstlisting}[language=XML] @@ -834,87 +834,87 @@ \subsubsection{ObservationLocation} 0.03 - + \end{lstlisting} -Specifying errors is optional but recommended for both time and space -components. +Specifying errors is optional but recommended for both time and space +components. -The {\tt } element has a {\tt coord\_system\_id} attribute and the -{\tt } has a {\tt id} attribute. The value of both of these -should be identical, and represent the space-time coordinate system that will be -used for the event position and time. +The {\tt } element has a {\tt coord\_system\_id} attribute and the +{\tt } has a {\tt id} attribute. The value of both of these +should be identical, and represent the space-time coordinate system that will be +used for the event position and time. -A {\tt coord\_system\_id} and {\tt id} are built from a time part, a space part, -and a ``center'' specification, concatenated in that order and separated by -hyphens. Astronomical coordinate systems are extremely varied, but all VOEvent -subscribers should be prepared to handle coordinates expressed as combinations -of these basic defaults: +A {\tt coord\_system\_id} and {\tt id} are built from a time part, a space part, +and a ``center'' specification, concatenated in that order and separated by +hyphens. Astronomical coordinate systems are extremely varied, but all VOEvent +subscribers should be prepared to handle coordinates expressed as combinations +of these basic defaults: \begin{itemize} -\item The time part can be \emph{UTC} (Coordinated Universal Time -\citep{bib26}), \emph{TT} (Terrestrial Time, currently 65.184 seconds ahead of -UTC), \emph{GPS} time, or \emph{TDB} (Barycentric Dynamical Time). The full list -of valid timescales is available as an IVOA vocabulary: +\item The time part can be \emph{UTC} (Coordinated Universal Time +\citep{bib26}), \emph{TT} (Terrestrial Time, currently 65.184 seconds ahead of +UTC), \emph{GPS} time, or \emph{TDB} (Barycentric Dynamical Time). The full list +of valid timescales is available as an IVOA vocabulary: \url{https://www.ivoa.net/rdf/timescale} -\item The space part can be equatorial coordinates (right ascension and -declination) expressed in either the \emph{ICRS} or \emph{FK5} coordinate -systems. The list of valid reference frames is available as an IVOA vocabulary: +\item The space part can be equatorial coordinates (right ascension and +declination) expressed in either the \emph{ICRS} or \emph{FK5} coordinate +systems. The list of valid reference frames is available as an IVOA vocabulary: \url{https://www.ivoa.net/rdf/refframe} -\item The center specification can be \emph{TOPO} (i.e., the location of the -observatory), \emph{GEO} (geocentric coordinates), or \emph{BARY} (relative to +\item The center specification can be \emph{TOPO} (i.e., the location of the +observatory), \emph{GEO} (geocentric coordinates), or \emph{BARY} (relative to the barycenter of the solar system). The full list of valid reference positions is available as an IVOA vocabulary: \url{https://www.ivoa.net/rdf/refposition} \end{itemize} -It is assumed that the center reference position (origin) is the same for both -space and time coordinates. That means, for instance, that \emph{BARY} should -only be paired with \emph{TDB} (and vice-versa). See the STC specification -\citep{2007ivoa.spec.1030R} %\citep{std:STC} -for further discussion. The list of {\tt } defaults that +It is assumed that the center reference position (origin) is the same for both +space and time coordinates. That means, for instance, that \emph{BARY} should +only be paired with \emph{TDB} (and vice-versa). See the STC specification +\citep{2007ivoa.spec.1030R} %\citep{std:STC} +for further discussion. The list of {\tt } defaults that VOEvent brokers and clients may be called upon to understand is: \\ -\emph{TT-ICRS-TOPO, UTC-ICRS-TOPO, TT-FK5-TOPO, UTC-FK5-TOPO, GPS-ICRS-TOPO, -GPS-FK5-TOPO, TT-ICRS-GEO, UTC-ICRS-GEO, TT-FK5-GEO, UTC-FK5-GEO, GPS-ICRS-GEO, -GPS-FK5-GEO, TDB-ICRS-BARY, TDB-FK5-BARY}. - -The STC specification, in particular {\tt } and its contained -elements, allows more exotic coordinate systems (for example, describing -planetary surfaces). Further description of how VOEvent packets might be -constructed to convey such information to subscribers is outside the scope of -this document. As with other elements of an alert packet, subscribers must be -prepared to understand coordinates expressing the science and experimental -design pertinent to the particular classes of sky transients that are of -interest. +\emph{TT-ICRS-TOPO, UTC-ICRS-TOPO, TT-FK5-TOPO, UTC-FK5-TOPO, GPS-ICRS-TOPO, +GPS-FK5-TOPO, TT-ICRS-GEO, UTC-ICRS-GEO, TT-FK5-GEO, UTC-FK5-GEO, GPS-ICRS-GEO, +GPS-FK5-GEO, TDB-ICRS-BARY, TDB-FK5-BARY}. + +The STC specification, in particular {\tt } and its contained +elements, allows more exotic coordinate systems (for example, describing +planetary surfaces). Further description of how VOEvent packets might be +constructed to convey such information to subscribers is outside the scope of +this document. As with other elements of an alert packet, subscribers must be +prepared to understand coordinates expressing the science and experimental +design pertinent to the particular classes of sky transients that are of +interest. In short, subscribers are responsible for choosing what VOEvent packets and thus {\tt coord\_system\_id} values they will accept. Further, subscribers may choose not to distinguish between coordinate systems that are only subtly different for -their purposes --- for instance between \emph{ICRS} or \emph{FK5}, or between -\emph{TOPO} or \emph{GEO}. As software determines whether a packet's {\tt +their purposes --- for instance between \emph{ICRS} or \emph{FK5}, or between +\emph{TOPO} or \emph{GEO}. As software determines whether a packet's {\tt coord\_system\_id} describes a supported coordinate system, the question is also -what accuracy is required and what coordinate transformations may be implicitly -or explicitly performed to that level of accuracy. +what accuracy is required and what coordinate transformations may be implicitly +or explicitly performed to that level of accuracy. -A similar question faces the authors of VOEvent packets, who must make a -judicious choice between the available coordinate system options to meet the -expected scientific needs of consumers of those packets. If a detailed or high -accuracy coordinate system selection is not needed, \emph{\bf UTC-ICRS-TOPO} -would be a good choice as an interoperability standard. +A similar question faces the authors of VOEvent packets, who must make a +judicious choice between the available coordinate system options to meet the +expected scientific needs of consumers of those packets. If a detailed or high +accuracy coordinate system selection is not needed, \emph{\bf UTC-ICRS-TOPO} +would be a good choice as an interoperability standard. \subsubsection{ObservatoryLocation} \label{sec:3.4.2} -The {\tt } element is used to express the location from -which the observation being described was made. It is a required element for -expressing topocentric coordinate systems. An instance of {\tt +The {\tt } element is used to express the location from +which the observation being described was made. It is a required element for +expressing topocentric coordinate systems. An instance of {\tt } may take two forms. In the first, an observatory location -may be taken from a library, for example: +may be taken from a library, for example: {\footnotesize \begin{verbatim} - + \end{verbatim}} -The {\tt id} here indicates the name of the observatory, other examples being: -Keck, KPNO, JCMT, MMTO, VLA, etc., or it may indicate one of the following -generic observatory locations: +The {\tt id} here indicates the name of the observatory, other examples being: +Keck, KPNO, JCMT, MMTO, VLA, etc., or it may indicate one of the following +generic observatory locations: \begin{itemize} \item \emph{GEOSURFACE} - any location on the surface of the earth \item \emph{GEOLEO} - any location in Low Earth Orbit (altitude<700 km) @@ -923,18 +923,18 @@ \subsubsection{ObservatoryLocation} \item \emph{GEOLUN} - any location within the Moon's orbit \end{itemize} -For example, a packet might contain the following {\tt } -to indicate that the coordinates expressed in the {\tt } element are -located with an accuracy comprising the Earth's surface: +For example, a packet might contain the following {\tt } +to indicate that the coordinates expressed in the {\tt } element are +located with an accuracy comprising the Earth's surface: \begin{lstlisting}[language=XML] - + \end{lstlisting} -The second option for {\tt } is that an observatory can be -located by specifying the actual coordinate values of longitude, latitude and -altitude on the surface of the Earth. Note the use of a coordinate system for -the surface of the Earth (UTC-GEOD-TOPO) is natural for an observatory location, -whereas coordinate systems in the previous section are for astronomical events. +The second option for {\tt } is that an observatory can be +located by specifying the actual coordinate values of longitude, latitude and +altitude on the surface of the Earth. Note the use of a coordinate system for +the surface of the Earth (UTC-GEOD-TOPO) is natural for an observatory location, +whereas coordinate systems in the previous section are for astronomical events. \begin{lstlisting}[language=XML] @@ -947,371 +947,371 @@ \subsubsection{ObservatoryLocation} - + \end{lstlisting} Each {\tt C1}, {\tt C2} and {\tt C3} element have {\tt pos\_unit} and {\tt ucd} -optional attributes. +optional attributes. \subsubsection{Parsing the WhereWhen Element} \label{sec:3.4.3} When parsing a VOEvent packet, the following pseudocode may be of use to provide -the time, the right ascension and the declination, if the author used -\emph{ICRS} spatial coordinates and \emph{UTC} time. +the time, the right ascension and the declination, if the author used +\emph{ICRS} spatial coordinates and \emph{UTC} time. \begin{lstlisting}[language=XML] Let x =/voe:VOEvent/WhereWhen/ObsDataLocation/ObservationLocation/AstroCoords If x[@coord_system_id='UTC-ICRS-TOPO'] then Let Time = x/Time/TimeInstant/ISOTime Let RA = x/Position2D/Value2/C1 - Let Dec = x/Position2D/Value2/C2 + Let Dec = x/Position2D/Value2/C2 \end{lstlisting} -The coordinate system is first checked to verify that it is set to a specific +The coordinate system is first checked to verify that it is set to a specific value(s), \emph{UTC-ICRS-TOPO}. In practice, a subscriber may not care about the -difference between \emph{ICRS} and \emph{FK5} (of the order of 0.01'') or +difference between \emph{ICRS} and \emph{FK5} (of the order of 0.01'') or between \emph{TOPO} and \emph{GEO} (in terms of timing, this is of the order of -25 ms for ground-based and low-earth-orbit observatories). Software may be +25 ms for ground-based and low-earth-orbit observatories). Software may be written to simply accept anything that contains \emph{ICRS} or \emph{FK5}, -\emph{TOPO} or \emph{GEO}. +\emph{TOPO} or \emph{GEO}. \subsubsection{Solar System Events} \label{sec:3.4.4} -Solar System events include Solar events and planetary events. +Solar System events include Solar events and planetary events. -Solar events have similar requirement as astronomical events in terms of +Solar events have similar requirement as astronomical events in terms of Observatory and Observation location but are using a different reference frames. -The following coordinate systems are recognised for solar event data: +The following coordinate systems are recognised for solar event data: \begin{itemize} -\item \emph{UTC-HPC-TOPO} --- Cartesian helio-projective coordinates (solar +\item \emph{UTC-HPC-TOPO} --- Cartesian helio-projective coordinates (solar disk) -\item \emph{UTC-HPR-TOPO} --- Polar helio-projective coordinates (coronal +\item \emph{UTC-HPR-TOPO} --- Polar helio-projective coordinates (coronal events) \item \emph{UTC-HGS-TOPO} --- Stonyhurst heliographic coordinates \item \emph{UTC-HGC-TOPO} --- Carrington heliographic coordinates \end{itemize} -What this means is that these coordinate combinations will be supported in the -library and that, hence, use of VOEvent by the solar research community is -supported. It does not imply, of course, that all VOEvent participants are -expected to recognise and handle these solar coordinates --- nor, for that -matter, that solar subscribers be able to handle equatorial coordinates. +What this means is that these coordinate combinations will be supported in the +library and that, hence, use of VOEvent by the solar research community is +supported. It does not imply, of course, that all VOEvent participants are +expected to recognise and handle these solar coordinates --- nor, for that +matter, that solar subscribers be able to handle equatorial coordinates. Planetary events (including events at Earth, in a global solar system context, -e.g., for Space Weather or Near Earth Objects) have specific requirements that -have been discussed by \citet{2018arXiv181112680C}. Since many solar system body -reference frames exist, we do not list them here. We call for an IVOA vocabulary +e.g., for Space Weather or Near Earth Objects) have specific requirements that +have been discussed by \citet{2018arXiv181112680C}. Since many solar system body +reference frames exist, we do not list them here. We call for an IVOA vocabulary for managing the valid terms of well-known solar system reference frames. -A {\tt PositionName} element is available in the {\tt -ObservationLocation/AstroCoords} element. It is used to refer to named objects, -at which the event is observed without coordinates (e.g., for unresolved -observations, or global impact). +A {\tt PositionName} element is available in the {\tt +ObservationLocation/AstroCoords} element. It is used to refer to named objects, +at which the event is observed without coordinates (e.g., for unresolved +observations, or global impact). -A {\tt TimeInterval} element is available in the {\tt -ObservationLocation/AstroCoords/Time} element. It is composed of two elements -{\tt ISOTimeStart} and {\tt ISOTimeStop}, both defined similarly to the {\tt -ISOTime} element of {\tt TimeInstant}. This pair of dates is used to refer to -interval observations or predictions. This interval concept is different than -the error on the event Time, but rather corresponds to the boundaries of a -temporally extended event. +A {\tt TimeInterval} element is available in the {\tt +ObservationLocation/AstroCoords/Time} element. It is composed of two elements +{\tt ISOTimeStart} and {\tt ISOTimeStop}, both defined similarly to the {\tt +ISOTime} element of {\tt TimeInstant}. This pair of dates is used to refer to +interval observations or predictions. This interval concept is different than +the error on the event Time, but rather corresponds to the boundaries of a +temporally extended event. \subsubsection{Events Observed from Spacecraft} \label{sec:3.4.5} -Transient event alerts resulting from observations made on distant spacecraft -may reference coordinates that require correction for ground-based follow-up. -The precise definition of ``distant'' will depend on the objects observed, the -instrumentation and the science program. For remote objects such as gamma-ray -bursts or supernovae, it is likely that spatial coordinates measured from -spacecraft in Earth orbit will be immediately useful --- indeed, the error box -of the reported coordinates may be much larger than than the pointing accuracy -of the follow-up telescope. On the other hand, the field of view of the -instrument on that telescope may be many times larger than the error box. -Subscribers must always balance such concerns --- this is just one facet of -matching ``scientific impedance'' between discovery and follow-up observations. - -Even if the spatial targeting coordinates require no correction, the light -travel time may be quite significant between a spacecraft and any follow-up -telescopes on the Earth. Subscribers may need to adjust wavefront arrival times -to suit. - -Authors of such events may choose to handle reporting the location of the -spacecraft in different ways. First, they may simply construct the complex {\tt -} element that correctly represents the rapidly moving -location of an orbiting observatory. Further discussion of this topic is outside -the scope of the present document, see the STC specification -\citep{2007ivoa.spec.1030R}. Of course, any subscribers to such an event stream -would have to understand such an {\tt } in detail and be -able to calculate appropriate time-varying adjustments to the coordinates in -support of their particular science program. - -Alternately, an author of event alert packets resulting from spacecraft -observations might simply choose to correct their observations themselves into -geocentric or barycentric coordinates. Finally, for spacecraft in Earth orbit, -authors might choose to report an {\tt } such as -\emph{GEOLUN}, indicating a rough position precise to the width of the Moon's -orbit. These two options might be combined by both making a geocentric -correction --- for instance, to simplify the handling of timing information --- -with the reporting of a \emph{GEOLEO} location, for example. +Transient event alerts resulting from observations made on distant spacecraft +may reference coordinates that require correction for ground-based follow-up. +The precise definition of ``distant'' will depend on the objects observed, the +instrumentation and the science program. For remote objects such as gamma-ray +bursts or supernovae, it is likely that spatial coordinates measured from +spacecraft in Earth orbit will be immediately useful --- indeed, the error box +of the reported coordinates may be much larger than than the pointing accuracy +of the follow-up telescope. On the other hand, the field of view of the +instrument on that telescope may be many times larger than the error box. +Subscribers must always balance such concerns --- this is just one facet of +matching ``scientific impedance'' between discovery and follow-up observations. + +Even if the spatial targeting coordinates require no correction, the light +travel time may be quite significant between a spacecraft and any follow-up +telescopes on the Earth. Subscribers may need to adjust wavefront arrival times +to suit. + +Authors of such events may choose to handle reporting the location of the +spacecraft in different ways. First, they may simply construct the complex {\tt +} element that correctly represents the rapidly moving +location of an orbiting observatory. Further discussion of this topic is outside +the scope of the present document, see the STC specification +\citep{2007ivoa.spec.1030R}. Of course, any subscribers to such an event stream +would have to understand such an {\tt } in detail and be +able to calculate appropriate time-varying adjustments to the coordinates in +support of their particular science program. + +Alternately, an author of event alert packets resulting from spacecraft +observations might simply choose to correct their observations themselves into +geocentric or barycentric coordinates. Finally, for spacecraft in Earth orbit, +authors might choose to report an {\tt } such as +\emph{GEOLUN}, indicating a rough position precise to the width of the Moon's +orbit. These two options might be combined by both making a geocentric +correction --- for instance, to simplify the handling of timing information --- +with the reporting of a \emph{GEOLEO} location, for example. \subsection{{\tt } --- Instrument Configuration} \label{sec:3.5} -The {\tt } element supplies instrument specific information. A VOEvent -describes events in the sky, not events in the focal plane of a telescope. Only -specialised classes of event will benefit from providing detailed information -about instrumental or experimental design. A {\tt } contains zero or more -{\tt } elements (see \S\ref{sec:3.9}) and {\tt } -elements, that together characterise the instrument(s) that produced the -observation(s) that resulted in issuing the VOEvent packet. A URI pointing to a -previous VOEvent asserts that an identical instrumental configuration was used: +The {\tt } element supplies instrument specific information. A VOEvent +describes events in the sky, not events in the focal plane of a telescope. Only +specialised classes of event will benefit from providing detailed information +about instrumental or experimental design. A {\tt } contains zero or more +{\tt } elements (see \S\ref{sec:3.9}) and {\tt } +elements, that together characterise the instrument(s) that produced the +observation(s) that resulted in issuing the VOEvent packet. A URI pointing to a +previous VOEvent asserts that an identical instrumental configuration was used: \begin{lstlisting}[language=XML] The Echelle spectrograph - + \end{lstlisting} \subsection{{\tt } --- Initial Scientific Assessment} \label{sec:3.6} -{\tt } seeks to capture the emerging concept of the nature of the -astronomical objects and processes that generated the observations noted in the -{\tt } element. Natural language words and phrases are used to express the -hypothesised astrophysics, pending a standard VO ontology or formal UCD-like +{\tt } seeks to capture the emerging concept of the nature of the +astronomical objects and processes that generated the observations noted in the +{\tt } element. Natural language words and phrases are used to express the +hypothesised astrophysics, pending a standard VO ontology or formal UCD-like vocabulary of astronomical concepts (see \citep{2018ivoa.spec.0527P}). -% and [\hyperref[bib19]{19}], for example => reference removed, since the +% and [\hyperref[bib19]{19}], for example => reference removed, since the % document is not available anymore at provided URL. -The {\tt } element has two optional attributes, {\tt importance} and {\tt -expires}, providing ratings of the relative noteworthiness and urgency of each +The {\tt } element has two optional attributes, {\tt importance} and {\tt +expires}, providing ratings of the relative noteworthiness and urgency of each VOEvent, respectively. Subscribers should consider the {\tt importance} and {\tt -expires} ratings from a particular publisher in combination with other VOEvent -metadata in interpreting an alert for their purposes. The publishers of each -category of event are encouraged to develop a self-consistent rating scheme for -these values. +expires} ratings from a particular publisher in combination with other VOEvent +metadata in interpreting an alert for their purposes. The publishers of each +category of event are encouraged to develop a self-consistent rating scheme for +these values. \noindent {\bf 3.6.1} {\tt importance}\label{sec:3.6.1} --- -The {\tt importance} provides a rating of the noteworthiness of the VOEvent, -expressed as a floating point number bounded between 0.0 and 1.0 (inclusive). +The {\tt importance} provides a rating of the noteworthiness of the VOEvent, +expressed as a floating point number bounded between 0.0 and 1.0 (inclusive). The meaning of {\tt importance} is unspecified other than that larger values are -considered of generally greater importance. +considered of generally greater importance. -\noindent {\bf 3.6.2} {\tt expires}\label{sec:3.6.2} --- +\noindent {\bf 3.6.2} {\tt expires}\label{sec:3.6.2} --- The {\tt expires} attribute provides a rating of the urgency or time-criticality of the VOEvent, expressed as an ISO-8601\footnote{\url{ -https://www.w3.org/TR/NOTE-datetime}} representation of some date and time in +https://www.w3.org/TR/NOTE-datetime}} representation of some date and time in the future. The meaning of {\tt expires} is application dependent but will often -represent the date and time after which a follow-up observation might be -belated. - -A {\tt } element contains one or more {\tt } and {\tt } -sub-elements. These may be used to assert concepts that specify a scientific -classification of the nature of the event, or rather to attach the name of some -specific astronomical object or feature. These may be organised using the {\tt -} element, which permits expressing the nature of the {\tt relation} -of the contained elements to the event in question as well as an estimate of its -likelihood via its {\tt probability} attribute. - -\setcounter{subsubsection}{2} +represent the date and time after which a follow-up observation might be +belated. + +A {\tt } element contains one or more {\tt } and {\tt } +sub-elements. These may be used to assert concepts that specify a scientific +classification of the nature of the event, or rather to attach the name of some +specific astronomical object or feature. These may be organised using the {\tt +} element, which permits expressing the nature of the {\tt relation} +of the contained elements to the event in question as well as an estimate of its +likelihood via its {\tt probability} attribute. + +\setcounter{subsubsection}{2} \subsubsection{{\tt } --- classification}\label{sec:3.6.3} -The value of a {\tt } element uses a controlled vocabulary to express -the hypothesized astrophysics. This standard VO ontology or formal UCD-like -vocabulary of astronomical concepts vocabulary is still in development (see +The value of a {\tt } element uses a controlled vocabulary to express +the hypothesized astrophysics. This standard VO ontology or formal UCD-like +vocabulary of astronomical concepts vocabulary is still in development (see \citep{2018ivoa.spec.0527P}). -%\citep{std:UCD} and [\hyperref[bib19]{19}], for example). +%\citep{std:UCD} and [\hyperref[bib19]{19}], for example). \subsubsection{{\tt } --- natural language}\label{sec:3.6.4} -This element provides a natural language description of the concept, either as -a replacement for the {\tt } element, or as an elaboration. +This element provides a natural language description of the concept, either as +a replacement for the {\tt } element, or as an elaboration. \subsubsection{{\tt } --- identification}\label{sec:3.6.5} -{\tt } provides the name of a specific astronomical object. It is -preferred, but not required, to use standard astronomical nomenclature, -\emph{e.g.}, as recognized by NED \citep{bib22} or SIMBAD \citep{bib23}. +{\tt } provides the name of a specific astronomical object. It is +preferred, but not required, to use standard astronomical nomenclature, +\emph{e.g.}, as recognized by NED \citep{bib22} or SIMBAD \citep{bib23}. \subsubsection{{\tt } --- hypotheses inferred}\label{sec:3.6.6} -An {\tt } may be used to group or associate one or more {\tt } +An {\tt } may be used to group or associate one or more {\tt } or {\tt } elements. {\tt } has two optional attributes, {\tt -probability} and {\tt relation}: +probability} and {\tt relation}: -\noindent {\bf 3.6.6.1} {\tt probability}\label{sec:3.6.6.1} --- The {\tt +\noindent {\bf 3.6.6.1} {\tt probability}\label{sec:3.6.6.1} --- The {\tt probability} attribute is an estimate of the likelihood of the {\tt } accurately describing the event in question. It is expressed as a floating point number bounded between 0.0 and 1.0 (inclusive). In particular, note that a {\tt -probability} of 0.0 can be used to eliminate {\tt } from further -consideration. +probability} of 0.0 can be used to eliminate {\tt } from further +consideration. \noindent {\bf 3.6.6.2} {\tt relation}\label{sec:3.6.6.2} --- The {\tt relation} -attribute is a natural language string that expresses the degree of connection -between the {\tt } and the event described by the packet. Typical -values might be ``associated'' --- a SN is associated with a particular galaxy ---- or ``identified'' --- a SN is identified as corresponding to a particular +attribute is a natural language string that expresses the degree of connection +between the {\tt } and the event described by the packet. Typical +values might be ``associated'' --- a SN is associated with a particular galaxy +--- or ``identified'' --- a SN is identified as corresponding to a particular precursor star. Such a one-to-one identification is considered to be the default -{\tt relation} in the absence of the attribute. +{\tt relation} in the absence of the attribute. -This example asserts that the creator of the packet is 100\% certain that the -event being described is equivalent to \emph{Tycho's Star}, which has been -identified as a \emph{Type Ia Supernova}, and is ``associated'' with the -\emph{SN remnant} known as \emph{3C 10}. This was an important discovery, but -is no longer a very urgent one: +This example asserts that the creator of the packet is 100\% certain that the +event being described is equivalent to \emph{Tycho's Star}, which has been +identified as a \emph{Type Ia Supernova}, and is ``associated'' with the +\emph{SN remnant} known as \emph{3C 10}. This was an important discovery, but +is no longer a very urgent one: \begin{lstlisting}[language=XML] Tycho's Stella Nova http://ivoat.ivoa.net/stars.supernova.Ia - + 3C 10 http://ivoat.ivoa.net/ISM.SNRemnant Supernova remnant - + \end{lstlisting} \subsection{{\tt } --- Follow-up Observations} \label{sec:3.7} -A VOEvent packet without a {\tt } element can be assumed to be -asserting information about a new celestial discovery. Citations reference -previous events to do one of three things: +A VOEvent packet without a {\tt } element can be assumed to be +asserting information about a new celestial discovery. Citations reference +previous events to do one of three things: \begin{itemize} \item follow-up an event alert with more observations or other relevant data, or \item supersede a prior event with better, equivalent information, or \item issue a complete retraction of a previous event. \end{itemize} -Citations form the edges of a directed graph whose nodes are VOEvent instances; -they allow merging multiple events into a single related thread, a way to -collect multi-sourced data into a coherent whole. Projects that implement -VOEvent handling may decide to implement for different conditions of citation ---- perhaps assuming a sparse or structured citation graph, or a small or large -arity for each event. We recommend that the meaning of `citation' should be a -strong one: \emph{if a reader is to understand an event, then the reader should -understand the cited event}. This is the relation between a comment and a post, -between one observation of a transient and another relevant observation. -However, not everything should be cited: while the papers of Einstein may be -relevant, they need not be always cited! A different notion is that of +Citations form the edges of a directed graph whose nodes are VOEvent instances; +they allow merging multiple events into a single related thread, a way to +collect multi-sourced data into a coherent whole. Projects that implement +VOEvent handling may decide to implement for different conditions of citation +--- perhaps assuming a sparse or structured citation graph, or a small or large +arity for each event. We recommend that the meaning of `citation' should be a +strong one: \emph{if a reader is to understand an event, then the reader should +understand the cited event}. This is the relation between a comment and a post, +between one observation of a transient and another relevant observation. +However, not everything should be cited: while the papers of Einstein may be +relevant, they need not be always cited! A different notion is that of association of sources: as in a radio source being near an optical source. If an -author wishes to express this notion, the {\tt } element can carry -this information (see section \ref{sec:3.6.6}). +author wishes to express this notion, the {\tt } element can carry +this information (see section \ref{sec:3.6.6}). -A {\tt } element contains one or more {\tt } elements. -The standard does not attempt to enforce references to be logically consistent; -this is the responsibility of publishers and subscribers. +A {\tt } element contains one or more {\tt } elements. +The standard does not attempt to enforce references to be logically consistent; +this is the responsibility of publishers and subscribers. \subsubsection{{\tt } --- Cited event and relationship} \label{sec:3.7.1} -An {\tt } element contains the IVORN of a previously published -VOEvent packet. Each {\tt } describes the relationship of the -current packet to that previous VOEvent. It has one required attribute: - -\paragraph{\tt cite}\label{sec:3.7.1.1} --- The {cite} attribute accepts three -possible enumerated values, ``\emph{followup}'', ``\emph{supersedes}'' or -``\emph{retraction}''. There is no default value. - -The value of the {\tt cite} attribute modifies the VOEvent semantics. In -contrast to a VOEvent announcing a discovery (\emph{i.e.}, a packet with no -citations), a VOEvent may be explicitly a ``\emph{followup}'', citing one or -more earlier packets --- meaning that the described real or virtual observation -was done as a response to those cited packet(s). In this case, the supplied -information is assumed to be a new, independent measurement. - -The {\tt cite} may be ``\emph{supersedes}'', which can be used to express a -variety of possible event contingencies. A prior VOEvent may be superseded, for -example, if reprocessing of the original observation has resulted in different -values for quantities expressed by {\tt } or {\tt } or if the -investigators have formed a new {\tt } regarding the event. On the other -hand, if a later observation has simply resulted in different measurements to -report, this would typically be issued as a ``\emph{followup}''. - -When a citation is made with a ``\emph{supersedes}'' or ``\emph{retraction}'' -attribute, it is assumed that {\bf all} of the previous information is -superseded: and so the cited event is no longer needed other than for archival -or historical purposes. If there is datum X and datum Y in the original, and X -gets improved calibration, then Y must also be copied to the new event, or else -its value will no longer be seen. There is, however, no guarantee that a -superseded or retracted event will not be subsequently cited or referenced. +An {\tt } element contains the IVORN of a previously published +VOEvent packet. Each {\tt } describes the relationship of the +current packet to that previous VOEvent. It has one required attribute: + +\paragraph{\tt cite}\label{sec:3.7.1.1} --- The {cite} attribute accepts three +possible enumerated values, ``\emph{followup}'', ``\emph{supersedes}'' or +``\emph{retraction}''. There is no default value. + +The value of the {\tt cite} attribute modifies the VOEvent semantics. In +contrast to a VOEvent announcing a discovery (\emph{i.e.}, a packet with no +citations), a VOEvent may be explicitly a ``\emph{followup}'', citing one or +more earlier packets --- meaning that the described real or virtual observation +was done as a response to those cited packet(s). In this case, the supplied +information is assumed to be a new, independent measurement. + +The {\tt cite} may be ``\emph{supersedes}'', which can be used to express a +variety of possible event contingencies. A prior VOEvent may be superseded, for +example, if reprocessing of the original observation has resulted in different +values for quantities expressed by {\tt } or {\tt } or if the +investigators have formed a new {\tt } regarding the event. On the other +hand, if a later observation has simply resulted in different measurements to +report, this would typically be issued as a ``\emph{followup}''. + +When a citation is made with a ``\emph{supersedes}'' or ``\emph{retraction}'' +attribute, it is assumed that {\bf all} of the previous information is +superseded: and so the cited event is no longer needed other than for archival +or historical purposes. If there is datum X and datum Y in the original, and X +gets improved calibration, then Y must also be copied to the new event, or else +its value will no longer be seen. There is, however, no guarantee that a +superseded or retracted event will not be subsequently cited or referenced. A ``\emph{supersedes}'' {\tt cite} can also be used to merge two or more earlier -VOEvent threads that are later determined to be related in some fashion. The -VOEvents to be merged are indicated with separate {\tt } elements. -The proper interpretation of such a merger would depend on a VOEvent client -having received all intervening packets from all relevant threads. Finally, -``\emph{supersedes}'' can be used in combination with a ``\emph{followup}'' to +VOEvent threads that are later determined to be related in some fashion. The +VOEvents to be merged are indicated with separate {\tt } elements. +The proper interpretation of such a merger would depend on a VOEvent client +having received all intervening packets from all relevant threads. Finally, +``\emph{supersedes}'' can be used in combination with a ``\emph{followup}'' to divide a single VOEvent into two or more new threads. First, follow-up the event in one packet and then supersede the original event, rather than the follow-up, -in a second packet (with a second identifier that can start a second thread). +in a second packet (with a second identifier that can start a second thread). -The ``\emph{retraction}" {\tt cite} indicates that the initial discovery event +The ``\emph{retraction}" {\tt cite} indicates that the initial discovery event is being completely retracted for some reason. The publisher of a retraction may be other than the publisher of the original VOEvent --- subscribers are free to -interpret such a situation as they see fit. +interpret such a situation as they see fit. Splitting, merging or retracting a VOEvent should typically be accompanied by a -{\tt } element discussing why such actions are being taken. +{\tt } element discussing why such actions are being taken. -An attempt is made to retract the sighting of Tycho's supernova: +An attempt is made to retract the sighting of Tycho's supernova: \begin{lstlisting}[language=XML] - ivo://uraniborg.hven#1572-11-11/0001 + ivo://uraniborg.hven#1572-11-11/0001 Oops! - + \end{lstlisting} \subsection{{\tt } --- Human Oriented Content} \label{sec:3.8} A {\tt } may be included within any element or sub-element of a -VOEvent to add human readable content. {\tt }s may NOT contain {\tt -}. Users may wish to embellish Description sections with HTML tags +VOEvent to add human readable content. {\tt }s may NOT contain {\tt +}. Users may wish to embellish Description sections with HTML tags such as images and URL links, and these should not be seen by the XML parser, as -they will cause the VOEvent XML to be invalid against the schema. However, it is -possible to use the CDATA mechanism of XML to quote text at length, so this may -be used for complicated tagged Descriptions. See the example in section -\ref{sec:4} for usage. +they will cause the VOEvent XML to be invalid against the schema. However, it is +possible to use the CDATA mechanism of XML to quote text at length, so this may +be used for complicated tagged Descriptions. See the example in section +\ref{sec:4} for usage. \subsection{{\tt } --- External Content} \label{sec:3.9} -A {\tt } may be included in any element or sub-element of a VOEvent -packet to describe an association with external content via a Uniform Resource -Identifier \citep{2016ivoa.spec.0523D}. In addition to the locator for the -content, there is also a locator for the meaning of the content, which is -another URI, specified by the {\tt meaning} attribute. It is anticipated that a -Note will be written discussing the IVOA-wide usage of such meaning locators. A -client application may ignore {\tt } elements with unrecognized {\tt -meaning} attributes. On the other hand, the client may ignore the `meaning' -attribute if the position of the {\tt } element is sufficient to -establish semantics; for example if it is contained in a {\tt }, then -presumably it gives drill-down semantics for the precise meaning of that {\tt -}. A {\tt } must be expressed as an empty element, with -attributes only. - -A {\tt } element has the attributes: -\subsubsection{\tt uri}\label{sec:3.9.1}--- The identifier of another document -(anyURI\footnote{\url{https://www.w3.org/TR/xmlschema11-2/\#anyURI}}). This -attribute must be present. -\subsubsection{\tt meaning}\label{sec:3.9.2}--- The nature of the document -referenced (anyURI). This attribute is optional. +A {\tt } may be included in any element or sub-element of a VOEvent +packet to describe an association with external content via a Uniform Resource +Identifier \citep{2016ivoa.spec.0523D}. In addition to the locator for the +content, there is also a locator for the meaning of the content, which is +another URI, specified by the {\tt meaning} attribute. It is anticipated that a +Note will be written discussing the IVOA-wide usage of such meaning locators. A +client application may ignore {\tt } elements with unrecognized {\tt +meaning} attributes. On the other hand, the client may ignore the `meaning' +attribute if the position of the {\tt } element is sufficient to +establish semantics; for example if it is contained in a {\tt }, then +presumably it gives drill-down semantics for the precise meaning of that {\tt +}. A {\tt } must be expressed as an empty element, with +attributes only. + +A {\tt } element has the attributes: +\subsubsection{\tt uri}\label{sec:3.9.1}--- The identifier of another document +(anyURI\footnote{\url{https://www.w3.org/TR/xmlschema11-2/\#anyURI}}). This +attribute must be present. +\subsubsection{\tt meaning}\label{sec:3.9.2}--- The nature of the document +referenced (anyURI). This attribute is optional. \subsubsection{\tt mimetype}\label{sec:3.9.3}--- An optional MIME type\footnote{ -\url{https://www.iana.org/assignments/media-types/media-types.xhtml}} for the -referenced document. -\subsubsection{\tt type}\label{sec:3.9.4}[DEPRECATED] --- The type of the -document as described in VOEvent v1.11. -\subsubsection{\tt name}\label{sec:3.9.5}[DEPRECATED] --- A short name as -described in VOEvent v1.11. - -A {\tt } is used to provide general purpose ancillary data with -well-defined meaning. Here a fits image is presented (h.fits), and also a link -to the data model that is needed for a machine to understand the meaning. +\url{https://www.iana.org/assignments/media-types/media-types.xhtml}} for the +referenced document. +\subsubsection{\tt type}\label{sec:3.9.4}[DEPRECATED] --- The type of the +document as described in VOEvent v1.11. +\subsubsection{\tt name}\label{sec:3.9.5}[DEPRECATED] --- A short name as +described in VOEvent v1.11. + +A {\tt } is used to provide general purpose ancillary data with +well-defined meaning. Here a fits image is presented (h.fits), and also a link +to the data model that is needed for a machine to understand the meaning. \begin{lstlisting}[language=XML] - - + \end{lstlisting} -An example of the indirection of a VOEvent packet using {\tt }: +An example of the indirection of a VOEvent packet using {\tt }: \begin{lstlisting}[language=XML] - + - + \end{lstlisting} \section{Event Streams and the Registry} @@ -1448,7 +1448,7 @@ \subsection{Finding VOEvent Streams} NATURAL JOIN rr.capability NATURAL JOIN rr.interface NATURAL JOIN rr.res_subject -WHERE +WHERE standard_id='ivo://ivoa.net/std/voevent' AND 1=ivo_nocasematch(res_subject, '%supernova%') AND role='std' @@ -1456,22 +1456,22 @@ \subsection{Finding VOEvent Streams} \section{VOEvent Example} \label{sec:4} -This imaginary event is a brightness measurement of a past supernova from the -RAPTOR \citep{bib10} telescope. The {\tt } section reports a {\tt -} and {\tt } followed by a {\tt } about seeing -and a {\tt } with the actual report: the magnitude is 19.5, measured -278.02 days after the reference time, which is reported in the {\tt -} section. There is a {\tt } of measured distances to the -presumed host galaxy. The packet represents a follow-up observation of an -earlier event, as defined in the {\tt } element. +This imaginary event is a brightness measurement of a past supernova from the +RAPTOR \citep{bib10} telescope. The {\tt } section reports a {\tt +} and {\tt } followed by a {\tt } about seeing +and a {\tt } with the actual report: the magnitude is 19.5, measured +278.02 days after the reference time, which is reported in the {\tt +} section. There is a {\tt
} of measured distances to the +presumed host galaxy. The packet represents a follow-up observation of an +earlier event, as defined in the {\tt } element. \begin{lstlisting}[language=XML] - ivo://raptor.lanl/organization @@ -1480,23 +1480,23 @@ \section{VOEvent Example} An imaginary event report about SN 2009lw. - - Time is days since the ref time in the + Time is days since the ref time in the WhereWhen section - - -
- Individual Moduli and Distances for NGC 0931 + Individual Moduli and Distances for NGC 0931 from NED @@ -1539,7 +1539,7 @@ \section{VOEvent Example} - Raptor AB at Los Alamos. ]]> @@ -1558,9 +1558,9 @@ \section{VOEvent Example} \section{Schema Diagram for VOEvent} \label{sec:5} -This image summarizes the basic structure of the event packet. The image shows -how the {\tt } and {\tt } elements can appear in many -different places, abbreviated by D and R. Elements and their hierarchy are in +This image summarizes the basic structure of the event packet. The image shows +how the {\tt } and {\tt } elements can appear in many +different places, abbreviated by D and R. Elements and their hierarchy are in black, attributes in green, required attributes underlined. \begin{figure}[th] \begin{center} @@ -1582,66 +1582,66 @@ \section{Modification History} \subsection{Changes from VOEvent 2.0} \label{appendix:last-changes} \begin{itemize} -\item The {\tt contributor} element has new attributes: {\tt ivorn}, {\tt -altIdentifier} and {\tt role}. -\item The restricted list of {\tt AstroCoordSystem} is removed. It was -previously an {\tt idValues} type, now it is a simple {\tt xs:string} type. -This allows to have extra Solar and Planetary frames without modifying the -schema. The {\tt idValues} type and its references (in {\tt AstroCoordSystem} -and {\tt coord\_system\_id}) have been removed. The {\tt AstroCoordSystem} can -be fully described with a {\tt TimeFrame} and a {\tt SpaceFrame} (according to +\item The {\tt contributor} element has new attributes: {\tt ivorn}, {\tt +altIdentifier} and {\tt role}. +\item The restricted list of {\tt AstroCoordSystem} is removed. It was +previously an {\tt idValues} type, now it is a simple {\tt xs:string} type. +This allows to have extra Solar and Planetary frames without modifying the +schema. The {\tt idValues} type and its references (in {\tt AstroCoordSystem} +and {\tt coord\_system\_id}) have been removed. The {\tt AstroCoordSystem} can +be fully described with a {\tt TimeFrame} and a {\tt SpaceFrame} (according to STC-1.33). -\item Annotations in {\tt AstroCoords/Time} and {\tt AstroCoords/Position2D} +\item Annotations in {\tt AstroCoords/Time} and {\tt AstroCoords/Position2D} have been included in the schema (according to STC-1.33). \item The concept of {\tt AstroCoords/PositionName} in introduced with type {\tt xs:string}. This allows to identify a target by its name (such as a named solar -system body). -\item The concept of {\tt TimeInterval} is introduced in the {\tt
} element to express simple tables, see section -\ref{sec:3.3.3}. -\item The {\tt } and {\tt } elements may have an attribute -``{\tt utype}'' to express how it fits into an IVOA data model. -\item The VOEvent packet structure still conforms to the IVOA Space-Time -Coordinates standard, but there is a new, simplified schema for these elements -that is completely within the VOEvent schema. -\item GPS time is now a valid time system for VOEvents -\item The semantic implication of a {\tt } element is clarified: -section \ref{sec:3.7} -\item The {\tt } element has a more sophisticated notion of meaning; -it is a general URI reference to a wide range of possible content, rather than -just a simple HTML link, and there is also a {\tt mimetype} attribute. +\ref{sec:3.3.3}. +\item The {\tt } and {\tt } elements may have an attribute +``{\tt utype}'' to express how it fits into an IVOA data model. +\item The VOEvent packet structure still conforms to the IVOA Space-Time +Coordinates standard, but there is a new, simplified schema for these elements +that is completely within the VOEvent schema. +\item GPS time is now a valid time system for VOEvents +\item The semantic implication of a {\tt } element is clarified: +section \ref{sec:3.7} +\item The {\tt } element has a more sophisticated notion of meaning; +it is a general URI reference to a wide range of possible content, rather than +just a simple HTML link, and there is also a {\tt mimetype} attribute. \end{itemize} \section{Schema} \label{sec7} -The XML schema available at -\url{http://www.ivoa.net/xml/VOEvent/VOEvent-v2.1.xsd} corresponds to this -document, but it is the document that is normative. +The XML schema available at +\url{http://www.ivoa.net/xml/VOEvent/VOEvent-v2.1.xsd} corresponds to this +document, but it is the document that is normative. \end{document} diff --git a/VOEventRegExt-v2.0.xsd b/VOEventRegExt-v2.0.xsd index ca11c87..7ab1240 100644 --- a/VOEventRegExt-v2.0.xsd +++ b/VOEventRegExt-v2.0.xsd @@ -1,5 +1,5 @@ - - This will normally be a key from + This will normally be a key from ivo://ivoa.net/std/VOEvent starting with acc-. From 200aba5472ec38bebe5ff660b26726711f4a6426 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Fri, 27 Sep 2024 16:11:30 +0200 Subject: [PATCH 2/3] Minor changes after the RFC review by Markus (who also takes the liberty of adding himself to the author list here: I've contributed the Registry chapter) --- .gitignore | 3 + Makefile | 12 +++- VOEvent.tex | 184 +++++++++++++++++++++++++++------------------------- ivoatex | 2 +- 4 files changed, 112 insertions(+), 89 deletions(-) diff --git a/.gitignore b/.gitignore index b0e20a4..13fba59 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,6 @@ ivoatexmeta.tex *.tar.gz *.swp role_diagram.svg +gitmeta.tex +*.fdb_latexmk +*.fls diff --git a/Makefile b/Makefile index 88cf5d6..056d0d4 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ AUTHOR_EMAIL=baptiste.cecconi@obspm.fr # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex -SOURCES = $(DOCNAME).tex role_diagram.pdf +SOURCES = $(DOCNAME).tex role_diagram.pdf gitmeta.tex # List of image files to be included in submitted package (anything that # can be rendered directly by common web browsers) @@ -32,3 +32,13 @@ VECTORFIGURES = AUX_FILES = VOEvent-v2.1.xsd VOEventRegExt-v2.0.xsd resrec-sample.vor include ivoatex/Makefile + +-include ivoatex/Makefile + +ivoatex/Makefile: + @echo "*** ivoatex submodule not found. Initialising submodules." + @echo + git submodule update --init + +test: + @echo "No tests defined yet" diff --git a/VOEvent.tex b/VOEvent.tex index 0184939..412dee0 100644 --- a/VOEvent.tex +++ b/VOEvent.tex @@ -1,11 +1,12 @@ \documentclass[11pt,a4paper]{ivoa} \input tthdefs +\input gitmeta \usepackage{hyperref} \usepackage{verbatim} \lstloadlanguages{XML,SQL} \lstset{flexiblecolumns=true,numberstyle=\small,showstringspaces=False, - identifierstyle=\texttt} + identifierstyle=\texttt,basicstyle=\footnotesize} \title{Sky Event Reporting Metadata (VOEvent)} @@ -17,11 +18,12 @@ \author{\\Scott {\bf Barthelmy}, NASA Goddard Spaceflight Center, USA} \author{\\Joshua S. {\bf Bloom}, University of California, Berkeley, USA} \author{\\John M. {\bf Brewer}, Yale University, USA} +\author{\\Markus {\bf Demleitner}, Universität Heidelberg, Germany} \author{\\Robert B. {\bf Denny}, DC-3 Dreams SP, USA} \author{\\Mike {\bf Fitzpatrick}, National Optical Astronomy Observatory, USA} \author{\\Matthew {\bf Graham}, California Institute of Technology, USA} \author{\\Norman {\bf Gray}, University of Glasgow, UK} -\author{\\Frederic {\bf Hessman}, University of Gottingen, Germany} +\author{\\Frederic {\bf Hessman}, University of Göttingen, Germany} \author{\\Pierre {\bf Le Sidaner}, Observatoire de Paris, France} \author{\\Szabolcs {\bf Marka}, Columbia University, USA} \author{\\Dave {\bf Morris}, University of Edinburg, UK} @@ -106,24 +108,6 @@ \section*{Status of this Document} The list of \href{http://www.ivoa.net/Documents/}{current IVOA Recommendations and other technical documents} can be found at \url{http://www.ivoa.net/Documents/}. -VOEvent is an IVOA standard, which means that it fits into a rich matrix of -other IVOA standards: the image below shows where VOEvent fits into the broader -IVOA architecture. VOEvents inherit much of the structure and semantics of {\bf -VOTable} \citep{2019ivoa.spec.1021O}, including the {\bf UCD} -\citep{2018ivoa.spec.0527P} scheme for semantics of quantities and the VOUnits -standard \citep{2014ivoa.spec.0523D}. VOEvent takes space-time coordinates from -the {\bf STC} \citep{2007ivoa.spec.1030R}, and it uses the URI semantics of the -IVOA {\bf Vocabulary} \citep{2009ivoa.spec.1007G} effort. IVOA {\bf Identifiers} -\citep{2016ivoa.spec.0523D} are used for events and their parent streams and -servers, and both these latter will be described by IVOA {\bf Resource Metadata} -\citep{2007ivoa.spec.0302H} and stored in the registry. - -\begin{figure}[ht!] -\centering\includegraphics[width=0.9\textwidth]{role_diagram} -\caption{VOEvent standard in the VO architecture diagram} -\label{fig:diagram} -\end{figure} - \section{Introduction} Throughout human history, unexpected events in the sky have been interpreted as @@ -184,7 +168,7 @@ \section{Introduction} or more fully automated. These rates indicate events that must be handled by machines, not humans. Subscribing agents must be able to automatically filter a tractable number of events without missing any that may be key to achieving -theirgoals. In general, the number of pending events from a large-scale survey +their goals. In general, the number of pending events from a large-scale survey telescope (such as LSST) that are above the horizon at a given observatory during a given observing session may be orders of magnitude larger than a human can sift through productively. Selection criteria will need to be quite precise @@ -244,6 +228,27 @@ \section{Introduction} of the document, conveying the semantics of a VOEvent packet. Explicit examples of VOEvent packets are in \S\ref{sec:4}, and linked references in \S\ref{sec:5}. +\subsection{Role within the VO Architecture} + +\begin{figure}[ht!] +\centering\includegraphics[width=0.9\textwidth]{role_diagram} +\caption{VOEvent standard in the VO architecture diagram} +\label{fig:diagram} +\end{figure} + +Fig.~\ref{fig:diagram} shows the role this document plays within the +IVOA architecture \citep{2021ivoa.spec.1101D}. + +VOEvents inherit much of the structure and semantics of {\bf +VOTable} \citep{2019ivoa.spec.1021O}, including the {\bf UCD} +\citep{2018ivoa.spec.0527P} scheme for semantics of quantities and the VOUnits +standard \citep{2023ivoa.spec.1215G}. VOEvent takes space-time coordinates from +the {\bf STC} \citep{2007ivoa.spec.1030R}, and it uses the URI semantics of the +IVOA {\bf Vocabulary} 1.0 \citep{2009ivoa.spec.1007G} effort. IVOA {\bf Identifiers} +\citep{2016ivoa.spec.0523D} are used for events and their parent streams and +servers, and both these latter are described by IVOA {\bf Resource Metadata} +\citep{2007ivoa.spec.0302H} and stored in the VO Registry. + \section{Usage} \label{sec:2} This document defines the syntax and semantics of an alert packet known as @@ -269,7 +274,7 @@ \subsection{Publishing VOEvent Packets} needed to retrieve the contact information for the author. An authoring organisation or individual may often rely on autonomous systems to actually create and transport the individual alert messages. -\item A \emph{\bf Publisher} receives alerts from one-or-more authors, and +\item A \emph{\bf Publisher} receives alerts from one or more authors, and assigns a unique identifier to each resulting packet. Either the author or the publisher generates the actual XML syntax of the event, but the publisher is responsible for the validity of the packet relative to the VOEvent schema. @@ -297,7 +302,8 @@ \subsection{Publishing VOEvent Packets} \subsection{VO Identifiers (IVORNs)} \label{sec:2.2} -VOEvent benefits from the IVOA identifiers developed for the VO registry. Such +VOEvent benefits from the IVOA identifiers developed for the VO registry. +In this document, such an identifier is called an \emph{IVORN}, that is, an \emph{International Virtual Observatory Resource Name}. It is required to begin with ``{\tt ivo://}'', and will stand in for a particular packet. A \emph{registered} VOEvent packet is one @@ -466,7 +472,7 @@ \subsection{{\tt } --- identifiers, roles and versions} For example, a {\tt } packet resulting from Tycho Brahe's discovery of a ``Stella Nova'' in Cassiopeia on 11 November 1572 might start: -\begin{lstlisting}[language=XML] +\begin{lstlisting} \end{lstlisting} @@ -488,7 +494,7 @@ \subsubsection{\tt } contributors can also be noted. An example of Author information might be: -\begin{lstlisting}[language=XML] +\begin{lstlisting} Rapid Telescope for Optical Response Raptor @@ -529,11 +535,11 @@ \subsubsection{\tt } yyyy-mm-ddThh:mm:ss}}). The timescale --- for curation purposes only --- is assumed to be Coordinated Universal Time (UTC). Discussions of date and time for the expression of meaningful scientific coordinates may be found in -\citep{2007ivoa.spec.1030R} and \citep{bib26}. +\citet{2007ivoa.spec.1030R} and \citet{bib26}. Minimal {\tt } usage might resemble: -\begin{lstlisting}[language=XML] +\begin{lstlisting} ivo://uraniborg.hven/Tycho 1573-05-05T01:23:45Z @@ -550,7 +556,7 @@ \subsection{{\tt } --- Event Characterisation} The {\tt } and {\tt } elements work together to characterise the nature of a VOEvent. That is: {\tt } has author-defined parameters about what was measured directly, or other relevant information about the event, -versus {\tt } is a data model of fixed schema about the hypothesised +whereas {\tt } is governed by a data model with a fixed schema about the hypothesised underlying cause or causes of the astrophysical event. In general, an observation is the association of one or more dependent variables @@ -562,9 +568,9 @@ \subsection{{\tt } --- Event Characterisation} A {\tt } element contains a list of {\tt } elements which may be associated and labeled using {\tt } elements. It may also have one or -more
elements, each of which can contain {\tt } and {\tt } +more \texttt{
} elements, each of which can contain {\tt } and {\tt } elements: these last define a whole column, or vector of data, rather than a -single primitive value as with . See \S\ref{sec:4} for an example of +single primitive value as with \texttt{}. See \S\ref{sec:4} for an example of usage. \subsubsection{{\tt } --- Numbers and strings with semantics} @@ -572,8 +578,7 @@ \subsubsection{{\tt } --- Numbers and strings with semantics} \label{sec:3.3.1} {\tt } elements may be used to represent the values of arbitrarily named quantities. Thus a publisher need not establish a fixed schema for all events -they issue. Unified Content Descriptors (UCDs) \citep{2018ivoa.spec.0527P}. -%\citep{std:UCD} +they issue. Unified Content Descriptors (UCDs) \citep{2018ivoa.spec.0527P} may be used to clarify meaning. Usage of {\tt } and {\tt } is similar to the VOTable specification, see \S4.9 of \citep{2019ivoa.spec.1021O}. @@ -597,9 +602,8 @@ \subsubsection{{\tt } --- Numbers and strings with semantics} performed. \noindent {\bf3.3.1.3} {\tt unit}\label{sec:3.3.1.3} --- The unit for -interpreting {\tt value}. See \S4.4 of \citep{2019ivoa.spec.1021O} -%\citep{std:VOTABLE} -which relies on VOUnits \citep{2014ivoa.spec.0523D}. +interpreting {\tt value}. See \S4.4 of \citet{2019ivoa.spec.1021O} +which relies on VOUnits \citep{2023ivoa.spec.1215G}. \noindent {\bf3.3.1.4} {\tt ucd}\label{sec:3.3.1.4} --- A UCD \citep{2018ivoa.spec.0527P} @@ -610,11 +614,11 @@ \subsubsection{{\tt } --- Numbers and strings with semantics} the data type of the {\tt }. Allowed values are ``string'', ``int'', or ``float'', with the default being ``string''. \begin{itemize} -\item For {\tt dataType=float}, the value must contain a possibly signed decimal +\item For \verb|dataType="float"|, the value must contain a possibly signed decimal or floating point number, possibly embedded in whitespace; it may also be -$\pm$nan or $\pm$inf. If the value cannot be parsed this way, for example null +$\pm$nan or $\pm$inf. If the value cannot be parsed this way, for example an empty string, it may return zero or NaN, but no exception should be thrown. -\item For {\tt dataType=int}, the value must contain a possibly signed decimal +\item For \verb|dataType="int"|, the value must contain a possibly signed decimal number, possibly embedded in whitespace. Conversion of floating point numbers to integers truncates (towards zero). If the value cannot be parsed this way, for example null string, it will return zero, and no exception should be thrown. @@ -626,16 +630,17 @@ \subsubsection{{\tt } --- Numbers and strings with semantics} page\footnote{\url{http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/Utypes}}. For example, here are three values from a GCN \citep{bib04} notice: -\begin{lstlisting}[language=XML] +\begin{lstlisting} TRIGGER_NUM = 114299 RATE_SIGNIF = 20.49 GRB_INTEN = 73288 \end{lstlisting} + In VOEvent, these can be represented as: -\begin{lstlisting}[language=XML] +\begin{lstlisting} - - Best significance after trying all algorithms - - + + Best significance after trying all algorithms + + \end{lstlisting} @@ -655,12 +660,12 @@ \subsubsection{{\tt } --- collection of related Params} number. In a GCN notice, for example, we might see this line: -\begin{lstlisting}[language=XML] +\begin{lstlisting} GRB_INTEN: 73288 [cnts] Peak=1310 [cnts/sec] \end{lstlisting} which could be expressed with one Param with a Value element, and the other with a Value attribute: -\begin{lstlisting}[language=XML] +\begin{lstlisting} 73288 @@ -740,7 +745,7 @@ \subsubsection{{\tt
} --- simple tabular data} \noindent {\bf3.3.3.4} {\tt unit}\label{sec:3.3.3.4} --- The unit for interpreting the values as given in the {\tt
} table cells. See \S4.4 of -\citep{2019ivoa.spec.1021O}, which relies on \citep{2014ivoa.spec.0523D}. +\citet{2019ivoa.spec.1021O}, which relies on \citet{2014ivoa.spec.0523D}. \noindent {\bf3.3.3.5} {\tt ucd}\label{sec:3.3.3.5} --- A UCD \citep{2018ivoa.spec.0527P} expression characterizing the nature of the data in @@ -751,25 +756,27 @@ \subsubsection{{\tt } --- simple tabular data} ``float'', with the default being ``string''. \noindent {\bf3.3.3.7} {\tt utype}\label{sec:3.3.3.7} --- A utype (see \S4.6 of -\citep{2019ivoa.spec.1021O}) defines this {\tt } as part of a larger data +\citet{2019ivoa.spec.1021O}) defines this {\tt } as part of a larger data structure, such as one of the IVOA standard data models. The following is an example of a Table element. Note the {\tt dataType} attribute that is used to interpret the values in the table cells. -\begin{lstlisting}[language=XML] +\begin{lstlisting}
- Individual Moduli and Distances for NGC 0931 from NED - - - - + Individual Moduli and Distances for NGC 0931 from + NED + + + + - - - - - - + + + + + +
33.160.3842.91997ApJS..109..333W
33.320.3846.11997ApJS..109..333W
33.510.4850.42009ApJS..182..474S
33.550.3851.31997ApJS..109..333W
33.710.4355.22009ApJS..182..474S
34.010.8063.31997ApJS..109..333W
33.160.3842.91997ApJS..109..333W
33.320.3846.11997ApJS..109..333W
33.510.4850.42009ApJS..182..474S
\end{lstlisting} @@ -797,7 +804,7 @@ \subsection{{\tt } --- Space-Time Coordinates} and the observatory are in constant motion, and STC inextricably relates spatial and temporal information. -\begin{lstlisting}[language=XML] +\begin{lstlisting} @@ -816,7 +823,7 @@ \subsubsection{ObservationLocation} of the event, {\tt }, containing a reference back to the coordinate system specification. For example: -\begin{lstlisting}[language=XML] +\begin{lstlisting} @@ -906,12 +913,13 @@ \subsubsection{ObservatoryLocation} The {\tt } element is used to express the location from which the observation being described was made. It is a required element for expressing topocentric coordinate systems. An instance of {\tt -} may take two forms. In the first, an observatory location +} may take two forms. In the first, an observatory location may be taken from a library, for example: -{\footnotesize -\begin{verbatim} + +\begin{lstlisting} -\end{verbatim}} +\end{lstlisting} + The {\tt id} here indicates the name of the observatory, other examples being: Keck, KPNO, JCMT, MMTO, VLA, etc., or it may indicate one of the following generic observatory locations: @@ -926,7 +934,7 @@ \subsubsection{ObservatoryLocation} For example, a packet might contain the following {\tt } to indicate that the coordinates expressed in the {\tt } element are located with an accuracy comprising the Earth's surface: -\begin{lstlisting}[language=XML] +\begin{lstlisting} \end{lstlisting} @@ -935,7 +943,7 @@ \subsubsection{ObservatoryLocation} altitude on the surface of the Earth. Note the use of a coordinate system for the surface of the Earth (UTC-GEOD-TOPO) is natural for an observatory location, whereas coordinate systems in the previous section are for astronomical events. -\begin{lstlisting}[language=XML] +\begin{lstlisting} @@ -958,7 +966,7 @@ \subsubsection{Parsing the WhereWhen Element} When parsing a VOEvent packet, the following pseudocode may be of use to provide the time, the right ascension and the declination, if the author used \emph{ICRS} spatial coordinates and \emph{UTC} time. -\begin{lstlisting}[language=XML] +\begin{lstlisting} Let x =/voe:VOEvent/WhereWhen/ObsDataLocation/ObservationLocation/AstroCoords If x[@coord_system_id='UTC-ICRS-TOPO'] then Let Time = x/Time/TimeInstant/ISOTime @@ -977,7 +985,7 @@ \subsubsection{Parsing the WhereWhen Element} \subsubsection{Solar System Events} \label{sec:3.4.4} -Solar System events include Solar events and planetary events. +Solar system events include Solar events and planetary events. Solar events have similar requirement as astronomical events in terms of Observatory and Observation location but are using a different reference frames. @@ -1004,12 +1012,12 @@ \subsubsection{Solar System Events} for managing the valid terms of well-known solar system reference frames. A {\tt PositionName} element is available in the {\tt -ObservationLocation/AstroCoords} element. It is used to refer to named objects, +ObservationLocation/Ast\-roCoords} element. It is used to refer to named objects, at which the event is observed without coordinates (e.g., for unresolved -observations, or global impact). +observations, or a global impact). A {\tt TimeInterval} element is available in the {\tt -ObservationLocation/AstroCoords/Time} element. It is composed of two elements +ObservationLocation/Astro\-Coords/Time} element. It is composed of two elements {\tt ISOTimeStart} and {\tt ISOTimeStop}, both defined similarly to the {\tt ISOTime} element of {\tt TimeInstant}. This pair of dates is used to refer to interval observations or predictions. This interval concept is different than @@ -1065,7 +1073,7 @@ \subsection{{\tt } --- Instrument Configuration} elements, that together characterise the instrument(s) that produced the observation(s) that resulted in issuing the VOEvent packet. A URI pointing to a previous VOEvent asserts that an identical instrumental configuration was used: -\begin{lstlisting}[language=XML] +\begin{lstlisting} The Echelle spectrograph @@ -1078,7 +1086,7 @@ \subsection{{\tt } --- Initial Scientific Assessment} astronomical objects and processes that generated the observations noted in the {\tt } element. Natural language words and phrases are used to express the hypothesised astrophysics, pending a standard VO ontology or formal UCD-like -vocabulary of astronomical concepts (see \citep{2018ivoa.spec.0527P}). +vocabulary of astronomical concepts (see \citet{2018ivoa.spec.0527P}). % and [\hyperref[bib19]{19}], for example => reference removed, since the % document is not available anymore at provided URL. The {\tt } element has two optional attributes, {\tt importance} and {\tt @@ -1116,7 +1124,7 @@ \subsubsection{{\tt } --- classification}\label{sec:3.6.3} The value of a {\tt } element uses a controlled vocabulary to express the hypothesized astrophysics. This standard VO ontology or formal UCD-like vocabulary of astronomical concepts vocabulary is still in development (see -\citep{2018ivoa.spec.0527P}). +\citet{2018ivoa.spec.0527P}). %\citep{std:UCD} and [\hyperref[bib19]{19}], for example). \subsubsection{{\tt } --- natural language}\label{sec:3.6.4} @@ -1153,7 +1161,7 @@ \subsubsection{{\tt } --- hypotheses inferred}\label{sec:3.6.6} identified as a \emph{Type Ia Supernova}, and is ``associated'' with the \emph{SN remnant} known as \emph{3C 10}. This was an important discovery, but is no longer a very urgent one: -\begin{lstlisting}[language=XML] +\begin{lstlisting} Tycho's Stella Nova @@ -1249,7 +1257,7 @@ \subsubsection{{\tt } --- Cited event and relationship} {\tt } element discussing why such actions are being taken. An attempt is made to retract the sighting of Tycho's supernova: -\begin{lstlisting}[language=XML] +\begin{lstlisting} ivo://uraniborg.hven#1572-11-11/0001 Oops! @@ -1300,14 +1308,14 @@ \subsubsection{\tt name}\label{sec:3.9.5}[DEPRECATED] --- A short name as A {\tt } is used to provide general purpose ancillary data with well-defined meaning. Here a fits image is presented (h.fits), and also a link to the data model that is needed for a machine to understand the meaning. -\begin{lstlisting}[language=XML] +\begin{lstlisting} \end{lstlisting} An example of the indirection of a VOEvent packet using {\tt }: -\begin{lstlisting}[language=XML] +\begin{lstlisting} @@ -1317,7 +1325,7 @@ \subsubsection{\tt name}\label{sec:3.9.5}[DEPRECATED] --- A short name as \section{Event Streams and the Registry} \label{sec:registry-matters} -In this section, we will reference several namespaces XML elements using +In this section, we will reference several namespaced XML elements using VO canonical prefixes. The prefixes used here are: \begin{itemize} @@ -1353,7 +1361,9 @@ \subsection{Registering Event Streams} \end{compactitem} It is recommended to register VOEvent streams using -\xmlel{vs:CatalogService} resources, as these allow service operators +\xmlel{vs:CatalogService} (or, if the stream is only accessible through +third-party services, \xmlel{vs:CatalogResource}) +resources, as these allow service operators to attach rich metadata like the originating facility and instrument, and possibly extra stream metadata in a tableset. However, this specification does not constrain the resource type. @@ -1371,7 +1381,7 @@ \subsection{Registering Event Streams} Zero or more endpoints publishing the event stream are declared within this capability element using \xmlel{vr:interface} elements with their \xmlel{role} attributes set to \verb|std|; such standard interfaces MUST -be of type \xmlel{voe:StreamEndpoint} and then by the schema MUST have +be of type \xmlel{voe:Stream\-Endpoint} and then by the schema MUST have a \xmlel{standardID} attribute, the value of which SHOULD reference one of the keys in this standard's registry record, \nolinkurl{ivo://ivoa.net/std/VOEvent}. @@ -1396,7 +1406,7 @@ \subsection{Registering Event Streams} Kafka. The Kafka stream is also availble through some other provider, perhaps to ensure high availability: -\begin{lstlisting}[language=XML] +\begin{lstlisting} @@ -1419,7 +1429,8 @@ \subsection{Finding VOEvent Streams} Normatively, VOEvent streams are located in the VO Registry as resources with capabilites whose \xmlel{standardID} attribute compares equal to -the VOEvent standard id \nolinkurl{ivo://ivoa.net/std/voevent}. +the VOEvent standard id \nolinkurl{ivo://ivoa.net/std/voevent} ignoring +case. This standard defines one mandatory details key for RegTAP \citep{2019ivoa.spec.1011D}: \verb|capability/interface/standardID|. @@ -1464,8 +1475,7 @@ \section{VOEvent Example} } section. There is a {\tt } of measured distances to the presumed host galaxy. The packet represents a follow-up observation of an earlier event, as defined in the {\tt } element. -\begin{lstlisting}[language=XML] - +\begin{lstlisting} Date: Sun, 17 Nov 2024 11:09:12 +0100 Subject: [PATCH 3/3] Fix integration preview with v4 API --- .github/workflows/build.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 4a08220..daafd94 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -28,7 +28,8 @@ jobs: test -f VOEvent.pdf test -f VOEvent.bbl - - uses: actions/upload-artifact@v1 + - name: Keep the PDF artefact + uses: actions/upload-artifact@v4 with: name: PDF Preview - path: VOEvent.pdf + path: ${{ env.doc_name }}.pdf