diff --git a/source/events/events.rst b/source/events/events.rst index 8183d1d..81d43b3 100644 --- a/source/events/events.rst +++ b/source/events/events.rst @@ -45,31 +45,24 @@ Optional columns * ``EVENT_TYPE`` tform: ``32X`` * Event quality partition. +* ``MULTIP`` tform: ``1I`` + * Telescope multiplicity. Number of telescopes that have seen the event. * ``GLON`` tform: ``1E``, unit: deg * Reconstructed event Galactic longitude (see :ref:`coords-galactic`). * ``GLAT`` tform: ``1E``, unit: deg * Reconstructed event Galactic latitude (see :ref:`coords-galactic`). * ``ALT`` tform: ``1E``, unit: deg - * Reconstructed altitude coordinate of event - (horizon system, see :ref:`coords-altaz`) + * Reconstructed altitude (see :ref:`coords-altaz`) * ``AZ`` tform: ``1E``, unit: deg - * Reconstructed azimuth coordinate of event - (horizon system, see :ref:`coords-altaz`) + * Reconstructed azimuth (see :ref:`coords-altaz`) * ``DETX`` tform: ``1E``, unit: deg - * Reconstructed event X-coordinate in detector system - (nominal system, see :ref:`coords-fov`). - See also the `OGIP event list`_ standard. + * Reconstructed field of view X (see :ref:`coords-fov`). * ``DETY`` tform: ``1E``, unit: deg - * Reconstructed event Y-coordinate in detector system - (nominal system, see :ref:`coords-fov`). - See also the `OGIP event list`_ standard. + * Reconstructed field of view Y (see :ref:`coords-fov`). * ``THETA`` tform: ``1E``, unit: deg - * Reconstructed offset from the observation pointing position + * Reconstructed field of view offset angle (see :ref:`coords-fov`). * ``PHI`` tform: ``1E``, unit: deg - * Reconstructed position angle from the observation pointing position - (position angles are counted counterclockwise from celestial North) -* ``MULTIP`` tform: ``1I`` - * Telescope multiplicity. Number of telescopes that have seen the event + * Reconstructed field of view position angle (see :ref:`coords-fov`). * ``DIR_ERR`` tform: ``1E``, unit: deg * Direction error of reconstruction * ``ENERGY_ERR`` tform: ``1E``, unit: TeV diff --git a/source/general/coordinates.rst b/source/general/coordinates.rst index 028889f..6044432 100644 --- a/source/general/coordinates.rst +++ b/source/general/coordinates.rst @@ -131,47 +131,76 @@ Astropy, i.e. this is without refraction corrections): Field of view ------------- -In Gamma-ray astronomy, sometimes field of view (FOV) coordinates are used. -Specifically some :ref:`background models ` are in the FOV coordinate system -and FOV coordinates can also be used for other IRFs. +FOV coordinates are currently used in two places in this spec: + +1. Some :ref:`background models ` are in the FOV coordinate system + and FOV coordinates can also be used for other IRFs. +2. FOV coordinates appear is as optional columns in the :ref:`events ` table. + While it is possible to compute FOV coordinates from the ``RA``, ``DEC``, ``TIME`` columns + and the observatory :ref:`coords-location`, some IACTs choose to add FOV + coordinate columns to their event lists for convenience. +In Gamma-ray astronomy, sometimes field of view (FOV) coordinates are used. The basic idea is to have a coordinate system that is centered on the array pointing position. We define FOV coordinates here to be spherical coordinates, there is no projection or WCS, only a spherical rotation. -Two versions of FOV coordinates are defined: +Two ways to give the spherical coordinate are defined: -1. ``(LON, LAT)`` with the pointing position on the equator at ``(0, 0)`` - * ``LON`` range -180 deg to + 180 deg - * ``LAT`` range -90 deg to + 90 deg +1. ``(LON, LAT)`` with the pointing position on the equator at ``(LON, LAT) = (0, 0)`` + * ``LON``: Longitude (range -180 deg to + 180 deg) + * ``LAT``: Latitude (range -90 deg to + 90 deg) 2. ``(THETA, PHI)`` with the pointing position at the pole ``THETA=0`` - * ``THETA`` range 0 deg to +180 deg - * ``PHI`` range 0 deg to 360 deg - * ``THETA`` is the angular separation wrt. the pointing position. - * TODO: define PHI orientation - * TODO: give example with numbers to make PHI orientation clear + * ``THETA``: Offset angle (range 0 deg to +180 deg) + * ``PHI``: Position angle (range 0 deg to 360 deg) -Also, there are two versions of FOV coordinates defined: +Two orientations of the FOV coordinate system are defined: -1. Aligned with ``ALTAZ`` -2. Aligned with ``RADEC`` +1. Aligned with the ``ALTAZ`` system +2. Aligned with the ``RADEC`` system -To summarise, the following coordinates are defined: +This yields the following possible coordinates: =============== ================================== Field Description =============== ================================== FOV_ALTAZ_LON Longitude in ALTAZ FOV system FOV_ALTAZ_LAT Latitude in ALTAZ FOV system -FOV_ALTAZ_THETA Offset in ALTAZ FOV system +FOV_ALTAZ_THETA Offset angle in ALTAZ FOV system FOV_ALTAZ_PHI Position angle in ALTAZ FOV system --------------- ---------------------------------- FOV_RADEC_LON Longitude in RADEC FOV system FOV_RADEC_LAT Latitude in RADEC FOV system -FOV_RADEC_THETA Offset in RADEC FOV system +FOV_RADEC_THETA Offset angle in RADEC FOV system FOV_RADEC_PHI Position angle in RADEC FOV system =============== ================================== +* The FOV offset angle (separation to pointing position) ``THETA`` doesn't depend + on the orientation. So in this spec, often simply ``THETA`` is used, + and that is equal to ``FOV_ALTAZ_THETA`` and ``FOV_RADEC_THETA``. +* The other FOV coordinates depend on the alignment and orientation of a second + coordinate systems (``OTHER``, either ``ALTAZ`` or ``RADEC``). + * FOV PHI is counterclockwise from OTHER north, + i.e. ``PHI=0 deg`` pointing to OTHER LAT, + and ``PHI=270 deg`` pointing to OTHER LON + * FOV LON should increase with decreasing OTHER LON + * FOV LAT should increase with increasing OTHER LAT + +In the :ref:`events ` table, the column names ``DETX`` and ``DETY`` +are sometimes used. This originates from the `OGIP event list`_ standard, +which uses these names for "detector coordinates". Given that IACTs don't have +a detector chip (or at least the FOV coordinates used in high-level analysis are +different from the IACT camera coordinate detectors), it wasn't clear what to put, +both ``(DETX, DETY) = (FOV_ALTAZ_LON, FOV_ALTAZ_LAT)`` +and ``(DETX, DETY) = (FOV_RADEC_LON, FOV_RADEC_LAT)`` +and very early on even TAN projections were used. + +Given this situation that there is no concensus yet, one suggestion is to avoid +putting FOV coordinates in EVENTS, or if they are added, to clearly state how +they are defined. This still leaves the problem with the background models, +in case they are non-radially symmetric. We expect CTA to make a decision and to define +FOV coordinate systems soon, to resolve this issue. + .. _coords-location: Earth location diff --git a/source/irfs/full_enclosure/bkg/index.rst b/source/irfs/full_enclosure/bkg/index.rst index 4319d01..a0058dd 100644 --- a/source/irfs/full_enclosure/bkg/index.rst +++ b/source/irfs/full_enclosure/bkg/index.rst @@ -23,7 +23,7 @@ Required columns: * ``ENERG_LO``, ``ENERG_HI`` -- ndim: 1, unit: TeV * Reconstructed energy axis * ``THETA_LO``, ``THETA_HI`` -- ndim: 1, unit: deg - * Field of view offset axis + * Field of view offset axis (see :ref:`coords-fov`). * ``BKG`` -- ndim: 2, unit: s^-1 MeV^-1 sr^-1 * Absolute post-select background rate (expected background per time, energy and solid angle). @@ -58,7 +58,7 @@ Required columns: * ``ENERG_LO``, ``ENERG_HI`` -- ndim: 1, unit: TeV * Reconstructed energy axis * ``DETX_LO``, ``DETX_HI``, ``DETY_LO``, ``DETY_HI`` -- ndim: 1, unit: deg - * Field of view coordinates binning, see :ref:`coords-fov` + * Field of view coordinates binning (see :ref:`coords-fov`) * ``BKG`` -- ndim: 3, unit: s^-1 MeV^-1 sr^-1 * Absolute post-select background rate (expected background per time, energy and solid angle). diff --git a/source/irfs/full_enclosure/edisp/index.rst b/source/irfs/full_enclosure/edisp/index.rst index 21f89cd..af44de5 100644 --- a/source/irfs/full_enclosure/edisp/index.rst +++ b/source/irfs/full_enclosure/edisp/index.rst @@ -20,7 +20,7 @@ Columns: * ``MIGRA_LO``, ``MIGRA_HI`` -- ndim: 1, unit: dimensionless * Energy migration axis (defined above) * ``THETA_LO``, ``THETA_HI`` -- ndim: 1, unit: deg - * Field of view offset axis + * Field of view offset axis (see :ref:`coords-fov`) * ``MATRIX`` -- ndim: 3, unit: dimensionless * Energy dispersion :math:`dP/d\mu`, see :ref:`iact-edisp`. diff --git a/source/irfs/full_enclosure/psf/psf_3gauss/index.rst b/source/irfs/full_enclosure/psf/psf_3gauss/index.rst index 2fb5b9c..2785fe6 100644 --- a/source/irfs/full_enclosure/psf/psf_3gauss/index.rst +++ b/source/irfs/full_enclosure/psf/psf_3gauss/index.rst @@ -47,7 +47,7 @@ Columns: * ``ENERG_LO``, ``ENERG_HI`` -- ndim: 1, unit: TeV * True energy axis * ``THETA_LO``, ``THETA_HI`` -- ndim: 1, unit: deg - * Field of view offset axis + * Field of view offset axis (see :ref:`coords-fov`) * ``SCALE`` -- ndim: 2, unit: none * Absolute scale of the 1st Gaussian * ``SIGMA_1``, ``SIGMA_2``, ``SIGMA_3`` -- ndim: 2, unit: deg diff --git a/source/irfs/full_enclosure/psf/psf_king/index.rst b/source/irfs/full_enclosure/psf/psf_king/index.rst index 5173948..51b87eb 100644 --- a/source/irfs/full_enclosure/psf/psf_king/index.rst +++ b/source/irfs/full_enclosure/psf/psf_king/index.rst @@ -26,7 +26,7 @@ Columns: * ``ENERG_LO``, ``ENERG_HI`` -- ndim: 1, unit: TeV * True energy axis * ``THETA_LO``, ``THETA_HI`` -- ndim: 1, unit: deg - * Field of view offset axis + * Field of view offset axis (see :ref:`coords-fov`) * ``GAMMA`` -- ndim: 2, unit: none * Model parameter (see formula above) * ``SIGMA`` -- ndim: 2, unit: deg diff --git a/source/irfs/full_enclosure/psf/psf_table/index.rst b/source/irfs/full_enclosure/psf/psf_table/index.rst index ebd7dc3..7a4811d 100644 --- a/source/irfs/full_enclosure/psf/psf_table/index.rst +++ b/source/irfs/full_enclosure/psf/psf_table/index.rst @@ -18,7 +18,7 @@ Columns: * ``ENERG_LO``, ``ENERG_HI`` -- ndim: 1, unit: TeV * True energy axis * ``THETA_LO``, ``THETA_HI`` -- ndim: 1, unit: deg - * Field of view offset axis + * Field of view offset axis (see :ref:`coords-fov`) * ``RAD_LO``, ``RAD_HI`` -- ndim: 1, unit: deg * Offset angle from source position * ``RPSF`` -- ndim: 3, unit: sr^-1 diff --git a/source/irfs/irf_axes/index.rst b/source/irfs/irf_axes/index.rst index f099182..2b6364f 100644 --- a/source/irfs/irf_axes/index.rst +++ b/source/irfs/irf_axes/index.rst @@ -12,8 +12,8 @@ stored in columns. The following names are recommended: for basic recommendations. Column names should be ``ENERGY`` or ``ENERG_LO``, ``ENERG_HI`` because that is used (consistently I think) for OGIP and Fermi-LAT. For separate HDUs, the extension names should be ``ENERGIES`` or ``EBOUNDS`` (used by Fermi-LAT consistently). -* Sky coordinates should be called ``RA``, ``DEC``, ``GLON``, ``GLAT``, ``ALT``, ``AZ``. -* Field of view coordinates ``DETX``, ``DETY`` or ``THETA``, ``PHI`` for offset and azimuth angle in the field of view. +* Sky coordinates should be called ``RA``, ``DEC``, ``GLON``, ``GLAT``, ``ALT``, ``AZ`` (see :ref:`coords`) +* Field of view coordinates ``DETX``, ``DETY`` or ``THETA``, ``PHI`` for offset and position angle in the field of view (see :ref:`coords-fov`). * Offset wrt. the source position should be called ``RAD`` (this is what the OGIP PSF formats use). In the specific case of point-like IRFs: