Refine Use Cases and DataLink descriptions in UseCases.tex

UseCases.tex

@@ -100,7 +100,7 @@ \subsubsection{Use Case --- Search for event bundles via DataLink that include C
 AND (access_format = ’application/x-votable+xml;content=datalink’)
 \end{verbatim}
 
-Then, for each row of the output, we get the ``access\_url'' of the Obscore table to provide access to the data.
+Then, for each row of the output, we get access to a DataLink table (in VOTable) describing associated data linked to the event-list dataset using the ``access\_url'' column value of the response ObsCore table.
 
 
 \subsubsection{Use Case --- Search for event bundles that include Cas A for X-ray spectrophotometric evolution studies}
@@ -151,57 +151,41 @@ \subsubsection{Use Case --- Search for event lists and their \glspl{IRF} of CTAO
 AND (energy_max >= 1.0e+12)
 \end{verbatim}
 
-The query output is a VOTable that follows the DALI specification.
+The query output is a VOTable that follows the DataLink VO standard.
 
 We process this VOTABLE to access to the data:
 
 \begin{enumerate}[(i)]
-  \item for each row of the query output, get the ``obs\_id'' and the ``access\_url'' of the DataLink,
-  \item get the VOTABLE associated with the ``access'',
-  \item for each row of the VOTABLE, get the ``content\_qualifier'' and the ``access\_url'',
-  \item download the data associated to each ``accessURL''.
+  \item for each row of the query output, get the ``obs\_id'' and the ``access\_url'' of the DataLink describing the ObsCore dataset entry,
+  \item get the DataLink VOTable showing the datasets associated to this entry
+  \item for each row of the DataLink VOTable, get the ``content\_qualifier'' and the ``access\_url'' column's value,
+  \item download the data associated to each ``access\_url'' value.
 \end{enumerate}
-
-\begin{verbatim}
-FOR EACH ROW OF OUTPUT_VOTABLE:
-  OBS_ID = OUTPUT_VOTABLE['ID']
-  DATALINK_TABLE = GET OUTPUT_VOTABLE['access_url']
-  FOR EACH ROW OF DATALINK_TABLE:
-    - IF ROW['content_qualifier'] = 'aeff'
-    	AEFF_FILE['OBS_ID'] = GET RAW['accessURL']
-    - IF ROW['content_qualifier'] = 'edisp'
-    	EDISP_FILE['OBS_ID'] = GET RAW['accessURL']
-    - IF ROW['content_qualifier'] = 'psf'
-    	PSF_FILE['OBS_ID'] = GET RAW['accessURL']
-    - IF ROW['content_qualifier'] = 'bkgrate'
-    	BKGRATE_FILE['OBS_ID'] = GET RAW['accessURL']
-    - IF ROW['content_qualifier'] = 'event-list'
-    	EVENT_FILE['OBS_ID'] = GET RAW['accessURL']
-\end{verbatim}
+% removed pseudo code
 
 Table \ref{tab:datalink1} displays an example of the DataLink response table attached to such an event-list discovery.
 The obs\_publisher\_did of the single discovered event-list is repeated in the ID column of the DataLink table.
-Mandatory FIELDS service\_def and error\_messsage are omitted because they are empty
+Mandatory FIELDS service\_def and error\_messsage are omitted because they are empty.
 
 \begin{landscape}
 \begin{center}
 \begin{longtable}{|p{0.15\linewidth}|p{0.2\linewidth}|p{0.08\linewidth}|p{0.22\linewidth}|p{0.1\linewidth}|p{0.12\linewidth}|p{0.13\linewidth}|}
 \hline%\sptablerule
 \textbf{ID}  &\textbf{\footnotesize access\_url}  &\textbf{\footnotesize semantics}&\textbf{\footnotesize description} &\textbf{\footnotesize content\_type} &\textbf{\footnotesize content\_length} &\textbf{\footnotesize content\_qualifier}\cr
 \hline%\sptablerule
-{\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt1.ext1} & {\footnotesize \#this} & {\footnotesize event-list}  {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize text/xml} & {\footnotesize 1000000} & {\footnotesize event-list} \cr
+{\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt1.ext1} & {\footnotesize \#this} & {\footnotesize event-list}  {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize fits/table} & {\footnotesize 1000000} & {\footnotesize event-list} \cr
 \hline%\sptablerule
-{\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt2.ext2} & {\footnotesize \#calibration} & {\footnotesize Effective AREA of the telescope/instrument associated with the event-list}  {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize text/csv} & {\footnotesize 10000} & {\footnotesize aeff} \cr
+{\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt2.ext2} & {\footnotesize \#calibration} & {\footnotesize Effective AREA of the telescope/instrument associated with the event-list}  {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize OGIP-fits ?} & {\footnotesize 10000} & {\footnotesize aeff} \cr
 \hline%\sptablerule
-{\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt3.ext3} & {\footnotesize \#calibration} & {\footnotesize Energy dispersion of event-list}  {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize text/csv} & {\footnotesize 10000} & {\footnotesize edisp} \cr
+{\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt3.ext3} & {\footnotesize \#calibration} & {\footnotesize Energy dispersion of event-list}  {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize fits/table} & {\footnotesize 10000} & {\footnotesize edisp} \cr
 \hline%\sptablerule
 {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt4.ext4} & {\footnotesize \#calibration} & {\footnotesize Point spread function of event-list } {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize image/fits} & {\footnotesize 50000} & {\footnotesize psf} \cr
 \hline%\sptablerule
 {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize https://xxx.yyy/zzz/ttt5.ext5} & {\footnotesize \#calibration} & {\footnotesize Background rate of  event-list } {\footnotesize ivo://xxx/yyy/zzz\#ttt} & {\footnotesize text/csv} & {\footnotesize 1000} & {\footnotesize bkgrate} \cr
 \hline%\sptablerule
 
-\caption{DataLink response table attached to an event-list  record in ObsCore.}
-
+\caption{DataLink response table attached to an event-list record in ObsCore.}
+% mireille we should use a real example like one of the response from M. Servillat's ObsTap service for HESS data.
 
 \label{tab:datalink1}
 \end{longtable}
@@ -218,7 +202,7 @@ \subsubsection{Use Case --- Search for spatially resolved spectropolarimetric ob
   \item Target name = ``Crab'' or position inside 5 arcmin from (83.6324, $+22.0174$),
   \item dataproduct\_type = ``event-bundle'',
   \item calib\_level $\geq 2$,
-  \item s\_resolution $> 100$,
+  \item em\_res\_power $> 100$,
   \item energy\_min $< 100000$,
   \item energy\_max $> 1000$,
   \item o\_ucd contains ``phys.polarization'',
@@ -233,7 +217,7 @@ \subsubsection{Use Case --- Search for spatially resolved spectropolarimetric ob
 CONTAINS(POINT(s_ra, s_dec), CIRCLE(83.6324, +22.0174, 0.083333)) = 1)
 AND (dataproduct_type = 'event-bundle')
 AND (calib_level >= 2)
-AND (s_resolution > 100)
+AND (em_res_power > 100)
 AND (energy_min < 100000.0) AND (energy_max >= 1000.0)
 AND (o_ucd LIKE '%phys.polarization%')
 AND (o.ucd LIKE '%pos.eq%')
@@ -337,6 +321,8 @@ \subsubsection{Use Case --- Retrieve the instrument response functions for a com
 AND (event_type = 'track')
 \end{verbatim}
 
+% mireille : this query searches in KM3net data collection, but should it be also sent to a CTA archive in order to build the comparison? 
+
 \subsubsection{Use Case --- Study the combined neutrino flux for the Galactic plane}
 
 {\em Identify all neutrino data sets in the region of the Galactic plane to perform a combined neutrino flux study extending a study like the IceCube \textbf{Observation of high-energy neutrinos from the Galactic plane. DOI: 10.1126/science.adc9818}, using event lists and IRFs of datasets optimized for the analysis of diffuse neutrino emission.}
@@ -406,11 +392,13 @@ \subsubsection{Use Case --- Search for Chandra Source Catalog position error MCM
 AND (dataproduct_subtype = 'poserr')
 AND (obs_collection = 'CSC2')
 \end{verbatim}
+% mireille naive question: do we really need the join with the ivoa.obscore_hea table ? 
+% constraints on event_type would require it 
 
 
 \subsubsection{Use Case --- Search for flux maps for CTAO-North observations between two observations ID}
 
-{\em Identify all flux maps from the observation of CTAO-North between selected observation identifiers selected by the user .\/}
+{\em Identify all flux maps from the CTAO-North data collection within a range of observation identifiers selected by the user .\/}
 
 \medskip
 \noindent Find all datasets satisfying:
@@ -440,13 +428,17 @@ \subsubsection{Use Case --- Search for M31 source light curves and aperture phot
 
 {\em Identify all light curves and aperture photometry probability density functions of X-ray sources detected in the field of M31 covering the energy range 0.3--7.0 keV that include observation data in the interval MJD 56320--56325 TT during which interval a transient event was thought to have occurred.  Because the data products are expected to include extremely sparse time axes, the t\_intervals TMOC must be used for the query.\/}
 
+%mireille
+%\TODO{when data product is light-curve, use the new term "light-curve" of the product-type vocabulary instead of "timeseries" which is the top concept in the vocabulary. This vocabulary should be adopted for the new implementations of ObsCore 1.1 and the next versions. }
+
 \medskip
 \noindent Find all datasets satisfying:
 \begin{enumerate}[(i)]
   \item Position within 1.5 degrees from (10.6847, $+41.2688$),
-  \item dataproduct\_type = ``timeseries'' {\em or\/} ``pdf'',
+  \item dataproduct\_type = ``light-curve'' {\em or\/} ``pdf'',
   \item calib\_level = 4,
-  \item energy\_min $\leq 0.3$ {\em and\/} energy\_max $\geq 7.0$,
+ % mireille \item energy\_min $\leq 0.3$ {\em and\/} energy\_max $\geq 7.0$,
+   \item energy\_min $\geq 0.3$ {\em and\/} energy\_max $\leq 7.0$,
   \item t\_intervals TMOC intersects\footnote{We note that this function does not yet exist in ADQL} MJD 56320--56325 TT.
 \end{enumerate}
 
@@ -456,7 +448,7 @@ \subsubsection{Use Case --- Search for M31 source light curves and aperture phot
 NATURAL JOIN  ivoa.obscore_hea
 WHERE
 (CONTAINS(POINT(s_ra, s_dec), CIRCLE(10.6847, +41.2688, 1.5)) = 1)
-AND ((dataproduct_type = 'timeseries') OR (dataproduct_type = 'pdf'))
+AND ((dataproduct_type = 'light-curve') OR (dataproduct_type = 'pdf'))
 AND (calib_level = 4)
 AND (energy_min <= 300.0) AND (energy_max >= 7000.0)
 AND (INTERSECTS(TMOC(17, t_intervals), TMOC(17, 56320.0, 56325.0)) = 1)
@@ -482,9 +474,9 @@ \subsubsection{Use Case --- Search for the CTAO flux light curves of PKS 2155-30
 WHERE
 (dataproduct_type = 'light-curve')
 AND (obs_collection = 'CTAO-DR1'
-AND t_min >= 62502
-AND t_max <= 62866
-AND target_name = 'PKS 2155-304'
+AND (t_min >= 62502)
+AND (t_max <= 62866)
+AND target_name = 'PKS 2155-304')
 \end{verbatim}
 
 %\subsubsection{Use Case --- Search for the \glspl{IRF} for a given direction and observation duration regardless of a neutrino event observation}