\documentclass[11pt,a4paper]{ivoa}
\usepackage{todonotes}
\input tthdefs

\newenvironment{widedescription}[1][0pt]
  {\list{}{\labelwidth=0pt \addtolength{\leftmargin}{-0.5cm}%
    \addtolength{\rightmargin}{-0.5cm}%
   \let\makelabel\descriptionlabel}}
  {\endlist}

\lstloadlanguages{XML}
\lstset{flexiblecolumns=true,tagstyle=\ttfamily,
showstringspaces=False,basicstyle=\footnotesize}

\title{A Proposal for a TIMESYS Element in VOTable}

% see ivoatexDoc for what group names to use here
\ivoagroup{Time Domain}

\author{Demleitner, M.}
\author{Nebot, A.}
\author{Bonnarel, F.}
\author{Michel, L.}
\author{Fernique, P.}
\author{Boch, T.}

\editor{Markus Demleitner}

\previousversion[http://ivoa.net/documents/Notes/TimeSys/20181029]{Version
1.0 (2018-10-29)}
       

\begin{document}
\begin{abstract}
Interoperability for data sets containing time-valued data requires
the unambiguous declaration of certain pieces of metadata for that data,
in particular the declaration of the time scale used and the reference position
for which a time is given.  This note proposes a simple means to
furnish times in VOTables with the necessary metadata.  It is not
intended to replace efforts on full STC annotation using an
IVOA-approved data model, but rather to supplant it with an easily
implemented and agreed-upon mechanism until the advanced technologies
are sufficiently defined and adopted.
\end{abstract}

\section*{Acknowledgments}

Parts of this document were developed within the Horizon 2020 project
ASTERICS (grant agreement number 653477).  
We gratefully acknowlege valuable input
on current time scale definitions and issues with historical time scales
by Steve Allen (Lick Observatory).


\section*{Conformance-related definitions}

The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.

The \emph{Virtual Observatory (VO)} is a
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
The \href{http://www.ivoa.net}{International
Virtual Observatory Alliance (IVOA)} is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications.


\section{Introduction}

\subsection{History}

While simple metadata of spatial coordinates could be declared in
VOTables since before the first version of the standard
\citep{2004ivoa.spec.0811O} using the COOSYS element, the declaration of
metadata of temporal coordinates was deferred to a comprehensive data
model for space-time coordinates (STC).  However, neither the data model
\citep{2007ivoa.spec.1030R} nor the mechanism annotate VOTables with the
roles defined by it \citep{note:votstc} gained sufficient traction in
the community.  While the IVOA community works towards replacing both
the data model (``STC2'') and the annotation mechanism (``VODML
mapping''), the timescale for the wide adoption of these technologies is
unclear.

In effect, there currently (late 2018) is no widely accepted standard
for the association of time-valued columns in VOTables with its system
metadata.  Several proposals have been brought up by various parties.
This note formalises one of
them and will be compatible with all of them in the sense that the
annotation proposed here will not conflict with further annotation.

\subsection{Use Case and Scope}

The basic interoperability use case for time series and similar data
products in the VO is the combination of two time series.  This requires
bringing the two time coordinates into a common frame as regards time
scales (e.g., UTC, TT, TDB) and reference positions (e.g., the
instrument, the center of the Earth, the barycenter of the solar system,
or perhaps even the Galactic center).  Neglecting such metadata
typically leads to errors of the order of a few tens of seconds in the
case of the time scales (e.g., leap seconds or relativistic effects) or
of a few minutes in the case of reference positions, although
conceptually it might as well be tens of kiloyears if the Galactic
center were allowed as a reference position.

An additional important piece of metadata is the time origin of the time
scale (also called the ``epoch'', but since that term has a quite
different meaning in many fields of astronomy, its usage for a zero
point of a time scale is discouraged
in VO contexts).  For instance, the time origin of the Modified Julian
Date (MJD) that is in wide use in the VO is 2400000.5 in Julian Date,
whereas the time origin of the common Unix times is 1970-01-01T00:00:00
UTC.  Other time origins are in wide use, either for added precision or
for convenience.

Hence, this proposal covers the declaration of

\begin{compactenum}
\item the time scale
\item the reference position, and
\item the time origin
\end{compactenum}

for any temporal quantity in VOTables, whether stored in a table column
(which means the annotation of FIELDs) or as a single value in a PARAM.

The proposal is \emph{not} concerned with time representations; the
distinction between times given as a floating point value (e.g., JD, julian or besselian years,
unix times) and as civil dates is already effected by VOTable and the
DALI \emph{timestamp} xtype \citep{2017ivoa.spec.0517D}.  If further
time representations ever appeared desirable (e.g., SOFA's
high-precision times stored in two double precision floating-point
values), they would probably be described with further xtypes in DALI.

