2023 and before 1 changes

Makefile

@@ -4,13 +4,13 @@
 DOCNAME = SODA
 
 # count up; you probably do not want to bother with versions <1.0
-DOCVERSION = 1.0
+DOCVERSION = 1.1
 
 # Publication date, ISO format; update manually for "releases"
-DOCDATE = 2017-05-17
+DOCDATE = 2024-05-23
 
 # What is it you're writing: NOTE, WD, PR, or REC
-DOCTYPE = REC
+DOCTYPE = WD
 
 [email protected]
 

SODA.tex

@@ -412,24 +412,52 @@ \subsubsection{ID}
 The UCD describing the ID parameter is
 \ucd{meta.ref.url;meta.curation}.SODA
 
-\subsection{Filtering Parameters}
+\subsubsection{RESPONSEFORMAT}
+\label{sec:FORMAT}
 
-Filtering parameters are used to extract subsets of large
-datasets or data files. The extraction uses a best possible match to the requested subset. In case the parameter values excede the size of the archived dataset  the service operates a reduction of these values to the archived dataset size.
+This optional parameter allows format conversion. By default the native format is kept. Values taken by this parameter will be the media types of the target format. \\
+Examples: 
+\begin{itemize}
+\item Conversion of a FITS image to png: 
+\begin{lstlisting}
+RESPONSEFORMAT="image/png"
+\end{lstlisting}
+\item Conversion of one or several FITS images or cubes to HiPS format. 
+\begin{lstlisting}
+RESPONSEFORMAT="application/hips"
+\end{lstlisting}
+\item And the reverse conversion: 
+\begin{lstlisting}
+RESPONSEFORMAT="application/fits"
+\end{lstlisting}
+\end{itemize}
 
-\subsubsection{MOC}
-The MOC parameter defines a subset of space using the \xtype{moc} defined in DALI. The parameter syntax is defined as in the MOC specification \citep{MOC2}
+The format conversion can be done in combination with the filtering or the transformation described below. When a conversion is not made available by the service or is  impossible the service MUST answer by an error message stating "Format transformation not available". By default there will be no format conversion.
 
-Examples :
-\begin{itemize}
+Conversion to the hips format requires the transformation from any sky projection to HPX. Any other provided PROJECTION value MUST be ignored. In the same conversion to hips case, the  SODA response provides the URL to the top of the HiPS directory.
 
-\item Extracting cells 1 and 2 at order 1 will read this way MOC = 1/1 2
-\item Extracting cells 1 at order 1 and cells 1 to 6 at order 2 will read MOC = 1/1 2/1-6
+\subsubsection{METADATA}\label{sec:METADATA}
+This optional parameter allows to provide dataset metadata instead of an excerpt of the dataset itself. It allows to retrieve the metadata consistent with a specific   datamodel given by its standardID or a FITS header for the "headder" value.  All SODA service MUST be able to provide at least the Obscore metadata. Other datamodels are possible.
 
-\end{itemize}
+This parameter can be used in combination with filtering or transformation parameters in such a way that the metadata describe the filtered or transformed dataset.
+
+ The "none" value for this parameter will drive the excerpt of data as in version 1.0 of the SODA specification. The default value fo this parameter is "None". 
+
+ Example - for a FITS header : 
+\begin{lstlisting}
+METADATA="header"
+\end{lstlisting} 
+
+
+
+
+
+\subsection{Filtering Parameters}
+
+Filtering parameters are used to extract subsets of large
+datasets or data files. The extraction uses a best possible match to the requested subset. In case the parameter values excede the size of the archived dataset  the service operates a reduction of these values to the archived dataset size.
 
 
-At the time of writing there is no possibility to extend this ascii syntax to TMOC or STMOC
 
 \subsubsection{POS}
 \label{sec:POS}
@@ -516,6 +544,20 @@ \subsubsection{POS}
 service descriptor; either POS is included or not and if included then
 all keywords must be supported.
 
+\subsubsection{MOC}
+The MOC parameter defines a subset of space using the \xtype{moc} defined in DALI. The parameter syntax is defined as in the MOC specification \citep{MOC2}
+
+Examples :
+\begin{itemize}
+
+\item Extracting cells 1 and 2 at order 1 will read this way MOC = 1/1 2
+\item Extracting cells 1 at order 1 and cells 1 to 6 at order 2 will read MOC = 1/1 2/1-6
+
+\end{itemize}
+
+
+At the time of writing there is no possibility to extend this ascii syntax to TMOC or STMOC
+
 \subsubsection{CIRCLE} 
 \label{sec:CIRCLE}
 
@@ -542,16 +584,14 @@ \subsubsection{POLYGON}
 Example: a  polygon from (12,34) to (14,34) to (14,36) to (12,36) and
 (implicitly) back to (12,34):
 
