diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index d9e265e..98ab575 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -18,7 +18,7 @@ on: branches: - master - wd-v1.0 - - apps-review + - dal-review - pr-1.0 jobs: diff --git a/doc/MANGO.tex b/doc/MANGO.tex index 58a9f88..d54e2f4 100644 --- a/doc/MANGO.tex +++ b/doc/MANGO.tex @@ -157,7 +157,8 @@ \subsection{Role within the VO Architecture} \end{figure} Fig.~\ref{fig:archdiag} shows the role this document plays within the -IVOA architecture \citep{2010ivoa.rept.1123A}. This model reuses existing data models like Measure and Coords, and PhotDM. Implementations can use the TAP protocol and distribute data model instances in VOTable. +IVOA architecture \citep{2010ivoa.rept.1123A}. This model reuses existing data models like Measure and Coords, and PhotDM. +Implementations can use DAL protocols (e.g. TAP, Simple Cone Search) and distribute data model instances in VOTable. UCD, VOUnits and Vocabularies are also re-used. \section{Representing observed astronomical objects : Use Cases and Requirements} @@ -242,22 +243,22 @@ \section{Model Overview} \begin{figure} \includegraphics[width=1.0\textwidth]{../model/overview.png} \caption{Model overview} - \label{overview} + \label{fig:overview} \end{figure} - -The root class of the model \texttt{MANGOObject} has only +The model architecture is shown in Fig \ref{fig:overview}. +The root class, \texttt{MangoObject}, has only one mandatory attribute, an \texttt{identifier}. Identifiers should be unique within a collection, e.g. a data table, although this feature is not required by the model. -In addition to its identifier, \texttt{MANGOObject} objects have 2 components: +In addition to its identifier, \texttt{MangoObject} objects have 2 components: \begin{itemize}[noitemsep,topsep=0pt,parsep=0pt,partopsep=0pt] - \item \texttt{dataOrigin} (origin of the \texttt{MANGOObject}) : The structure of this class is based on + \item \texttt{dataOrigin} (origin of the \texttt{MangoObject}) : The structure of this class is based on the recommendations of the DCP interest group \footnote{https://ivoa.net/documents/DataOrigin/index.html}. - \item \texttt{propertyDock} (place holder for all the \texttt{MANGOObject} properties) : + \item \texttt{propertyDock} (place holder for all the \texttt{MangoObject} properties) : This is an open-ended collection. Mango properties inherit from the base class \texttt{Property}, which contains everything necessary to identify both their nature and their role. @@ -329,7 +330,7 @@ \subsubsection{MANGO and MIVOT: 2 Strategies for Structuring Tabular Data} MANGO is used to represent catalogue data which are typically provided in tabular form by TAP services \citep{2019ivoa.spec.0927D} -or other DAL nodes (one of the reference implementation is based on a Vizier SCS). +or other DAL nodes (one of the reference implementation is based on a VizieR SCS). The linking between MANGO instances and table row elements is provided by MIVOT annotations. There are two possible strategies for establishing this mapping: diff --git a/doc/Makefile b/doc/Makefile index 3179e32..f6b3115 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,7 +7,7 @@ DOCNAME = MANGO DOCVERSION = 1.0 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2025-12-18 +DOCDATE = 2026-01-22 # What is it you're writing: NOTE, WD, PR, REC, PEN, or EN DOCTYPE = PR diff --git a/doc/ivoatexmeta.tex b/doc/ivoatexmeta.tex index 1facd64..3151793 100644 --- a/doc/ivoatexmeta.tex +++ b/doc/ivoatexmeta.tex @@ -1,7 +1,7 @@ % GENERATED FILE -- edit this in the Makefile \newcommand{\ivoaDocversion}{1.0} -\newcommand{\ivoaDocdate}{2025-12-18} -\newcommand{\ivoaDocdatecode}{20251218} +\newcommand{\ivoaDocdate}{2026-01-22} +\newcommand{\ivoaDocdatecode}{20260122} \newcommand{\ivoaDoctype}{PR} \newcommand{\ivoaDocname}{MANGO} \renewcommand{\ivoaBaseURL}{https://www.ivoa.net/documents/MANGO} diff --git a/doc/model.tex b/doc/model.tex index 1f62c1d..ef3f929 100644 --- a/doc/model.tex +++ b/doc/model.tex @@ -132,13 +132,13 @@ \section{Model: mango } \textbf{vodml-id: DataLink.content\_type} \newline \textbf{type: \hyperref[sect:ivoa]{ivoa:string}} \newline \textbf{multiplicity: 1} \newline - mime type of the content the link returns (see DataLink 1.1) + Provides the mime type of the content the link returns (see DataLink 1.1) \subsubsection{DataLink.access\_url} \textbf{vodml-id: DataLink.access\_url} \newline \textbf{type: \hyperref[sect:ivoa]{ivoa:anyURI}} \newline \textbf{multiplicity: 1} \newline - contains an URL for downloading a single resource. There is no restriction on the type of resource accessed by the links. + Contains an URL for downloading a single resource. There is no restriction on the type of resource accessed by the links. \subsubsection{DataLink.content\_qualifier} \textbf{vodml-id: DataLink.content\_qualifier} \newline @@ -150,7 +150,7 @@ \section{Model: mango } \textbf{vodml-id: DataLink.local\_semantics} \newline \textbf{type: \hyperref[sect:ivoa]{ivoa:string}} \newline \textbf{multiplicity: 1} \newline - Allows for identification of corresponding rows for different IDs in the same DataLink service where the combination of semantics, content\_type and content\_qualifier is not sufficient to identify them (see DataLink 1.1). + Allows for link identification where the combination of semantics, content\_type and content\_qualifier is not sufficient (see DataLink 1.1). \subsection{DateTime} \label{sect:DateTime} @@ -178,7 +178,7 @@ \section{Model: mango } \label{sect:EpochPosition} - This class (fig \ref{fig:EpochPosition}) is a flattened view of objects/concepts from the Astronomical Measurements Model \citep{2022ivoa.specQ1004R} that have been put together to form a consistent description of the position of an object moving over time. It consists of a celestial position, a proper motion, a radial velocity and a parallax and their associated errors encapsulated into the \texttt{EpochPositionErrors} class. The values of these properties are pulled from the underlying Astronomical Coordinates and Coordinate Systems model \citep{2022ivoa.spec.1004R} At a high level the properties map as follows: \begin{itemize} \item celestial position -> \texttt{meas:Position} \item proper motion -> \texttt{meas:ProperMotion} \item radial velocity -> \texttt{meas.Velocity} \item parallax -> no suitable counterpart at this time \end{itemize} All components use the same coordinate systems for both time and space coordinates. \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. \item The space coordinate system is imported from \texttt{coords:spaceSys}. \item The time coordinate system is imported from \texttt{coords:simeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead of the \texttt{epoch} field of \texttt{coords:spaceSys}. There are 2 reasons for this: \begin{itemize} \item Using the epoch of \texttt{coords:spaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. \item the observation date can be read in a column and therefore change with each data row. I this case, it cannot be stored as an element of the space coordinate system but as an \texttt{EPochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. This consistency is not enforced by the model. Possible correlations between \texttt{EpochPosition} parameters are handled by the \texttt{EpochPositionCorrelations} class. Errors along the different axes are grouped in the \texttt{EpochPositionErrors} class. In some cases the errors might conflict with the correlations: \begin{itemize} \item \texttt{Ellipse} errors on position or proper motion must not be used together with the \texttt{longitudeLatitude} (or \texttt{pmLongitudePmLatitude}) correlation fields. In fact, using elliptical errors implies a correlation between the two spatial axes which must not conflict with the correlations defined in \texttt{EpochPositionCorrelations}. \end{itemize} + This class (fig \ref{fig:EpochPosition}) is a flattened view of objects/concepts from the Astronomical Measurements Model \citep{2022ivoa.specQ1004R} that have been put together to form a consistent description of the position of an object moving over time. It consists of a celestial position, a proper motion, a radial velocity and a parallax and their associated errors encapsulated into the \texttt{EpochPositionErrors} class. The values of these properties are pulled from the underlying Astronomical Coordinates and Coordinate Systems model \citep{2022ivoa.spec.1004R} At a high level the properties map as follows: \begin{itemize} \item celestial position -> \texttt{meas:Position} \item proper motion -> \texttt{meas:ProperMotion} \item radial velocity -> \texttt{meas.Velocity} \item parallax -> no suitable counterpart at this time \end{itemize} All components use the same coordinate systems for both time and space coordinates. \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. \item The space coordinate system is imported from \texttt{coordsSpaceSys}. \item The time coordinate system is imported from \texttt{coords:TimeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead of the \texttt{epoch} field of \texttt{coords:SpaceSys}. There are 2 reasons for this: \begin{itemize} \item Using the epoch of \texttt{coords:SpaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. \item The observation date can be read in a column and therefore change with each data row. In this case, it cannot be stored as an element of the space coordinate system but as an \texttt{EpochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. This consistency is not enforced by the model. Possible correlations between \texttt{EpochPosition} parameters are handled by the \texttt{EpochPositionCorrelations} class. Errors along the different axes are grouped in the \texttt{EpochPositionErrors} class. In some cases the errors might conflict with the correlations: \begin{itemize} \item \texttt{Ellipse} errors on position or proper motion must not be used together with the \texttt{longitudeLatitude} (or \texttt{pmLongitudePmLatitude}) correlation fields. In fact, using elliptical errors implies a correlation between the two spatial axes which must not conflict with the correlations defined in \texttt{EpochPositionCorrelations}. \end{itemize} \subsubsection{EpochPosition.longitude} \textbf{vodml-id: EpochPosition.longitude} \newline @@ -428,13 +428,13 @@ \section{Model: mango } \subsection{Property} \label{sect:Property} - Class holder for a \textit{flavor} of property’ ie: there should be a Property subclass for each \textit{flavor} of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself. + Class holder for a \textit{flavor} of property, i.e., there should be a Property subclass for each \textit{flavor} of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself. \subsubsection{Property.semantics} \textbf{vodml-id: Property.semantics} \newline \textbf{type: \hyperref[sect:VocabularyTerm]{mango:VocabularyTerm}} \newline \textbf{multiplicity: 0..1} \newline - Reference to a semantic concept giving the nature of the property or of the set made of the property and its associated properties. The semantics field contains a URI for a concept that describes the meaning of the property. This attribute is intended to be machine-readable and to assist automated link selection, presentation, and usage. The value is always interpreted as a URI; relative URIs (Berners-Lee and Fielding et al., 2005) are completed using the base URI of the core DataLink vocabulary, \url{http://www.ivoa.net/rdf/datalink/core}. Terms from this vocabulary must always be written as relative URIs. This means that for concepts from the core vocabulary, the value in the semantics fields always starts with a hash. (datalink1.1). The semantics concept applies to a single property or to the set made of the property and its associated properties (e.g. position and flag). + Reference to a semantic concept giving the nature of the property or of the set made of the property and its associated properties (e.g. position and flag). This attribute is intended to be machine-readable and to assist automated property presentation, and usage. The value is always interpreted as a URI; relative URIs are completed using the base URI of the core UAT vocabulary, \url{http://www.ivoa.net/rdf/uat} (see \ref{sect:VocabularyTerm}). \subsubsection{Property.description} \textbf{vodml-id: Property.description} \newline @@ -512,7 +512,7 @@ \section{Model: mango } \subsection{iso} \label{sect:iso} - Primitive type for observation dates expressed as an ISO Date (e.g. "2025-08-07T09:29:14"). + Primitive type for observation dates expressed as an ISO-8601 Date (e.g. "2025-08-07T09:29:14"). \subsection{mjd} \label{sect:mjd} @@ -533,9 +533,9 @@ \section{Model: mango } \begin{itemize} \item[\textbf{SMOC}]: \textbf{vodml-id:} FootprintSerialization.SMOC \newline - \textbf{description:} Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). When using this serialisation, \texttt{spaceSys} can be ignored. + \textbf{description:} Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. SMOC should be in equatorial ICRS. This overrides \texttt{mango:Footprint.spaceSys} reference which can be ignored when using this serialisation. \item[\textbf{STC-S}]: \textbf{vodml-id:} FootprintSerialization.STC-S \newline - \textbf{description:} Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). When using this serialisation, \texttt{spaceSys} can be ignored. + \textbf{description:} Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). The STC-S space coordinate system overrides the \texttt{mango:Footprint.spaceSys} reference which can be ignored when using this serialisation. Although the STC-S standard has been an IVOA draft for many years, it is still used by certain services, which justifies MANGO's support for it. \item[\textbf{POLYGON}]: \textbf{vodml-id:} FootprintSerialization.POLYGON \newline \textbf{description:} Label indicating that the footprint has been serialized as a polygon as defined in \cite{2017ivoa.spec.0517D} section 3.3.7. Using the polygon serialization requires the space coordinate system to be defined. \end{itemize} diff --git a/doc/model_toc.tex b/doc/model_toc.tex index 55f6697..ca0c80a 100644 --- a/doc/model_toc.tex +++ b/doc/model_toc.tex @@ -55,13 +55,13 @@ \section{Model: mango} \subsection{Property} \label{sect:Property} - Class holder for a \textit{flavor} of property’ ie: there should be a Property subclass for each \textit{flavor} of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself. + Class holder for a \textit{flavor} of property, i.e., there should be a Property subclass for each \textit{flavor} of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself. \subsubsection{Property.semantics} \textbf{vodml-id: Property.semantics} \newline \textbf{type: \hyperref[sect:VocabularyTerm]{mango:VocabularyTerm}} \newline \textbf{multiplicity: 0..1} \newline - Reference to a semantic concept giving the nature of the property or of the set made of the property and its associated properties. The semantics field contains a URI for a concept that describes the meaning of the property. This attribute is intended to be machine-readable and to assist automated link selection, presentation, and usage. The value is always interpreted as a URI; relative URIs (Berners-Lee and Fielding et al., 2005) are completed using the base URI of the core DataLink vocabulary, \url{http://www.ivoa.net/rdf/datalink/core}. Terms from this vocabulary must always be written as relative URIs. This means that for concepts from the core vocabulary, the value in the semantics fields always starts with a hash. (datalink1.1). The semantics concept applies to a single property or to the set made of the property and its associated properties (e.g. position and flag). + Reference to a semantic concept giving the nature of the property or of the set made of the property and its associated properties (e.g. position and flag). This attribute is intended to be machine-readable and to assist automated property presentation, and usage. The value is always interpreted as a URI; relative URIs are completed using the base URI of the core UAT vocabulary, \url{http://www.ivoa.net/rdf/uat} (see \ref{sect:VocabularyTerm}). \subsubsection{Property.description} \textbf{vodml-id: Property.description} \newline @@ -114,7 +114,7 @@ \section{Date Time Types} \subsection{iso} \label{sect:iso} - Primitive type for observation dates expressed as an ISO Date (e.g. "2025-08-07T09:29:14"). + Primitive type for observation dates expressed as an ISO-8601 Date (e.g. "2025-08-07T09:29:14"). \section{Epoch Position Properties} @@ -125,7 +125,7 @@ \section{Epoch Position Properties} \label{fig:EpochPosition} \end{figure} \label{sect:EpochPosition} - This class (fig \ref{fig:EpochPosition}) is a flattened view of objects/concepts from the Astronomical Measurements Model \citep{2022ivoa.specQ1004R} that have been put together to form a consistent description of the position of an object moving over time. It consists of a celestial position, a proper motion, a radial velocity and a parallax and their associated errors encapsulated into the \texttt{EpochPositionErrors} class. The values of these properties are pulled from the underlying Astronomical Coordinates and Coordinate Systems model \citep{2022ivoa.spec.1004R} At a high level the properties map as follows: \begin{itemize} \item celestial position -> \texttt{meas:Position} \item proper motion -> \texttt{meas:ProperMotion} \item radial velocity -> \texttt{meas.Velocity} \item parallax -> no suitable counterpart at this time \end{itemize} All components use the same coordinate systems for both time and space coordinates. \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. \item The space coordinate system is imported from \texttt{coords:spaceSys}. \item The time coordinate system is imported from \texttt{coords:simeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead of the \texttt{epoch} field of \texttt{coords:spaceSys}. There are 2 reasons for this: \begin{itemize} \item Using the epoch of \texttt{coords:spaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. \item the observation date can be read in a column and therefore change with each data row. I this case, it cannot be stored as an element of the space coordinate system but as an \texttt{EPochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. This consistency is not enforced by the model. Possible correlations between \texttt{EpochPosition} parameters are handled by the \texttt{EpochPositionCorrelations} class. Errors along the different axes are grouped in the \texttt{EpochPositionErrors} class. In some cases the errors might conflict with the correlations: \begin{itemize} \item \texttt{Ellipse} errors on position or proper motion must not be used together with the \texttt{longitudeLatitude} (or \texttt{pmLongitudePmLatitude}) correlation fields. In fact, using elliptical errors implies a correlation between the two spatial axes which must not conflict with the correlations defined in \texttt{EpochPositionCorrelations}. \end{itemize} + This class (fig \ref{fig:EpochPosition}) is a flattened view of objects/concepts from the Astronomical Measurements Model \citep{2022ivoa.specQ1004R} that have been put together to form a consistent description of the position of an object moving over time. It consists of a celestial position, a proper motion, a radial velocity and a parallax and their associated errors encapsulated into the \texttt{EpochPositionErrors} class. The values of these properties are pulled from the underlying Astronomical Coordinates and Coordinate Systems model \citep{2022ivoa.spec.1004R} At a high level the properties map as follows: \begin{itemize} \item celestial position -> \texttt{meas:Position} \item proper motion -> \texttt{meas:ProperMotion} \item radial velocity -> \texttt{meas.Velocity} \item parallax -> no suitable counterpart at this time \end{itemize} All components use the same coordinate systems for both time and space coordinates. \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. \item The space coordinate system is imported from \texttt{coordsSpaceSys}. \item The time coordinate system is imported from \texttt{coords:TimeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead of the \texttt{epoch} field of \texttt{coords:SpaceSys}. There are 2 reasons for this: \begin{itemize} \item Using the epoch of \texttt{coords:SpaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. \item The observation date can be read in a column and therefore change with each data row. In this case, it cannot be stored as an element of the space coordinate system but as an \texttt{EpochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. This consistency is not enforced by the model. Possible correlations between \texttt{EpochPosition} parameters are handled by the \texttt{EpochPositionCorrelations} class. Errors along the different axes are grouped in the \texttt{EpochPositionErrors} class. In some cases the errors might conflict with the correlations: \begin{itemize} \item \texttt{Ellipse} errors on position or proper motion must not be used together with the \texttt{longitudeLatitude} (or \texttt{pmLongitudePmLatitude}) correlation fields. In fact, using elliptical errors implies a correlation between the two spatial axes which must not conflict with the correlations defined in \texttt{EpochPositionCorrelations}. \end{itemize} \subsubsection{EpochPosition.longitude} \textbf{vodml-id: EpochPosition.longitude} \newline @@ -492,9 +492,9 @@ \section{Other Properties} \small \begin{itemize} \item \textbf{SMOC}: \textbf{vodml-id:} FootprintSerialization.SMOC \newline - \textbf{description:} Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). When using this serialisation, \texttt{spaceSys} can be ignored. + \textbf{description:} Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. SMOC should be in equatorial ICRS. This overrides \texttt{mango:Footprint.spaceSys} reference which can be ignored when using this serialisation. \item \textbf{STC-S}: \textbf{vodml-id:} FootprintSerialization.STC-S \newline - \textbf{description:} Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). When using this serialisation, \texttt{spaceSys} can be ignored. + \textbf{description:} Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). The STC-S space coordinate system overrides the \texttt{mango:Footprint.spaceSys} reference which can be ignored when using this serialisation. Although the STC-S standard has been an IVOA draft for many years, it is still used by certain services, which justifies MANGO's support for it. \item \textbf{POLYGON}: \textbf{vodml-id:} FootprintSerialization.POLYGON \newline \textbf{description:} Label indicating that the footprint has been serialized as a polygon as defined in \cite{2017ivoa.spec.0517D} section 3.3.7. Using the polygon serialization requires the space coordinate system to be defined. \end{itemize} diff --git a/doc/role_diagram.pdf b/doc/role_diagram.pdf index 56fbb65..cd14d5f 100644 Binary files a/doc/role_diagram.pdf and b/doc/role_diagram.pdf differ diff --git a/doc/role_diagram.svg b/doc/role_diagram.svg index aee9b29..039c315 100644 --- a/doc/role_diagram.svg +++ b/doc/role_diagram.svg @@ -58,19 +58,19 @@ - ADQL - TAP + + DataLink - ObsCore + @@ -87,7 +87,7 @@ Meas Coords - DatasetDM + ProvDM @@ -96,7 +96,7 @@ - UWS + diff --git a/doc/role_diagram.xml b/doc/role_diagram.xml index e8d290f..e176a2e 100644 --- a/doc/role_diagram.xml +++ b/doc/role_diagram.xml @@ -56,19 +56,19 @@ of the various sections) to have the box centered. - + - + - + - + @@ -85,7 +85,7 @@ of the various sections) to have the box centered. - + @@ -94,7 +94,7 @@ of the various sections) to have the box centered. - + diff --git a/doc/usecase_vizier.tex b/doc/usecase_vizier.tex index 4cf96b5..45516da 100644 --- a/doc/usecase_vizier.tex +++ b/doc/usecase_vizier.tex @@ -3,21 +3,21 @@ VizieR provides science ready catalogues coming from space agencies or articles and covering number of different science cases. Published data encompass a very large set of measures (position, photometry, redshift, source type, etc.) depending on their origin. They can result from observations, simulations, models or catalog compilations. -Individual Vizier tables can contain data all related to one source (e.g. time series of positions or magnitudes) or to a set of sources (one row per source) or a mix of both. +Individual VizieR tables can contain data all related to one source (e.g. time series of positions or magnitudes) or to a set of sources (one row per source) or a mix of both. %The most frequent are observation tables which can serialize a single object to one or more records. % -Data sets are ingested in Vizier on author request. Before to be put online they are processed and documented by documentalists so as to ensure a certain level of interoperability. +Data sets are ingested in VizieR on author request. Before to be put online they are processed and documented by documentalists so as to ensure a certain level of interoperability. This work relies on the analyse of both data content and scientific paper. \begin{itemize} \item Missing meta-data, e.g. space frames or filters, are added when available in the paper. -\item Columns are renamed following the Vizier nomenclature in order make them compliant with the DBMS and to facilitate the grouping of all values related to one particular quantities (e.g. quality flag for a radial velocity) +\item Columns are renamed following the VizieR nomenclature in order make them compliant with the DBMS and to facilitate the grouping of all values related to one particular quantities (e.g. quality flag for a radial velocity) \item UCDs are checked or set for all columns. \item README files are generated. A README is a text file with a specific layout making it machine readable. \item Some values, not part of the original data but assigned by the CDS, are added to the tables (e.g. identifier, ICRS positions) \item Ancillary data pointing on associated data (e.g. spectra) or on linked services (e.g. visualisation), can also be added to enrich the table content. \end{itemize} -All Vizier meta data are gathered in a specific resource in a way to facilitate the localisation of data of interest. +All VizieR meta data are gathered in a specific resource in a way to facilitate the localisation of data of interest. The main specificity of the data is their heterogeneity \begin{itemize} \item Huge variety of data provenance and processing @@ -29,7 +29,7 @@ \item Large variety of associated data \end{itemize} -The Mango model must be able to provide a standard representation of most of the metadata contained in Vizier query responses, whether native or computed by the CDS, simple quantities or associated complex data. +The Mango model must be able to provide a standard representation of most of the metadata contained in VizieR query responses, whether native or computed by the CDS, simple quantities or associated complex data. Mango is not meant to replace the current management of the meta-data, it is a way to make those meta-data understandable for a wide panel of VO-compliant clients. %The tables processed are documented and standardized in order to be interoperable. The metadata includes coordinates systems and the magnitudes columns can be completed with photometric paremeters –these last metadata are not part of the original data but are assigned by CDS. @@ -51,9 +51,9 @@ % END GILLLES proposal -Vizier gathers and delivers a curated version of published catalogs from various missions and experiments. +VizieR gathers and delivers a curated version of published catalogs from various missions and experiments. It also distributes results of scientific papers, based on the computation , comparison and classification of sources extracted from archived data after science analysis. -Vizier handles a very large set of measures in position, photometry, redshift, source type, etc. +VizieR handles a very large set of measures in position, photometry, redshift, source type, etc. % FB : I don't think the end of this sentences was correct : "as authors original data." It adds value to it by recomputing additional quantities in various reference frames or equivalent spectral bands, units conversions , etc . It binds the resulting object description to other data sets representing the object, or its counterparts, or neighbourhood on sky (image), its spectral behaviour (spectrum, spectral energy distribution) or evolution through time (light curve, radial velocity curve, time series, etc.). diff --git a/doc/usecases.tex b/doc/usecases.tex index 2472e11..21b898f 100644 --- a/doc/usecases.tex +++ b/doc/usecases.tex @@ -159,17 +159,17 @@ \subsubsection{X-ray Observatory Archives} % ============================================ -\subsubsection{Vizier catalog archive} +\subsubsection{VizieR catalog archive} VizieR provides science ready catalogs coming from space agencies or articles from the astronomical journals, covering number of different science cases. Published data encompass a very large set of measures (position, photometry, redshift, source type, etc.) depending on their origin. They can result from observations, simulations, models or catalog compilations. -Individual Vizier tables can contain data all related to one source (e.g. time series of positions or magnitudes) or to a set of sources (one row per source) or a mix of both. +Individual VizieR tables can contain data all related to one source (e.g. time series of positions or magnitudes) or to a set of sources (one row per source) or a mix of both. The MANGO model must be able to provide a standard representation of most of the metadata contained -in Vizier query responses, either native or computed by the CDS, and organized either as +in VizieR query responses, either native or computed by the CDS, and organized either as simple quantities or as associated complex data. -MANGO is not meant to replace the current management of the ViZier metadata, but rather +MANGO is not meant to replace the current management of the VizieR metadata, but rather to make those understandable/interoperable for a wide panel of VO-compliant clients. \subsubsection{Client Use-cases} diff --git a/implementations/README.md b/implementations/README.md index de8b8ce..bf7ec72 100644 --- a/implementations/README.md +++ b/implementations/README.md @@ -9,7 +9,7 @@ This folder contains working examples as annotated VOTables that cover most of t - **query**: `SELECT TOP1 * FROM "public".mergedentry` - **format**: `application/x-votable+xml;content=mivot` -- **Gaia**:Vizier query response on the GAIA DR3 catalog. +- **Gaia**:VizieR query response on the GAIA DR3 catalog. The VOTable has been annotated on by hand with the Pyvo MIVOT API. - **file**: `gaia_with_mivot.xml` - **service**: `https://vizier.cds.unistra.fr/viz-bin/votable` @@ -21,7 +21,7 @@ This folder contains working examples as annotated VOTables that cover most of t - **service**: `https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/argus` - **query**: `SELECT TOP 1 ivoa.ObsCore.obs_id,ivoa.ObsCore.s_region,ivoa.ObsCore.access_url FROM ivoa.ObsCore` -- **vizier_cs_I_239**:Cone search response on the I/239 Vizier table. +- **vizier_cs_I_239**:Cone search response on the I/239 VizieR table. The VOTable has been annotated on the flight by the server. - **file**: `vizier_cs_I_239.xml` - **service**: `https://cds/viz-bin/conesearch/V1.5/I/239/hip_main` diff --git a/mivot/mango/mango.AssociatedMangoObject.xml b/mivot/mango/mango.AssociatedMangoObject.xml index aaa974b..b4b93bb 100644 --- a/mivot/mango/mango.AssociatedMangoObject.xml +++ b/mivot/mango/mango.AssociatedMangoObject.xml @@ -13,7 +13,8 @@ a description of the data origin and an identifier." --> - diff --git a/mivot/mango/mango.EpochPosition.xml b/mivot/mango/mango.EpochPosition.xml index 4284324..1aa5177 100644 --- a/mivot/mango/mango.EpochPosition.xml +++ b/mivot/mango/mango.EpochPosition.xml @@ -20,21 +20,21 @@ All components use the same coordinate systems for both time and space coordinat \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. - \item The space coordinate system is imported from \texttt{coords:spaceSys}. - \item The time coordinate system is imported from \texttt{coords:simeSys}. + \item The space coordinate system is imported from \texttt{coordsSpaceSys}. + \item The time coordinate system is imported from \texttt{coords:TimeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead -of the \texttt{epoch} field of \texttt{coords:spaceSys}. +of the \texttt{epoch} field of \texttt{coords:SpaceSys}. There are 2 reasons for this: \begin{itemize} - \item Using the epoch of \texttt{coords:spaceSys} requires to work with the + \item Using the epoch of \texttt{coords:SpaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. - \item the observation date can be read in a column and therefore change with each data row. - I this case, it cannot be stored as an element of the space coordinate system - but as an \texttt{EPochPosition} attribute. + \item The observation date can be read in a column and therefore change with each data row. + In this case, it cannot be stored as an element of the space coordinate system + but as an \texttt{EpochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. diff --git a/mivot/mango/mango.MangoObject.xml b/mivot/mango/mango.MangoObject.xml index 415cfdc..327a484 100644 --- a/mivot/mango/mango.MangoObject.xml +++ b/mivot/mango/mango.MangoObject.xml @@ -5,7 +5,8 @@ a description of the data origin and an identifier." --> - @@ -17,7 +18,8 @@ This class specifies both type and role of the property, and hosts the property - @@ -50,7 +52,8 @@ a description of the data origin and an identifier." --> - diff --git a/mivot/mango/mango.Property.xml b/mivot/mango/mango.Property.xml index 7db97fd..afd7274 100644 --- a/mivot/mango/mango.Property.xml +++ b/mivot/mango/mango.Property.xml @@ -1,5 +1,6 @@ - diff --git a/vo-dml/desc.mango.vo-dml.xml b/vo-dml/desc.mango.vo-dml.xml index 96322ae..8df972c 100644 --- a/vo-dml/desc.mango.vo-dml.xml +++ b/vo-dml/desc.mango.vo-dml.xml @@ -43,7 +43,7 @@ This enables the metadata representation to be improved and complex quantities t iso iso - Primitive type for observation dates expressed as an ISO Date (e.g. "2025-08-07T09:29:14"). + Primitive type for observation dates expressed as an ISO-8601 Date (e.g. "2025-08-07T09:29:14"). ivoa:datetime @@ -78,15 +78,19 @@ This enables the metadata representation to be improved and complex quantities t FootprintSerialization.SMOC SMOC Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. -SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). -When using this serialisation, \texttt{spaceSys} can be ignored. +SMOC should be in equatorial ICRS. +This overrides \texttt{mango:Footprint.spaceSys} reference which can be ignored when +using this serialisation. FootprintSerialization.STC-S STC-S - Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). -SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). -When using this serialisation, \texttt{spaceSys} can be ignored. + Label indicating that the footprint has been serialized as a STC-S string +(see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). +The STC-S space coordinate system overrides the \texttt{mango:Footprint.spaceSys} +reference which can be ignored when using this serialisation. +Although the STC-S standard has been an IVOA draft for many years, +it is still used by certain services, which justifies MANGO's support for it. FootprintSerialization.POLYGON @@ -261,7 +265,7 @@ flattened DataLink (1.1) responses. DataLink.content_type content_type - mime type of the content the link returns (see DataLink 1.1) + Provides the mime type of the content the link returns (see DataLink 1.1) ivoa:string @@ -273,7 +277,7 @@ flattened DataLink (1.1) responses. DataLink.access_url access_url - contains an URL for downloading a single resource. + Contains an URL for downloading a single resource. There is no restriction on the type of resource accessed by the links. ivoa:anyURI @@ -306,10 +310,8 @@ concept URIs will have to be used in this case. (DataLink 1.1) DataLink.local_semantics local_semantics - Allows for identification of corresponding rows -for different IDs in the same DataLink service where the combination of -semantics, content_type and content_qualifier is not sufficient to identify -them (see DataLink 1.1). + Allows for link identification where the combination of +semantics, content_type and content_qualifier is not sufficient (see DataLink 1.1). ivoa:string @@ -367,7 +369,8 @@ them (see DataLink 1.1). Property Property - Class holder for a \textit{flavor} of property’ ie: there should be a Property subclass for each \textit{flavor} of Property being hosted. + Class holder for a \textit{flavor} of property, i.e., there should be a Property subclass for each \textit{flavor} +of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself. @@ -375,19 +378,12 @@ This class specifies both type and role of the property, and hosts the property Property.semantics semantics Reference to a semantic concept giving the nature of the property -or of the set made of the property and its associated properties. +or of the set made of the property and its associated properties (e.g. position and flag). -The semantics field contains a URI for a concept that describes the meaning of the property. -This attribute is intended to be machine-readable and to assist automated link selection, -presentation, and usage. -The value is always interpreted as a URI; relative URIs (Berners-Lee and -Fielding et al., 2005) are completed using the base URI of the core DataLink -vocabulary, \url{http://www.ivoa.net/rdf/datalink/core}. Terms from this -vocabulary must always be written as relative URIs. -This means that for concepts from the core vocabulary, the value in the semantics fields always -starts with a hash. (datalink1.1). -The semantics concept applies to a single property or to the set made of the property and -its associated properties (e.g. position and flag). +This attribute is intended to be machine-readable and to assist automated property presentation, and usage. +The value is always interpreted as a URI; relative URIs are completed using the base URI of the core UAT +vocabulary, \url{http://www.ivoa.net/rdf/uat} (see \ref{sect:VocabularyTerm}). + mango:VocabularyTerm @@ -747,21 +743,21 @@ All components use the same coordinate systems for both time and space coordinat \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. - \item The space coordinate system is imported from \texttt{coords:spaceSys}. - \item The time coordinate system is imported from \texttt{coords:simeSys}. + \item The space coordinate system is imported from \texttt{coordsSpaceSys}. + \item The time coordinate system is imported from \texttt{coords:TimeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead -of the \texttt{epoch} field of \texttt{coords:spaceSys}. +of the \texttt{epoch} field of \texttt{coords:SpaceSys}. There are 2 reasons for this: \begin{itemize} - \item Using the epoch of \texttt{coords:spaceSys} requires to work with the + \item Using the epoch of \texttt{coords:SpaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. - \item the observation date can be read in a column and therefore change with each data row. - I this case, it cannot be stored as an element of the space coordinate system - but as an \texttt{EPochPosition} attribute. + \item The observation date can be read in a column and therefore change with each data row. + In this case, it cannot be stored as an element of the space coordinate system + but as an \texttt{EpochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. diff --git a/vo-dml/desc/desc.DataLink.access_url.txt b/vo-dml/desc/desc.DataLink.access_url.txt index 6a3c75d..bbca110 100644 --- a/vo-dml/desc/desc.DataLink.access_url.txt +++ b/vo-dml/desc/desc.DataLink.access_url.txt @@ -1,2 +1,2 @@ -contains an URL for downloading a single resource. +Contains an URL for downloading a single resource. There is no restriction on the type of resource accessed by the links. \ No newline at end of file diff --git a/vo-dml/desc/desc.DataLink.content_type.txt b/vo-dml/desc/desc.DataLink.content_type.txt index 9d1574c..64254b8 100644 --- a/vo-dml/desc/desc.DataLink.content_type.txt +++ b/vo-dml/desc/desc.DataLink.content_type.txt @@ -1 +1 @@ -mime type of the content the link returns (see DataLink 1.1) \ No newline at end of file +Provides the mime type of the content the link returns (see DataLink 1.1) \ No newline at end of file diff --git a/vo-dml/desc/desc.DataLink.local_semantics.txt b/vo-dml/desc/desc.DataLink.local_semantics.txt index 98836a1..09bb29b 100644 --- a/vo-dml/desc/desc.DataLink.local_semantics.txt +++ b/vo-dml/desc/desc.DataLink.local_semantics.txt @@ -1,4 +1,2 @@ -Allows for identification of corresponding rows -for different IDs in the same DataLink service where the combination of -semantics, content_type and content_qualifier is not sufficient to identify -them (see DataLink 1.1). \ No newline at end of file +Allows for link identification where the combination of +semantics, content_type and content_qualifier is not sufficient (see DataLink 1.1). \ No newline at end of file diff --git a/vo-dml/desc/desc.EpochPosition.txt b/vo-dml/desc/desc.EpochPosition.txt index e50fb27..dc6f57c 100644 --- a/vo-dml/desc/desc.EpochPosition.txt +++ b/vo-dml/desc/desc.EpochPosition.txt @@ -19,21 +19,21 @@ All components use the same coordinate systems for both time and space coordinat \begin{itemize} \item Both position and proper motion reuse \texttt{coords:LonLatPoint} elements. - \item The space coordinate system is imported from \texttt{coords:spaceSys}. - \item The time coordinate system is imported from \texttt{coords:simeSys}. + \item The space coordinate system is imported from \texttt{coordsSpaceSys}. + \item The time coordinate system is imported from \texttt{coords:TimeSys}. \end{itemize} It is recommended to use the \texttt{ObsDate} field to store the epoch of the observation instead -of the \texttt{epoch} field of \texttt{coords:spaceSys}. +of the \texttt{epoch} field of \texttt{coords:SpaceSys}. There are 2 reasons for this: \begin{itemize} - \item Using the epoch of \texttt{coords:spaceSys} requires to work with the + \item Using the epoch of \texttt{coords:SpaceSys} requires to work with the \texttt{coords:CustomRefLocation} class to carry the reference location. This class does not support the standard reference locations such as e.g. BARYCENTER. - \item the observation date can be read in a column and therefore change with each data row. - I this case, it cannot be stored as an element of the space coordinate system - but as an \texttt{EPochPosition} attribute. + \item The observation date can be read in a column and therefore change with each data row. + In this case, it cannot be stored as an element of the space coordinate system + but as an \texttt{EpochPosition} attribute. \end{itemize} All components have their own units which must be consistent with each other. diff --git a/vo-dml/desc/desc.FootprintSerialization.SMOC.txt b/vo-dml/desc/desc.FootprintSerialization.SMOC.txt index 37bac58..7491722 100644 --- a/vo-dml/desc/desc.FootprintSerialization.SMOC.txt +++ b/vo-dml/desc/desc.FootprintSerialization.SMOC.txt @@ -1,3 +1,4 @@ Label indicating that the footprint has been serialized as a SMOC \citep{2022ivoa.spec.0727F}. -SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). -When using this serialisation, \texttt{spaceSys} can be ignored. \ No newline at end of file +SMOC should be in equatorial ICRS. +This overrides \texttt{mango:Footprint.spaceSys} reference which can be ignored when +using this serialisation. \ No newline at end of file diff --git a/vo-dml/desc/desc.FootprintSerialization.STC-S.txt b/vo-dml/desc/desc.FootprintSerialization.STC-S.txt index 2cec987..d15c086 100644 --- a/vo-dml/desc/desc.FootprintSerialization.STC-S.txt +++ b/vo-dml/desc/desc.FootprintSerialization.STC-S.txt @@ -1,3 +1,6 @@ -Label indicating that the footprint has been serialized as a STC-S string (see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). -SMOC should be in equatorial ICRS. This overrides the attached space coordinate system (\texttt{spaceSys} reference). -When using this serialisation, \texttt{spaceSys} can be ignored. \ No newline at end of file +Label indicating that the footprint has been serialized as a STC-S string +(see \url{https://www.ivoa.net/documents/STC-S/20130917/index.html}). +The STC-S space coordinate system overrides the \texttt{mango:Footprint.spaceSys} +reference which can be ignored when using this serialisation. +Although the STC-S standard has been an IVOA draft for many years, +it is still used by certain services, which justifies MANGO's support for it. \ No newline at end of file diff --git a/vo-dml/desc/desc.Property.semantics.txt b/vo-dml/desc/desc.Property.semantics.txt index 6d55e21..f0772f6 100644 --- a/vo-dml/desc/desc.Property.semantics.txt +++ b/vo-dml/desc/desc.Property.semantics.txt @@ -1,14 +1,6 @@ Reference to a semantic concept giving the nature of the property -or of the set made of the property and its associated properties. +or of the set made of the property and its associated properties (e.g. position and flag). -The semantics field contains a URI for a concept that describes the meaning of the property. -This attribute is intended to be machine-readable and to assist automated link selection, -presentation, and usage. -The value is always interpreted as a URI; relative URIs (Berners-Lee and -Fielding et al., 2005) are completed using the base URI of the core DataLink -vocabulary, \url{http://www.ivoa.net/rdf/datalink/core}. Terms from this -vocabulary must always be written as relative URIs. -This means that for concepts from the core vocabulary, the value in the semantics fields always -starts with a hash. (datalink1.1). -The semantics concept applies to a single property or to the set made of the property and -its associated properties (e.g. position and flag). \ No newline at end of file +This attribute is intended to be machine-readable and to assist automated property presentation, and usage. +The value is always interpreted as a URI; relative URIs are completed using the base URI of the core UAT +vocabulary, \url{http://www.ivoa.net/rdf/uat} (see \ref{sect:VocabularyTerm}). diff --git a/vo-dml/desc/desc.Property.txt b/vo-dml/desc/desc.Property.txt index 3b9edb6..aab938d 100644 --- a/vo-dml/desc/desc.Property.txt +++ b/vo-dml/desc/desc.Property.txt @@ -1,3 +1,4 @@ -Class holder for a \textit{flavor} of property’ ie: there should be a Property subclass for each \textit{flavor} of Property being hosted. +Class holder for a \textit{flavor} of property, i.e., there should be a Property subclass for each \textit{flavor} +of Property being hosted. The property types are not limited to “physical or calculated” (eg: flags, assigned labels) This class specifies both type and role of the property, and hosts the property instance itself. diff --git a/vo-dml/desc/desc.iso.txt b/vo-dml/desc/desc.iso.txt index 03c88d6..8b120c9 100644 --- a/vo-dml/desc/desc.iso.txt +++ b/vo-dml/desc/desc.iso.txt @@ -1 +1 @@ -Primitive type for observation dates expressed as an ISO Date (e.g. "2025-08-07T09:29:14"). +Primitive type for observation dates expressed as an ISO-8601 Date (e.g. "2025-08-07T09:29:14").