CASA frequency conversion tutorial #ALMA #python

casa-frequency-conversion.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "23517181-4cb5-417a-8a1f-2db30aaf2290",
   "metadata": {},
   "source": [
    "# CASA frequency conversion tutorial\n",
    "\n",
    "This notebook demonstrates how we can use casatools to convert frequency frame.\n",
    "\n",
    "## Dataset\n",
    "\n",
    "Dataset and metadata for the conversion can be defined in the following cell. Please update as needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a3eb76d0-4bc0-4a0f-9d82-688cd7550b62",
   "metadata": {},
   "outputs": [],
   "source": [
    "vis = 'uid___A002_X85c183_X36f.ms'\n",
    "antenna_id = 0\n",
    "field_id = 1\n",
    "spw_id = 23"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d18ab46-6ef2-48f8-84e7-92f45234d596",
   "metadata": {},
   "source": [
    "## CASA tools\n",
    "\n",
    "We use `measures` and `quanta` for frequency frame conversion. We also use `msmetadata` and `table` to retrieve necessary information from MS."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "66a90e93-daba-431e-b9ad-11b83662a3e5",
   "metadata": {},
   "outputs": [],
   "source": [
    "from casatools import quanta, measures, msmetadata, table\n",
    "me = measures()\n",
    "msmd = msmetadata()\n",
    "qa = quanta()\n",
    "tb = table()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "981ccaa4-a8bb-4297-9222-5b5453e10817",
   "metadata": {},
   "source": [
    "## Conversion\n",
    "\n",
    "Basic procedure for frame conversion is fairly simple.\n",
    "\n",
    "1. initialize `measures` instance (`me` hereafter)\n",
    "2. give source frame information necessary for the conversion to `me`, and\n",
    "3. run frame conversion method with the value to be converted and destination frame information\n",
    "4. update source frame information as needed\n",
    "5. run frame conversion method with another value and destination frame information\n",
    "6. repeat 4. and 5. as needed\n",
    "\n",
    "### Conversion: initialize `me`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "319c69d4-5e2a-4fbd-97a5-cd5026ab58e3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "me.done()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9d1926f-ab69-488b-9dd2-70e7fe59d100",
   "metadata": {},
   "source": [
    "### Conversion: give source frame information to `me`\n",
    "\n",
    "All the information should be retrieved from MS using `msmetadata` instance (`msmd` hereafter). Necessary information for frequency frame conversion is,\n",
    "\n",
    "* field direction\n",
    "* antenna position\n",
    "* observing time\n",
    "\n",
    "For accurate conversion, observing time must be taken from appropriate rows of TIME column in MAIN table, using `table` tool. Here, we use `msmd` to get some reasonable (but might be less accurate) value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "e953a773-1b66-4dda-96b2-94879cd9b175",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Frame: Epoch: 56839::21:59:57.1200 (TDB = 56839.9, UT1 = 56839.9, TT = 56839.9)\n",
      "       Position: [2.22507e+06, -5.44015e+06, -2.4815e+06]\n",
      "        (Longitude = -1.18255 Latitude = -0.399493)\n",
      "       Direction: [-0.95735, -0.0960034, 0.272516]\n",
      "        (J2000 = [-174.273, 15.8141] deg)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2024-03-04 02:16:19\tINFO\tmsmetadata_cmpt.cc::open\tPerforming internal consistency checks on uid___A002_X85c183_X36f.ms...\n"
     ]
    }
   ],
   "source": [
    "# open MS\n",
    "msmd.open(vis)\n",
    "\n",
    "# get field direction \n",
    "field_direction = msmd.refdir(field_id)\n",
    "\n",
    "# get antenna position\n",
    "antenna_position = msmd.antennaposition(antenna_id)\n",
    "\n",
    "# observing time: here we pick up some reasonable value from target scans\n",
    "# returned values are in seconds and in UTC\n",
    "times_on_source = msmd.timesforintent('OBSERVE_TARGET#ON_SOURCE')\n",
    "t0, t1 = times_on_source.min(), times_on_source.max()\n",
    "\n",
    "# convert time values into time measure (epoch)\n",
    "e0 = me.epoch(rf='UTC', v0=qa.quantity(t0, 's'))\n",
    "e1 = me.epoch(rf='UTC', v0=qa.quantity(t1, 's'))\n",
    "\n",
    "# frequency values to be converted\n",
    "channel_frequencies = msmd.chanfreqs(spw=spw_id, unit='Hz')\n",
    "\n",
    "# close MS\n",
    "msmd.close()\n",
    "\n",
    "# give the information to me\n",
    "me.doframe(e0)\n",
    "me.doframe(antenna_position)\n",
    "me.doframe(field_direction)\n",
    "\n",
    "# confirm frame information \n",
    "print(me.showframe())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e65e3ebf-ddd7-4f3d-a03b-9b5d1a6ee5c4",
   "metadata": {},
   "source": [
    "### Conversion: run frame conversion\n",
    "\n",
    "Perform frequency conversion from frequency value and its source frame to destination frame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "355fcc23-4424-4dab-b4ef-882266987907",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SOURCE FREQUENCY:\n",
      "{'m0': {'unit': 'Hz', 'value': 113686300390.625}, 'refer': 'TOPO', 'type': 'frequency'}\n",
      "DESTINATION FREQUENCY:\n",
      "{'m0': {'unit': 'Hz', 'value': 113695180437.1707}, 'refer': 'LSRK', 'type': 'frequency'}\n"
     ]
    }
   ],
   "source": [
    "spw_table = vis + '/SPECTRAL_WINDOW'\n",
    "tb.open(spw_table)\n",
    "column_keys = tb.getcolkeywords('CHAN_FREQ')\n",
    "freq_ref = tb.getcell('MEAS_FREQ_REF', spw_id)\n",
    "channel_frequency_list = tb.getcell('CHAN_FREQ', spw_id)\n",
    "tb.close()\n",
    "\n",
    "# get source frame information\n",
    "source_frame_index = list(column_keys['MEASINFO']['TabRefCodes']).index(freq_ref)\n",
    "source_frame = column_keys['MEASINFO']['TabRefTypes'][source_frame_index]\n",
    "\n",
    "# destination frame information is LSRK\n",
    "destination_frame = 'LSRK'\n",
    "\n",
    "# create frequency measure: here we pick up one frequency value for demo\n",
    "freq_value = channel_frequency_list[0]\n",
    "freq_unit = column_keys['QuantumUnits'][0]\n",
    "freq_from = me.frequency(rf=source_frame, v0=qa.quantity(freq_value, freq_unit))\n",
    "\n",
    "# run frame conversion\n",
    "freq_to_0 = me.measure(v=freq_from, rf=destination_frame)\n",
    "\n",
    "print('SOURCE FREQUENCY:')\n",
    "print(freq_from)\n",
    "\n",
    "print('DESTINATION FREQUENCY:')\n",
    "print(freq_to_0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60e80239-c650-414e-876a-1a1d5a1e4d33",
   "metadata": {},
   "source": [
    "### Conversion: update source frame information as needed\n",
    "\n",
    "In this example, only information requires update is time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "62fff1de-abce-46e6-b190-6f6876dad805",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Frame: Epoch: 56839::22:40:12.8640 (TDB = 56839.9, UT1 = 56839.9, TT = 56839.9)\n",
      "       Position: [2.22507e+06, -5.44015e+06, -2.4815e+06]\n",
      "        (Longitude = -1.18255 Latitude = -0.399493)\n",
      "       Direction: [-0.95735, -0.0960034, 0.272516]\n",
      "        (J2000 = [-174.273, 15.8141] deg)\n"
     ]
    }
   ],
   "source": [
    "me.doframe(e1)\n",
    "\n",
    "print(me.showframe())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e8c7d65-6c14-4252-8120-183b08f7f46a",
   "metadata": {},
   "source": [
    "### Conversion: run frame conversion method with another value\n",
    "\n",
    "Convert the same frequency value using different time reference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "bd5fd748-bc37-47a1-a84f-5ea04c13caa6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SOURCE FREQUENCY:\n",
      "{'m0': {'unit': 'Hz', 'value': 113686300390.625}, 'refer': 'TOPO', 'type': 'frequency'}\n",
      "DESTINATION FREQUENCY (0):\n",
      "{'m0': {'unit': 'Hz', 'value': 113695180437.1707}, 'refer': 'LSRK', 'type': 'frequency'}\n",
      "DESTINATION FREQUENCY (1):\n",
      "{'m0': {'unit': 'Hz', 'value': 113695206971.95573}, 'refer': 'LSRK', 'type': 'frequency'}\n"
     ]
    }
   ],
   "source": [
    "# run frame conversion\n",
    "freq_to_1 = me.measure(v=freq_from, rf=destination_frame)\n",
    "\n",
    "print('SOURCE FREQUENCY:')\n",
    "print(freq_from)\n",
    "\n",
    "print('DESTINATION FREQUENCY (0):')\n",
    "print(freq_to_0)\n",
    "\n",
    "print('DESTINATION FREQUENCY (1):')\n",
    "print(freq_to_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71b767c6-8f16-45c8-869d-7d80059781e9",
   "metadata": {},
   "source": [
    "### Conversion: finalization\n",
    "\n",
    "Clear frame information registered to `me`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "8cb01592-f0b4-4b96-8808-18905bcc833e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "me.done()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}