Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Field of view coordinates and IRF axis names #13

Merged
merged 1 commit into from
Jun 27, 2018
+63 −41
Merged

Field of view coordinates and IRF axis names #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 8 additions & 15 deletions source/events/events.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't DETX and DETY be replaced by the more clearly named FOV_ALTAZ_LON, etc...?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my comment above.

* ``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
Expand Down
65 changes: 47 additions & 18 deletions source/general/coordinates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <bkg>` 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 <bkg>` 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 <iact-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 <iact-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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't recommend to not put FOV coordinates in EVENTS. Maybe better to encourage to use unambiguous names such as e.g. FOV_ALTAZ_LON, FOV_ALTAZ_LAT.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm -1 on encouraging the use of new column names such as FOV_ALTAZ_LON, FOV_ALTAZ_LAT and starting to add support for those in exporters and Gammapy / ctools.
We weren't able to agree with DETX / DETY even while no-one was using it, so it's highly unlikely that we're going to agree on new column names.
I really suggest to leave this decision to the future and to CTA, we can't resolve this here while the relevant people aren't participating in the discussion and no-one has decision making power.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, fine with me!


.. _coords-location:

Earth location
Expand Down
4 changes: 2 additions & 2 deletions source/irfs/full_enclosure/bkg/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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`)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are of course also somewhat ambiguous, it's not clear along which system these are aligned. Add a note that this should be specified clearly?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have written long comments / notes in the general FOV section. Does it really help to partly re-hash those comments here?
If you think so, would you be willing to add a commit to this branch with any text changes you like?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, this is probably not necessary. Ignore my comment.

* ``BKG`` -- ndim: 3, unit: s^-1 MeV^-1 sr^-1
* Absolute post-select background rate
(expected background per time, energy and solid angle).
Expand Down
2 changes: 1 addition & 1 deletion source/irfs/full_enclosure/edisp/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
2 changes: 1 addition & 1 deletion source/irfs/full_enclosure/psf/psf_3gauss/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion source/irfs/full_enclosure/psf/psf_king/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion source/irfs/full_enclosure/psf/psf_table/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions source/irfs/irf_axes/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down