03-coordinates.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Celestial coordinates\n",
    "\n",
    "The [astropy.coordinates](https://docs.astropy.org/en/stable/coordinates/index.html) sub-package in astropy provides a way to represent and manipulate celestial coordinates. It supports many different coordinate systems and transformations, and includes support for velocities in addition to positions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<section class=\"objectives panel panel-warning\">\n",
    "<div class=\"panel-heading\">\n",
    "<h2><span class=\"fa fa-certificate\"></span> Objectives</h2>\n",
    "</div>\n",
    "\n",
    "\n",
    "<div class=\"panel-body\">\n",
    "\n",
    "<ul>\n",
    "<li>Create SkyCoord objects</li>\n",
    "<li>Access individual coordinates</li>\n",
    "<li>Format coordinates</li>\n",
    "<li>Transforming coordinates</li>\n",
    "<li>Using 3D coordinates and velocities</li>\n",
    "<li>Calculating separations</li>\n",
    "<li>Using arrays of coordinates</li>\n",
    "</ul>\n",
    "\n",
    "</div>\n",
    "\n",
    "</section>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documentation\n",
    "\n",
    "This notebook only shows a subset of the functionality in astropy.coordinates. For more information about the features presented below as well as other available features, you can read the\n",
    "[astropy.coordinates documentation](https://docs.astropy.org/en/stable/coordinates/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "plt.rc('image', origin='lower')\n",
    "plt.rc('figure', figsize=(10, 6))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating SkyCoord objects\n",
    "\n",
    "The main user-facing class in astropy.coordinates is the ``SkyCoord`` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A SkyCoord object can represent one or more coordinates, and there are a number of different ways to initialize such an object. If you have the coordinates as quantities, you can do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the default is to assume that the coordinates are in the ICRS frame and represent Right Ascension and Declination. You can also initialize coordinates from strings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create coordinates in other frames - for example Galactic coordinates - you can use the ``frame=`` argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that here we've also specified the names of the coordinates explicitly using ``l=`` and ``b=`` (they are not required but can make code more readable)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialization from SIMBAD identifier\n",
    "\n",
    "If you are doing quick calculations and want to use the coordinates of a source in the SIMBAD database, you can easily create a ``SkyCoord`` object from the object name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, note that this should not be used when precision is critical - the positions are approximate especially for extended sources."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing individual coordinates\n",
    "\n",
    "Once you have a coordinate object, you can access the individual coordinates using attributes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Longitude class is a sub-class of Quantity so you can convert it to specific units as you would a quantity:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "but the Longitude class also provides shortcuts for this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Formatting coordinates\n",
    "\n",
    "You can format a coordinate object as a string using ``to_string()``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default format uses floating point values, but you may want instead to use standard sexagesimal format: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can control the precision using the ``precision=`` keyword argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Transforming coordinates\n",
    "\n",
    "``SkyCoord`` objects can be transformed between frames using the ``.transform_to()`` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also specify frame objects if you need more control:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A more advanced example is to convert the coordinates to altitude/azimuth as seen from a particular observer at a specific time (in UTC):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3D coordinates\n",
    "\n",
    "The above examples are for coordinates on the sky, which are assumed to be at infinity. However, it is also possible to specify a third coordinate (the distance to the object):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can convert this to the Galactocentric frame, which is a frame that represents coordinates in cartesian coordinates by default (centered on the center of the Milky Way)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Velocities/proper motions\n",
    "\n",
    "In addition to being able to represent fixed positions in space, it is also possible to add velocities to coordinates, for example to express radial velocity, proper motions, or 3D space motion. For example, to add a radial velocity and proper motion to a coordinate in the ICRS frame, you can do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "coord4 = SkyCoord(ra=13.443 * u.deg,\n",
    "                  dec=-33.298 * u.deg, distance=1 * u.kpc,\n",
    "                  pm_ra_cosdec=0.1 * u.arcsec / u.yr,\n",
    "                  pm_dec=-0.08 * u.arcsec / u.yr,\n",
    "                  radial_velocity=20 * u.km / u.s)\n",
    "coord4"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Velocities are then correctly propagated when transforming to different systems:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Separations\n",
    "\n",
    "Given two coordinates, we can determine the separation between them on the sky:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also do this in 3D to find a physical distance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using arrays in coordinates\n",
    "\n",
    "A common use case is the need to represent large catalogs of coordinates - in this case, it is very inefficient to use a ``SkyCoord`` object for each source. Instead, you can store arrays of coordinates inside ``SkyCoord``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most of the operations shown above should then also work seamlessly with arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Solar system bodies\n",
    "\n",
    "A [get_body](https://docs.astropy.org/en/stable/api/astropy.coordinates.get_body.html) convenience function is provided in astropy.coordinates to retrieve the 3D coordinates of solar system bodies. This can be done either using default built-in ephemeris, or the more accurate JPL ephemeris (see the ``get_body`` documentation). For now, we will use the default:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<section class=\"challenge panel panel-success\">\n",
    "<div class=\"panel-heading\">\n",
    "<h2><span class=\"fa fa-pencil\"></span> Challenge</h2>\n",
    "</div>\n",
    "\n",
    "\n",
    "<div class=\"panel-body\">\n",
    "\n",
    "<p>The answer to some of the following can be found in <a href=\"https://docs.astropy.org/en/stable/time/index.html\">the documentation</a>!</p>\n",
    "<ol>\n",
    "<li>Find the coordinates of the Crab Nebula (M1) in ICRS coordinates, and convert them to Galactic Coordinates.</li>\n",
    "<li>Find the separation on the sky between the Crab Nebula and the star 'T Tauri' in degrees</li>\n",
    "<li>Generate random positions in the Galactic plane (between l=0 and l=360 and b=-1 and b=+1), then make a plot showing the position on the sky of these points in FK5.</li>\n",
    "<li>Make a plot showing the altitude above the horizon of the Sun as seen from Madrid over the course of today</li>\n",
    "</ol>\n",
    "\n",
    "</div>\n",
    "\n",
    "</section>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center><i>This notebook was written by <a href=\"https://aperiosoftware.com/\">Aperio Software Ltd.</a> &copy; 2019, and is licensed under a <a href=\"https://creativecommons.org/licenses/by/4.0/\">Creative Commons Attribution 4.0 International License (CC BY 4.0)</a></i></center>\n",
    "\n",
    "![cc](https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg)"
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}