%%%%%%%%%%%%%%%%%%%%%%%%%% To allow same version tex / htx \def\ifhtx{\iffalse} % Lines used only for the HTML version \ifhtx % Declarations for HTX (HTML) %\begin{head} % \tag{META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1"} % \begin{title}VOTable \Version\ Proposal\end{title} % \tag{META NAME="robots" content="index"} % \tag{META NAME="description" content="VOTable Proposal"} % \tag{META REV="made" HREF="mailto:VOTable@ivoa.net"} % \tag{META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Linux)"} % \tag{META NAME="AUTHOR" CONTENT="Francois Ochsenbein, Roy Williams"} % \tag{META NAME="CREATED" CONTENT="20020315;23390000"} % \tag{META NAME="CHANGEDBY" CONTENT="Francois Ochsenbein"} % \tag{META NAME="CHANGED" CONTENT="20020315"} %\end{head} \def\Arefs#1#2{\Aref{#1}{#2}} \def\Arefx#1#2{\Aref{#1}{#2}} \def\Tref#1#2{\Aref{#1}{#2}} \def\Fref#1#2{\Aref{#1}{#2}} \def\twikiname#1#2{\makebox[10em][l]{\qquad\A{http://www.ivoa.net/twiki/bin/view/IVOA/#1}{#2}}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cgidef{ -tex \slash {{\fg{blue}/}} \attr #1{{\tt{\fg{DarkRed}#1}}} \elem #1{{\tt{\fg{DarkRed}#1}}} \elemdef #2{{\fg{blue}$<$}{\tt{\fg{DarkRed}#1}#2}{\fg{blue}$>$}} \xtag #1{\elemdef{#1}{}} \attrval #2{{\tt{\fg{DarkRed}#1}="{\fg{DarkMagenta}#2}"}} \utype #1{\attrval{utype}{#1}} \elemdef #2{{\fg{blue}<}{\tt{\fg{DarkRed}#1}#2}{\fg{blue}>}} \value #1{"{\fg{DarkMagenta}#1}"} \emref #1{{\fg{SteelBlue4}#1}} %\emref #1{{\fg{DarkGoldenrod}#1}} \emcom #1{{\fg{DarkMagenta}#1}} \emstc #1{{\fg{DarkGreen}#1}} {comment} #1{{\fg{darkblue}\em(#1)} }{} \Plain #1{\plain{#1}} \order {~\image{oplus.gif} } \unorder {~\image{circ2.gif} } \deprecated {~\image{dagger.gif} } \choice {\image{leadsto2.gif} } \left #1{} \right #1{} \Vobs {Virtual Observatory} \requiredattr #1{{\tt\bf{\fg{DarkBlue}#1}}} \filex html }%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \else % Declarations for LaTeX \documentclass[10pt,notitlepage,onecolumn,lcustom]{ivoa} \parskip=1ex % More space between paragraphs %%% Suppress the ridicously large top separation of item lists \makeatletter \toks@\expandafter{\@listI} \edef\@listI{\the\toks@\setlength{\topsep}{1pt}} \makeatother \topsep=0pt %\documentclass[12pt,notitlepage,onecolumn]{ivoa} %\documentclass{article} %\usepackage[pdftex]{graphicx} % Accept Images \usepackage{color} % Accept Colors \usepackage{verbatim} % Accept inputverbatim \usepackage{alltt} % Accept tt with macros \usepackage[plain,section]{algorithm} \usepackage[noend]{algpseudocode} \usepackage{multirow} % Enable hyphenation of teletype words (we've got lots of long ones % here...) \newcommand{\origttfamily}{} \let\origttfamily=\ttfamily \renewcommand{\ttfamily}{\origttfamily \hyphenchar\font=`\-} %% Comment/uncomment lines below to follow your LateX distribution... %% %% If document is processed with latex, dvips and ps2pdf %% \ifx\pdftexversion\undefined \usepackage[dvips]{graphicx} \DeclareGraphicsExtensions{.eps,.ps} %% Uncomment following line if you want PDF thumbnails % \usepackage[ps2pdf]{thumbpdf} % for old hyperref, use: \usepackage[ps2pdf]{hyperref} %% for recent hyperref, use: % \usepackage[ps2pdf,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,% % colorlinks,linkcolor=blue,urlcolor=blue]{hyperref} %% %% else if document is processed with pdflatex %% \else \usepackage[pdftex]{graphicx} %% graphics for pdftex (supports .pdf .jpg .png) \usepackage{epstopdf} %% requires epstopdf %% this is to support .ps files : \makeatletter \g@addto@macro\Gin@extensions{,.ps} \@namedef{Gin@rule@.ps}#1{{pdf}{.pdf}{`ps2pdf #1}} \makeatother %% comment above lines if you have included ps files %\DeclareGraphicsExtensions{.pdf,.jpg,.png} %% Uncomment following line if you want PDF thumbnails % \usepackage[pdftex]{thumbpdf} %% for old hyperref, use: % \usepackage[ps2pdf]{hyperref} % for recent hyperref, use: \usepackage[pdftex,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,% colorlinks,linkcolor=blue,urlcolor=blue]{hyperref} \pdfadjustspacing=1 %\def\A#1#2{{#2}\footnote{#1}} \let\A=\href %\def\A#1#2{\href{#1}{#2}} \fi \let\fg=\color % fg = foreground color \let\Beg=\begin \topmargin=-1cm \raggedbottom \oddsidemargin=0cm \parindent=0pt \arrayrulewidth=0.75pt\renewcommand{\arraystretch}{1.2} \definecolor{DarkRed}{rgb}{0.5,0,0} \definecolor{DarkBlue}{rgb}{0,0,0.5} \definecolor{DarkGreen}{rgb}{0,0.5,0} \definecolor{DarkPurple}{rgb}{0.3,0.1,0.5} \definecolor{DarkGoldenrod}{rgb}{0.72,0.5,0.05} \definecolor{SteelBlue4}{rgb}{0.1,0.25,0.4} \def\slash {{\fg{blue}/}} \def\filex{pdf} % File extension \def\attr#1{{\tt{\fg{DarkRed}#1}}} \def\requiredattr#1{{\tt\bf{\fg{DarkBlue}#1}}} \def\elem#1{{\tt{\fg{DarkRed}#1}}} \def\attrval#1#2{{\tt\fg{DarkRed}#1="{\fg{DarkPurple}#2}"}} \def\utype#1{\attrval{utype}{#1}} \def\allowhyphens{\penalty0\hskip0pt} \def\stcutype#1{\utype{\fg{DarkGreen}stc:\allowhyphens #1}} \def\elemdef#1#2{{\fg{blue}$<$}{\tt{\fg{DarkRed}#1}#2}{\fg{blue}$>$}} \def\Aref#1#2{section~\ref{#1}} \def\Arefs#1{section~\ref{#1}} \def\Arefx#1#2{appendix~\ref{#1}} \def\Tref#1#2{Table~\ref{#1}} \def\Fref#1#2{Figure~\ref{#1}} \def\value#1{{\tt"}{\fg{DarkPurple}#1}{\tt"}} %\def\emref#1{{\fg{DarkGoldenrod}#1}} \def\emref#1{{\fg{SteelBlue4}#1}} \def\emcom#1{{\fg{DarkPurple}#1}} \def\emstc#1{{\fg{DarkGreen}#1}} \def\ucd#1{{\fg{DarkPurple}#1}} \def\order{$\oplus$ } \def\unorder{{\large $\circ$ }} \def\deprecated {$\dagger$ } %\def\paramonly {$^{(p)}$} \def\choice{{$\mapsto$ }} \def\twikiname#1#2{\makebox[10em][l]{{#2}}} \def\Vobs{Virtual Observatory} %\def\inputverbatim#1{% %\begingroup \catcode``=13 \@noligs \tt \let\do\@makeother \dospecials %\obeylines \obeyspaces \frenchspacing \input #1 \endgroup } \def\thickrule{\noindent\rule{\textwidth}{1pt}} \def\Plain#1{{\sf #1}} \begin{document} \newenvironment{TABULAR}[2]{\begin{tabular}{#2}}{\end{tabular}} \newenvironment{plain}{\begin{quote}}{\end{quote}} %\def\plain#1{#1} \fi %%%%%%%%%%%%%%%%%%%%%%%%%% To allow same version tex / htx %% %% Header of the document... %% % Provide a title for your document \title{Referencing STC in VOTable} % Give date and version number \date{2010-02-16} % Choose one document type from below \ivoatype{IVOA Note} %\ivoatype{IVOA WG Internal Draft} %\ivoatype{IVOA Proposed Recommendation} %\ivoatype{IVOA Recommendation} \version{1.9} \editor{Fran\c cois {Ochsenbein}} \urlthisversion{%\par\noindent {\bf This version:}\\ %\hspace*{5em} \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20090612.\filex}} \urllastversion{%\par\noindent {\bf Latest version:}\\ %\hspace*{5em} \url{http://www.ivoa.net/Documents/latest/VOTableSTC.\filex} } \previousversion{%\par\noindent {\bf Previous versions:}\\ \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20081030.\filex} \quad V1.02\\ \hspace*{1.8em} \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20081018.\filex} \quad V1.01\\ \hspace*{1.8em} \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20080910.\filex} \quad V1.00\\ \hspace*{1.8em} \url{http://www.ivoa.net/Documents/Notes/VOTableSTC/VOTableSTC-20090612.\filex} } % \url{http://www.ivoa.net/Documents/PR/VOTable/VOTable-20031017.html} % \quad V1.0 (2002-04-15) % \url{http://www.ivoa.net/Documents/PR/VOTable/VOTable-20040811.html} % \quad V1.1 (2004-08-11) %} % Give author list: separate different authors with \\ % You can add email addresses with links \url{mailto:yourname@ivoa.net} \author{ \normalsize \twikiname{FrancoisOchsenbein}{Fran\c cois {\bf Ochsenbein}} \quad{\em Observatoire Astronomique de Strasbourg, France} \\ \normalsize \twikiname{JonathanMcDowell}{Jonathan {\bf McDowell}} \quad{\em Harvard-Smithsonian Center for Astrophysics, Cambridge MA, USA} \\ \normalsize \twikiname{ArnoldRots}{Arnold {\bf Rots}} \quad{\em Harvard-Smithsonian Center for Astrophysics, Cambridge MA, USA} \\ \normalsize \twikiname{Markus Demleitner}{Markus {\bf Demleitner}} \quad{\em Zentrum f\"ur Astronomie Heidelberg, Germany} \\ } %\normalsize\ifhtx\else\hspace*{-0.75em}\fi % {{\em with contributions from:}}\\ %\normalsize \twikiname{FrancoisBonnarel}{Fran\c cois {\bf Bonnarel }} % \quad{\em Observatoire de Strasbourg, France} \\ %\normalsize \twikiname{MireilleLouys}{Mireille {\bf Louys}} % \quad{\em Observatoire de Strasbourg, France} \\ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\begin{document} \maketitle % print header in standard form \section*{Abstract} This note describes the recommended way to reference the coordinate systems in usage in Astronomy for an accurate specification of spatial and temporal reference frames. It was made in agreement between the {\em VOTable} and the {\em Data Models} Working Groups. \iffalse \noindent The main part of this document describes the adopted part of the VOTable standard; it is followed by appendices presenting extensions which have been proposed and/or discussed, but which are not part of the standard. \fi \section*{Status of this document} This is an IVOA Note. It attempts to clarify how to reference unambiguously, in a \A{http://ivoa.net/Documents/latest/VOTable.html}{VOTable} document containing space- and/or time-related data, the reference systems in which these data are expressed, systems which are described by the \A{http://ivoa.net/Documents/latest/STC.html}{STC data model}. \begin{quote} %{\em This document has been produced by the } %\A{http://www.ivoa.net/twiki/bin/view/IVOA/IvoaVOTable}{IVOA % VOTable Working Group}. \em Comments to this note are welcome; it is expected that the expression of other data models into VOTable terms will be added in the future. \end{quote} \section*{Acknowledgments} This document is based on the W3C documentation standards, but has been adapted for the IVOA. \tableofcontents \section{Introduction} Astronomical catalogues are a very common source of tabular data, and among these the catalogs collecting astronomical sources observed at specific sky locations and epochs routinely have to be compared to other catalogues containing information related to the same sources, but observed or modelled in different contexts: observations at different epochs, different wavelengths, simulated results, etc. An accurate knowledge of the meaning of the parameters included in these catalogues -- and thus the systems in which they are expressed -- is therefore essential if one expects to derive scientifically significant conclusions from the comparisons of these data. In the context of the Virtual Observatory, such data is typically exchanged employing VOTables. Historically, a dedicated \elem{COOSYS} element was introduced in the original version (1.0) of the VOTable specification. It did specify some minimal level of details about the coordinate system used in the table, merely supporting an enumeration of the most commonly used coordinate frames (ICRS, historical equatorial frames, galactic, ecliptic, etc) associated to a couple of parameters (equinox and epoch). It was realized that the \elem{COOSYS} element was too restrictive, and thus it was deprecated in VOTable version 1.2. The description of coordinate systems should now proceed on the basis of the IVOA data model for space-time coordinates [2]. To link elements of a VOTable with those of a data model, version 1.1 of the VOTable specification introduced the \attr{utype} attribute. It is allowed on most VOTable elements, among others on \elem{GROUP}, \elem{FIELD}, \elem{INFO}, and, since 1.2, \elem{FIELDref} and \elem{PARAMref}. This note contains the specification of this linkage using \attr{utype}s. \section{ Specifying coordinate components in VOTable } \label{spec} The specification of astronomical coordinates using the IVOA STC data model [2] requires two definitions: \begin{enumerate} \item the definition of the \emph{coordinate system} (the frame in which the coordinates are expressed), which in STC-X takes place in an \elem{AstroCoordSystem} element. \item the definition of the \emph{roles} present in a given data set and the assignment of values. In STC-X, this is done using an \elem{AstroCoords} element. \end{enumerate} \subsection{Location of Definitions} When serializing STC information to VOTables, there are at most two \elem{GROUP} elements per STC definition, where an arbitrary number of STC definitions my be embedded into a VOTable. Coordinate systems (the \elem{AstroCoordSystem} element in STC-X) are contained in \elem{GROUP}s with \stcutype{AstroCoordSystem}; we refer to these as AstroCoordSystem groups. The definition of the roles of particular \elem{FIELD} or \elem{PARAM} elements are maintained in \elem{GROUP}s with \stcutype{AstroCoords}, called AstroCoords group henceforth. They correspond to the \elem{AstroCoords} or \elem{AstroCoordArea} elements of STC-X. To allow for embedding multiple STC definitions, a VOTable can contain any number of GROUPs with these \attr{utype}s. AstroCoordSystem may be at any position at which they are allowed by the VOTable standard but \emph{must} occur lexcially before any AstroCoords groups referencing them. Thus, it is recommended to write them as direct children of \elem{VOTABLE}. AstroCoords groups \emph{must} be direct children of either the \elem{TABLE} element containing the \elem{FIELD} and \elem{PARAM} elements described or, if a data set spans several tables, of the \elem{RESOURCE} element containing the \elem{TABLE}s. \subsection{Values and Utypes} \label{valuty} When adding STC information to a VOTable, the first step is to serialize the complex STC structure to a sequence of pairs of \attr{utype}s and values. This process is defined here in terms of the STC-X serialization [4] since its schema currently provides the most rigorous definition of how STC metadata should be serialized, although it was not designed for this purpose and the serialization rules below therefore become somewhat lengthy. Any equivalent way of creating the key-value pairs is, of course, equally valid. Most text content in the STC-X schema is floating point. For the current purposes, this is not enough, since roles in the STC data model might be filled both by values (in which case they would end up in \elem{PARAM} elements) and by value references, i.e., references to \elem{FIELD} elements. To accomodate this, assume XML \attr{id}s were allowed in the STC-X schema wherever ``values'' of any kind are allowed. To generate the \attr{utype}-value pairs for a given STC structure, first generate a tree of STC-X, substituting floating point literals with column references (\attr{id}s of \elem{FIELD}s) as appropriate. Then execute the procedure {\sc emitUtypesNode} (algorithm \ref{alg:treetoutype}) on the root node, passing an empty string for $u$. For the determination of node names, namespaces are disregarded, i.e., a node with QName \{http://www.ivoa.net/xml/STC/stc-v1.30.xsd\}C1 would enter the \attr{utype} as C1. \begin{algorithm} \caption{Generation of \attr{utype}s from STC-X trees} \label{alg:treetoutype} \begin{algorithmic} \Procedure{emitUtypesNode}{$n$, $u$} \Comment{$n$ is a node within an STCX-Tree} \Comment{$u$ is a string usually containing the parent's \attr{utype}} \If{$u$ is empty} \State{$u\gets$ \verb|'stc:'+| ${\rm name}(n)$} \Else \If{$n$'s type inherits from one of the types in table~\ref{tab:subsgroups}} \State {$u\gets u+\verb|'.'|+n$'s substitution group's utype fragment} \Else \State{$u\gets u+\verb|'.'|+{\rm name}(n)$} \EndIf \EndIf \If {$n$ has non-empty text content} \State emit a pair of $u$ and $n$'s text content \EndIf \State call {\sc emitAttrUtypes}($n$, $u$) \For{all child nodes nodes $n'$ of $n$} \State call {\sc emitUtypesNode($n'$, $u$)} \EndFor \EndProcedure \end{algorithmic} \end{algorithm} \begin{algorithm} \caption{Generation of \attr{utype}s from STC-X attributes} \label{alg:attrtoutype} \begin{algorithmic} \Procedure{emitAttrUtypes}{$n$, $u_0$} \Comment $n$ is a node within an STCX-Tree \Comment $u_0$ is a string containing the $n$'s utype \For{all key-value pairs $k$, $v$ formed from the $n$'s attributes} \If{$k$ is not in the set of banned attributes} \Comment{The banned attributes are given in table~\ref{tab:bannedattrs}.} \State $u\leftarrow u_0+\verb|'.'|+k$ \State Emit a pair $u$, $v$. \EndIf \EndFor \EndProcedure \end{algorithmic} \end{algorithm} \begin{table}[htbp] \ifhtx\label{tab:subsgroups}\begin{tabular}{|ll|} \multicolumn{2}{c}{Substitution group/\attr{utype} mapping (for algorithm \ref{alg:treetoutype})}\\ \else\caption{\label{tab:subsgroups} {Substitution group/\attr{utype} mapping (for algorithm \ref{alg:treetoutype})}} \begin{tabular}{|ll|}\hline\fi Substitution group head&\attr{utype} fragment \\ \hline spaceRefFrameType&\verb|SpaceRefFrame|\\ referencePositionType&\verb|ReferencePosition|\\ coordFlavorType&\verb|CoordFlavor|\\ \hline\end{tabular} \end{table} \begin{table}[htbp] \ifhtx\label{tab:bannedattrs}\begin{tabular}{|ll|} \multicolumn{2}{c}{Banned attributes for \attr{utype} generation (for algorithm \ref{alg:attrtoutype}).}\\ \else\caption{\label{tab:bannedattrs} {Banned attributes for \attr{utype} generation (for algorithm \ref{alg:attrtoutype}).}} \begin{tabular}{|ll|}\hline\fi \attr{idref}&\multirow{4}{*}{\parbox{0.6\textwidth}{Use the VOTable's native referencing instead; this may require changing the literals to avoid name clashes.}}\\ \attr{id}&\\ \attr{frame\_id}&\\ \attr{coord\_system\_id}&\\ \hline \attr{ucd}&\multirow{8}{*}{\parbox{0.6\textwidth}{Allowing these would create conflicts with VOTable's mechanisms of specifying them.}}\\ \attr{unit}&\\ \attr{pos\_angle\_unit}&\\ \attr{pos\_unit}&\\ \attr{spectral\_unit}&\\ \attr{time\_unit}&\\ \attr{vel\_time\_unit}&\\ \attr{gen\_unit}&\\ \hline \attr{xlink:type}& \parbox{0.6\textwidth}{Fixed equal to simple here.}\\ \hline \end{tabular} \end{table} If this procedure yields two values for a single \attr{utype}, the result is undefined, but a \attr{utype} generating program {\em should} raise an error. This means the STC-X instance documents containing, e.g., multiple generic coordinate systems or multiple area specifications cannot be serialized to \attr{utype}s using this algorithm. We believe this is acceptable for the purpose addressed in this note; generic coordinates are not supported by the mechanism defined here anyway. A (non-normative) XSLT style sheet generating such sequences is available from http://vo.ari.uni-heidelberg.de/docs/utypes.xsl \subsection{AstroCoordSystem groups} An AstroCoordSystem group contains a sequence of \elem{INFO} elements. These give, through their \attr{utype} and \attr{value} attributes, the \attr{utype}/value pairs obtained by serializing the AstroCoordSystem node of an STC DOM using the recipe given in section~\ref{valuty}. If the generating STC-X element for an \elem{INFO} has \attr{ucd} and/or \attr{unit} attributes, these \emph{should} be present on the \elem{INFO} element. If the value correspoding to a \attr{utype} is a \elem{FIELD} reference, it is \emph{not} added to the AstroCoordSystem group. \elem{FIELDref}s are \emph{not} allowed here since the group could be used to define a table that does not contain the referenced \elem{FIELD}. Instead, any such \elem{FIELDref}s would go into the table's appropriate AstroCoords group. Since the coordinate system(s) usually do not change between catalog rows, such constructs are expected to be rare. Implementations not supporting \elem{FIELDref}s with coordinate system \attr{utype}s should, however, emit user-readable diagnostics when encountering them. Any \elem{INFO} element obtained in the specified way may be omitted on output. On parsing, the rules on handling unknown properties stated in [2] apply. An AstroCoordSystem group \emph{must} have an \attr{ID} and an attribute \stcutype{AstroCoordSystem}. An AstroCoordSystem group \emph{should} have an \elem{INFO} element with \stcutype{} and a value of the XML namespace URI of the data model used. It is recommended to only use one version of the data model in any given VOTable, even when multiple AstroCoordSystem groups are present. Clients are \emph{may} ignore such \elem{INFO} elements but \emph{should} preserve them when writing VOTables. A special case for many applications is the use of coordinate systems from the STC library [2]. By the rules laid out above, they yield AstroCoordSystem groups just containing the version declaration and the reference. See Example \ref{example1} below. \begin{table}[htbp] %\begin{center} \ifhtx\label{tab:STClib}\begin{tabular}{|lp{0.7\textwidth}|} \multicolumn{2}{c}{Common systems defined in the STC library; to obtain valid values for \utype{AstroCoordSystem.href}, prepend {\tt ivo://STClib/CoordSys\#} }\\ \else\caption{\label{tab:STClib} {Common systems defined in the STC library; to obtain valid values for \utype{AstroCoordSystem.href}, prepend {\tt ivo://STClib/CoordSys\#}}} \begin{tabular}{|lp{0.65\textwidth}|}\hline\fi {\tt TT-ICRS-TOPO} & Terrestrial time reported at local place, ICRS orientation of axes with origin at local place\\ {\tt TT-FK5-TOPO} & As TT-ICRS-TOPO, but in FK5 system at Equinox J2000.0 \\ {\tt UTC-ICRS-TOPO} & Universal Coordinated Time reported at local place, ICRS orientation of axes with origin at local place\\ {\tt UTC-FK5-TOPO} & As UTC-ICRS-TOPO but in FK5 system at Equinox J2000.0 \\ {\tt TT-ICRS-GEO} & Terrestrial time reported at center of Earth, ICRS orientation of axes with origin at center of Earth \\ {\tt TT-FK5-GEO} & As UTC-ICRS-TOPO, but in FK5 system at Equinox J2000.0 \\ {\tt UTC-ICRS-GEO} & Universal Coordinated Time reported at center of Earth, ICRS orientation of axes with origin at center of Earth \\ {\tt UTC-FK5-GEO} & As UTC-ICRS-GEO, but in FK5 system at Equinox J2000.0 \\ {\tt TDB-ICRS-BARY} & Barycentric Dynamical Time reported at Solar System Barycenter, ICRS orientation of axes with origin at Solar System Barycenter \\ {\tt TDB-ECLIPTIC-BARY} & Barycentric Dynamical Time reported at Solar System Barycenter, along the Ecliptic axes (the equinox has to be specified) \\ \hline\end{tabular} %\end{center} \end{table} \subsection{AstroCoords groups} \label{coordinates} %\item The AstroCoords group contains a representation of the \elem{AstroCoords} and \elem{AstroCoordArea} elements of an STC specification. While it can contain utype/value pairs in \elem{INFO}s like an AstroCoordSystem group, it will typically mainly contain a sequence of \elem{FIELD\-ref} or \elem{PARAMref} elements giving STC utypes in their \attr{utype} attribute and referencing the corresponding \elem{FIELD}s through their \attr{ID}s. An AstroCoords group \emph{must} have a \stcutype{AstroCoords}. An AstroCoords group \emph{must} define a coordinate system using a \attrval{ref}{{\rm\em coordSys\_name}} attribute, where {\rm\em coordSys\_name} is the \attr{ID} assigned in the corresponding AstroCoordSystem group defined above; The epoch is not part of the STC data model in version 1.30. It will be present in future versions. Until these versions are adopted by the IVOA, for epochs on positions use \stcutype{AstroCoords.Position.Epoch}. The value in an \elem{INFO} element must be of VOTable type astroYear (i.e., it has a form like B1950 or J2000.0). You can also use the \attr{utype} in a \elem{FIELDref} or a \elem{PARAMref}; in this case, time scale, reference position, etc., can be defined using standard STC mechanisms. %\end{enumerate} It is quite possible to have several groups of coordinates in a single table, either in a common system (a common value of the \attr{ref} attribute of the \elem{GROUP}s having \stcutype{AstroCoordSystem}), or in several different systems (several \elem{GROUP}s with different \attr{ID} attributes). %A few examples are given below to illustrate the referencing mechanism. \section{Examples} \label{sec:examples} Three examples are given here. The first one refers to the STClib described in the Appendix C of the STC model [2]; the other two illustrate the definition of non-standard coordinate system. In all examples, we emphasize with different colors the \emstc{STC-related utypes} and the \emref{corresponding ID/ref attributes} to visualize their role in the XML output below. \subsection{List of observations} This simple example of a VOTable document lists 3 observations made with a telescope; each observation is characterized by the location (on the sky) of the CCD center, date/time of observation, and the exposure time. % % \label{example1} \iffalse% ref="\emref{ivo://STClib/CoordSys\#UTC-ICRS-TOPO}"> ref="\emref{mainFrame}"> \fi \ifhtx\Beg{tabular}{\bg{LightCyan} CELLPADDING=5}{||l||} \else\begingroup\small \fi \begin{alltt} Observation log {\ifhtx\else\small\fi }
035.0798-05.23362005-11-01T12:00:551200
035.0547-05.22532005-11-01T12:25:20600
035.0463-05.25032005-11-01T12:36:20600
\end{alltt} \ifhtx\End{tabular} \else %\caption{\label{example1}A simple VOTable example} \endgroup \fi \begin{table}[hbtp] %\begin{center} \ifhtx\label{tab:utypeucd}\begin{tabular}{|l|p{0.60\textwidth}|} \multicolumn{2}{c}{{Some common \attr{utypes} in AstroCoords groups}}\\ \else\caption{\label{tab:utypeucd} {Some common \attr{utype}s in AstroCoords groups}} \begin{tabular}{|l|p{0.60\textwidth}|}\hline\fi {\bf utype} & {\bf Comments} \\ \hline\hline \multicolumn{2}{|l|}{{\bf\emstc{stc:AstroCoords.Time}...} time components. }\\ \hline\hline \emstc{TimeInstant.ISOTime} & Date with ISO-8601 convention ({\em e.g.} \hfil {\tt 2008-10-25T12:14:15}) \\ \emstc{TimeInstant.JDTime} & Julian date, applies to e.g. a variable phenomenon ({\em e.g.} {\tt 2454765.09323})\\ \emstc{TimeInstant.TimeOrigin.JDTime} & Reference date \\ \emstc{TimeInstant.TimeOffset} & Time elapsed since the {\em TimeOrigin} \\ \hline\hline \multicolumn{2}{|l|}{{\bf\emstc{stc:AstroCoords.Position2D}...} position on the celestial sphere}\\ \hline\hline \emstc{Value2.C1} & Right ascension or longitude \\ \emstc{Value2.C2} & Declination or Latitude \\ \emstc{Error2Radius} & Error radius of the spherical position \\ \emstc{Error2.C1} & Error on the Right Ascension or Longitude \\ \emstc{Error2.C2} & Error on the Declination or Latitude \\ \hline\hline \multicolumn{2}{|l|}{{\bf\emstc{stc:AstroCoords.Velocity2D}...} proper motion on the celestial sphere}\\ \hline\hline \emstc{Velocity1D} & Total proper motion \\ \emstc{Velocity2D.C1} & Proper motion in RA or Longitude \\ \emstc{Error2.C1} & Error on a proper motion in RA or Longitude \\ \hline\hline \multicolumn{2}{|l|}{{\bf\emstc{stc:AstroCoords.Position3D}...} position in a 3-D spherical system, as in \Aref{example3}{example 3}} \\ \hline\hline \emstc{Value3.C1} & Ecliptic longitude \\ \emstc{Value3.C2} & Ecliptic latitude \\ \emstc{Value3.C3} & Distance to solar system barycenter \\ \hline \end{tabular} %\end{center} \end{table} \subsection{Extract of the Hipparcos catalog} The Hipparcos catalog is the primary realization of the International Celestial Reference System (ICRS) for optical wavelengths. Its positions and proper motions are given for the epoch J1991.25 (roughly the mid-point of the mission). The astrometric frame is barycentric (the barycenter of the Solar system is assumed to be the origin of the frame); and the times used throughout the Hipparcos catalog (for the {\em epoch photometry}) is the geocentric terrestrial time [3]. % % \label{example2} \ifhtx\Beg{tabular}{\bg{LightCyan} CELLPADDING=5}{||l||} \else\begingroup\small \fi \begin{alltt} The original Hipparcos catalogue uses different origins for spatial (barycentric) and temporal (geocentric) components. \emcom{} \emcom{} \emcom{} \emcom{} A (tiny) excerpt from the Hipparcos catalog \emcom{} Identifier (HIP number) (H1) Magnitude in Johnson V (H5) alpha, degrees (ICRS, Epoch=J1991.25) (H8) delta, degrees (ICRS, Epoch=J1991.25) (H9) ? Trigonometric parallax (H11) Proper motion mu\_alpha.cos(delta) ICRS(H12) (for J1991.25 epoch) ? Proper motion mu\_delta, ICRS (H13) (for J1991.25 epoch) Standard error in Plx (H16) {\ifhtx\else\small\fi }
19.100.000911851.08901332 3.54-5.20-1.881.39
29.270.00379737-19.49883745 21.90181.21-0.933.10
36.610.0050079538.85928608 2.815.24-2.910.63
48.060.00838170-51.89354612 7.7562.850.160.97
58.550.00996534-40.59122440 2.872.539.071.11
\end{alltt} \ifhtx\End{tabular} \else \endgroup \fi \begin{table}[hbtp] %\begin{center} \ifhtx\label{tab:commonvalues}\begin{tabular}{|ll|} \multicolumn{2}{c}{Some common utypes and typical values for \attr{utype}s in AstroCoordSystem groups}\\ \else\begin{center} \caption{\label{tab:commonvalues} {Some common utypes and typical values for \attr{utype}s in AstroCoordSystem groups}} \begin{tabular}{|l|l|}\hline\fi \multicolumn{2}{|l|}{\label{tab:timescale} Common values for \emstc{stc:AstroCoordSystem.TimeFrame.TimeScale}}\\ \hline {\tt TT} & Terrestrial time \\ {\tt TAI} & Temps Atomique International \\ {\tt UTC} & Coordinated Universal Time \\ {\tt TDB} & Barycentric Dynamical Time \\ {\tt LST} & Local Sideral Time\\ {\tt LOCAL}& Local definition \\ \hline \multicolumn{2}{|l|}{\label{tab:timescale} Common values for \emstc{stc:AstroCoordSystem.*.ReferencePosition}}\\ \hline {\tt TOPOCENTER} & local position (generally on the Earth surface) \\ {\tt GEOCENTER} & center of Earth \\ {\tt HELIOCENTER} & center of Sun \\ {\tt BARYCENTER} & barycenter of the Solar System \\ {\tt LSR} & Local Standard of Rest \\ {\tt GALACTIC\_CENTER} & center of our Galaxy \\ \hline \multicolumn{2}{|l|}{\label{tab:timescale} Common values for \emstc{stc:AstroCoordSystem.SpaceFrame.CoordFlavor}}\\ \hline {\tt SPHERICAL} & Spherical coordinates, 2-D (2 angles) and 3-D(additional distance) \ifhtx\br\else\\ & \fi {\em(\emstc{coord\_naxes} required for 3-D)}\\ {\tt CARTESIAN} & Cartesian frame \\ {\tt POLAR} & Longitude + polar distance \\ \hline \multicolumn{2}{|l|}{\label{tab:timescale} Common values for \emstc{stc:AstroCoordSystem.SpaceFrame.SpaceRefFrame}}\\ \hline {\tt ICRS} & International Reference System\\ {\tt FK5} & Equatorial frame based on FK5 (default equinox J2000)\\ {\tt FK4} & Equatorial frame based on FK4 (default equinox B1950)\\ {\tt ECLIPTIC} & Ecliptic frame (default equinox J2000)\\ {\tt GALACTIC} & (New) Galactic frame\\ {\tt SUPER\_GALACTIC} & Local Group \\ {\tt J2000} & Equatorial on FK5, Equinox=J2000 \\ {\tt B1950} & Equatorial on FK4, Equinox=B1950\\ \hline\end{tabular} \ifhtx\else\end{center}\fi \end{table} \subsection{Ephemeris of a Comet} This example gives the position of the comet 125P as a function of time. Notice that the planetary model used is specified by an \elem{INFO} element having \stcutype{AstroCoordSystem.SpaceFrame.ReferencePosition.Pla\-ne\-ta\-ry\-Ephem} % % \label{example3} \ifhtx\Beg{tabular}{\bg{LightCyan} CELLPADDING=5}{||l||} \else\begingroup\small \fi \begin{alltt} \emcom{} \emcom{} \emcom{} Ephemeris of comet 125P in July 2007 Date UTC alpha, degrees delta, degrees Distance from geocenter Visual magnitude {\ifhtx\else\small\fi }
2454284.0180.1745177+10.2710289 1.46882572517.06
2454286.0181.2970157+09.8077289 1.47679882917.07
2454288.0182.4335757+09.3344139 1.484770578 17.09
2454290.0183.5839061+08.8513908 1.49275003317.11
2454292.0184.7477408+08.3589893 1.50074524217.13
\end{alltt} \ifhtx\End{tabular} \else %\caption{\label{example1}A simple VOTable example} \endgroup \fi %\clearpage \section{Usage Notes} Since most constructs available in the STC data model can be expressed using the mechanism proposed here, STC specifications may become quite complex. It is thus to be expected that most VOTable clients will only implement a subset of the functionality described here and in [2]. We recommend that writers at least support writing (multiple) AstroCoords groups with STC library references and \elem{FIELDref}s to time coordinates, their errors, space coordinates, their simple component-wise errors, the derivatives (proper motion, radial velocity) of the space coordinates and simple component-wise errors of those. With readers, the situation in less clear since STC information might be completely ignorable for some purposes, crucial in others. Software targeted beyond personal use should, however, at least support the retrieval of utype/value pairs belonging to each \elem{FIELD} together with some sort of token giving what AstroCoords group a field \elem{FIELD} is described by\footnote{the -- legal -- case of a \elem{FIELD} being used in multiple AstroCoords groups can be ignored on this level} and, of course, the role it plays within these AstroCoords. This can be implemented with a reasonable effort and gives more specialized clients a fair chance to extract relevant information. Table~\ref{tab:utypeucd} gives a list of roles that one will likely encounter. Table~\ref{tab:commonvalues} gives some \attr{utype}s and common values as encountered in AstroCoordSystem groups. %\clearpage \section{History and Modifications} \begin{itemize} \item Version 1.0 (2008-09-10) to 1.01 (2008-10-18): \begin{itemize} \item the reference to STC-Lib definitions in the form \attrval{ref}{ivo://STC\-lib/CoordSys\#UTC-ICRS-TOPO} was removed (not conforming to the {\em ID/IDref} XML definitions). The \elem{PARAM} with the \\ \stcutype{AstroCoordSystem.coord\_system\_id} is used instead (\Aref{example1}{example 1}) \item the \elem{PARAM} element with \stcutype{AstroCoordSystem.coord\_sys\-tem\_id} is reserved for {STC-Lib} standard values; these parameters were removed from examples in \Aref{example2}{example 2} and \Aref{example3}{example 3}. \item specification of coordinate components (\Aref{spec}{section 4}) was partly rewritten. \end{itemize} \item Version 1.01 (2008-10-18) to 1.02 (2008-10-30): cosmetics \item Version 1.02 (2008-10-30) to 1.1 (2009-06-12): \begin{itemize} \item explicitation of how to specify the epoch of coordinates (section \Aref{coordinates}) \item recommendation to write the coordinate definitions {\em before} referencing them (section \Aref{spec}{4}). \item usage of \attrval{xtype}{iso8601} in \Aref{example1}{example 1} \end{itemize} \item Version 1.9 (2010-01-10) \begin{itemize} \item Use \elem{INFO} rather than \elem{PARAM} elements to encode utype-value-pairs (they do not need artificial names, and we do not need type information any more) \item Define utypes and values in terms of the STC-X serialization. \item Remove second-level groups within AstroCoordSystem (there can be only one of each anyway). \item Define the value of AstroCoords.PositionEpoch in terms of VOTable's astroYear; in consequence, remove AstroCoords.Position.Epoch.Scale \item Move stclib references into AstroCoordSystem.href. \end{itemize} \end{itemize} \section{References} \noindent [1] Fran\c cois Ochsenbein, et al. VOTable Recommendation \\ \hspace*{1em} http://ivoa.net/Documents/latest/VOTable.html \noindent [2] Arnold Rots Space-Time Coordinate Metadata for the Virtual Observatory (v1.30) \\ \hspace*{1em} http://ivoa.net/Documents/latest/STC.html \noindent [3] {\em The Hipparcos and Tycho Catalogues}, ESA SP1200 June 1997, Vol.1, section 1.2 (also available in \A{http://cdsarc.u-strasbg.fr/ftp/cats/I/239/version_cd/docs/vol1/sect1_02.pdf} {PDF}) \noindent [4] Arnold Rots STC-X: Space-Time Coordinate (STC) Metadata XML Implementation \\ \hspace*{1em} http://www.ivoa.net/Documents/latest/STC-X.html %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% A P P E N D I C E S %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\ifhtx\par\thickrule\par\Beg{tabular}{\bg{LightBlue} CELLPADDING=5}{l}\quad %\else\clearpage\fi %\appendix %\noindent {\bf\LARGE Appendices} %\ifhtx\End{tabular}\fi \end{document}