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 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 14dbd4f..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) @@ -26,9 +26,19 @@ 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 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-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}. + +\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 -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. +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 +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,396 +414,397 @@ \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. - -\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: -\begin{lstlisting}[language=XML] -} packet resulting from Tycho Brahe's discovery of +a ``Stella Nova'' in Cassiopeia on 11 November 1572 might start: +\begin{lstlisting} + \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: -\begin{lstlisting}[language=XML] +An example of Author information might be: +\begin{lstlisting} 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 +\citet{2007ivoa.spec.1030R} and \citet{bib26}. -Minimal {\tt } usage might resemble: -\begin{lstlisting}[language=XML] +Minimal {\tt } usage might resemble: +\begin{lstlisting} 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, +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 +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 \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 \texttt{}. 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 -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}. - -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 }: - -\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.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 +{\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} +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. + +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.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 +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} -%\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 \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 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 -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 \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. \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: -\begin{lstlisting}[language=XML] -TRIGGER_NUM = 114299 RATE_SIGNIF = 20.49 GRB_INTEN = 73288 +For example, here are three values from a GCN \citep{bib04} notice: +\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] + +In VOEvent, these can be represented as: +\begin{lstlisting} - - Best significance after trying all algorithms - - - + + 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: - -\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. - -In a GCN notice, for example, we might see this line: -\begin{lstlisting}[language=XML] -GRB_INTEN: 73288 [cnts] Peak=1310 [cnts/sec] +{\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.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: +\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] +which could be expressed with one Param with a Value element, and the other with +a Value attribute: +\begin{lstlisting} 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 +\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 +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. -\begin{lstlisting}[language=XML] + +\noindent {\bf3.3.3.7} {\tt utype}\label{sec:3.3.3.7} --- A utype (see \S4.6 of +\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} - 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} \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. - -\begin{lstlisting}[language=XML] +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} @@ -810,13 +817,13 @@ \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] +\begin{lstlisting} @@ -834,87 +841,88 @@ \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 -} may take two forms. In the first, an observatory location -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 } 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: + +\begin{lstlisting} + +\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: \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,19 +931,19 @@ \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: -\begin{lstlisting}[language=XML] - +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} + \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. -\begin{lstlisting}[language=XML] +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} @@ -947,377 +955,377 @@ \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. -\begin{lstlisting}[language=XML] +the time, the right ascension and the declination, if the author used +\emph{ICRS} spatial coordinates and \emph{UTC} time. +\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 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/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 a 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/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 +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: -\begin{lstlisting}[language=XML] +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} 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 -vocabulary of astronomical concepts (see \citep{2018ivoa.spec.0527P}). -% and [\hyperref[bib19]{19}], for example => reference removed, since the +{\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 \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 -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 -\citep{2018ivoa.spec.0527P}). -%\citep{std:UCD} and [\hyperref[bib19]{19}], for example). +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 +\citet{2018ivoa.spec.0527P}). +%\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. - -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] +{\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: +\begin{lstlisting} 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: -\begin{lstlisting}[language=XML] +An attempt is made to retract the sighting of Tycho's supernova: +\begin{lstlisting} - 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. -\begin{lstlisting}[language=XML] +\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} - - + \end{lstlisting} -An example of the indirection of a VOEvent packet using {\tt }: -\begin{lstlisting}[language=XML] - +An example of the indirection of a VOEvent packet using {\tt }: +\begin{lstlisting} + - + \end{lstlisting} \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|. @@ -1448,7 +1459,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 +1467,21 @@ \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. -\begin{lstlisting}[language=XML] - -} 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} + ivo://raptor.lanl/organization @@ -1480,23 +1490,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 +1549,7 @@ \section{VOEvent Example} - Raptor AB at Los Alamos. ]]> @@ -1558,9 +1568,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 +1592,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-. diff --git a/ivoatex b/ivoatex index 29eb5f1..85a59fe 160000 --- a/ivoatex +++ b/ivoatex @@ -1 +1 @@ -Subproject commit 29eb5f123b5986502e304ff6117ace0222a28d14 +Subproject commit 85a59fe8e6abd86bbe3ef4e12fd3dade71a54924