From 57987b42e0f42ff30cbfb4c048ab7d6dea96d450 Mon Sep 17 00:00:00 2001 From: Leo Singer Date: Wed, 21 Feb 2024 12:51:33 -0500 Subject: [PATCH] Replace localization uncertainty properties with one error radius Replace the localization properties `uncertainty_shape`, `ra_uncertainty`, `dec_uncertainty`, and `position_angle` with a single property called `ra_dec_error`. The original localization uncertainty properties were ill-conceived in many ways: 1. The names `ra_uncertainty` and `dec_uncertainty` were misleading. For example, for ellipses, these fields actually represented the lengths of the semi-major and semi-minor axes, and not the uncertainty in ra or dec. 2. The names of these properties were inconsistent with other schema. Every other uncertainty property exept for these has a name ending in `_error`, not `_uncertainty`. 3. The `rectangle` shape was not useful. The most significant examples of quadrilateral localization regions are IPN error boxes. However, these are parallelograms, not rectangles, so the shape would have been under-specified. We have observed that all current missions in GCN either report error circles or HEALPix maps. Given that observation, this patch replaces all of the ill-conceived localization properties with a single `ra_dec_error` field which is the radius in degrees of the error circle. In the future, there might be a mission that requires ellipses. We won't deal with that now, but in that event we would have a few different backwards-compatible options. For example, we could: - Treat the `ra_dec_error` field as the semi-major axis, and add optional fields `ra_dec_error_b` and `ra_dec_error_pa` for the semi-minor axis and the position angle, respectively; or - Allow `ra_dec_error` to be either a single scalar, or an array of up to three numbers, representing the semi-major axis, semi-minor axis, and position angle, respectively. Fixes #120. --- gcn/notices/burstcube/Alert.example.json | 4 +--- gcn/notices/burstcube/Test.example.json | 4 +--- gcn/notices/core/Localization.example.json | 5 +---- gcn/notices/core/Localization.schema.json | 20 ++----------------- .../icecube/lvk_nu_track_search.example.json | 6 ++---- .../test/gold_bronze.update.example.json | 4 +--- .../gold_bronze_track_alerts.example.json | 3 +-- .../swift/bat/guano.loc_arc_min.example.json | 2 +- 8 files changed, 10 insertions(+), 38 deletions(-) diff --git a/gcn/notices/burstcube/Alert.example.json b/gcn/notices/burstcube/Alert.example.json index 4f8427ff..8859f55a 100644 --- a/gcn/notices/burstcube/Alert.example.json +++ b/gcn/notices/burstcube/Alert.example.json @@ -9,9 +9,7 @@ "id": ["240601000"], "ra": 232.0, "dec": -53.1, - "uncertainty_shape": "circle", - "ra_uncertainty": [10], - "dec_uncertainty": [10], + "ra_dec_error": 10, "containment_probability": 0.9, "systematic_included": false, "healpix_url": "https://heasarc.gsfc.nasa.gov/burstcube/trigger/240601000/current/240601000_locmap.fits", diff --git a/gcn/notices/burstcube/Test.example.json b/gcn/notices/burstcube/Test.example.json index 48b9b4d5..e846463f 100644 --- a/gcn/notices/burstcube/Test.example.json +++ b/gcn/notices/burstcube/Test.example.json @@ -9,9 +9,7 @@ "id": ["240601000"], "ra": 232.0, "dec": -53.1, - "uncertainty_shape": "circle", - "ra_uncertainty": [10], - "dec_uncertainty": [10], + "ra_dec_error": 10, "containment_probability": 0.9, "systematic_included": false, "healpix_url": "https://heasarc.gsfc.nasa.gov/burstcube/trigger/240601000/current/240601000_locmap.fits", diff --git a/gcn/notices/core/Localization.example.json b/gcn/notices/core/Localization.example.json index 9f13fca2..4b64d85b 100644 --- a/gcn/notices/core/Localization.example.json +++ b/gcn/notices/core/Localization.example.json @@ -2,10 +2,7 @@ "$schema": "https://gcn.nasa.gov/schema/main/gcn/notices/core/Localization.schema.json", "ra": 120, "dec": 45, - "uncertainty_shape": "ellipse", - "ra_uncertainty": [-0.1, 0.05], - "dec_uncertainity": [-0.2, 0.5], - "position_angle": 0, + "ra_dec_error": 0.5, "containment_probability": 0.95, "systematic_included": true, "instrument_phi": 90, diff --git a/gcn/notices/core/Localization.schema.json b/gcn/notices/core/Localization.schema.json index 376c067e..2f050f54 100644 --- a/gcn/notices/core/Localization.schema.json +++ b/gcn/notices/core/Localization.schema.json @@ -13,25 +13,9 @@ "type": "number", "description": "ICRS declination [deg], utilizes the J2000 epoch and an equatorial coordinate system" }, - "uncertainty_shape": { - "enum": ["circle", "ellipse", "rectangle"], - "description": "In what manner are the errors in RA and Dec defined - as circular, elliptical, or rectangular shapes", - "default": "circle" - }, - "ra_uncertainty": { - "type": "array", - "maxItems": 2, - "description": "Uncertainty in RA [deg] with optional asymmetric errors, measured from the RA in the schema; respective ex: [r], [r1], [l1-, l1+]. For ellipse, ra axis is r1 or semi-major axis." - }, - "dec_uncertainty": { - "type": "array", - "maxItems": 2, - "description": "Uncertainty in Dec [deg] with optional asymmetric errors, measured from the Dec in the schema; respective ex: [r2], [l2-, l2+]. Not reported if circular and Dec axis is r2 or semi-minor axis for ellipse." - }, - "position_angle": { + "ra_dec_error": { "type": "number", - "description": "Anti-clockwise position angle from RA axis [deg]. Used if uncertainty_shape ellipse or rectangle is tilted w.r.t. standard (RA, Dec) coordinate.", - "default": 0 + "description": "Radius [deg] of error circle with the given probability of containing the true, but unknown, position of the source (see containment_probability)" }, "containment_probability": { "type": "number", diff --git a/gcn/notices/icecube/lvk_nu_track_search.example.json b/gcn/notices/icecube/lvk_nu_track_search.example.json index 98534276..63fb3398 100644 --- a/gcn/notices/icecube/lvk_nu_track_search.example.json +++ b/gcn/notices/icecube/lvk_nu_track_search.example.json @@ -17,8 +17,7 @@ "localization": { "ra": 17.48, "dec": 16.15, - "uncertainty_shape": "circle", - "ra_uncertainty": [0.43], + "ra_dec_error": 0.43, "containment_probability": 0.9, "systematic_included": false }, @@ -30,8 +29,7 @@ "localization": { "ra": 13.82, "dec": 18.66, - "uncertainty_shape": "circle", - "ra_uncertainty": [0.88], + "ra_dec_error": 0.88, "containment_probability": 0.9, "systematic_included": false }, diff --git a/gcn/notices/icecube/test/gold_bronze.update.example.json b/gcn/notices/icecube/test/gold_bronze.update.example.json index e6324419..89b5fe23 100644 --- a/gcn/notices/icecube/test/gold_bronze.update.example.json +++ b/gcn/notices/icecube/test/gold_bronze.update.example.json @@ -7,10 +7,8 @@ "alert_type": "update", "ra": 345.82, "dec": 9.01, - "uncertainty_shape": "rectangle", "position_angle": 0, - "ra_uncertainty": [-1.5, 1.4], - "dec_uncertainty": [-1.2, 1.3], + "ra_dec_error": 1.3, "containment_probability": 0.9, "systematic_included": false, "healpix_url": "https://roc.icecube.wisc.edu/public/", diff --git a/gcn/notices/icecube/test/gold_bronze_track_alerts.example.json b/gcn/notices/icecube/test/gold_bronze_track_alerts.example.json index 03f47015..2f5d9f39 100644 --- a/gcn/notices/icecube/test/gold_bronze_track_alerts.example.json +++ b/gcn/notices/icecube/test/gold_bronze_track_alerts.example.json @@ -6,8 +6,7 @@ "alert_type": "initial", "ra": 345.82, "dec": 9.01, - "uncertainty_shape": "circle", - "ra_uncertainty": [0.51], + "ra_dec_error": 0.51, "containment_probability": 0.9, "systematic_included": false, "trigger_time": "2023-04-16T05:22:26.150574Z", diff --git a/gcn/notices/swift/bat/guano.loc_arc_min.example.json b/gcn/notices/swift/bat/guano.loc_arc_min.example.json index dfffcd1d..798b5e29 100644 --- a/gcn/notices/swift/bat/guano.loc_arc_min.example.json +++ b/gcn/notices/swift/bat/guano.loc_arc_min.example.json @@ -10,7 +10,7 @@ "trigger_time": "2022-12-31T21:46:05.13Z", "ra": 336.26, "dec": 25.139, - "ra_uncertainty": [0.05], + "ra_dec_error": 0.05, "containment_probability": 0.9, "systematic_included": true, "rate_snr": 15.8,