search

open-gamma-ray-astro / gamma-astro-data-formats

Data formats for gamma-ray astronomy
https://gamma-astro-data-formats.readthedocs.io
Creative Commons Attribution 4.0 International
30 stars 27 forks source link

PSF Table documentation #174

Open GernotMaier opened 3 years ago

GernotMaier commented 3 years ago

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):

maxnoe commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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.