PSF Table documentation

[GernotMaier]

The documentation of the PSF tables is not entirely clear and could be clarified by better wording or using other expressions. There is jargon used, which makes it hard to understand. This issue is to discuss improvements.

This is the page: https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/psf/psf_table/index.html#psf-table

1. Field of view offset axis: the FOV does not have an offset and there is no FOV-offset axis. I guess what is meant is the angular distance to centre of the array pointing direction? I suggest to change this accordingly. The current explanation requires to first understanding the FOV coordinates.
2. Offset angle from source position: this is simply the distance between simulated and reconstructed direction? This can be calculated without assuming an astronomical source (e.g., from diffuse simulations, or from many 'sources' on a grid in the FOV). I suggest the much simpler expression 'angular distance between true and reconstruction event direction'

For the FOV coordinates (https://gamma-astro-data-formats.readthedocs.io/en/latest/general/coordinates.html#coords-fov):

• a little sketch would help a lot!
• using equator and pole is mathematical correct, but might be confusing to readers who think about celestial plots or Earth's equatorial plane.
• note that at least for some experiments, these are not spherical coordinates but coordinates in a plane tangential to the array pointing direction (which for small FOVs and is approximately the same)

[maxnoe]

Agree with mostly everything said here.

note that at least for some experiments, these are not spherical coordinates but coordinates in a plane tangential to the array pointing direction (which for small FOVs and is approximately the same)

This is the only thing I disagree with. The standard here basically prescribes using proper spherical coordinates, which is the right thing to do. Experiments using other coordinate systems should convert to spherical when exporting IRFs in these formats.

[TarekHC]

I also agree with @GernotMaier. Current specifications are full of jargons and we should definitely improve the wording.

The best way to proceed is for @GernotMaier to create a pull-request with the proposed changes, so we can directly comment on them (this one should be easy, you already proposed good alternatives in your issue). If there is general consensus that the changes improve the wording use, then we just accept the pull request.

[GernotMaier]

This is the only thing I disagree with. The standard here basically prescribes using proper spherical coordinates, which is the right thing to do. Experiments using other coordinate systems should convert to spherical when exporting IRFs in these formats.

No worries, I don't suggest to change anything in the coordinate definitions here. Just to be clearer through adding a half sentence or so.