QuickReference.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Overview\n",
    "NASA services can be queried from Python in multiple ways.\n",
    "* Generic Virtual Observatory (VO) queries.\n",
    "  * Call sequence is consistent, including for non-NASA resources.\n",
    "  * Some reference notebooks available at https://heasarc.gsfc.nasa.gov/vo/summary/python.html\n",
    "* Astroquery interfaces\n",
    "  * Call sequences not quite as consistent, but follow similar patterns.\n",
    "  * See https://astroquery.readthedocs.io/en/latest/\n",
    "* Ad hoc archive-specific interfaces"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. VO Services\n",
    "## 2.1 Lookup Services in VO Directory (Registry)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Surpress known innocuous warnings\n",
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\", module=\"astropy.io.votable.*\")\n",
    "\n",
    "from navo_utils.registry import Registry\n",
    "\n",
    "# Simple example:  Find Cone Search services related to SWIFT.\n",
    "services=Registry.query(service_type='cone', keyword='swift')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1.1 Use different arguments/values to modify the simple example\n",
    "| Argument | Description | Examples |\n",
    "| :-----: | :-----------: | :--------: |\n",
    "| **service_type (required)** | Type of service | 'cone', 'image', 'spectra', 'table' |\n",
    "| **keyword** | Results will contain the keyword in ivoid, title, or description | 'galex', 'swift' |\n",
    "| **waveband** | Resulting services have data in the specified waveband(s) | 'gamma-ray', 'X-ray', 'EUV', 'UV' , 'optical' , 'infrared' , 'millimeter' , 'radio', 'UV,optical' |\n",
    "| **publisher** | Name (or substring of) publishing organization | 'CDS', 'HEASARC', 'Space Telescope', 'IPAC' |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1.2 Inspect the results.\n",
    "See http://docs.astropy.org/en/stable/table/ for more on working with Astropy Tables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(services.info)  # Show the number of rows and the column names.\n",
    "print(services)  # Default display of Astropy Table.\n",
    "print(services[:3]['short_name', 'reference_url'])  # Show first 3 short names and reference URLs.\n",
    "\n",
    "# or in a Jupyter notebook\n",
    "services.show_in_notebook()  # Display an interactive table in the notebook.\n",
    "Registry.display_results(services)  # Format result to make long descriptions more readable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.2 Cone search\n",
    "Example:  Find a cone search service for the USNO-B catalog and search it around M51 with a .5 degree radius.  (More inspection could be done on the service list instead of blindly choosing the first service.)  The *coords* argument can be anything accepted by: https://astroquery.readthedocs.io/en/latest/api/astroquery.utils.parse_coordinates.html#astroquery.utils.parse_coordinates\n",
    "\n",
    "More information on creating Astropy SkyCoord objects: http://docs.astropy.org/en/stable/api/astropy.coordinates.SkyCoord.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from navo_utils.cone import Cone\n",
    "services=Registry.query(service_type='cone', keyword='usno-b')\n",
    "results = Cone.query(service=services[0], coords='m51',radius=.5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.3 Image search\n",
    "Example:  Find an image search service for GALEX, and search it around coordinates 13:37:00.950,-29:51:55.51 (M83) with a radius of .2 degrees.  Download the first file in the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from navo_utils.image import Image, ImageColumn\n",
    "services=Registry.query(service_type='image', keyword='galex', publisher='Space Telescope')\n",
    "image_results_list = Image.query(service=services[0], coords='13:37:00.950,-29:51:55.51', radius=0.2)\n",
    "image_results = image_results_list[0]  # List would be longer if list of services was input.\n",
    "\n",
    "from astropy.utils.data import download_file\n",
    "local_path = download_file(image_results[0][ImageColumn.ACCESS_URL])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.4 Spectral search\n",
    "Example:  Find a spectral service for x-ray data.  Query it around Delta Ori, and download the first data product.  Note that the results table can be inspected for potentially useful columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from navo_utils.spectra import Spectra, SpectraColumn\n",
    "from astropy.coordinates import SkyCoord\n",
    "\n",
    "delori = SkyCoord.from_name(\"delta ori\")\n",
    "\n",
    "services = Registry.query(service_type='spectr', waveband='x-ray')\n",
    "spectra_results_list = Spectra.query(service=services[0], coords=delori, radius=0.1)\n",
    "spectra_results = spectra_results_list[0]  # List would be longer if list of services was input.\n",
    "\n",
    "from astropy.utils.data import download_file\n",
    "local_path = download_file(spectra_results[0][SpectraColumn.ACCESS_URL])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.5 Table search\n",
    "Example:  Find the HEASARC Table Access Protocol (TAP) service, get some information about the available tables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from navo_utils.tap import Tap\n",
    "tap_services = Registry.query(service_type='table',source='heasarc')\n",
    "tap_url = str(tap_services[0]['access_url'])\n",
    "\n",
    "Tap.list_tables(tap_url)  # list table names and descriptions\n",
    "Tap.list_tables(tap_url, contains='chan')  # list table names and descriptions where name contains 'chan'\n",
    "table_list = Tap.get_tables(tap_url)  # Same as list_tables, but returns list of table objects\n",
    "Tap.list_columns(tap_url,tablename=\"public.zcat\")  # list columns for table 'public.zcat'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Example:  Perform a cone search on the ZCAT catalog."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "query = \"\"\"\n",
    "select name, ra, dec, bmag, redshift from public.zcat as cat \n",
    "where contains(point('ICRS',cat.ra,cat.dec),circle('ICRS',202.5,47.0,1.0))=1 \n",
    "and cat.bmag < 14\n",
    "\"\"\"\n",
    "results=Tap.query(tap_url,query)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Astroquery \n",
    "Many archives have Astroquery modules for data access, including:\n",
    "\n",
    "* [HEASARC Queries (astroquery.heasarc)](https://astroquery.readthedocs.io/en/latest/heasarc/heasarc.html)\n",
    "* [HITRAN Queries (astroquery.hitran)](https://astroquery.readthedocs.io/en/latest/hitran/hitran.html)\n",
    "* [IRSA Image Server program interface (IBE) Queries (astroquery.ibe)](https://astroquery.readthedocs.io/en/latest/ibe/ibe.html)\n",
    "* [IRSA Queries (astroquery.irsa)](https://astroquery.readthedocs.io/en/latest/irsa/irsa.html)\n",
    "* [IRSA Dust Extinction Service Queries (astroquery.irsa_dust)](https://astroquery.readthedocs.io/en/latest/irsa/irsa_dust.html)\n",
    "* [JPL Spectroscopy Queries (astroquery.jplspec)](https://astroquery.readthedocs.io/en/latest/jplspec/jplspec.html)\n",
    "* [MAST Queries (astroquery.mast)](https://astroquery.readthedocs.io/en/latest/mast/mast.html)\n",
    "* [NASA ADS Queries (astroquery.nasa_ads)](https://astroquery.readthedocs.io/en/latest/nasa_ads/nasa_ads.html)\n",
    "* [NED Queries (astroquery.ned)](https://astroquery.readthedocs.io/en/latest/ned/ned.html)\n",
    "\n",
    "For more, see https://astroquery.readthedocs.io/en/latest/\n",
    "\n",
    "## 3.1 NED\n",
    "Example:  Get an Astropy Table containing the objects from paper 2018ApJ...858...62K.  For more on the API, see https://astroquery.readthedocs.io/en/latest/ned/ned.html "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astroquery.ned import Ned\n",
    "objects_in_paper = Ned.query_refcode('2018ApJ...858...62K')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}