/[volute]/trunk/projects/dal/SODA/SODA.tex
ViewVC logotype

Diff of /trunk/projects/dal/SODA/SODA.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3722 by msdemlei, Tue Nov 15 08:32:42 2016 UTC revision 3723 by msdemlei, Thu Nov 17 16:15:45 2016 UTC
# Line 851  Line 851 
851  \subsection{SODA Service Descriptor from DataLink}  \subsection{SODA Service Descriptor from DataLink}
852  \label{sec:disc-links-soda}  \label{sec:disc-links-soda}
853    
854  In the general case, data discovery responses may contain usable HTTP  The alternative scenario has the discovery service return Datalink
855  URL(s), e.g. in an Obscore \citep{std:OBSCORE} response, the  documents (see \citet{std:DataLink} for ways to do that).  These
856  \texttt{access\_url} contains a link that invokes a DataLink  Datalink documents can then contain one or more SODA descriptor(s),
857  \citep{std:DataLink} links resource and the access\_format column  most typically one per dataset described.  To allow SODA clients
858  contains the standard DataLink \citep{std:DataLink} content-type. Alternatively the  the inference of parameter ranges and the presentation of useful
859  response document may contain a service descriptor for an associated DataLink  user interfaces, data providers SHOULD communicate the admissable
860  links capability. The following example shows the second form:  ranges of the parameters in question using the VOTable
861    \xmlel{VALUES} element.
862    
863    For float-valued intervals (e.g., the standard BAND and TIME
864    parameters), \xmlel{VALUES/MIN} and \xmlel{VALUES/MAX} are used to
865    communicate the range of values for which clients can expect to
866    receive data.  Example:
867    
868  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
869  <RESOURCE type="results">    <PARAM name="BAND" unit="m" ucd="em.wl"
870  <TABLE>      datatype="double" arraysize="2"      
871    <FIELD name="obs_publisher_did" ucd="meta.ref.url;meta.curation"      xtype="interval" value="">    
872          ID="primaryID"      <DESCRIPTION>The wavelength intervals to be extracted</DESCRIPTION>
873          datatype="char" arraysize="*">      <VALUES>                                                          
874      <DESCRIPTION>The publisher identifier for the dataset</DESCRIPTION>        <MIN value="3e-7"/>
875    </FIELD>        <MAX value="8e-7"/>
876  ...      </VALUE>            
877  </TABLE>    </PARAM>  
 </RESOURCE>  
 <RESOURCE type="meta" utype="adhoc:service">  
   <PARAM name="standardID" datatype="char" arraysize="*"  
          value="ivo://ivoa.net/std/DataLink#links-1.0" />  
   <PARAM name="accessURL" datatype="char" arraysize="*"  
          value="http://example.com/srv/links" />  
   <GROUP name="inputParams">  
     <PARAM name="ID" ucd="meta.ref.url;meta.curation"  
             ref="primaryID"  
             datatype="char" arraysize="*" value=""/>  
   </GROUP>  
 </RESOURCE>  
878  \end{lstlisting}  \end{lstlisting}
879    
880  The client must call this service (with an identifier from the data  Enumerated values, both for integeral and textual types, use
881  discovery response) in order to get details about the available  \xmlel{VALUES/OPTION} elements unless there are too many possible
882  resources (files to download, related resources, and services that can  values.  Again, only values for which nonempty responses can be
883  be used to access the files). One or more of these related services can  expected for the described dataset should be listed.  Example:
 be SODA services.  
   
 In this case, the response containing the links will not include all the  
 dataset metadata necessary to determine values for SODA filtering  
 parameters. While generic service descriptors (see above) are still  
 permitted, it is much more useful if the links response contains data- or  
 file-specific service descriptors that make use of the ability to  
 include metadata in the parameter descriptions. Thus, the provider will  
 normally include one or more data-specific service descriptors for each  
 input ID, but scalability should not be a problem because clients  
 normally use a single or small number of ID(s) per invocation.  
