Merge pull request #2 from pdowler/main

include diagrams exported from REC doc

Author: pdowler

Char-Spatial.png

@@ -18,13 +18,17 @@
        {Fran\c{c}ois Bonnarel}
 \author{Alberto Micol}
 
-\editor{????Alfred Usher Thor????}
+\editor{Mireille Louys}
+\editor{Doug Tody}
+\editor[http://www.ivoa.net/twiki/bin/view/IVOA/PatrickDowler]{Patrick Dowler}
+\editor{Daniel Durand}
 
 % \previousversion[????URL????]{????Concise Document Label????}
 \previousversion[http://www.ivoa.net/Documents/ObsCore/20161004/PR-ObsCore-v1.1-20161004.pdf]{R-ObsCore-v1.1-20161004.pdf}
 \previousversion[https://www.ivoa.net/documents/ObsCore/20111028/REC-ObsCore-v1.0-20111028.pdf]{REC-ObsCore-v1.0-20111028.pdf}
 
 \usepackage{longtable}
+\usepackage{float}
 
 \begin{document}
 \begin{abstract}
@@ -119,12 +123,18 @@ \subsection{First building block: Data Models}
 Time Coordinates (STC), Spectrum and SSA, and the Characterisation data models that are currently used in IVOA services
 and applications.
 
-%\includegraphics[width=15.923cm,height=11.942cm]{ObsCore-img002.jpg}
-Figure 1.  Architecture of an ObsTAP service: it is based on the ObsCore data model,
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.9\textwidth]{role_diagram.jpg}
+\caption{Architecture of an ObsTAP service}
+\label{fig:archdiag}
+\end{figure}
+The architecture of an ObsTAP service: it is based on the ObsCore data model,
 which re-uses parts of Characterisation, Spectrum, STC data models and the UCD and Units specifications. As a service
 ObsTAP relies on ADQL, TAP, UWS, TAPRegExt, VOSI and VOTable. Examples and use-cases are exposed following the
 recommendation for DALI examples.
 
+
 \subsection{Second building block: the Table Access Protocol (TAP)}
 TAP defines a service protocol for accessing tabular data such as astronomical catalogs, or more generally, database
 tables.  TAP allows a client to (step 1) browse through the various tables and columns (names, units, etc.) in an
@@ -154,13 +164,13 @@ \subsection{The goal of this effort}
 
 This document is organized as follows:
 \begin{itemize}
-\item Section \ref{bkm:Ref159237242} briefly presents the types of the use cases collected from the astronomical
+\item Section \ref{sec:use-cases} briefly presents the types of the use cases collected from the astronomical
 community by the IVOA Uptake committee. 
-\item Section \ref{bkm:Ref159237280} defines the core components of the Observation data model. The elements of the data
-model are summarized in Figure 2. Mandatory ObsTAP fields are summarized in Table 1.
-\item Section \ref{bkm:Ref159237315} specifies the required data model fields as they are used in the TAP service: table
+\item Section \ref{sec:core-components} defines the core components of the Observation data model. The elements of the data
+model are summarized in Figure \ref{fig:obsdataset}. Mandatory ObsTAP fields are summarized in Table 1.
+\item Section \ref{sec:obstap-impl} specifies the required data model fields as they are used in the TAP service: table
 names, column names, column data type, UCD, Utype from the Observation Core components data model, and required units. 
-\item Section \ref{bkm:Ref298341494} describes how to register an ObsTAP service in a Virtual Observatory registry. 
+\item Section \ref{sec:obstap-register} describes how to register an ObsTAP service in a Virtual Observatory registry. 
 More detailed information is available in the appendices.
 \item Examples are cited in Appendix A
 \item Section 6 summarizes updates of this document.
@@ -169,8 +179,9 @@ \subsection{The goal of this effort}
 \item Appendix C shows the detailed content of the TAP\_SCHEMA tables and how to build up and fill them for the
 implementation of an ObsTAP service.
 \end{itemize}
+
 \section[Use cases]{Use cases}
-\label{bkm:Ref159237242}Our primary focus is on data discovery.  To this end a number of use-cases have been defined,
+\label{sec:use-cases}Our primary focus is on data discovery.  To this end a number of use-cases have been defined,
 aimed at finding observational data products in the VO domain by broadcasting the same query to multiple archives
 (global data discoverability and accessibility).  To achieve this we need to give data providers a set of metadata
 attributes that they can easily map to their database system in order to support queries of the sort listed below.
@@ -191,11 +202,10 @@ \subsection{The goal of this effort}
 
 The detailed list of use cases proposed for data discovery is given in Appendix A.
 
-\subsection{Role within the VO Architecture}
-
-\begin{figure}
-\centering
+%\subsection{Role within the VO Architecture}
 
+%\begin{figure}
+%\centering
 % As of ivoatex 1.2, the architecture diagram is generated by ivoatex in
 % SVG; copy ivoatex/archdiag-full.xml to role_diagram.xml and throw out
 % all lines not relevant to your standard.
@@ -205,13 +215,12 @@ \subsection{Role within the VO Architecture}
 %\includegraphics[width=0.9\textwidth]{role_diagram.pdf}
 %\caption{Architecture diagram for this document}
 %\label{fig:archdiag}
-\end{figure}
-
-Fig.~\ref{fig:archdiag} shows the role this document plays within the
-IVOA architecture \citep{2021ivoa.spec.1101D}.
+%\end{figure}
+%Fig.~\ref{fig:archdiag} shows the role this document plays within the
+%IVOA architecture \citep{2021ivoa.spec.1101D}.
 
 \section[Observation Core Components Data Model]{Observation Core Components Data Model}
-\label{bkm:Ref159237280}This section highlights and describes the core components of the Observation data model,
+\label{sec:core-components}This section highlights and describes the core components of the Observation data model,
 synthetized today in the Dataset Metadata DM specification. The term ``core components'' is meant to refer to those
 elements of the larger ``Observation Data Model'' that are required to support the use cases listed in Appendix A.  In
 reality this effort is the outcome of a trade-off between what astronomers want and what data providers are ready to
@@ -231,6 +240,7 @@ \subsection{Role within the VO Architecture}
 here in order to keep the core model simple.
 
 \subsection[UML description of the model]{UML description of the model}
+\label{sec:uml}
 This section provides a graphical overview of the Observation Core Components data model using the unified modeling
 language (UML).  The UML class diagram shown in Figure 2 depicts the overall Observation Data Model, detailing those
 aspects that are relevant to the Core Components, while omitting those not relevant.  The Characterisation classes
@@ -239,27 +249,50 @@ \subsection{Role within the VO Architecture}
 Spectrum/SSA data model where only a subset of the attributes are actually necessary for data discovery.  For our
 purposes here we show Characterisation classes only down to the level of the Support class (level 3).
 
-%\includegraphics[width=17.489cm,height=19.59cm]{ObsCore-img003.png}
-\label{bkm:Ref158037359}Figure F3. Depicted here are the classes used to organize
-observational metadata. Classes may be linked either via association or aggregation.  The minimal set of necessary
-attributes for data discovery is shown in brown.
+\begin{figure}[H]
+\centering
+%\includegraphics[width=17.489cm,height=19.59cm]{ObsDataset.png}
+\includegraphics[width=0.9\textwidth]{ObsDataset.png}
+\caption{ObsDataset metadata}
+\label{fig:obsdataset}
+\end{figure}
+Figure \ref{fig:obsdataset} depicts the classes used to organize observational metadata. Classes may be linked either via 
+association or aggregation.  The minimal set of necessary attributes for data discovery is shown in brown.
 
 For the sake of clarity, the SpatialAxis, SpectralAxis and TimeAxis classes on the diagram are not expanded on the main
 class diagram. Details for these axes are shown in Figure 3 for the spatial axis, Figure 4 for the spectral axis and
 Figure 5 for the time axis.
 
-%\includegraphics[width=14.605cm,height=10.239cm]{ObsCore-img004.png}
-\label{bkm:Ref158037577}Figure F5. Details of the classes linked to the description of the
+\begin{figure}[H]
+\centering
+%\includegraphics[width=14.605cm,height=10.239cm]{Char-Spatial.png}
+\includegraphics[width=0.9\textwidth]{Char-Spatial.png}
+\caption{Spatial Axis Characterisation}
+\label{fig:char-spatial}
+\end{figure}
+Figure \ref{fig:char-spatial} shows the details of the classes linked to the description of the
 spatial axis for an Observation dataset. All axes in this model inherit the main structure from the
 CharacterisationAxis class, but some peculiar attributes are necessary for Space coordinates.
 
-%\includegraphics[width=17.427cm,height=10.495cm]{ObsCore-img005.png}
-\label{bkm:Ref158037643}Figure F5. Spectral axis: details of the classes necessary to
+\begin{figure}[H]
+\centering
+%\includegraphics[width=17.427cm,height=10.495cm]{Char-Spectral.png}
+\includegraphics[width=0.9\textwidth]{Char-Spectral.png}
+\caption{Spectral Axis Characterisation}
+\label{fig:char-spectral}
+\end{figure}
+Figure \ref{fig:char-spectral} shows the Spectral axis: details of the classes necessary to
 describe the spectral properties of an Observation dataset. UCD and units are essential to disentangle various possible
 spectral quantities.
 
-%\includegraphics[width=13.524cm,height=9.075cm]{ObsCore-img006.png}
-\label{bkm:Ref291003095}Figure F6.  The classes from the Characterisation DM used to
+\begin{figure}[H]
+\centering
+%\includegraphics[width=13.524cm,height=9.075cm]{Char-Time.png}
+\includegraphics[width=0.9\textwidth]{Char-Time.png}
+\caption{Time Axis Characterisation}
+\label{fig:char-time}
+\end{figure}
+Figure \ref{fig:char-time} shows the classes from the Characterisation DM used to
 describe time metadata.
 
 Details on the ObsCoreDM axes definitions are available in the Characterisation data model standard document
@@ -477,7 +510,7 @@ \subsubsection{File Content and Format}
 See section \ref{bkm:Ref289893457} for more details and implementation requirements.
 
 \section{Implementation of ObsCore in a TAP Service}
-\label{bkm:Ref159237315}The ObsCore model must be implemented within Table Access Protocol (TAP) services such that all
+\label{sec:obstap-impl}The ObsCore model must be implemented within Table Access Protocol (TAP) services such that all
 valid queries can be executed unchanged on any service that implements the model.  Additional optional or
 provider-defined columns are permitted (see section \ref{bkm:Ref421295535}) so long as all mandatory columns are
 provided.  The protocol does not specify any specific ordering of fields in the query response so long as the mandatory
@@ -870,7 +903,7 @@ \subsection{Additional Columns}
 ones. Queries built up using additional columns defined specifically for a given archive might not be portable.
 
 \section{Registering an ObsTAP Service}
-\label{bkm:Ref298341494}The standard identifier for this version of the ObsCore model now follows the IVOA Identifiers
+\label{sec:obstap-register}The standard identifier for this version of the ObsCore model now follows the IVOA Identifiers
 v2.0 specification \cite{CITATIONDem16l1036} and should be ivo://ivoa.net/std/ObsCore\#core-1.1
 
 The ObsCore data model will be registered using this identifier in the StandardsRegExt (standards registry extension)