Localization ellipse angle

[jballet]

I have investigated the error ellipses returned by the localize() functionality of fermipy. I concluded that the ellipse major and minor axes are all right.
However, the angles do not look right. According to my comparison with the pointlike angles that we provide in the FGL catalogs, they have the wrong sign and an offset of 90°.
I looked at two particular examples with large ellipticities (pointlike plots , fermipy for FL16Y00076 , fermipy for FL16Y09119 ) and the ellipses in the plots look similarly oriented. So it appears to be largely a convention (and also documentation) issue.

The IAU convention is that position angle is defined with respect to celestial north and increases toward RA (which means the standard anti clock-wise convention, when RA increases to the left as in standard astronomical convention).
pointlike returns angles of -62° and +73° for FL16Y00076 and FL16Y09119, which are fully consistent with the green dashed ellipses on the pointlike plots.
fermipy, on the other hand, returns angles of 173° (= -7°) and +11°.
The close-ups provided by the second localization step (for FL16Y00076 and FL16Y09119 ) may help.
The ellipses are close to horizontal so it may be that the reference is the X axis (rather than the Y axis). The global negative correlation that I see with pointlike angles on many sources implies that the angle increases in the wrong direction. Indeed FL16Y00076 (which has angle 173°=-7°) appears to be at a positive angle wrt the X axis, while FL16Y09119 (which has angle +11°) appears to be at a negative angle wrt the X axis.

Another issue arises when working in Galactic coordinates, as I do. For FL16Y00076 I get an angle of +8°. I understand it is wrt the X axis of the image (and with the wrong sign, as above), so wrt to Galactic coordinates (although the convention is that PA is wrt celestial north).

Since this is largely a convention issue rather than a bug, I do not attach a test harness. The current ones take 1 hour, so they are not very practical.

Recommendation:

1. Change the reference to the Y axis
2. Change the sign
3. Document the fact that the angle is in the coordinate system defined by the image rather than the celestial system

Documentation:

1. it should describe the plots. The legend introduces confusion (why are there two entries for each of 68% and 99% Uncertainty). Are the green ellipses in the TS map and the white ones in the peak plot the same (presumably yes)? Are the black dashed contours in both plots the same (presumaby no, they apply to each image)?
2. it should tell that pos_angle is the angle between the major axis and the image axis (which one?) rather than to celestial north (which is the standard convention).
3. it should warn that the "localize" and "localize_peak" plots are not aligned. According to what I see on the examples (it is better seen on FL16Y00076, which is at high declination), the "localize" plots do not have north along the Y axis. I suspect this is because they are part of larger TS maps (which cover the full RoI). The TS maps have north up, but excerpts around sources offset laterally do not. On the contrary, the "localize_peak" maps have north along the Y axis.

This was obtained in fermipy 1.4.0 on S3DF