Feature skycoord

docs/mivot/index.rst

@@ -164,6 +164,27 @@ with the `astropy.io.votable` API:
 
 In this case, it is up to the user to ensure that the read data rows are those mapped by the Mivot annotations.
 
+Get a SkyCoord Instance Directly From the Annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you get a ``MivotInstance`` representing the last row read, you can use it to create an ``astropy.SkyCoord`` object.
+
+.. code-block:: python
+    :caption: Accessing the model view of Astropy table rows
+
+	from pyvo.mivot import MivotViewer
+    from pyvo.mivot.utils.dict_utils import DictUtils
+
+    m_viewer = MivotViewer(path_to_votable)
+    mivot_instance = m_viewer.dm_instance
+    print(mivot_instance.get_SkyCoord())
+    <SkyCoord (ICRS): (ra, dec) in deg(52.26722684, 59.94033461)
+          (pm_ra_cosdec, pm_dec) in mas / yr(-0.82, -1.85)>
+
+This feature works under the condition that the annotations contain a valid instance of ``mango:EPochPosition``. 
+Although not a standard at the time of writing, the class structure supported by this implementation must match the figure above.
+If the annotation do no contain any vali object, `None` is returned.
+
 For XML Hackers
 ---------------
 

pyvo/mivot/features/sky_coord_builder.py

