tutorials/aas233_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\\*\\* *If you followed a link from our repository or tinyurl and are using this online through Binder, please note that the tutorial is only fully functional in Firefox at the moment.* \\*\\*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import and initialize statements from 'Get started'\n",
    "\n",
    "*(Select a cell and press `ctrl` + `Enter` to run it.)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time\n",
    "\n",
    "from astropy.coordinates import SkyCoord\n",
    "from astropy import units as u\n",
    "from astropy.table import Table, Column\n",
    "from astropy.time import Time, TimeDelta # note capitalization\n",
    "\n",
    "import numpy as np\n",
    "\n",
    "from astroquery.vizier import Vizier\n",
    "from astroquery.nasa_exoplanet_archive import NasaExoplanetArchive\n",
    "\n",
    "from pywwt.jupyter import WWTJupyterWidget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt = WWTJupyterWidget()\n",
    "wwt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*WWT works under HTTP, while Binder uses HTTPS. As such, in order to access all features of pywwt, Binder users will need to disable HTTPS for this session. Firefox users can do this with the following steps:*\n",
    "- *Click the lock icon to the left of the address bar,*\n",
    "- *Select the arrow next to “Connection,”*\n",
    "- *Then, press the “Disable protection for now” button. (Protection is disabled for this page and only during this session, not for your whole browser. We are working on upgrading WWT so this step is no longer necessary.)*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting K2’s footprint and exoplanet yield"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**First, we use a class from the `astroquery` package to query NASA's Exoplanet Archive and return an `astropy` table that contains information about every confirmed exoplanet so far. It's a large table, so we'll only keep the columns necessary to run this example.**\n",
    "\n",
    "*(If the `astroquery` call doesn't load, uncomment and run the following cell to download the table from a `pywwt`-affiliated GitHub repository.)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "xarch = NasaExoplanetArchive.get_confirmed_planets_table()\n",
    "xarch.keep_columns(['pl_hostname', 'pl_letter', 'st_dist', 'ra', 'dec'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#xarch = Table.read('https://raw.githubusercontent.com/WorldWideTelescope/pywwt-notebooks/master/tutorials/data/k2_table.ecsv',\n",
    "#                   format='ascii.ecsv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*(Open a new cell above this one and see what the table looks like by entering `xarch` and running it.)*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Next, we slice the table twice so it only contains entries of 'b' planets observed by K2.** \n",
    "\n",
    "K2 planets and stars are named using a consistent system: \n",
    "\n",
    "```K2 + 'system number' + 'letter'```. \n",
    "\n",
    "The letter for a star is typically 'a', the first exoplanet confirmed in the system is 'b', and so on.\n",
    "\n",
    "We are plotting stars, but since the table only contains exoplanets (letters from 'b' onward), we will slice the table so only planets with the `b` suffix remain. That gives us one entry per system.\n",
    "\n",
    "**`k2_pl` searches the `xarch` column that lists star names and only keeps those with K2 at the beginning. Then, `k2_st` searches the suffix of the planet name and only keeps `b` planets.**\n",
    "\n",
    "*(If you aren't familiar with list comprehensions, see [Note 1](aas233_tutorial.ipynb#Note-1).)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# select only k2 planets\n",
    "k2_pl = xarch[ [row.startswith('K2') for row in xarch['pl_hostname']] ]\n",
    "\n",
    "# select only 'b' planets from k2\n",
    "k2_st = k2_pl[ ['b' in row for row in k2_pl['pl_letter']] ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**After that, we load the footprint of the K2 campaign fields on the sky using pywwt's `add_fov` method.**\n",
    "\n",
    "*(Loading K2's footprint usually takes a minute, so please be patient with this step.)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "field = wwt.add_fov(wwt.instruments.k2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Move the viewer down here and watch what happens next.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Once the footprint has loaded, we finally create the data layer that will plot our points in the viewer.**\n",
    "\n",
    "`pywwt` reads the locations from the keyword arguments `lon_att` and `lat_att`, and we feed it the names of the columns in `k2_st` that contain the stellar right ascensions and declinations. We can also set other attributes like color and size in the function call."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lay = wwt.layers.add_data_layer(table=k2_st, frame='Sky',\n",
    "                                lon_att='ra', lat_att='dec',\n",
    "                                color='#c4d600', size_scale=40)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Do you see the points? If not, try making them larger."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lay.size_scale *= 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to see the points and footprint without a sky background, `pywwt` also has a black layer available."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.foreground_opacity = 0\n",
    "wwt.background = wwt.imagery.other.black"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**It is also possible to visualize data layers in `pywwt`'s 3D solar system mode. To do so, we'll switch the view.**\n",
    "\n",
    "We will also remove the K2 footprint, as `add_fov` is designed to work in 2D."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "field.remove()\n",
    "wwt.set_view('solar system')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Bring the viewer down here, zoom out, and you'll see K2's exoplanet-hosting stars in 3D. All of them are currently the same distance from Earth -- let's fix that.**\n",
    "\n",
    "Data layers also have attributes related to distance and altitude. We set `alt_type` to the correct type for our scenario, and let `pywwt` know which column of the table contains distance with `alt_att`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lay.alt_type = 'distance'\n",
    "lay.alt_att = 'st_dist'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Zoom out again and see the stars at their proper distances.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting and watching gamma ray bursts (GRBs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**In this example (adapted from [a notebook](https://nbviewer.jupyter.org/github/marksubbarao/pyWWT_AAS225/blob/master/Fermi%20Gamma%20Ray%20Bursts%20.ipynb) by Mark SubbaRao), we use the Fermi Gamma-ray Burst Monitor's GRB catalog to get information about GRB events from 2008 to 2014.**\n",
    "\n",
    "The goal here is not just to plot the locations of these events, but also to use `pywwt`'s time controls to bring this time series data set to life. We will loop through time, refresh the data layer as the GRBs \"occur,\" and watch as they pop up in the viewer."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**First, we'll retrieve the data from a `pywwt`-affiliated repository on GitHub.**\n",
    "\n",
    "*(This table, like the exoplanet one, can also be also be loaded via `astroquery`, but the process of manipulating it to fit our needs takes more time than we have in the tutorial. If you're curious about it, see [Note 2](aas233_tutorial.ipynb#Note-2).)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bursts = Table.read('https://raw.githubusercontent.com/WorldWideTelescope/pywwt-notebooks/master/tutorials/data/grb_table.ecsv',\n",
    "                    format='ascii.ecsv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "scrolled": false
   },
   "source": [
    "*(Again, open a new cell above this one and see what the table looks like by entering `bursts` and running it.)*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Let's refresh the viewer by re-executing the `wwt = WWTJupyterWidget()` cell. After that, since we're working with gamma ray bursts, let's switch to a background layer in that region of the electromagnetic spectrum.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.foreground_opacity = 0\n",
    "wwt.background = wwt.imagery.gamma.fermi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Now, let's create the data layer.**\n",
    "\n",
    "This time, notice that we assign the 'cmap' column to be tracked by `pywwt`. This is because we will have the points change color both during and after the GRB events occur."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lay = wwt.layers.add_data_layer(table=bursts, frame='Sky',\n",
    "                                lon_att='ra', lat_att='dec',\n",
    "                                size_scale=90, cmap_att='cmap')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**We need to define some variables before running the time loop.**\n",
    "- *`start`* and *`finish`* are `astropy` Time objects and define the beginning and end of the loop through time. They're set to be the times just before the first and after the last GRB events, respectively.\n",
    "- *`step`* is an `astropy` TimeDelta object and can be added to a Time object to create a new time. We will \"step\" the loop forward in intervals of 10 days. It needs a unit from `astropy`'s Units object, too.\n",
    "- *`now`* is the Time object that will be added to by `step` in each iteration of the loop. It represents the current time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "start = Time(bursts[0]['iso_times'], format='jd')\n",
    "finish = Time(bursts[-1]['iso_times'], format='jd')\n",
    "#start = Time('2008-07-11', format='iso')\n",
    "#finish = Time('2008-08-01', format='iso')\n",
    "\n",
    "step = TimeDelta(10 * u.day)\n",
    "now = start + step"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Next, let's bring the viewer down here and center it on the earliest GRB in the data set.**\n",
    "\n",
    "That way, we'll see colors begin to change immediately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wwt.center_on_coordinates(SkyCoord(bursts[0]['ra'], bursts[0]['dec'], \n",
    "                                   unit=u.deg))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Finally, it's time to write and run the loop.**\n",
    "\n",
    "In each iteration, here is the strategy:\n",
    "- Set the time in the viewer to `now`;\n",
    "- `active`: Compare `now` to the values in the 'iso_times' column of `bursts` to find which entries had an event in the period between the previous iteration and now ([Note 3.1](aas233_tutorial.ipynb#Note-3));\n",
    "- `last_active`: Do the same to find which entries had an event in the `step`-day period before the current period ([Note 3.2](aas233_tutorial.ipynb#Note-3));\n",
    "- Turn `burst` entries with events in that period white (active);\n",
    "- Turn `burst` entries occuring just before that period green (passed);\n",
    "- Update the layer in `pywwt` with the new version of `burst` where the colors are changed;\n",
    "- Use the `sleep` method of the `time` package to pause the loop so the data layer has time to finish updating;\n",
    "- Add `step` to `now` and repeat until we've reached the time of `finish`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "while now <= finish:\n",
    "    wwt.set_current_time(now)\n",
    "        \n",
    "    active = np.intersect1d(\n",
    "        np.where(bursts['iso_times'] > (now - step).jd),\n",
    "        np.where(bursts['iso_times'] <= now.jd))\n",
    "    \n",
    "    passed = np.intersect1d(\n",
    "        np.where(bursts['iso_times'] > (now - 2 * step).jd),\n",
    "        np.where(bursts['iso_times'] <= (now - step).jd))\n",
    "    \n",
    "    if len(active) > 0:\n",
    "        bursts[active[0] : active[-1] + 1]['cmap'] = '#ffffff'\n",
    "    if len(passed) > 0:\n",
    "        bursts[passed[0] : passed[-1] + 1]['cmap'] = '#00ff00'\n",
    "    \n",
    "    lay.update_data(bursts)\n",
    "    \n",
    "    #print(now)\n",
    "    time.sleep(1)\n",
    "    now += step"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***Is it working? If so, congratulations, enjoy the view, and stay in touch! Find us at the AAS booth, work with us all day tomorrow at Hack Together Day, and contribute ideas, suggestions, and fixes at our [GitHub repository](https://github.com/WorldWideTelescope/pywwt).***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Note 1\n",
    "*The constructions used to build `k2_pl` and `k2_st` are called \"list comprehensions,\" and they are shortcuts for building lists. The regular, equivalent method to create `k2_st`, looks like this:*\n",
    "\n",
    "```\n",
    "index_list = []\n",
    "for i, row in enumerate(xarch, 0):\n",
    "    if row['pl_hostname'].startswith('K2'):\n",
    "        index_list.append(i)\n",
    "\n",
    "k2_pl = xarch[index_list]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Note 2\n",
    "\n",
    "*For my own reference as well as yours, this is how I used astroquery to build the table of GRB events.*\n",
    "\n",
    "```\n",
    "# retrieve the list of GRBs\n",
    "v = Vizier()\n",
    "v.ROW_LIMIT = -1\n",
    "cats = v.get_catalogs('J/ApJS/223/28N/GBM')\n",
    "\n",
    "# take the table and cut unnecessary columns\n",
    "bursts = cats[0]\n",
    "bursts.keep_columns([\"GRB\", \"RAJ2000\", \"DEJ2000\", \"Time\",\n",
    "                     \"Trig\", \"Fl.w\", \"Fl.n\"])\n",
    "\n",
    "# rename some columns\n",
    "bursts.rename_column('RAJ2000','ra')\n",
    "bursts.rename_column('DEJ2000','dec')\n",
    "bursts.rename_column('Trig', 'obs_time')\n",
    "\n",
    "# only keep entries with nonzero 'GRB' values \n",
    "# (we need that for the loop)\n",
    "bursts = bursts[bursts[\"GRB\"].nonzero()[0]]\n",
    "\n",
    "# add a column with times readable by pywwt\n",
    "grb_times = []\n",
    "for i, name in enumerate(bursts['GRB']):\n",
    "    # name format: 080714B\n",
    "    # year (2 digits), month (2 digits), day (2 digits), letter\n",
    "    # style is changed to '2008-07-14 02:04:12.053', \n",
    "    # ...then converted to julian date\n",
    "\n",
    "    formatted = Time('20' + name[:2] + '-' \n",
    "                 + name[2:4] + '-' + name[4:6] + ' ' \n",
    "                 + bursts['obs_time'][i], format='iso').jd\n",
    "    grb_times.append(formatted)\n",
    "\n",
    "bursts.add_column(Column(grb_times), name='iso_times')\n",
    "\n",
    "# add a colormap column to the table\n",
    "cmap = ['#000000'] * len(bursts)\n",
    "bursts.add_column(Column(cmap), name='cmap')\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Note 3\n",
    "1. i.e. between `now - step` and `now`. e.g. between July 11 and July 21 if `now == Time('2008-07-21')` and `step == TimeDelta(10 * u.day)`;\n",
    "2. Given the variables in 1, the period here would be between between July 1 and July 11."
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}