This proposal also does \emph{not} talk about units, which are
sufficiently covered by the existing VOTable standard 
\citep{2013ivoa.spec.0920O} and the ancillary VOUnits standard
\citep{2014ivoa.spec.0523D}.  As long as these standards are followed,
no interoperability problems are forseen regardless of whether times are
given in years, days, seconds or any derivation of them.

\section{A TIMESYS Element}

To cover the use cases outlined above, we propose to introduce a new
VOTable element, TIMESYS.  It is allowed whereever COOSYS is and would
reside lexically behind COOSYS definitions if these are present.  
Multiple TIMESYS
elements are allowed (and are, indeed, even necessary in several
applications).

In keeping with the pattern set by COOSYS, FIELDs (and possibly PARAMs)
SHOULD reference the TIMESYS giving their frame using the VOTable
\xmlel{ref} attribute; absent such a \xmlel{ref}, readers SHOULD assume
the lexically first TIMESYS element in the VOTable to be pertinent for
time-like quantities.

We note in passing that moving to an annotation pattern in which TIMESYS
references FIELDs and PARAMs would be preferable and, indeed, is
possible by adding an reference-valued attribute to TIMESYS.  We do not
propose this at this point because this would introduce an asymmetry
between COOSYS and TIMESYS.

The metadata discussed above are given in attributes to the element,
specifically:

\begin{bigdescription}
\item[\xmlel{timeorigin}] This is the time origin of the time coordinate,
given as a Julian Date for the the time scale and reference point
defined.  It is usually given as a floating point
literal; for convenience, the magic strings \verb|MJD-origin| (standing
for 2400000.5) and \verb|JD-origin| (standing for 0) are also allowed.
The timeorigin attribute MUST be given unless the time's representation
contains a year of a calendar era, in which case it MUST NOT be present.  
In VOTables, these
representations currently are Gregorian calendar years with
xtype="timestamp", or years in the Julian or Besselian calendar when a column
has yr, a or Ba as its unit and no time origin is 
given.\footnote{When using calendar epochs written in yr or Ba, note
that conventionally Julian years are tied to the TDB timescale and 
Besselian years to ET (written here as TT)
\citep{2015A+A...574A..36R}.}
Future
VOTable or VOUnits versions may define other such representations.
\item[\xmlel{timescale}]  This is the time scale used.  The IVOA defines
a set of interoperable time scales.  An initial list is given in
sect.~\ref{sect:timescales}.  In the prototype, this list is hardcoded
in the schema; we believe that the list should reside in an IVOA
vocabulary in implementation both in order to attach precise meanings
and in order to allow extensions to the list without having to change
the schema.
\item[\xmlel{refposition}] The reference position again is a simple string,
with the initial set of defined values given in
sect.~\ref{sect:refposes}.  Again, while the prototype schema contains
an enumeration of the allowed values, we believe these should eventually
reside in an IVOA vocabulary.
\end{bigdescription}

The attribute names correspond to attributes of the frame type in
current drafts of the STC2 data model.

\subsection{An Initial List of Timescales}
\label{sect:timescales}