-\begin{lstlisting}
-POLYGON=12 34 14 34 14 36 12 36
-\end{lstlisting}
 
 The UCD describing the POLYGON parameter is
 \ucd{pos.outline;obs}.
 
 POLYGON is equivalent in functionality to \texttt{POS=POLYGON ...}.  Data type  and unit metadata are unambiguously defined.
 
 
+
 \subsubsection{BAND}
 \label{sec:BAND}
 
@@ -667,6 +707,95 @@ \subsubsection{POL}
 The UCD  describing the POL parameter is
 \ucd{meta.code;phys.polarization}.
 
+\subsubsection{PIXELS}
+\label{sec:PIXELS}
+The PIXELS parameter defines a subpart of the dataset to be extracted following the fitsio syntax. 
+It is also possible to extract only every pixel upon n. Supporting PIXELS in the same query with spatial, spectral or time filtering
+parameters is optional and SHOULD be interpreted within the scope of PARAMETER multiplicity\\
+Examples :
+
+\begin{itemize}
+\item pixels 50 to 70 in x and 200 to 300 in y from a 2D image 
+\begin{lstlisting}
+PIXELS=[50:70,200:300]
+\end{lstlisting}
+
+\item pixels 50 to 70 in x, 200 to 300  in y and all pixels in z  from a 3D cube
+\begin{lstlisting}
+PIXELS=[50:70,200:300,*]
+\end{lstlisting}
+
+\item every even pixel from 50 to 70 in x, 200 to 300  in y and every pixel upon 10 between 100 and 1500 in z   from a 3D cube
+\begin{lstlisting}
+PIXELS=[50:70:2,200:300:2,100:1500:10]
+\end{lstlisting}
+
+\end{itemize}
+
+\subsection{Transform parameters}
+
+This subsection is an addition of the current specification. The parameters described here were not present in SODA version 1.0. they define together a sODA service capability which is optional for a SODA service.
+
+\subsubsection{DPTYPE}
+\label{sec:DPTYPE}
+This optional  parameter allows to modify the product type of the output dataset. Typical case is to reduce a spectral subcube to a 2D image or a spectrum. DPTYPE allowed values are taken from the dataproduct\_type vocabulary. This parameter is binded to the filtering parameters which define the ranges and area in which to sum up the dataset measurements to achieve the dimensionality reduction. 
+\begin{lstlisting}
+DPTYPE="spectrum"&POS=POLYGON 50.5 27.2 50.7 27.2 50.7 27.6 50.5 27.6
+\end{lstlisting}
+
+For a cube, SODA operation above  will sum up all spectra inside the spatial coverage, while the same query parameters with DPTYPE=cube (which is the default) will produce a cube spatial cutout. In the case of dimensionality reduction the corresponding resolution transform parameter MUST be ignored.
+
+\begin{lstlisting}
+DPTYPE="image"&BAND=0.1 0.4
+\end{lstlisting}
+For a cube, SODA operation above will sum up all channels inside the spectral bounds, while the same query parameters with DPTYPE=cube will produce a cube spectral cutout.  
+
+In the case of dimensionality reduction the corresponding appropriate resolution transform parameter (SPATRES,SPECRP) MUST be ignored.
+
+\subsubsection{SPATRES}
+
+
+Implementation of this parameter is optional. Using a SPATRES value different from the original spatial resolution makes the service to rebin the data in order to match the spatres value. The parameter unit is arcsec.  
+
+Example : SPATRES = 3  
+
+This statement resquests a response dataset with spatial resolution equal to 3 arcsec.
+
+\subsubsection{SPECRP}
+
+Implementation of this parameter is optional. Using a SPECREC value different from the original spectral resolving power makes the service to rebin the data in order to match the specrp resolution power value. The parameter is uniless.  
+
+Example : SPECRP = 1000  
+
+This statement resquests a response dataset with spectral resolving power  equal to 1000.
+
+\subsubsection{TIMERES}
+
+Implementation of this parameter is optional. Using a TIMERES value different from the original time resolution  makes the service to rebin the data in order to match the timeres value. The parameter unit is seconds.  
+
+Example : TIMERES = 0.001  
+
+This statement resquests a response dataset with time resolution equal to 1 ms.
+
+\subsubsection{PROJECTION}
+
+Implementation of this parameter is optional. Using a PROJECTION value different from the original sky projection of the data makes the service repoject the data onto the requested sky projection. The possible values of this parameter is similar to the list of WCS projections and expressed with the 3 lettre WCS projection code.
+
+Example PROJECTION = SIN
+
+This statement requests a response dataset reprojected using the sinus sky projection.
+
+\subsubsection{ROTATION}
+
+Implementation of this parameter is optional. Using a ROTATION value different from the original rotation of the vertical axis of the data with respect to the North makes the service rotate the data in order to match  the requested position angle. The  parameter unit is in degree and is in the range -180 to +180.
+
+Example ROTATION = 50.0
+
+This statement requests a response dataset rotated 50 degrees towards East.
+
+
+
+
 
 \subsection{Filtering parameters and ObsCore data model}