pywwt-notebooks/NASA Exoplanet Archive.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Visualizing the NASA Exoplanet Archive"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook, we will visualize the table of confirmed exoplanets from the [NASA Exoplanet Archive](https://exoplanetarchive.ipac.caltech.edu/index.html) (as of 30th September 2019), and we will take a look at some of the more advanced features of tabular data visualization."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 1: Loading the tabular data\n",
    "\n",
    "We start off by loading the table using the [astropy.table](https://docs.astropy.org/en/stable/table/) module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from astropy.table import Table\n",
    "\n",
    "exoplanets = Table.read(os.path.join('data', 'planets_2019.09.30_16.25.03.votable'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and we take a look at the first five rows to familiarize ourselves with the data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "exoplanets[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 2: Setting up WWT\n",
    "\n",
    "First, we need to connect to the WWT app. If WWT isn't running yet, activate the JupyterLab command palette from the View menu, and select \"WorldWide Telescope\". Then all we need to do is run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pywwt.jupyter import connect_to_app\n",
    "wwt = await connect_to_app().becomes_ready()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the `wwt` variable will let us talk to the WWT app."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Step 3: Adding a tabular data layer\n",
    "\n",
    "We are now ready to add the data to WWT. We start off by calling ``add_table_layer`` to create the layer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer = wwt.layers.add_table_layer(exoplanets)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default the points are quite small, so we can enlarge them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.size_scale = 50"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should now see points appear in the widget above. Have a look around and see what the distribution of these confirmed exoplanets is on the sky. For example, you can use the following to point the view at the Kepler field:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy import units as u\n",
    "from astropy.coordinates import SkyCoord\n",
    "wwt.center_on_coordinates(SkyCoord(76.32, 13.5, unit='deg', frame='galactic'), fov=20 * u.deg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color-coding and scaling of points by attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All the points are currently white, but you can also choose to color code points by one of the other attributes. For example, we can color code the points by effective temperature of the parent star:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.cmap_att = 'st_teff'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``cmap_vmin`` and ``cmap_vmax`` properties can be used to specify which values should be used as the extremes for the colorbar:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.cmap_vmin = 5000\n",
    "layer.cmap_vmax = 8000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and finally the colormap can be set using the ``cmap`` attribute, which takes either the name of a [Matplotlib colormap](https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html) or a Matplotlib colormap object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.cmap = 'RdYlBu'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also scale the size of the points by one of the attributes — for example by the mass of the planet, and similarly we can set lower and upper values for the scaling:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.size_att = 'pl_bmassj'\n",
    "layer.size_vmin = 0\n",
    "layer.size_vmax = 30"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualizing the data in 3D"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Luckily, the exoplanet catalog contains *Gaia* distances to most of the planetary systems, so we can now tell the layer about the third dimension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.alt_att = 'gaia_dist'\n",
    "layer.alt_type = 'distance'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally we can switch PyWWT to 3D mode and explore the spatial distribution of the systems:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.set_view('solar system')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Start zooming out, with a two finger scroll, using your mouse wheel, or by pressing 'x'. Some of the larger points dominate the view, so we can turn off the scaling by size:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.size_att = ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keep on zooming out until you can see (an artist’s rendering of) the plane of the Milky Way. At this point, you should see a cone of systems which corresponds to those discovered in the original Kepler field!\n",
    "\n",
    "You may notice that some points appear and disappear as you rotate around. To avoid this effect, set the following option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "layer.far_side_visible = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When this option is ``False`` (the default), points on the other side of the Sun (or the reference object being used for plotting) are hidden — this is useful when plotting on e.g. planets and the Sun, but not when looking at this kind of data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## What's Next\n",
    "\n",
    "To see how to plot a data table that contains a time axis, check out the [GRBs Over Time](./GRBs%20Over%20Time.ipynb) tutorial."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Credits\n",
    "\n",
    "This notebook was prepared by Thomas Robitaille."
   ]
  }
 ],
 "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.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}