SODA, section 4.3
François Bonnarel
francois.bonnarel at astro.unistra.fr
Wed Nov 9 16:58:47 CET 2016
Dear all,
One single point for today.
Le 08/11/2016 à 15:50, Markus Demleitner a écrit :
> Dear Colleagues,
>
> I'm sorry to open up this painful chapter again, but while doing a
> review of the SODA PR with a view to implement it, I was dismayed by
> several aspects of section 4.3 (which is SODA in Datalink and
> therefore what I really care about).
>
> (1) I don't think the discussion of the various ways a DAL
> response might convey datalink URLs helps the discussion of SODA. On
> the contrary, I'd say it is confusing and should be removed; this is all
> of 4.3 up to "normally use a single or small number of ID(s) per
> invocation."
>
> Instead, by way of introduction, I think
>
> The alternative scenario has the discovery service return Datalink
> documents (see \citep{std:Datalink} for ways to do that). These
> Datalink documents can then contain one or more SODA descriptor(s),
> most typically one per dataset described. To allow SODA clients
> the inference of parameter ranges and the presentation of useful
> user interfaces, data providers SHOULD communicate the admissable
> ranges of the parameters in question using the VOTable
> \xmlel{VALUES} element.
>
> (2) This should be followed by a halfway formal definition of how
> this should be done. Just giving an example is not good enough and
> will lead to endless interoperability problems. Even worse, the
> example for BAND is against the expectation a normal VOTable user
> will have; it's suggesting <MAX value="300.0e-9 800.0e-9"/> where, I
> claim, most everyone would expect
> <MIN value="300.0e-9"/>
> <MAX value="800.0e-9"/>
>
> It's bad enough that we have the ugly hacks for CIRCLE and POLYGON,
> let's not uglify VOTable where we don't absolutely need to. Also, in
> the example DESCRIPTIONs are missing -- these are important, in
> particular further down the road when people have custom parameters.
>
> So, I'd suggest to take out the rest of 4.3, too, and to then continue:
>
> For float-valued intervals (e.g., the standard BAND and TIME
> parameters), \xmlel{VALUES/MIN} and \xmlel{VALUES/MAX} are used to
> communicate the range of values for which clients can expect to
> receive data. Example:
>
> \begin{lstlisting}[language=XML]
> <PARAM name="BAND" unit="m" ucd="em.wl"
> datatype="double" arraysize="2"
> xtype="interval" value="">
> <DESCRIPTION>The wavelength intervals to be extracted</DESCRIPTION>
> <VALUES>
> <MIN value="3e-7"/>
> <MAX value="8e-7"/>
> </VALUE>
> </PARAM>
> \end{lstlisting}
>
> Enumerated values, both for integeral and textual types, use
> \xmlel{VALUES/OPTION} elements unless there are too many possible
> values. Again, only values for which nonempty responses can be
> expected for the described dataset should be listed. Example:
>
> \begin{lstlisting}[language=XML]
> <PARAM name="POL" ucd="meta.code;phys.polarization"
> datatype="char" arraysize="*" value="">
> <DESCRIPTION>Polarization states to be extracted.</DESCRIPTION>
> <VALUES>
> <OPTION>I</OPTION>
> <OPTION>V</OPTION>
> </VALUE>
> </PARAM>
> \end{lstlisting}
>
> In case the option enumeration becomes too large, the descirption
> of the parameter should carefully describe what values are
> admissable, e.g., by providing a link to an enumeration in the
> \xmlel{DESCRIPTION}.
>
> Intervals of integers are described analogous to float-valued
> intervals, i.e., using \xmlel{MIN} and \xmlel{MAX} elements.
>
> Standard VOTable semantics are insufficient for the metadata of
> the SODA POLYGON and CIRCLE parameters. We therefore define
> special cases.
>
> For CIRCLE, only a \xmlel{MAX} is given. It contains three
> floating point values, separated by whitespace. These correspond
> to the RA and Dec of the center of a spherical circle covering the
> dataset, and a radius of such a covering circle. Data providers
> SHOULD make sure they choose the center and radius such that the
> covering circle is close to the minimal one of the dataset.
> Example:
>
> \begin{lstlisting}[language=XML]
> <PARAM name="CIRCLE" unit="deg" ucd="phys.angArea;obs"
> datatype="double" arraysize="3"
> xtype="circle" value="">
> <DESCRIPTION>A spherical circle to be contained by the cutout</DESCRIPTION>
> <VALUES> <MAX value="12.0 34.0 0.5"/> </VALUES>
> </PARAM>
> \end{lstlisting}
>
> For POLYGON, again only a \xmlel{MAX} is given. It consists of
> a sequence of floating-point values, again separated by blanks,
> describing RA and Dec of the vertices of a spherical polygon
> covering the dataset. Data providers are encouraged to choose a
> minimal polygon. Example:
>
> \begin{lstlisting}[language=XML]
> <PARAM name="POLYGON" unit="deg" ucd="phys.angArea;obs"
> datatype="double" arraysize="*"
> xtype="polygon" value="">
> <DESCRIPTION>A polygon to be contained by the cutout</DESCRIPTION>
> <VALUES>
> <MAX value="11.5 33.5 12.5 33.5 12.5 34.5 11.5 34.5"/>
> </VALUES>
> </PARAM>
> \end{lstlisting}
>
> Angles in both CIRCLE and POLYGON are in degrees. As in the input
> the ICRS reference system is assumed.
>
> For POS, useful metadata cannot be given. Services supporting POS
> should therefore provide POLYGON as well, and clients wishing to
> use POS can infer sensible values for that parameter from
> \xmlel{VALUES} given for POLYGON.
>
> Sorry for coming in with this now, but the
>
> <MAX value="300.0e-9 800.0e-9"/>
>
> that really shocked me only came in in July, so perhaps it's not my
> fault alone.
Well, this was proposed by Pat at the May interop and was discussed in
the SODA splinter. I remember you were reluctant but not against. So Pat
added this in the July version, indeed.
The idea is that the parameter is not a single value but an interval.
And in VOTable MIN and MAX are intended to give the range of a single
value PARAM. This is a real trick !!!
However I see that "Apps" is also complaining about this on the RFC
page. So ...
Regards
François
>
> Anyway: content-wise I claim the changes with my proposal are minimal
> (essentially, just use MIN/MAX as intended), but implementors have a
> much clearer guideline as to what to implement against.
>
> So -- can we just replace 4.3 as suggested?
>
> Cheers,
>
> Markus
More information about the dal
mailing list