Merge pull request #97 from lmichel/FB_Review

FB review

Author: lmichel

doc/MANGO.tex

@@ -9,7 +9,7 @@
 \setlength\extrarowheight{2pt}
 
 \newcolumntype{L}{>{\centering\arraybackslash}m{3cm}}
-\title{MANGO: A Model for ANnotating Generic Objects}
+\title{MANGO: Metadata ANnotation for Generic Objects}
 
 % see ivoatexDoc for what group names to use here
 \ivoagroup{DM}
@@ -116,8 +116,8 @@ \section{Introduction}
 DM working group and more generally for the IVOA.
 In the past years, there were some proposals to design a global model for sources \citep{wd:jesusdm}
 as well as for catalogs \citep{wd:catalog}.
-Other proposals, more model-agnostic, were focused on the data annotation in VOTables
-\citep{note:stcvot} \citep{note:seb}.
+Other proposals based on models (STC1.33, PhotDM1.0) that were not machine-readable, focused on data annotation in 
+VOTables \citep{note:stcvot} \citep{note:seb}.
 In this case the goal was no longer to design a source model but to provide a complete description of
 individual quantities (positions, velocity, fluxes, magnitudes…).
 None of these proposals has come to completion due to the complexity of the task.
@@ -169,8 +169,8 @@ \subsection{Use Cases}
 \subsection{Requirements}
 
 From the above list of use-cases, we have identified 4 domains for which
-the model should provide added value: 1) nature of supported quantities 2) data description enhancement,
-3) description of quantities consisting of several columns and 4) connected quantities.
+the model should provide added value: 1) nature of supported quantities 2) enhancement of the data description,
+3) description of quantities consisting of several columns and 4) connection of different quantities.
 
 
 \begin{itemize}
@@ -223,7 +223,7 @@ \subsection{Requirements}
                 This feature is required to compare positions given by surveys with high astrometry accuracy such as GAIA.
        \end{itemize} 
 
-    \item Connected quantities : 
+    \item Connection of quantities : 
        \begin{itemize}[noitemsep,topsep=0pt,parsep=0pt,partopsep=0pt]
            \item MANGO must be able to setup links between different properties of the same table. 
                  This can be relevant for instance for attaching detection likelihoods with source positions
@@ -244,7 +244,7 @@ \section{Model Overview}
 \end{figure}
 
 
-The root class of the model \texttt{MANGOObject} which has only
+The root class of the model \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.
@@ -289,7 +289,7 @@ \subsection{Properties}
  \hline
  \texttt{EpochPosition} & Grouping of position with velocity and time & Parameters to solve the epoch propagation case\\  
  \hline
- \texttt{Magnitude} & Flux or Magnitude & many \\ 
+ \texttt{Brightness} & Flux or Magnitude & many \\ 
  \hline
  \texttt{Color} & Hardness ratio or magnitude ratio & many  \\ [1ex] 
  \hline

doc/Makefile

@@ -4,10 +4,10 @@
 DOCNAME = MANGO
 
 # count up; you probably do not want to bother with versions <1.0
-DOCVERSION = 0.1
+DOCVERSION = 1.0
 
 # Publication date, ISO format; update manually for "releases"
-DOCDATE = 2025-06-06
+DOCDATE = 2025-06-20
 
 # What is it you're writing: NOTE, WD, PR, REC, PEN, or EN
 DOCTYPE = PR

doc/ivoatexmeta.tex

@@ -1,7 +1,7 @@
 % GENERATED FILE -- edit this in the Makefile