@@ -0,0 +1,162 @@
+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+"""
+Utility transforming MIVOT annotation into SKYCoord instances
+"""
+
+from astropy.coordinates import SkyCoord
+from astropy import units as u
+from astropy.coordinates import ICRS, Galactic, FK4, FK5
+
+
+class MangoRoles:
+    """
+    Place holder for the roles of the mango:EpochPosition roles
+    """
+    LONGITUDE = "longitude"
+    LATITUDE = "latitude"
+    PM_LONGITUDE = "pmLongitude"
+    PM_LATITUDE = "pmLatitude"
+    PARALLAX = "parallax"
+    RADIAL_VELOCITY = "radialVelocity"
+    EPOCH = "epoch"
+    FRAME = "frame"
+    EQUINOX = "equinox"
+    PMCOSDELTAPPLIED = "pmCosDeltApplied"
+
+
+# Mapping of the MANGO parameters on the SkyCoord parameters
+skycoord_param_default = {
+    MangoRoles.LONGITUDE: 'ra', MangoRoles.LATITUDE: 'dec', MangoRoles.PARALLAX: 'distance',
+    MangoRoles.PM_LONGITUDE: 'pm_ra_cosdec', MangoRoles.PM_LATITUDE: 'pm_dec',
+    MangoRoles.RADIAL_VELOCITY: 'radial_velocity', MangoRoles.EPOCH: 'obstime'}
+
+skycoord_param_galactic = {
+    MangoRoles.LONGITUDE: 'l', MangoRoles.LATITUDE: 'b', MangoRoles.PARALLAX: 'distance',
+    MangoRoles.PM_LONGITUDE: 'pm_l_cosb', MangoRoles.PM_LATITUDE: 'pm_b',
+    MangoRoles.RADIAL_VELOCITY: 'radial_velocity', MangoRoles.EPOCH: 'obstime'}
+
+
+class SkyCoordBuilder(object):
+    '''
+    Utility generating SkyCoord instances from MIVOT annotations
+
+    - SkyCoord instances can only be built from model classes containing the minimal
+    set of required parameters (a position).
+    - In this implementation, only the mango:EpochPosition class is supported since
+      it proposes anything required to compute the epoch propagation which is a major use-case
+    '''
+
+    def __init__(self, mivot_instance_dict):
+        '''
+        Constructor
+
+        parameters
+        -----------
+        - mivot_instance_dict: viewer.MivotInstance.to_dict()
+                               Internal dictionary of the dynamic Python object generated
+                               from the MIVOT block
+        '''
+        self._mivot_instance_dict = mivot_instance_dict
+        self._map_coord_names = None
+
+    def build_sky_coord(self):
+        """
+        Build a SkyCoord instance from the dynamic Python object attribute.
+
+        returns
+        -------
+        - SkyCoord instance or None
+        """
+        if not self._mivot_instance_dict:
+            return None
+        if self._mivot_instance_dict["dmtype"] == "mango:EpochPosition":
+            return self._build_sky_coord_from_mango()
+        return None
+
+    def _set_year_time_format(self, hk_field):
+        """
+        Format a date expressed in year as J-year
+
+        parameters
+        ----------
+        - hk_field: MIVOT instance parameter as a dict
+
+        returns
+        -------
+        - formatted string
+        """
+        return (f"j{hk_field['value']}" if hk_field["unit"] in ("yr", "year")
+                else hk_field["value"])
+
+    def _get_space_frame(self):
+        """
+        Build an astropy space frame instance from the MIVOT annotations.
+
+        - Equinox are supported fot FK4/5
+        - Ref location are not supported
+
+        returns
+        -------
+        - Astropy space frame
+        """
+        coo_sys = self._mivot_instance_dict["coordSys"]
+        equinox = None
+        frame = coo_sys["spaceRefFrame"]["value"].lower()
+
+        if frame == 'fk4':
+            self._map_coord_names = skycoord_param_default
+            if "equinox" in coo_sys:
+                equinox = self._set_year_time_format(coo_sys["equinox"])
+                return FK4(equinox=equinox)
+            return FK4()
+
+        if frame == 'fk5':
+            self._map_coord_names = skycoord_param_default
+            if "equinox" in coo_sys:
+                equinox = self._set_year_time_format(coo_sys["equinox"])
+                return FK5(equinox=equinox)
+            return FK5()
+
+        if frame == 'galactic':
+            self._map_coord_names = skycoord_param_galactic
+            return Galactic()
+
+        self._map_coord_names = skycoord_param_default
+        return ICRS()
+
+    def _build_sky_coord_from_mango(self):
+        """
+        Build silently a SlyCoord instance from the mango:EpochPosition instance.
+        No error is trapped, unconsistencies in the mango:EpochPosition instance will
+        raise Astropy errors.
+
+        - The epoch (obstime) is meant to be given as J-year.
+        - ICRS frame is taken by default
+        - The cos-delta correction is meant to be applied.
+          The case mango:pmCosDeltApplied = False is not suppored yet
+
+        returns
+        -------
+        - SkyCoord instance
+        """
+        kwargs = {}
+        kwargs["frame"] = self._get_space_frame()
+
+        for key, value in self._map_coord_names.items():
+            # ignore not set parameters
+            if key not in self._mivot_instance_dict:
+                continue
+            hk_field = self._mivot_instance_dict[key]
+            # format the observation time (J-year by default)
+            if value == "obstime":
+                kwargs[value] = self._set_year_time_format(hk_field)
+            # Convert the parallax (mango) into a distance
+            elif value == "distance":
+                kwargs[value] = (hk_field["value"]
+                                 * u.Unit(hk_field["unit"]).to(u.parsec, equivalencies=u.parallax()))
+                kwargs[value] = kwargs[value] * u.parsec
+            elif "unit" in hk_field and hk_field["unit"]:
+                kwargs[value] = hk_field["value"] * u.Unit(hk_field["unit"])
+            else:
+                kwargs[value] = hk_field["value"]
+        return SkyCoord(**kwargs)

pyvo/mivot/tests/test_sky_coord_builder.py