884    
885  A data-specific SODA sync service descriptor describing the standard  \begin{lstlisting}[language=XML]
886  parameters (see~\ref{sec:parameters}) with plausible values:    <PARAM name="POL" ucd="meta.code;phys.polarization"
887        datatype="char" arraysize="*" value="">          
888        <DESCRIPTION>Polarization states to be extracted.</DESCRIPTION>
889        <VALUES>
890          <OPTION>I</OPTION>
891          <OPTION>V</OPTION>
892        </VALUE>
893      </PARAM>
894    \end{lstlisting}
895    
896    In case the option enumeration becomes too large, the descirption
897    of the parameter should carefully describe what values are
898    admissable, e.g., by providing a link to an enumeration in the
899    \xmlel{DESCRIPTION}.
900    
901    Intervals of integers are described analogous to float-valued
902    intervals, i.e., using \xmlel{MIN} and \xmlel{MAX} elements.
903    
904    Standard VOTable semantics are insufficient for the metadata of the SODA
905    POLYGON and CIRCLE parameters.  We therefore define special cases for
906    the \xmlel{xtype}s \emph{circle} and \emph{polygon} at least until such
907    time as a proper data model for space-time coordinates defines a
908    different way to communicate such coverages within VOTables.
909    
910    For CIRCLE, only a \xmlel{MAX} is given. It contains three
911    floating point values, separated by whitespace.  These correspond
912    to the RA and Dec of the center of a spherical circle covering the
913    dataset, and a radius of such a covering circle.  Data providers
914    SHOULD make sure they choose the center and radius such that the
915    covering circle is close to the minimal one of the dataset.
916    Example:
917    
918    \begin{lstlisting}[language=XML]
919    <PARAM name="CIRCLE" unit="deg" ucd="phys.angArea;obs"
920      datatype="double" arraysize="3"
921      xtype="circle" value="">
922      <DESCRIPTION>
923        A spherical circle to be contained by the cutout
924      </DESCRIPTION>
925      <VALUES> <MAX value="12.0 34.0 0.5"/> </VALUES>
926      </PARAM>
927    \end{lstlisting}
928    
929    For POLYGON, again only a \xmlel{MAX} is given.  It consists of
930    a sequence of floating-point values, again separated by blanks,
931    describing RA and Dec of the vertices of a spherical polygon
932    covering the dataset.  Data providers are encouraged to choose a
933    minimal polygon.  Example:
934    
935  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
936  <RESOURCE type="meta" ID="soda-xdk48g" utype="adhoc:service">  <PARAM name="POLYGON"  unit="deg" ucd="phys.angArea;obs"
937    <PARAM name="standardID" datatype="char" arraysize="*"          datatype="double" arraysize="*"
938          value="ivo://ivoa.net/std/SODA#sync-1.0" />          xtype="polygon"  value="">
939    <PARAM name="accessURL" datatype="char" arraysize="*"    <DESCRIPTION>A polygon to be contained by the cutout</DESCRIPTION>
940          value="http://example.com/soda/sync" />    <VALUES>
941    <GROUP name="inputParams">      <MAX value="11.5 33.5 12.5 33.5 12.5 34.5 11.5 34.5"/>
942      <!-- ID value for a specific RA-DEC-FREQ cube -->    </VALUES>
943      <PARAM name="ID" ucd="meta.ref.url;meta.curation"  </PARAM>
             datatype="char" arraysize="*"  
             value="internal:123" />  
     <PARAM  name="POS" ucd="phys.angArea;obs"  
             datatype="char" arraysize="*" value="" />  
     <PARAM name="CIRCLE" unit="deg" ucd="phys.angArea;obs"  
             datatype="double" arraysize="3"  
             xtype="circle" value="">  
       <VALUES> <MAX value="12.0 34.0 0.5"/> </VALUES>  
     </PARAM>  
     <PARAM name="POLYGON"  unit="deg" ucd="phys.angArea;obs"  
             datatype="double" arraysize="*"  
             xtype="polygon"  value="">  
       <VALUES>  
         <MAX value="11.5 33.5 12.5 33.5 12.5 34.5 11.5 34.5"/>  
       </VALUES>  
     </PARAM>  
     <PARAM name="BAND" unit="m" ucd="em.wl"  
             datatype="double" arraysize="2"  
             xtype="interval" value="">  
       <VALUES>  
         <MAX value="300.0e-9 800.0e-9"/>  
       </VALUES>  
     </PARAM>  
   </GROUP>  
 </RESOURCE>  
944  \end{lstlisting}  \end{lstlisting}
945    
946  In this example, the \xmlel{ID} attribute of the service descriptor  Angles in both CIRCLE and POLYGON are in degrees.  As in the input,
947  resource (soda-xdk48g) is generated and would be referenced from the  the ICRS reference system is assumed, with no further metadata (e.g.,
948  \texttt{service\_def} column of the links table. Since this is a  reference position) prescribed by this standard.  Further metadata may
949  data-specific descriptor, the ID parameter has a fixed value instead of  should be given using standard STC annotation when the formalism to do
950  a ref attribute, and the CIRCLE, POLYGON, and BAND parameters have suggested  that is finalised.
951  values. The suggested values are the nominal maximum values which are  
952  interpreted as values of the regions or intervals that contain the  For POS, useful metadata cannot be given.  Services supporting POS
953  data. For example, the value given for the POLYGON parameter is the  should therefore provide POLYGON as well, and clients wishing to
954  bounding polygon for this data. The absence of a POL parameter means  use POS should infer sensible values for that parameter from
955  that polarization cutout is either not supported or not applicable to  \xmlel{VALUES} given for POLYGON.
956  this data.  
   
 In order to make it easier for clients, data-specific service  
 descriptors should only include parameter descriptions when the action  
 (cutout) can actually result in a modification of the data. For example,  
 if the axis has only one bin (e.g. time axis for an RA-DEC-FREQ cube),  
 then the associated parameter (e.g. TIME) should not be included in the  
 descriptor - even when valid time bounds metadata is known.  
   
 Providing values in the parameter descriptions of a data-specific  
 service descriptor implies that the resource generating this has access  
 to the applicable metadata. Depending on system architecture, this may  
 difficult to implement.  An ``autodescription'' mechanism where the SODA  
 service itself can generate a data-specific service descriptor of itself  
 may be included in SODA-1.1 or later.  
957    
958  \section{\{sync\} Responses}  \section{\{sync\} Responses}
959    

Legend:
Removed from v.3722  
changed lines
  Added in v.3723

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26