-\newcommand{\ivoaDocversion}{0.1}
-\newcommand{\ivoaDocdate}{2025-06-06}
-\newcommand{\ivoaDocdatecode}{20250606}
+\newcommand{\ivoaDocversion}{1.0}
+\newcommand{\ivoaDocdate}{2025-06-20}
+\newcommand{\ivoaDocdatecode}{20250620}
 \newcommand{\ivoaDoctype}{PR}
 \newcommand{\ivoaDocname}{MANGO}
 \renewcommand{\ivoaBaseURL}{https://www.ivoa.net/documents/MANGO}

doc/mango.frame.SUM_FLAG.xml

@@ -0,0 +1,24 @@
+<INSTANCE dmtype="mango:StatusValues" dmid="CoordSystem_SUM_FLAG_id" >
+    <COLLECTION dmrole="mango:StatusValues.values">
+      <INSTANCE dmrole="" dmtype="mango:StatusValue">
+         <ATTRIBUTE dmrole="mango:StatusValue.value" dmtype="ivoa:integer" value="0" />
+         <ATTRIBUTE dmrole="mango:StatusValue.description" dmtype="ivoa:string" value="Good Detection" />
+      </INSTANCE>
+      <INSTANCE dmrole="" dmtype="mango:StatusValue">
+         <ATTRIBUTE dmrole="mango:StatusValue.value" dmtype="ivoa:integer" value="1" />
+         <ATTRIBUTE dmrole="mango:StatusValue.description" dmtype="ivoa:string" value="Source parameters may be affected " />
+      </INSTANCE>
+      <INSTANCE dmrole="" dmtype="mango:StatusValue">
+         <ATTRIBUTE dmrole="mango:StatusValue.value" dmtype="ivoa:integer" value="2" />
+         <ATTRIBUTE dmrole="mango:StatusValue.description" dmtype="ivoa:string" value="Possibly spurious" />
+      </INSTANCE>
+      <INSTANCE dmrole="" dmtype="mango:StatusValue">
+         <ATTRIBUTE dmrole="mango:StatusValue.value" dmtype="ivoa:integer" value="3" />
+         <ATTRIBUTE dmrole="mango:StatusValue.description" dmtype="ivoa:string" value="Area where spurious detection may occur" />
+      </INSTANCE>
+      <INSTANCE dmrole="" dmtype="mango:StatusValue">
+         <ATTRIBUTE dmrole="mango:StatusValue.value" dmtype="ivoa:integer" value="4" />
+         <ATTRIBUTE dmrole="mango:StatusValue.description" dmtype="ivoa:string" value="Possibly spurious and area where spurious detection may occur" />
+      </INSTANCE>
+   </COLLECTION>
+</INSTANCE>

doc/model.tex

@@ -352,7 +352,7 @@ \section{Model: mango }
 
   \subsection{Footprint}
   \label{sect:Footprint}
-    Description of the spatial extent of the MANGO object (e.g. for dust clouds). Footprint is serialized as a string. \begin{itemize} \item The supported serialization modes are listed in the \texttt{ShapeSerialization} enumeration. \item If the space coordinate system is not embedded in the serialization mode, it can be defined by the \texttt{spaceSys} reference. \end{itemize}
+    Description of the spatial extent of the MANGO object (e.g. for dust clouds). Footprint is serialized as a string. \begin{itemize} \item The supported serialization modes are listed in the \texttt{FootprintSerialization} enumeration. \item If the space coordinate system is not embedded in the serialization mode, it can be defined by the \texttt{spaceSys} reference. \end{itemize}
 
     \subsubsection{Footprint.serialization}
       \textbf{vodml-id: Footprint.serialization} \newline

doc/model_toc.tex

@@ -498,7 +498,7 @@ \section{Other Properties}
 
   \subsection{Footprint}
     \label{sect:Footprint}
-    Description of the spatial extent of the MANGO object (e.g. for dust clouds). Footprint is serialized as a string. \begin{itemize} \item The supported serialization modes are listed in the \texttt{ShapeSerialization} enumeration. \item If the space coordinate system is not embedded in the serialization mode, it can be defined by the \texttt{spaceSys} reference. \end{itemize}
+    Description of the spatial extent of the MANGO object (e.g. for dust clouds). Footprint is serialized as a string. \begin{itemize} \item The supported serialization modes are listed in the \texttt{FootprintSerialization} enumeration. \item If the space coordinate system is not embedded in the serialization mode, it can be defined by the \texttt{spaceSys} reference. \end{itemize}
 
     \subsubsection{Footprint.serialization}
     \textbf{vodml-id: Footprint.serialization} \newline

doc/usecase_xmatch.tex

@@ -12,7 +12,7 @@
 In the latter case (cross-match between two tables taking into account positional errors),
 the tool needs to be able to retrieve the errors associated to the each position in each table.
 
-UCDs may help in identifying the errors associated to a positional columns as shown in table \ref{tbl::pos-errors}.
+UCDs may help in identifying the errors associated positional columns as shown in table \ref{tbl::pos-errors}.
 
 
 \begin{table}[!htbp]

doc/usecases.tex

@@ -38,10 +38,10 @@ \subsubsection{GAIA}
 
 \subsubsection{Euclid}
 The Euclid telescope has been designed to unveil some of the questions about the
-dark Universe, including dark matter and dark energy, what would include, f.i
+dark Universe, including dark matter and dark energy, what would include, for instance,
 quite accurate measurements of the expansion of the Universe.
 
-Euclid will mainly observe extragalactic objects providing, f.i information
+Euclid will mainly observe extragalactic objects providing, for instance, information
 about the shapes of galaxies, gravitational lensing, baryon acoustic oscillations
 and distances to galaxies using spectroscopic data.
 
@@ -66,6 +66,7 @@ \subsubsection{Euclid}
     \item correlation with other catalogues
     \item photometry (ground + satellite )
     \item morphology class
+    \item footprint
     \item redshift
     \item photometric redshift
 \end{itemize}
@@ -77,13 +78,12 @@ \subsubsection{Exoplanets}
 The use cases identified requires the following metadata:
 \begin{itemize}[noitemsep,topsep=0pt,parsep=0pt,partopsep=0pt]
 	\item the degree of confidence in the detection: exoplanets candidates
-w.r.t. confirmed ones, plus last update of the record content ;
+          with respect to confirmed ones, plus last update of the record content ;
 	\item the method used in the discovery (since it affects the available
-stellar system description parameters);
+          stellar system description parameters);
 	\item a set of stellar host characteristics (besides sky coordinates):
