Merge pull request #145 from GreenBankObservatory/veldef_function

Veldef function

src/dysh/fits/__init__.py

@@ -1,4 +1,5 @@
 """Classes and functions for importing SDFITS files"""
+from dysh.fits.core import *  # noqa
 from dysh.fits.gb20mfitsload import GB20MFITSLoad  # noqa
 from dysh.fits.gbtfitsload import GBTFITSLoad  # noqa
 from dysh.fits.sdfitsload import SDFITSLoad  # noqa

src/dysh/fits/core.py

@@ -0,0 +1,78 @@
+"""
+Core functions for FITS/SDFITS
+"""
+
+# Velocity frame conventions, partially stolen from pyspeckit.
+# See also Section6.2.5.2 of the GBT observer's guide https://www.gb.nrao.edu/scienceDocs/GBTog.pdf
+
+frame_dict = {
+    "VLSR": "LSRK",
+    "VRAD": "LSRK",
+    "VELO": "LSRK",
+    "VOPT": "LSRK",
+    "LSRD": "LSRD",
+    "LSRK": "LSRK",
+    "-LSR": "LSRK",
+    "-HEL": "heliocentric",
+    "-BAR": "barycentric",
+    "BAR": "barycentric",
+    "BARY": "barycentric",
+    "-OBS": "obs",
+    "VHEL": "heliocentric",
+    "VGEO": "topocentric",
+    "TOPO": "topocentric",
+    "VREST": "rest",
+    "Z": "rest",
+    "FREQ": "rest",
+    "WAV": "rest",
+    "WAVE": "rest",
+    "CMB": "cmb",
+    "GALAC": "galactic",
+    "GALA": "galactic",
+    "ALAC": "galactic",
+}
+
+# Dictionary to convert from FITS velocity convention to specutils string.
+# At GBT, VELO was written by sdfits filler for some unknown amount of
+# time instead of RELA, so allow for it here
+vconv_dict = {
+    "OPTI": "doppler_optical",
+    "RADI": "doppler_radio",
+    "RELA": "doppler_relativistic",
+    "VELO": "doppler_relativistic",
+}
+
+
+def decode_veldef(veldef):
+    """
+    Parse the SDFITS VELDEF value into its two components, the velocity
+    definition and velocity reference frame.  This value must contain
+    no more than 8 characters where the first 4 characters describe the velocity
+    definition and the last 4 characters describe the reference frame.
+
+    Parameters
+    ----------
+    veldef : str
+        The definition string, consisting of a velocity convention and a velocity frame, e.g.,  'OPTI-LSR'
+
+    Returns
+    -------
+    A str tuple of velocity convention and velocity frame type, e.g., ('doppler_radio', 'LSRK')
+    """
+    if len(veldef) > 8:
+        # in future, possibly relax this requirement
+        # if string not coming from FITS
+        raise ValueError(f"VELDEF string {veldef} must be no more than 8 characters.")
+    vconv = veldef[:4]
+    try:
+        velocity_convention = vconv_dict[vconv]
+    except KeyError:
+        raise KeyError(f"Velocity convention {vconv} not recognized.")
+
+    frame = veldef[4:]
+    try:
+        frame_type = frame_dict[frame]
+    except KeyError:
+        raise KeyError(f"Velocity frame {frame} not recognized.")
+
+    return velocity_convention, frame_type

src/dysh/fits/tests/test_fits_core.py

@@ -0,0 +1,48 @@
+from dysh.fits import decode_veldef
+
+
+class TestCore:
+    """Test dysh.fits core functions"""
+
+    def test_veldef(self):
+        # first make sure we get correct answers for normal inputs
+        inputs = [
+            "RADILSRK",
+            "RADI-LSR",
+            "RADILSRD",
+            "OPTICMB",
+            "VELO-BAR",
+            "OPTIBARY",
+            "RELATOPO",
+            "RADIGALA",
+            "OPTI-HEL",
+        ]
+        outputs = [
+            ("doppler_radio", "LSRK"),
+            ("doppler_radio", "LSRK"),
+            ("doppler_radio", "LSRD"),
+            ("doppler_optical", "cmb"),
+            ("doppler_relativistic", "barycentric"),
+            ("doppler_optical", "barycentric"),
+            ("doppler_relativistic", "topocentric"),
+            ("doppler_radio", "galactic"),
+            ("doppler_optical", "heliocentric"),
+        ]
+        for i, j in zip(inputs, outputs):
+            assert decode_veldef(i) == j
+
+        # Now test that bad input raises an exception
+        try:
+            decode_veldef("This is more than 8 chars")
+        except ValueError:
+            assert True
+        try:
+            # frame fails
+            decode_veldef("OPTI-LRS")
+        except KeyError:
+            assert True
+        try:
+            # convention fails
+            decode_veldef("MAXILSRK")
+        except KeyError:
+            assert True