@@ -0,0 +1,149 @@
+'''
+The first service in operation the annotates query responses in the fly is Vizier
+https://cds/viz-bin/mivotconesearch/VizierParams
+Data are mapped on the mango:EpochPropagtion class as it is implemented in the current code.
+This test case is based on 2 VOTables:
+Both tests check the generation of SkyCoord instances from the MivotInstances buil
+for the output of this service.
+'''
+import pytest
+from pyvo.mivot.version_checker import check_astropy_version
+from pyvo.mivot.viewer.mivot_instance import MivotInstance
+from pyvo.mivot.features.sky_coord_builder import SkyCoordBuilder
+
+# annotations generated by Vizier as given to the MivotInstance
+vizier_dict = {
+    "dmtype": "mango:EpochPosition",
+    "longitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 52.26722684,
+        "unit": "deg",
+        "ref": "RAICRS",
+    },
+    "latitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 59.94033461,
+        "unit": "deg",
+        "ref": "DEICRS",
+    },
+    "pmLongitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": -0.82,
+        "unit": "mas/yr",
+        "ref": "pmRA",
+    },
+    "pmLatitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": -1.85,
+        "unit": "mas/yr",
+        "ref": "pmDE",
+    },
+    "epoch": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 1991.25,
+        "unit": "yr",
+        "ref": None,
+    },
+    "coordSys": {
+        "dmtype": "coords:SpaceSys",
+        "dmid": "SpaceFrame_ICRS",
+        "dmrole": "coords:Coordinate.coordSys",
+        "spaceRefFrame": {
+            "dmtype": "coords:SpaceFrame",
+            "value": "ICRS",
+            "unit": None,
+            "ref": None,
+        },
+    },
+}
+# The same edited by hand (parallax added and FK5 + Equinox frame)
+vizier_equin_dict = {
+    "dmtype": "mango:EpochPosition",
+    "longitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 52.26722684,
+        "unit": "deg",
+        "ref": "RAICRS",
+    },
+    "latitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 59.94033461,
+        "unit": "deg",
+        "ref": "DEICRS",
+    },
+    "pmLongitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": -0.82,
+        "unit": "mas/yr",
+        "ref": "pmRA",
+    },
+    "pmLatitude": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": -1.85,
+        "unit": "mas/yr",
+        "ref": "pmDE",
+    },
+    "parallax": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 0.6,
+        "unit": "mas",
+        "ref": "parallax",
+    },
+    "epoch": {
+        "dmtype": "ivoa:RealQuantity",
+        "value": 1991.25,
+        "unit": "yr",
+        "ref": None,
+    },
+    "coordSys": {
+        "dmtype": "coords:SpaceSys",
+        "dmid": "SpaceFrame_ICRS",
+        "dmrole": "coords:Coordinate.coordSys",
+        "spaceRefFrame": {
+            "dmtype": "coords:SpaceFrame.spaceRefFrame",
+            "value": "FK5",
+            "unit": None,
+            "ref": None,
+        },
+        "equinox": {
+            "dmtype": "coords:SpaceFrame.equinox",
+            "value": "2012",
+            "unit": "yr",
+        },
+    },
+}
+
+
+@pytest.mark.skipif(not check_astropy_version(), reason="need astropy 6+")
+def test_vizier_output():
+    """ Test the SkyCoord issued from the Vizier response
+    """
+    mivot_instance = MivotInstance(**vizier_dict)
+    scb = SkyCoordBuilder(mivot_instance.to_dict())
+    scoo = scb.build_sky_coord()
+    assert (str(scoo).replace("\n", "").replace("  ", "")
+            == "<SkyCoord (ICRS): (ra, dec) in deg(52.26722684, 59.94033461) "
+               "(pm_ra_cosdec, pm_dec) in mas / yr(-0.82, -1.85)>")
+    scoo = mivot_instance.get_SkyCoord()
+    assert (str(scoo).replace("\n", "").replace("  ", "")
+            == "<SkyCoord (ICRS): (ra, dec) in deg(52.26722684, 59.94033461) "
+               "(pm_ra_cosdec, pm_dec) in mas / yr(-0.82, -1.85)>")
+
+
+@pytest.mark.skipif(not check_astropy_version(), reason="need astropy 6+")
+def test_vizier_output_with_equinox_and_parallax():
+    """Test the SkyCoord issued from the modofier Vizier response *
+    (parallax added and FK5 + Equinox frame)
+    """
+    mivot_instance = MivotInstance(**vizier_equin_dict)
+    scb = SkyCoordBuilder(mivot_instance.to_dict())
+    scoo = scb.build_sky_coord()
+    assert (str(scoo).replace("\n", "").replace("  ", "")
+            == "<SkyCoord (FK5: equinox=J2012.000): (ra, dec, distance) in "
+               "(deg, deg, pc)(52.26722684, 59.94033461, 600.) "
+               "(pm_ra_cosdec, pm_dec) in mas / yr(-0.82, -1.85)>")
+    scoo = mivot_instance.get_SkyCoord()
+    assert (str(scoo).replace("\n", "").replace("  ", "")
+            == "<SkyCoord (FK5: equinox=J2012.000): (ra, dec, distance) in "
+               "(deg, deg, pc)(52.26722684, 59.94033461, 600.) "
+               "(pm_ra_cosdec, pm_dec) in mas / yr(-0.82, -1.85)>")