Timesys note review

[Mark Taylor]

On Tue, 27 Nov 2018, Markus Demleitner wrote:

> TOPOCENTER
>    +------- EARTH_SURFACE
>    |             +-------------- LA_SILLA
>    |             +-------------- MAUNA_KEA
>    |             `-------------- CAMBRIDGE_UK
>    +------- LEO
>    |         +------------ ISS
>    |         `------------ ROSAT
>    `------- EARTH_L2
>                 +------------ GAIA
>                 `------------ JWST
> 
> and so on.  If a client happens to know MAUNA_KEA, it can use a proper
> transformation.  If not, it can *from the vocabulary* (i.e., from a
> resource maintained by "us") figure out that it's EARTH_SURFACE and that
> it therefore has to bump the systematic error by 25 ms.  If it
> doesn't know about EARTH_SURFACE, it can still figure out that the
> times are TOPOCENTER and that it should be careful.

That looks neat.
 
> On Thu, 1 Nov 2018 15:37:14 -0400, Arnold Rots <arots at cfa.harvard.edu> wrote:
> > I maintain that the better way to indicate the actual time stamp value
> > (i.e., not the TIMESYS) is to use well established representations.
> > Both JD and MJD are officially recognized by the IAU, while the limited
> > ISO-8601 is a convenient user-friendly representation that has the blessing
> > of the ISO.
> > [...]
> > So, I would suggest adding to TIMESYS an attribute like
> > origintype=JD|MJD|ISO and to the timestamp an attribute like
> > timetype=JD|MJD|ISO|ELAPSED and requiring the timeorigin and the unit only
> > to be present for timetype=ELAPSED.
> 
> JD, MJD, fractional years and much more are, in essence,
> *presentations*, i.e., what a client or a library exposes to its
> user.  I totally agree that for most clients, it is highly desirable
> to offer "Display in JD", "Display in MJD", and "Display as civil
> date" (and probably much more).
> 
> For a transport or annotation format, on the other hand, it is highly
> desirable to (a) avoid equivalent representations -- each equivalent
> representation is a source of bugs you get nothing for.  And it's
> important to (b) avoid conflicts of responsibility between various
> layers wherever possible.

I don't know if I buy (a).  It can, sometimes, get you readability.
See below.

> So, TIMESYS gives time *metadata*.  It therefore has no business
> declaring serialisation formats (such as whether the time is written as
> an ISO string or a fractional year) – in VOTable, we already have FIELD
> attributes for that (datatype, arraysize, unit, and xtype), and they
> do a reasonably good job at it.
> 
> Trying to second-guess that FIELD metadata in a different VOTable
> element would violate rule (b); all you get are more ways to write
> invalid VOTables: It doesn't let us write anything valid in addition
> to what we already can write.
> 
> Defining some special annotation for timeorigin=0 and
> timeorigin=2400000.5 then violates rule (a) -- it just introduces
> different ways to express the same semantics.  
> 
> With these two equivalent representations you open a can of
> unpleasant questions: how should a client decide whether to
> annotate an MJD column with <TIMESYS origintype="MJD"> or with
> <TIMESYS timeorigin="2400000.5">?  Should the second form be
> outlawed?  What happens if a client encounters that declaration?

(clearly, the second form should not be outlawed)

> So, while giving choice on the presentation layer certainly is a good
> idea (and I'd be open to recommending certain patterns to client
> writers), choice on the transport layer is an implementation
> liability and therefore better avoided.  Since it seems that
> timeorigin is enough to cover all cases that were mentioned, I've not
> changed the TIMESYS model in the note-1.1 draft.

Well yes, but really, MJD and JD are so frequently used that I'd
be inclined to bend the odd rule of data representation good
practice to accommodate them.  I don't like the suggested
timetype and origintype attributes because they introduce messy
logic in the definition and parsing, but how about just defining
"MJD" and "JD" (any others?) as aliases for "2400000.5" and "0"
respectively.  Of course this means you have to redefine the type
of the timeorigin attribute from "xs:double" to "xs:token" or
similar, which weakens the checking that XSD validation can do
here, but my guess is that it's likely to be more than outweighed
by avoiding validation-proof typos like timeorigin="240000.5",
not to mention the convenience and readability.
If clients come across something which is neither a double nor
one of the known aliases in the timeorigin attribute, they just
have to treat it as an error.

So then the examples in the document would become

   <TIMESYS ID="gaia_frame" refposition="BARYCENTER" timeorigin="JD"
            timescale="TCB"/>

and

   <TIMESYS refposition="TOPOCENTER" timescale="TT" timeorigin="MJD"
            ID="_MJD"/>

while e.g. the Gaia epoch photometry available from
http://geadata.esac.esa.int/data-server/data?RETRIEVAL_TYPE=epoch_photometry
could write:

   <TIMESYS refposition="BARYCENTER" timescale="TCB" timeorigin="2455197.5"
            ID="whatever"/>

And probably a large proportion of real life usages would look like
one of the first two examples above and not like the third one.

Somewhat related: I think the discussion of the timeorigin attribute
in section 2 should be tightened up a little bit, so it's clear that
a value MUST be present for non-year-like time values as well as
saying that it MUST NOT be present for calendar-year-like values.

So, I'd suggest something like:

   \item[\xmlel{timeorigin}] This is the time origin of the time coordinate,
   which MUST be present when the time value being annotated represents
   an interval elapsed from an origin, such as MJD.
   When present, the timeorigin represents a Julian Date for the time scale
   and reference point defined, and is given
   {\em either\/}
   as a floating point value formatted as for type \xmlel{xs:double},
   {\em or\/}
   as one of the special tokens "JD" (equivalent to "0")
   or "MJD" (equivalent to "2400000.5").
   If the time value being annotated represents an absolute date,
   this attribute MUST NOT be present.
   In VOTables, absolute date representations
   currently are Gregorian calendar years with
   xtype="timestamp", or values with units of "yr", "a" or "Ba"
   understood to be in the Julian or Besselian calendar.\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 absolute date
   representations.

... but no objection to rewriting it for reasons of correctness,
clarity or style.

Mark

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/