A prototype for online DAL examples and model snipets

Fri Feb 5 10:20:24 CET 2016

Laurent,

On Tue, Feb 02, 2016 at 05:46:14PM +0100, Laurent Michel wrote:
> In order to give some quick references to DAL query examples, we
> have setup a service prototype available here:
> 	http://saada.unistra.fr/voexamples
> 
> This service provides a set of examples for various protocols (currently
> Obscore and VODML). Each example (or snipet) has 4 sections (in plain text
> right now):
> - title
> - description
> - query (ADQL, XML....)
> - usage (how to run the example).
> 
> We identified 2 use cases:
> 1) Human users can browse the Web site to access individual examples. In this case, all sections are gathered on a single page.
> A keyword search may be implemented later.
> 
> 2) For software clients, each of these items can be consumed to build up a contextual help facility.
> Below is an example of an URL returning the "query" section of the "Composition" feature in "VODML".
> 	http://saada.unistra.fr/voexamples/vosi/vodml/Composition/query
> Whereas the following URL
> 	http://saada.unistra.fr/voexamples/vosi/obscore/usecase1.1
> returns a whole example as an XHTML page compliant with the VOSI examples specification.
> 
> Please, try it out and contribute with your comments and feedback.

Well, the original plan for DALI-examples was  that the examples all
reside on one page (or at least on very few pages, linked pages), as
in, for instance, http://dc.g-vo.org/tap/examples.  This lets a
client (TOPCAT already does this) simply pull the whole thing in and
build the service-provided examples (try a recent TOPCAT on GAVO's
TAP service and check out the examples menu).

Having a central page with obscore examples would be particularly
useful with DALI's continuation property.  Sites having obscore
could then, on their examples endpoint, just include

  <p>See also
  <a href="http://saada.unistra.fr/voexamples/vosi/obscore"
    property="continuation">Generic examples for ivoa.obscore</a></p>

and thus pull in all your examples.

The intention also was that there should be no need for having
separate files for DALI examples and "human" reading.  What made you
provide separate URLs?

As to the actual examples, for instance,
http://saada.unistra.fr/voexamples/vosi/obscore/usecase1.5 -- I'm
missing the RDFa annotation as per DALI -- is that an oversight?
Also, just as a matter of taste, I'd much prefer using proper markup
rather than pre in the explanatory text.  So, for that example I'd
write something like:

  <body vocab="ivo://ivoa.net/std/DALI#examples">
  <div id="usecase1.5" resource="#usecase1.5" typeof="example">
    <h2 property="name">Searching Quasars using Obscore</h2>
      <p>To locate science-ready datasets having spatially resolved
      spectra of high-redshift quasars, one could constrain matches in 
      <span property="table">ivoa.obscore</span> as follows:</p>

      <ul>
        <li>data type = IFU</li>
        <li>data quality: fully calibrated</li>
        <li>object class: quasar</li>
        <li>redshift > 3</li>
        <li>radio flux > 1 mJy</li>
      </li>

      <p>In a first step, you would get a set of appropriate positions
      from an appropriate service.  A good source, obviously, is SIMBAD
      (TAP access URL
      <code>http://simbad.u-strasbg.fr:80/simbad/sim-tap</code>).
      There, you could execute
      <pre>
  SELECT target_name AS name,coordsys,ra,dec FROM SomeObjectCatalog
  WHERE target_class = 'quasar'
    AND redshift >= 3.0
    AND flux_radio > 1.0</pre>

      <p>On this obscore service, you would then run:</p>

  <pre property="query">
  SELECT q.Name,q.ra_RAJ2000,q.dec_DEJ2000,o.*
  FROM TAP_UPLOAD.t1 AS q JOIN ivoa.ObsCore AS o
    ON CONTAINS(POINT('ICRS',q.ra_RAJ2000, q.dec_DEJ2000), o.s_region) = 1
  WHERE o.dataproduct_type = 'cube'
    AND o.calib_level >= 2
    AND (o.em_max - o.em_min)/o.em_res_power > 100
  </pre>

  <p>-- where you will have to adapt "TAP_UPLOAD.t1" to the conventions
  and the state of your TAP client.</p>

  </div>
  </body>

I'd maintain that's much more human- *and* machine readable.  The
"table" and "query" properties used here come for the TAP
implementation note and will be documented in TAP 1.1 (Pat -- is that
true?).

A good way to see if your document is machine-readable is to let a
machine read it; you can use TOPCAT for that for TAP examples.
Generically, the W3C RDFa validator is a good choice:

http://www.w3.org/2012/pyRdfa/Validator.html

If you run it on http://dc.g-vo.org/tap/examples you'll see the
machine can actually figure out the various examples given there.

Incidentally, don't worry about the warning about "Unusual URI
scheme" that that validator will give for DALI examples documents --
I'm afraid it'll be some time until ivo: won't be considered an
unusual URI scheme any more :-)

Cheers,

           Markus