The following list of timescales, evolved from the STC 1
data model \citep{2007ivoa.spec.1030R}, reflects the terms enumerated
for the \xmlel{timescale} attribute.  It is expected that the actual
VOTable 1.4 schema will reference a vocabulary (tentatively expected to
reside at \url{http://ivoa.net/rdf/timescale}), and we will try to
provide normative references where possible.

\begin{bigdescription}
\item[TAI] (International Atomic Time) atomic time standard, ${\rm TT}-
\rm{TAI} = 32.184 {\rm s}$.
\item[TT] (Terrestrial Time; IAU standard) time measured by a
continuous clock on the surface of an ideal Earth. Defined via TCG as
having been idential on 1977-01-01 and since running slower than it by
an empirically determined factor $L_C$.  It is continuous with the
ephemeris time ET widely used before 1984-01-01; in TIMESYS, the term TT
should therefore be used for times in ET, too.
\item[UT] Earth rotation time. We do not distinguish between UT0, UT1,
and UT2; applications requiring this level of precision need additional
metadata.  This should also be used to label GMT times in datasets covering 
dates between 1925-01-01 and 1972-01-01. GMT in astronomical use before
1925 had a 12 hour offset and would require a new term.
\item[UTC] (Universal Time, Coordinated) this is TAI, with leap seconds
inserted occasionally in order to keep UTC within 0.9 s of UT1 (a
different convention was in use before 1972-01-01).
\item[GPS] (Global Positioning System) runs (approximately) synchronously with
TAI
\item[TCG] (Geocentric Coordinate Time) time measured by a clock moving
with the Earth's center but not subject to the gavitational potential of
the Earth.
\item[TCB] (Barycentric Coordinate Time) derived from TCG, but
taking into account the relativistic effects of the gravitational potential at the barycenter as well as velocity time dilation
variations due to the eccentricity of the Earth’s orbit.  See
\citet{1999A+A...348..642I} for details.
\item[TDB] (Barycentric Dynamical Time) runs slower than TCB at a constant rate
so as to remain approximately in step with TT; runs therefore
quasi-synchronously with TT, except for the relativistic effects
introduced by variations in the Earth’s velocity relative to the
barycenter.
\item[UNKNOWN] This value indicates clients cannot transform the times
reliably; this is to be used for simulated data, free-running clocks,
or data for which information on the time scale has been lost.
\end{bigdescription}

\subsection{An Initial List of Reference Positions}
\label{sect:refposes}

The following list of reference positions, evolved from the STC 1
data model \citep{2007ivoa.spec.1030R}, reflects the terms enumerated
for the \xmlel{refposition} attribute.  It is expected that the actual
VOTable 1.4 schema will reference a vocabulary (tentatively expected to
reside at \url{http://ivoa.net/rdf/refposition}), and we will try to
provide normative references where possible.

\begin{bigdescription}
\item[TOPOCENTER] The location of the instrument that made the observation
\item[GEOCENTER] The center of the earth
\item[BARYCENTER] The barycenter of the solar system
\item[HELIOCENTER] The center of the sun
\item[EMBARYCENTER] The barycenter of the Earth-Moon system
\item[UNKNOWN] The times cannot be transformed to a different reference
position reliably.  This is to be used for simulated data or for data
for which the reference position has been lost.
\end{bigdescription}


\section{Examples}

At this point, the time series available from the ivoa.obscore table on
GAVO's Heidelberg TAP service\footnote{http://dc.g-vo.org/tap} offer the
TIMESYS annotation described here.  As an example, here is a excerpt
from a time series (slightly edited for compactness):

\begin{lstlisting}[language=XML]
  <RESOURCE>
    <COOSYS ID="system" epoch="J2015.5" system="ICRS"/>
    <TIMESYS ID="gaia_frame" refposition="BARYCENTER" timeorigin="0"
      timescale="TCB"/>
    <TABLE name="ts_data">
      <FIELD ID="obs_time" datatype="double" name="obs_time" 
        ucd="time.epoch" unit="d" ref="gaia_frame"/>
      <FIELD ID="flux" datatype="float" name="flux"
        ucd="phot.flux;em.opt.V" unit="s**-1"/>
      <FIELD ID="mag" datatype="float" name="mag" ucd="phot.mag;em.opt.V" 
        unit="mag"/>
      <FIELD ID="flux_error" datatype="float" name="flux_error"
        ucd="stat.error;phot.flux;em.opt.V" unit="s**-1"/>
      <PARAM datatype="double" name="ra" 
        ucd="pos.eq.ra" value="45.7164887146879" ref="system"/>
      <PARAM datatype="double" name="dec" 
        ucd="pos.eq.dec" value="1.18583048057467" ref="system"/>
      <DATA>
        <TABLEDATA>
          <TR>
            <TD>2457018.7846388435</TD>
            <TD>168.358</TD>
            <TD>20.12281560517953</TD>
            <TD>8.71437</TD>
          </TR>
          ...
        </TABLEDATA>
      </DATA>
    </TABLE
  </RESOURCE>
\end{lstlisting}

Note that TIMESYS can also be used to annotate PARAMs.  For instance, a
common epoch, given in MJD, in a VOTable could be written like this:

\begin{lstlisting}[language=XML]
<TIMESYS refposition="TOPOCENTER" timescale="TT" timeorigin="2400000.5"
   ID="_MJD"/>
<PARAM ref="_MJD" name="epoch" datatype="double"
  value="58424.37"/>
\end{lstlisting}

\section{Implementation Aspects}

If this or a similar proposal were to be adopted by the IVOA, 
both the VOTable specification and its schema would need to be updated.
A draft schema reflecting the proposal above comes with this note and is
available from \url{http://volute.g-vo.org/svn/trunk/projects/time-domain/timesysnote/VOTable-1.4-draft.xsd}.  As mentioned
above, we believe the lists of accepted reference positions and
time scales should probably reside in vocabularies rather than the schema
in the finished specification.

At this point, there is support on the server side for the proposal 
in the DaCHS suite \citep{2014A+C.....7...27D} as
of the 1.2.1 beta.  On the client side, the maintainers of the Aladin
\citep{soft:Aladin} and SPLAT Virtual Observatory clients
have signaled they are considering an
experimental adoption.

\appendix
\section{Changes from Previous Versions}

\subsection{Changes from version 1.0}

\begin{itemize}
\item Now allowing magic strings \verb|MJD-origin| and \verb|JD-origin|
in the \xmlel{timeorigin} attribute.
\item Fixed \verb|_MJD| example (which was plain broken in 1.0).
\item Replacing UT1 timescale with UT (reviewers remarked that actual UT1 
should be extremely rare in practice).
\item Improved descriptions of a few time scales based on reviewer
feedback.
\end{itemize}

\bibliography{ivoatex/ivoabib,ivoatex/docrepo}


\end{document}
