More comments on the draft

[iannevans]

Folks,

I've only had time to review the latest draft through the end of section 4 so far (i.e., prior to the Oct 30 meeting), which gets me about halfway through the document pages. I have a fairly extensive list of comments below. Most of them correct typos, or are grammatical updates, wordsmithing, or more precisely making certain statements within the document. However, there are a number of substantive comments included as well. I expect to continue reviewing the current draft from section 5 onwards over the next several days, and will likely have a similar density of comments.

My plan is to collect up all my comments into a single PR and submit that sometime next week.

Thanks,
--Ian

Page 1 - Update Date in Makefile.

Page 1 - Check author list (for example, I believe it should be "C. Boisson").

Page 5 - "It implies" --> "This requires".

Page 5 - Definitions of X-ray and gamm-ray energies are wrong. Change "(from ~0.1 eV to ~100 keV)" --> "(from ~0.1 keV" to 120 keV)" and "(from 100 MeV" --> "(from 120 keV". The soft gamma ray low energy should match the hard X-ray high energy.

Page 5 - "or other messenger" --> "or other messengers".

Page 5 - "(e.g. CIAO" --> "({\em e.g./}, CIAO".

Page 6 - "Universe" --> "universe".

Page 6 - Footnote "One can cite" --> "For example,".

Page 6 - Footnote "As opposed to signal integrating using a light detector." --> "As opposed to signal integrating ({\em e.g./}, using a photon detector).

Page 6 - "astronomical particle" --> "particle from an astrophysical source". Background counts can also have an astrophysical origin.

Page 6 - End of first paragraph, need to change "{\em event list/}." to "{\bf event-list}." or introduce the terminology we use in the document, for example "{\em event list/}, which we term an {\bf event-list} in this document.".

Page 6 - "{\bf event-lists}" --> "{\bf event-list}s" (two locations).

Page 6 - "The mappings between the observables and physical measurements of the source properties are called IRFs\footnote{...}; using techniques like forward-folding, they enable one to fit a model (with any combination of spectral, spatial, and temporal components) of the true flux of particles from a source arriving at the instrument to the measured quantities."
-->
"The mappings between physical measurements of the source properties and the observables are called Instrument Response Functions (IRFs\footnote{...}). Some IRFs are probabilistic in nature\footnote{...}, and in addition may depend on the set of events selected for analysis by the end user. They are usually not invertible, so methods such as forward-folding fitting (using source models with any combination of spectral, spatial, temporal, and/or polarization components that are estimated) are needed to estimate physical properties, such as the true flux of particles from a source arriving at the instrument, given the measured observable quantities.".

Page 6 - Delete "Some of the IRFs are probabilistic ... physical properties given observables.".

Page 6 - "are required to process HEA data" --> "are required to analyze HEA data".

Page 6 - "density funtion" --> "density function.".

Page 7 - "must be be modified" --> "must be modified".

Page 7 - 'are set to "-1"' --> 'set to "-1"; i.e., remove the "are".

Page 7 - "In addition, the hereafter modification proposal faces to the issue that some values of ObsCore attributes (dataproduct_type and calib_level) are defined both into the ObsCore standard document (Louys and Tody et al., 2017) and in the vocabularies documents (Demleitner and Gray et al., 2023, 2021), which might create some issues for the users. In this context, we have opted to propose in this document some modifications of both standards, even if we would have prefered that everything is uniquely defined in the IVOA Vocabulary. Some harmonization should be taken by the Data Model and Semantics working groups in order to avoid duplications. But until such work is achieved, we require modifications in ObsCore and Vocabulary."
-->
"Currently, some ObsCore attributes (dataproduct_type and calib_level) are formally defined in the ObsCore Recommendation Version 1.1 (Louys and Tody et al., 2017) and also in the vocabularies documents (Demleitner and Gray et al., 2023, 2021)\footnote{Primarily the Data Product Type Vocabulary, \url{https://www.ivoa.net/rdf/product_type}}, which may be referenced in future versions of the ObsCore Recommendation. For completeness, we are proposing in this document modifications to both the existing ObsCore Recommendation and IVOA vocabularies."
It's not our place to be telling the DM & Semantics WGs what they should be doing except in the sense of what is needed for HEA data discovery, and is inappropriate in this document.

Page 7 - After the 1st paragraph under 3.1 dataproduct_type, add "The modifications/additions to the set of ObsCore Recommendation Version 1.1 (Louys and Tody et al., 2017) {\em dataproduct_type/} (and, in some cases, {\em dataproduct_subtype/}) terms described herein apply equally to the IVOA Data Product Type Vocabulary, and will therefore be reperated in \S~5.". You want this here so you don't have to restate the same thing for each new dataproduct_type.

Page 8 - "The ObsCore v1.1 recommendation (Louys and Tody et al., 2017) only defines an event dataproduct_type as:" --> "The ObsCore Recommendation Version 1.1 (Louys and Tody et al., 2017) defines an event dataproduct_type as:"; i.e., remove the "only".

Page 8 - "We propose to add the following dataproduct_type term in both the ObsCore standard and into the IVOA Vocabulary of Data Product Types\footnote{...} to better define a HEA event-list and an event-bundle that includes the event-list and its associated data:"
-->
"We propose to add the following dataproduct_type terms to ObsCore to better define a HEA event-list and an event-bundle that includes the event-list and its associated data:"; also here verify that ObsCore is hyphenated correctly if necessary.

Page 8 - 'the term "event"' --> 'the term {\bf event}'.

Page 8 - "(e.g. VOEvent)" --> "({\em e.g./}, VOEvent)".

Page 8 - 'Using "event-list"' --> 'Using {\bf event-list}'.

Page 9 - "{\bf response-functions}" --> "{\bf response-function}s".

Page 10 - '{\bf dataproduct_type} = "measurements"' --> '{\em dataproduct_type/} = {\bf measurements}'.

Page 10 - "together with" --> "{\bf together} with".

Page 10 - Delete "Note that ... sub-section."

Page 10 - "in section 5" --> "in \S~5".

Page 10 - "In X-ray, this is" --> "This is"; doesn't just apply to X-ray - there are gamma-ray missions that are similar because the spacecraft pointing is not constant during the exposure.

Page 11 - "number of HE data products" --> "number of HEA data products".

Page 11 - "(e.g. to the" --> "({\em e.g./}, to the".

Page 11 - "(e.g. response-functions)." --> "({\em e.g./}, {\bf response-function}s).".

Page 11 - "If DataLink is provided, it should be indicated that the URL points to a Datalink service via the access_format = application/x-votable+xml;content=datalink."
-->
"If a DataLink is provided, {\em access_format/} should be set to ``application/x-votable+xml;content=datalink'' to indicate that the URL points to a DataLink service."

Page 11 - "(especially when the tracking is not fixed in the ICRS system)." --> "(especially when not tracking at sidereal rate or for facilities for which the PSF varies strongly across the telescope field of view)."

Page 12 - "), then we recommend" --> "), we recommend" (two locations).

Page 12 - "do not not encode" --> "do not encode".

Page 13 - "), then we recommend" --> "), we recommend".

Page 13 - "o_ucd=pos.eq,time,phys.pulseHeight." --> "{\em o_ucd=pos.eq;time;phys.pulseHeight/}.".

Page 14 - "{\bf event-lists}s table)." --> "{\bf event-lists}'s table).".

Page 14 - "spatial resolution and sky coverage, and spectral resolution, can" --> "spatial resolution, sky coverage, and spectral resolution can".

=Page 16 - "Since HEA telescopes are event-counting instruments, data can be accumulated even if the pointing moves or rotates relative to the sky during an observation. However, they way in which this happens has an impact on how the data are later processed.'
-->
"Since most HEA facilities record the arrival times of particle events, data accumulated when the telescope pointing moves or rotates relative to the sky during an observation can be located on the sky. The way in which the telescope moves may impact how the data should be processed, especially for observations in which multiple different astrophysical sources may be present within the field of view ({\em e.g./}, a solar system target moving relative to the fixed celestial background).".

Page 16 - "what the center of the field-of view moves with during an observation:" --> "the normal motion of the optical axis of the telescope during an observation:".

Page 16 - 'a "drift scan",' --> "a ``drift scan'',".

Page 16 - "fixed to a celestial body position like a planet or moon, or with no particular fixed coordinate system such as data taken when the instrument is slewing (i.e., where the field of view moves with arbitrary direction and speed while the instrument is repositioning)."
-->
"or fixed to a solar system body ({\em e.g./}, the moon, a planet, or a comet) position.".

Page 17 (from LaTeX file) - "To distinguish these, we propose to add an optional attribute {\bf tracking_type}, using the same values as used in \cite{2021ivoa.spec.0724S} ({\em sidereal}, {\em Solar-system-object-tracking}, {\em Fixed-az-el-transit}). Constraints on tracking mode can provide a simple way to discover data sets for a specific facility/instrument combination. We note that permissible {\bf tracking_type} values are possible beyond the predefined values.
-->
"We propose to add an optional attribute {\bf tracking_type} to distinguish these modes. Constraints on {\bf tracking_type} can provide a simple way to discover data sets for a specific facility/instrument combination. We propose predefined {\bf tracking_type} values for \gls{HEA} data include the following:
\begin{itemize}
\item \texttt{sidereal} : observations pointed at a fixed celstial targetlocation on the sky;
\item \texttt{fixed-az-el-transit} : observations fixed at a given elevation and azimuth;
\item \texttt{solar-system-object-tracking} : observations pointed at a moving target, like the moon or other solar system bodies;
\item \texttt{none} : observations with no telescope tracking.
\end{itemize}
We intend that the name of this attribute harmonizes with the name of the similar attribute in the proposed ``IVOA Obscore Extension for Radio Data''\footnote{\url{https://github.com/ivoa-std/ObsCoreExtensionForRadioData}} and note that the first three predefined values for {\bf tracking_type} also harmonize with that proposal. The \texttt{none} {\bf tracking_type} describes observations obtained while the telescope is not tracking ({\em e.g./}, observations obtained while the telescope is slewing). We further note that permissible {\bf tracking_type} values may vary from facility to facility and from instrument to instrument and additional values beyond the predefined values are possible.".

Page 17 (from LaTeX file) - "\subsection{{\em scan_mode}}

As for the radiotelescope arrays, different modes of observation of the sky are possible for \gls{HEA} instrumemts, leading to different instrument responses and special analysis schemes. The proposal of ObsCore Extension For Radio Data\footnote{The current note can be found \href{https://www.ivoa.net/documents/ObsCoreExtensionForRadioData/20240614/index.html}{here}.} proposes to add the field {\bf scan_mode} to qualify this observation property. The values are up to the data providers but pre-defined names are proposed: {\em on-source}, {\em on-off}, {\em raster-map} (that is the grid obervation for \glspl{IACT}), {\em on-the-fly-cross-map} or OTF (when telescopes are slewing between two points of the sky), {\em on-the-fly-map} (that is the wobble observation for \glspl{IACT}). We note that permissible {\bf scan_mode} values are possible beyond the predefined values."
-->
"\subsection{{\em scan_mode}}

Some \gls{HEA} facilities can obtain observations using different spatial scan modes that will affect the content of the observation, leading to different instrument responses and special analysis schemes. We propose to add an optional attribute {\bf scan_mode} to distinguish these modes. Constraints on {\bf scan_mode} can provide a simple way to discover data sets for a specific facility/instrument combination. We propose predefined {\bf scan_mode} values for \gls{HEA} data include the following:
\begin{itemize}
\item \texttt{on-source} : pointed observation;
\item \texttt{on-off} : switched observations between two spatial positions (source and background);
\item \texttt{raster-map} : observations on a predefined spatial mesh (generally regular and rectangular ({\em e.g./}, a grid observation for \glspl{IACT});
\item \texttt{on-the-fly-cross-scan} : observations along a predefined spatial pattern;
\item \texttt{on-the-fly-cross-map} : observations along parallel directions ({\em e.g./}, a wobble observation for \glspl{IACT});
\item \texttt{slew} : observations taken while the telescope is slewing.
\end{itemize}
We intend that the name of this attribute harmonizes with the name of the similar attribute in the proposed ``IVOA Obscore Extension for Radio Data''\footnote{\url{https://github.com/ivoa-std/ObsCoreExtensionForRadioData}} and note that the first five predefined values for {\bf scan_mode} also harmonize with that proposal. The \texttt{slew} {\bf scan_mode} describes observations obtained while the telescope is slewing ({\em, i.e./}, where the field of view moves with arbitrary direction and speed while the instrument is repositioning), which is a mode used extensively by some satellite-based \gls{HEA} facilities. We further note that permissible {\bf scan_mode} values may vary from facility to facility and from instrument to instrument and additional values beyond the predefined values are possible.".

Page 17 (from LaTeX file) -"\subsection{{\em pointing_mode}}

We are proposing for the \gls{HEA} to use the same fields with the same pre-defined values. For arrays of \glspl{IACT}, telescopes may not point all towards the same direction, convergent or divergent pointings may occur. In order to identify such observations, we propose to use the field {\bf pointing_mode}, with a default value of NULL'' to handle \gls{WCD} and neutrino instruments, and with possible values of {\em parallel}, {\em convergent} and {\em divergent}. Data providers are free to use additional values. For example, if a reference angle is used for a convergent pointing, a provider can use a value like convergent-5d''."
-->
"\subsection{{\em pointing_mode}}
Some \gls{HEA} facilities can obtain observations using multiple telescope simultaneously with the individual telescopes pointing in slightly different directions. For example, for the \glspl{IACT} telescope array, the individual telescope pointings may be in the same direction, convergent, or divergent. We propose to add an optional attribute {\bf pointing_mode}, with a default value of NULL'' to handle \gls{WCD} and neutrino instruments, to distinguish these modes. Constraints on {\bf pointing\_mode} can provide a simple way to discover data sets for a specific facility/instrument combination. We propose predefined {\bf spointing\_mode} values for \gls{HEA} data include the following: \begin{itemize} \item \texttt{parallel} : the telescopes are all pointing in the same direction; \item \texttt{convergent\[-ang\]} : the telescope pointings are convergent; \item \texttt{divergent\[-ang\]} : the telescope pointings are divergent. \end{itemize} The optional suffix [ang]'' specifies a reference angle for a convergent or divergent pointing, for example ``convergent-5d''. We note that permissible {\bf pointing_mode} values may vary from facility to facility and from instrument to instrument.".

Page 17 - "event partitioning based on a data analyis quality" --> "event partitioning, typically based on a data analyis quality".

Page 17 - "It will allow" --> "This attribute will allow".

Page 18 (from LaTeX file) - "Like for the ObsCore Recommandations, it is allowed to add any additional columns that a data provider aims to add. We recommand to add \gls{HEA} extra-columns into the \gls{HEA} Obscore Extension table, and not into the ObsCore table, for coherence purposes."
-->
"Similar to the ObsCore Recommendation, service providers may include additional columns to the ObsCore \gls{HEA} Extension table to expose additional metadata. While the service provider may choose to add additional columns to either the main ObsCore table or the ObsCore \gls{HEA} Extension table, we recommend that \gls{HEA}-data specific metadata columns be added to the ObsCore \gls{HEA} Extension table.".

Throughout - Proper names like "Chandra" need to be reresented consistently. Currently, they are represented differently throughout the text (in some cases {\em Chandra/} but in other cases {\rm Chandra}).

[iannevans]

Here is the complete list, excluding discussions on UCDs.

Page 1 - Update Date in Makefile.

Page 1 - Check author list (for example, I believe it should be "C. Boisson").

Page 5 - "It implies" --> "This requires".

Page 5 - Definitions of X-ray and gamm-ray energies are wrong. Change "(from ~0.1 eV to ~100 keV)" --> "(from ~0.1 keV" to 120 keV)" and "(from 100 MeV" --> "(from 120 keV". The soft gamma ray low energy should match the hard X-ray high energy.

Page 5 - "or other messenger" --> "or other messengers".

Page 5 - "(e.g. CIAO" --> "({\em e.g./}, CIAO".

Page 6 - "Universe" --> "universe".

Page 6 - Footnote "One can cite" --> "For example,".

Page 6 - Footnote "As opposed to signal integrating using a light detector." --> "As opposed to signal integrating ({\em e.g./}, using a photon detector).

Page 6 - "astronomical particle" --> "particle from an astrophysical source". Background counts can also have an astrophysical origin.

Page 6 - End of first paragraph, need to change "{\em event list/}." to "{\bf event-list}." or introduce the terminology we use in the document, for example "{\em event list/}, which we term an {\bf event-list} in this document.".

Page 6 - "{\bf event-lists}" --> "{\bf event-list}s" (two locations).

Page 6 - "The mappings between the observables and physical measurements of the source properties are called IRFs\footnote{...}; using techniques like forward-folding, they enable one to fit a model (with any combination of spectral, spatial, and temporal components) of the true flux of particles from a source arriving at the instrument to the measured quantities."
-->
"The mappings between physical measurements of the source properties and the observables are called Instrument Response Functions (IRFs\footnote{...}). Some IRFs are probabilistic in nature\footnote{...}, and in addition may depend on the set of events selected for analysis by the end user. They are usually not invertible, so methods such as forward-folding fitting (using source models with any combination of spectral, spatial, temporal, and/or polarization components that are estimated) are needed to estimate physical properties, such as the true flux of particles from a source arriving at the instrument, given the measured observable quantities.".

Page 6 - Delete "Some of the IRFs are probabilistic ... physical properties given observables.".

Page 6 - "are required to process HEA data" --> "are required to analyze HEA data".

Page 6 - "density funtion" --> "density function.".

Page 7 - "must be be modified" --> "must be modified".

Page 7 - 'are set to "-1"' --> 'set to "-1"; i.e., remove the "are".

Page 7 - "In addition, the hereafter modification proposal faces to the issue that some values of ObsCore attributes (dataproduct_type and calib_level) are defined both into the ObsCore standard document (Louys and Tody et al., 2017) and in the vocabularies documents (Demleitner and Gray et al., 2023, 2021), which might create some issues for the users. In this context, we have opted to propose in this document some modifications of both standards, even if we would have prefered that everything is uniquely defined in the IVOA Vocabulary. Some harmonization should be taken by the Data Model and Semantics working groups in order to avoid duplications. But until such work is achieved, we require modifications in ObsCore and Vocabulary."
-->
"Currently, some ObsCore attributes (dataproduct_type and calib_level) are formally defined in the ObsCore Recommendation Version 1.1 (Louys and Tody et al., 2017) and also in the vocabularies documents (Demleitner and Gray et al., 2023, 2021)\footnote{Primarily the Data Product Type Vocabulary, \url{https://www.ivoa.net/rdf/product_type}}, which may be referenced in future versions of the ObsCore Recommendation. For completeness, we are proposing in this document modifications to both the existing ObsCore Recommendation and IVOA vocabularies."
It's not our place to be telling the DM & Semantics WGs what they should be doing except in the sense of what is needed for HEA data discovery, and is inappropriate in this document.

Page 7 - After the 1st paragraph under 3.1 dataproduct_type, add "The modifications/additions to the set of ObsCore Recommendation Version 1.1 (Louys and Tody et al., 2017) {\em dataproduct_type/} (and, in some cases, {\em dataproduct_subtype/}) terms described herein apply equally to the IVOA Data Product Type Vocabulary, and will therefore be reperated in \S~5.". You want this here so you don't have to restate the same thing for each new dataproduct_type.

Page 8 - "The ObsCore v1.1 recommendation (Louys and Tody et al., 2017) only defines an event dataproduct_type as:" --> "The ObsCore Recommendation Version 1.1 (Louys and Tody et al., 2017) defines an event dataproduct_type as:"; i.e., remove the "only".

Page 8 - "We propose to add the following dataproduct_type term in both the ObsCore standard and into the IVOA Vocabulary of Data Product Types\footnote{...} to better define a HEA event-list and an event-bundle that includes the event-list and its associated data:"
-->
"We propose to add the following dataproduct_type terms to ObsCore to better define a HEA event-list and an event-bundle that includes the event-list and its associated data:"; also here verify that ObsCore is hyphenated correctly if necessary.

Page 8 - "event-list: a collection of observed particle-detection events, such as incoming high-energy particles. The table of event list is typically characterised by a spatial position, a time and an energy proxy."
-->
{\bf event-list}: A dataset that records a collection of observed particle-detection events, such as incoming high-energy particles, where an event is typically characterized by a spatial position, a time, and a spectral value ({\em e.g./}, an energy, a channel, a pulse height).

Page 8 - "event-bundle: compounded" --> "{\bf event-bundle}: a compounded"

Page 8 - 'the term "event"' --> 'the term {\bf event}'.

Page 8 - "(e.g. VOEvent)" --> "({\em e.g./}, VOEvent)".

Page 8 - 'Using "event-list"' --> 'Using {\bf event-list}'.

Page 9 - "response-function: a dataset that represents a mapping from a physical quantity to an observable. For HEA, this may be the components of the composite IRF such as an Auxiliary Response File (ARF), Redistribution Matrix File (RMF), Effective Area (AEFF), Energy Dispersion (EDISP), the Background Rate (BKGRATE). The Point Spread Function (PSF) is a response function that is generally applicable across multiple wavebands. While these datasets may generally be represented as an N-dimensional data cube, designating them as response-functions enhances data discovery for very common types of HEA dataset (see the use cases in appendix A)."
-->
"{\bf response-function}: A dataset that records the mapping from a physical quantity to an observable quantity.".

Page 9 - "The {\bf measurements} data product type" --> "The {\bf measurements} {\em dataproduct_type}".

Page 10 - '{\bf dataproduct_type} = "measurements"' --> '{\em dataproduct_type/} = {\bf measurements}'.

Page 10 - "together with" --> "{\bf together} with".

Page 10 - Delete "Note that ... sub-section."

Page 10 - "in section 5" --> "in \S~5".

Page 10 - "In X-ray, this is" --> "This is"; doesn't just apply to X-ray - there are gamma-ray missions that are similar because the spacecraft pointing is not constant during the exposure.

Page 11 - "number of HE data products" --> "number of HEA data products".

Page 11 - "(e.g. to the" --> "({\em e.g./}, to the".

Page 11 - "(e.g. response-functions)." --> "({\em e.g./}, {\bf response-function}s).".

Page 11 - "If DataLink is provided, it should be indicated that the URL points to a Datalink service via the access_format = application/x-votable+xml;content=datalink."
-->
"If a DataLink is provided, {\em access_format/} should be set to ``application/x-votable+xml;content=datalink'' to indicate that the URL points to a DataLink service."

Page 11 - "(especially when the tracking is not fixed in the ICRS system)." --> "(especially when not tracking at sidereal rate or for facilities for which the PSF varies strongly across the telescope field of view)."

Page 12 - "), then we recommend" --> "), we recommend" (two locations).

Page 12 - "do not not encode" --> "do not encode".

Page 13 - "), then we recommend" --> "), we recommend".

Page 13 - "o_ucd=pos.eq,time,phys.pulseHeight." --> "{\em o_ucd=pos.eq;time;phys.pulseHeight/}.".

Page 14 - "{\bf event-lists}s table)." --> "{\bf event-lists}'s table).".

Page 14 - "spatial resolution and sky coverage, and spectral resolution, can" --> "spatial resolution, sky coverage, and spectral resolution can".

=Page 16 - "Since HEA telescopes are event-counting instruments, data can be accumulated even if the pointing moves or rotates relative to the sky during an observation. However, they way in which this happens has an impact on how the data are later processed.'
-->
"Since most HEA facilities record the arrival times of particle events, data accumulated when the telescope pointing moves or rotates relative to the sky during an observation can be located on the sky. The way in which the telescope moves may impact how the data should be processed, especially for observations in which multiple different astrophysical sources may be present within the field of view ({\em e.g./}, a solar system target moving relative to the fixed celestial background).".

Page 16 - "what the center of the field-of view moves with during an observation:" --> "the normal motion of the optical axis of the telescope during an observation:".

Page 16 - 'a "drift scan",' --> "a ``drift scan'',".

Page 16 - "fixed to a celestial body position like a planet or moon, or with no particular fixed coordinate system such as data taken when the instrument is slewing (i.e., where the field of view moves with arbitrary direction and speed while the instrument is repositioning)."
-->
"or fixed to a solar system body ({\em e.g./}, the moon, a planet, or a comet) position.".

Page 17 (from LaTeX file) - "To distinguish these, we propose to add an optional attribute {\bf tracking_type}, using the same values as used in \cite{2021ivoa.spec.0724S} ({\em sidereal}, {\em Solar-system-object-tracking}, {\em Fixed-az-el-transit}). Constraints on tracking mode can provide a simple way to discover data sets for a specific facility/instrument combination. We note that permissible {\bf tracking_type} values are possible beyond the predefined values.
-->
"We propose to add an optional attribute {\bf tracking_type} to distinguish these modes. Constraints on {\bf tracking_type} can provide a simple way to discover data sets for a specific facility/instrument combination. We propose predefined {\bf tracking_type} values for \gls{HEA} data include the following:
\begin{itemize}
\item \texttt{sidereal}: observations pointed at a fixed celstial targetlocation on the sky;
\item \texttt{fixed-az-el-transit}: observations fixed at a given elevation and azimuth;
\item \texttt{solar-system-object-tracking}: observations pointed at a moving target, like the moon or other solar system bodies;
\item \texttt{none}: observations with no telescope tracking.
\end{itemize}
We intend that the name of this attribute harmonizes with the name of the similar attribute in the proposed ``IVOA Obscore Extension for Radio Data''\footnote{\url{https://github.com/ivoa-std/ObsCoreExtensionForRadioData}} and note that the first three predefined values for {\bf tracking_type} also harmonize with that proposal. The \texttt{none} {\bf tracking_type} describes observations obtained while the telescope is not tracking ({\em e.g./}, observations obtained while the telescope is slewing). We further note that permissible {\bf tracking_type} values may vary from facility to facility and from instrument to instrument and additional values beyond the predefined values are possible.".

Page 17 (from LaTeX file) - "\subsection{{\em scan_mode}}

As for the radiotelescope arrays, different modes of observation of the sky are possible for \gls{HEA} instrumemts, leading to different instrument responses and special analysis schemes. The proposal of ObsCore Extension For Radio Data\footnote{The current note can be found \href{https://www.ivoa.net/documents/ObsCoreExtensionForRadioData/20240614/index.html}{here}.} proposes to add the field {\bf scan_mode} to qualify this observation property. The values are up to the data providers but pre-defined names are proposed: {\em on-source}, {\em on-off}, {\em raster-map} (that is the grid obervation for \glspl{IACT}), {\em on-the-fly-cross-map} or OTF (when telescopes are slewing between two points of the sky), {\em on-the-fly-map} (that is the wobble observation for \glspl{IACT}). We note that permissible {\bf scan_mode} values are possible beyond the predefined values."
-->
"\subsection{{\em scan_mode}}

Some \gls{HEA} facilities can obtain observations using different spatial scan modes that will affect the content of the observation, leading to different instrument responses and special analysis schemes. We propose to add an optional attribute {\bf scan_mode} to distinguish these modes. Constraints on {\bf scan_mode} can provide a simple way to discover data sets for a specific facility/instrument combination. We propose predefined {\bf scan_mode} values for \gls{HEA} data include the following:
\begin{itemize}
\item \texttt{on-source}: pointed observation;
\item \texttt{on-off}: switched observations between two spatial positions (source and background);
\item \texttt{raster-map}: observations on a predefined spatial mesh (generally regular and rectangular ({\em e.g./}, a grid observation for \glspl{IACT});
\item \texttt{on-the-fly-cross-scan}: observations along a predefined spatial pattern;
\item \texttt{on-the-fly-cross-map}: observations along parallel directions ({\em e.g./}, a wobble observation for \glspl{IACT});
\item \texttt{slew} : observations taken while the telescope is slewing.
\end{itemize}
We intend that the name of this attribute harmonizes with the name of the similar attribute in the proposed ``IVOA Obscore Extension for Radio Data''\footnote{\url{https://github.com/ivoa-std/ObsCoreExtensionForRadioData}} and note that the first five predefined values for {\bf scan_mode} also harmonize with that proposal. The \texttt{slew} {\bf scan_mode} describes observations obtained while the telescope is slewing ({\em, i.e./}, where the field of view moves with arbitrary direction and speed while the instrument is repositioning), which is a mode used extensively by some satellite-based \gls{HEA} facilities. We further note that permissible {\bf scan_mode} values may vary from facility to facility and from instrument to instrument and additional values beyond the predefined values are possible.".

Page 17 (from LaTeX file) -"\subsection{{\em pointing_mode}}

We are proposing for the \gls{HEA} to use the same fields with the same pre-defined values. For arrays of \glspl{IACT}, telescopes may not point all towards the same direction, convergent or divergent pointings may occur. In order to identify such observations, we propose to use the field {\bf pointing_mode}, with a default value of NULL'' to handle \gls{WCD} and neutrino instruments, and with possible values of {\em parallel}, {\em convergent} and {\em divergent}. Data providers are free to use additional values. For example, if a reference angle is used for a convergent pointing, a provider can use a value like convergent-5d''."
-->
"\subsection{{\em pointing_mode}}
Some \gls{HEA} facilities can obtain observations using multiple telescope simultaneously with the individual telescopes pointing in slightly different directions. For example, for the \glspl{IACT} telescope array, the individual telescope pointings may be in the same direction, convergent, or divergent. We propose to add an optional attribute {\bf pointing_mode}, with a default value of NULL'' to handle \gls{WCD} and neutrino instruments, to distinguish these modes. Constraints on {\bf pointing\_mode} can provide a simple way to discover data sets for a specific facility/instrument combination. We propose predefined {\bf spointing\_mode} values for \gls{HEA} data include the following: \begin{itemize} \item \texttt{parallel}: the telescopes are all pointing in the same direction; \item \texttt{convergent\[-ang\]}: the telescope pointings are convergent; \item \texttt{divergent\[-ang\]}: the telescope pointings are divergent. \end{itemize} The optional suffix [ang]'' specifies a reference angle for a convergent or divergent pointing, for example ``convergent-5d''. We note that permissible {\bf pointing_mode} values may vary from facility to facility and from instrument to instrument.".

Page 17 - "event partitioning based on a data analyis quality" --> "event partitioning, typically based on a data analyis quality".

Page 17 - "It will allow" --> "This attribute will allow".

Page 18 (from LaTeX file) - "Like for the ObsCore Recommandations, it is allowed to add any additional columns that a data provider aims to add. We recommand to add \gls{HEA} extra-columns into the \gls{HEA} Obscore Extension table, and not into the ObsCore table, for coherence purposes."
-->
"Similar to the ObsCore Recommendation, service providers may include additional columns to the ObsCore \gls{HEA} Extension table to expose additional metadata. While the service provider may choose to add additional columns to either the main ObsCore table or the ObsCore \gls{HEA} Extension table, we recommend that \gls{HEA}-data specific metadata columns be added to the ObsCore \gls{HEA} Extension table.".

Throughout - Proper names like "Chandra" need to be reresented consistently. Currently, they are represented differently throughout the text (in some cases {\em Chandra/} but in other cases {\rm Chandra}).

---

Page 18 - "Evolution of the Data Product Type vocabulary" --> "Evolution of the Data Product Type Vocabulary"

Page 18 - After the 1st para of section 5.1, add "We propose to add vocabulary entries for the new data product types outlined in \S~\ref{sec:dataproduct_type} and also propose to slightly modify the existing definition of {\bf event-list} so that it aligns more accurately with the definition in that section. Additionally, we propose to add several more specific entries to the data product type vocabulary that specialize these types (especially {\bf response-function})."

Page 18 - "We first propose to better define an event-list:" --> "We first propose to more precisely define an {\bf event-list/}:"

Pages 18/19 - There is an issue with the event-list and response-function definitions in Section 5, in that they are inconsistent with the definitions on Pages 8/9. We need to choose one or the other (or a hybrid) and make sure the definitions are correct in both places. Perhaps we can agree on the following definitions to be used in both sections?
{\bf event-list}: A dataset that records a collection of observed particle-detection events, such as incoming high-energy particles, where an event is typically characterized by a spatial position, a time, and a spectral value ({\em e.g./}, an energy, a channel, a pulse height).
{\bf response-function}: A dataset that records the mapping from a physical quantity to an observable quantity. Narrower terms are preferred to indicate more precisely the type of {\bf response-function}.

Page 19 - "We then propose to add the following product types to define the different response functions (e.g. IRFs) generally used in HEA"
-->
"We then propose to add the following data product type to define response functions (IRFs)."

Page 19 - After the definition of response-function and prior to the definition of aeff, add "The following data product types specialize {\bf response function}. Note that while most of these are primarily used in \gls{HEA}, the Point Spread Function ({\bf psf}) is a {\bf response-function} that is generally applicable across multiple wavebands.".

Page 19 - Reorder the different types of response-function in alphabetical order.

Page 19 - "(e.g. for gamma-ray instrument it" --> "({\em e.g./}, for gamma-ray instruments this".

Page 19 - "Some use cases require access to an event-bundle, a bundle of datasets that includes the event-list and associated data:" --> "Some use cases require access to a bundle of datasets that includes the event-list and associated data. We define an {\bf event-bundle}:".

Page 19 - "compounded dataset" --> "A compounded dataset".

Page 20 - "dataset. It may also" --> "dataset, and may also".

Page 20 - "In addition to product types" --> "In addition to data product types".

Page 20 - "For example, the Chandra Source Catalog includes 38 types of advanced data products (for a total of ~90 million files) and ~50% of these data product types are not well represented by a dataproduct_type value that allows for meaningful data discovery. Users will certainly want to discover these data products independently from the associated observation data (and many of these data products combine data from multiple observations). We therefore propose the following additional dataproduct_types for these advanced data products, and note that these dataproduct_types will certainly be useful independent of waveband (i.e., they can be equally applicable to UV/optical, IR, and radio datasets):"
-->
"Users will certainly want to discover these data products independently from the associated observation data (and many of these data products combine data from multiple observations). We therefore propose the following additional data product types for these advanced data products, and note that these data product types will certainly be useful independent of waveband ({\em i.e./}, they can be equally applicable to UV/optical, IR, and radio datasets):".

Page 21 - Delete paragraph re measurements as the restriction is not present in the Data Product Type Vocabulary.

Page 22-24 - Set table in landscape.

Page 22-24 - Verify consistency of all descriptions with the text on Pages 18-20 and updated as needed.

Page 22 - Label "Draws" --> "Statistical Draws"; add "#measurements" as Parent.

Page 24 - Update units strings to use math mode.

Page 24 - "units = [W/m2/str/TeV]" --> "$\rm units = [W,m^{-2},str^{-1},eV^{-1}]$.

Page 24 - "These are not all covered by the UCD vocabulary. This would be particularly useful for cases where we actually should have the same UCDs as e.g. a Radio measurement, but where we use very di"erent units. For example: Jansky and erg/cm2/s/TeV are both types of "spectral flux density", but the unit analysis doesn’t agree due to frequency-energy equivalency.
-->
"The common \gls{HEA} flux definitions listed above are not all covered by the UCD vocabulary, and we propose to add appropate definitions to the UCD list in \S~\ref{UCDlist} below. This would be particularly useful for cases where a \gls{HEA} quantity should have the same UCDs as ({\em e.g./}) a Radio measurement but where very different units are used. For example, Jansky and $\rm erg,cm^}{-2},s^{-1},TeV$ are both spectral flux densities but the unit analysis doesn’t agree due to the frequency-energy equivalency." Move this paragraph to the end of section 5.1.6.

Page 24 - "Restating the descriptions to explicitly state" --> "Restating the existing Data Product Type descriptions that use ``flux'' to explicitly state". Move this paragraph to immediately below the list of flux definitions.

Page 25 - "are unrelated" --> "may be unrelated".

Page 25 - "A proposed solution" --> "One previously proposed solution".

Page 25 - "not really appropriate" -- > "not appropriate".

Page 25 - "The current definitions for the gamma-ray domains should be corrected and extended to include the HEA, Very High Energy (VHE) and Ultra High Energy (UHE) gamma-ray domains." --> "We propose correcting and extending the current list of UCD gamma-ray domains definitions to include the High Energy (HE), Very High Energy (VHE), and Ultra High Energy (UHE) gamma-ray domains.".

Page 26 - "For VHE (and GeV) data" --> "For VHE (and GeV) gamma-ray data".

Page 26 - "Observations may concern other particles than the one currently described in the UCD list. The following particles could be added: electron/positron, cosmic rays, as well as their energy"
-->
"The messengers for \gls{HEA} observations may include particles other than the ones currently described in the UCD list. We propose adding UCDs for electron/positron and cosmic rays, and unifying them under the {\em phys.particle/} UCD hierarchy.".

Page 26 - "We suggest restricting stat.max/stat.min to mean the maximum/minimum statistic and adding new terms stat.upperlimit/stat.lowerlimit for upper/lower limits. For upper/lower limits, one expects a confidence level to be provided, which could be described by a UCD stat.confidenceLevel."
-->
"Since statistical lower and upper limits play a significant role in \gls{HEA} data analysis, we propose adding new UCDs {\em stat.lowerlimit/} and {\em stat.upperlimit/} to explicitly identify data quantities as lower or upper limits. We suggest that the existing UCDs {\em stat.min/} and {\em stat.max/} be restricted to meaning the minimum and maximum statistic. A specification of a confidence level is necessary for the user to interpret lower and upper limits meaningfully, and this level can be described by the existing UCD {\em stat.confidenceLevel/}."

Page 26 - "One proposes also to add a likelihood profile as UCD"
-->
"The shape of any statistical distribution is an essential quantity for interpreting the meaning of any statistical properties. Too often a Gaussian distribution or a distribution that can be simply characterized by a simple set of moments ({\em e.g./}, mean, variance, skewness, kurtosis) are assumed, but in the extreme Poisson regime common in \gls{HEA} these assumptions are often invalid. We propose adding a UCD {\em stat.distribution/} to identify a quantity that defines the distribution of a statistical variable, for example a likelihood profile.".

Page 26 - "The proposed UCD entries are" --> "The proposed new/revised UCD entries are".

Page 26/27 - Italicize all UCD words in Tables 2 and 3.

Page 26 - "P stat.likelihood.profile Profile of likelihood values"
-->
"P stat.distribution Distribution of a statistical variable".

Page 26 - "phot.strcount" --> "phot.count.str".

Page 26 - "phot.diffcount" --> "phot.count.density".

Page 26 - "phot.strflux" --> "phot.flux.energy.str".

Page 27 - "phot.enflux" --> "phot.flux.energy.density".

Page 26 - Add phot.flux, phot.count to Table 2. I'm merging Tables 2 and 3 because Table 2 already contains entries that already exist as UCDs, and separating phot.flux/phot.count from the phot. values in Table 2 makes the discussion less clear.

Page 27 - "Table 2: UCD words proposed extension" --> Proposed new and revised UCD entries".

Page 27 - Delete Table 3.

Page 27 - "5.4 MIME-types Enhancements" --> "5.4 MIME-type Enhancements".

Page 27 - "Formats based on FITS could thus be declared as:
• x-fits-gadf: for FITS files following the GADF specification (Deil and Wood et al., 2022)
• x-fits-vodf: for FITS files following the VODF specification (Khélifi and Zanin et al., 2023)"
-->
"Many \gls{HEA} FITS format data products will comply with existing MIME-types discussed in the ObsCore Recommendation, such as {\bf application/fits} or {\bf application/x-fits-bintable}. However, the gamma-ray community has developed two additional data format standards and we propose to add the following MIME-types:
• {\bf x-fits-gadf}: FITS files following the Gamma-Astro-Data-Format (GADF) specification (Deil, C., Boisson, C., Kosack, K., et al. 2017a, in American Institute of Physics Conference Series, Vol. 1792, 6th International Symposium on High Energy Gamma-Ray Astronomy, 070006);
•{\bf x-fits-vodf}: FITS files following the Very-high-energy Open Data Format (VODF) specification (Khélifi and Zanin et al., 2023).".

Page 27 - "This section summarizes the proposal for the HEA extension of ObsCore. Note that the name of the extension could be ivoa.obscore_hea, ivoa.obscore-hea, ivoa.obscore_he or ivoa.obscore-he. We use here the first term in the Appendix A."
-->
"This section summarizes the proposal for the HEA extension of ObsCore. We use the term {\em ivoa.obscore_hea/} to described the extension here and in Appendix A.".

Pages 27/28 - Validate table entries against descriptions in the text; correct Unit/Type that are sometimes flipped; ensure types match types used in the ObsCore Recommendation Appendix B, e.g., "string"/"integer"/"double".

Page 29 - Delete Section 7?; no other similar documents include a Summary.

Pages 32-40 - Fix punctuation in all lists of query conditions.

Page 33 - Fix "ev_xel >= 1,000,000" in query conditions.

Page 33 - Fix spacing in 'Targetname=“CasA”', 'access_format =“datalink”'.

Page 33 - Delete "Then, for each row of the output, we get the “access_url” of the DataLink and access to the data." since we don't show that in the example.

Page 34 - Why does example A.1.5 use the same obs_id as Example A.1.4? Do CTAO obs_id's have the same format as Chandra?

Page 34 - Example A.1.5 query does not match stated query conditions; add 'dataproduct_type = "event-list"' to query conditions.

Page 36 - Example A.1.7 query does not match stated query conditions; update query conditions appropriately.

Page 37 - Fix width overflow in example A.1.8.

Page 37 - Fix "energy_max >= 10e+12" in query conditions.

Page 37/38 - Fix punctuation in the list of steps to process the VOTable.

Page 39 - Example A.2.2 query does not match stated query conditions; update query conditions appropriately (">' instead of ">="); fix "<=" in query conditions.

Page 40 - Fix ">=" in query conditions (two places); "(e.g. 2030" --> "({\em i.e./}, 2030" (two places).

Page 41 - Fix punctuation in list.

Throughout - Make capitalization of section headings uniform.

[iannevans]

I have some concerns about several of the UCDs proposed in draft section 5.3 since there are existing UCDs in December 2024 UCD vocabulary for several of them. We need to address these. Below, I’ve added comment lines below items to be reviewed, and the **** items need to be resolved (together with proposed resolutions).

S em.gamma.hard Hard gamma ray (500 keV - 100 MeV) Redefinition OK
S em.gamma.he High-Energy gamma ray (100 MeV - 10 GeV) New OK
S em.gamma.vhe Very-High-Energy gamma ray (10 GeV - 100 TeV) New OK
S em.gamma.uhe Ultra-High-Energy gamma ray (100 TeV - 10 PeV) New ?
— ****The existing highest energy gamma-ray domain (em.gamma.hard) used a catch-all (E >500 keV) description that includes arbitrarily high energies. If em.gamma.uhe cuts off at 10 PeV what UCD should be used for higher energies?

S phys.pulseHeight Pulse height amplitude measure New OK
S phys.particle.electron Related to electron/positron New OK
S phys.particle.cosmicray Related to cosmic rays particles New OK
P stat.error.negative Negative statistical error New OK
P stat.error.positive Positive statistical error New OK
P stat.upperlimit Upper limit New OK
P stat.lowerlimit Lower limit New OK
P stat.confidenceLevel Level of confidence for a upper/lower limit Existing NO
computation
— ****stat.confidenceLevel exists and is defined as “Level of confidence for a detection or classification process”. This is somewhat different from confidence level for a lower/upper limit as you are defining it (as discussed in an earlier email). We either need to broaden the description of the existing term to mean both (e.g., “Level of confidence for a statistical measure, detection, or classification process”), or come up with an alternative UCD.

P stat.likelihood.profile Profile of likelihood values New NO
— ****I propose replacing this with stat.distribution to define the “Distribution of a statistical variable”. This is more general than stat.likelihood.profile and the latter would effectively be equivalent to stat.likelihood;stat.distribution.

E phot.count Flux expressed in counts (dimension: Redefinition OK
[L^-2 T^-1])
— Redefinition adds dimensionality.

E phot.strcount Particle flux per steradian (dimension: New NO
[L^-2 T^-1 sr^-1])
— ****phot.radiance exists and is defined as “Radiance as energy flux per solid angle” so phot.count.radiance would be more consistent.

E phot.diffcount Particle flux density (or differential
particle flux) (dimension: [L^-2 T^-1 E^-1]) New NO
— ****phot.flux.density exists and is defines as "Flux density (per wl/freq/energy interval)” so phot.count.density would be more consistent.

E phot.flux Photon flux or irradiance or energy flux Redefinition NO
(dimension: [W L^-2])
— ****phot.flux currently exists and is defined as “Photon flux or irradiance”. The proposed description does not match the existing description, and the dimensionality does not match the proposed description. I suggest not redefining phot.flux but consider adding instead:
E phot.flux.energy Energy flux or irradiance New OK
(dimension: [M L^0 T^-3])
(Sorry I don’t use W in dimensionality analyses)

E phot.enflux Energy flux density (dimension: New NO
[W L^-2 sr^-1 E^-1)
— ****Suggest phot.flux.energy.density for consistency with phot.flux.energy. Note that phot.flux.density already exists and is defined as "Flux density (per wl/freq/energy interval)”. However, phot.flux is defined as “Photon flux or irradiance”.

E phot.strflux Energy flux per steradian or radiance New NO
(dimension: [W L^-2 sr^-1])
— ****Why can’t existing phot.radiance defined as “Radiance as energy flux per solid angle” be used? Why not propose to modify phot.radiance to add the dimensionality?

—****instr.evt-type is mentions in section 5.3.3 but a syntax code (presumably Q) or Description is not proposed for it.