-activity, mass, type,
-metallicity, age, some systemic values, like the global RV (radial
-velocity) of the system, and so on;
+          activity, mass, type, metallicity, age, some systemic values,
+          like the global RV (radial velocity) of the system, and so on;
 	\item (exo-)planet parameters, like mass, orbital period, orbit's
 eccentricity, RV semi-amplitude, time at periastron (for RV detections)
 or central transit time (for transit method), longitude of periastron,
@@ -173,11 +173,11 @@ \subsubsection{Vizier catalog archive}
 to make those understandable/interoperable for a wide panel of VO-compliant clients.
 
 \subsubsection{Client Use-cases}
-Right now, the meta-data provided within the VOTable allow client software such Aladin or Topcat to run most 
+Right now, the meta-data provided within the VOTable allow client software such as Aladin or Topcat to run most 
 of the functionalities expected by the user, either for data analysis or plotting.
 This information is often inferred from UCDs, UTypes or column names. It can also be given by the user.
-Client applications do not require working with full model instances but in some cases models 
-can make it explicit how quantities in an input table relate to each other.
+Client applications do not require the use of full model instances, but in some cases,
+models can make explicit the relationships between quantities in an input table.
 
 Most cases are oriented towards interpretation of columns for visualization, e.g.:
 \begin{itemize}[noitemsep,topsep=0pt,parsep=0pt,partopsep=0pt]
@@ -209,7 +209,7 @@ \subsubsection{Client Use-cases}
      associated errors and correlation coefficients)
 
     \item what is the error ellipse/oid to use for a sky/Cartesian crossmatch
-    (what columns provide the relevant errors and, if available,
+    (which columns provide the relevant errors and, if available,
      correlations)
 \end{itemize}
 
@@ -235,6 +235,6 @@ \subsubsection{Xmatch tool }
 In the latter case (cross-match between two tables taking into account positional errors),
 the tool needs to retrieve the errors associated to the each position in each table.
 
-UCDs may help in identifying the errors associated to a positional columns, 
+UCDs may help in identifying the errors associated to positional columns, 
 %as shown in table
 but this is not sufficient for tables with more complex cases based on multi-parameter cases.