{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# DEMO Notebook\n",
    "## Using imexam inside a Jupyter notebook with DS9 as your viewer\n",
    "DS9 can be used as a viewer for the imexam package. While the DS9 viewer is active you have access to all the DS9 menu options as well, and imexam will attemp to keep track of changes you make through either the command line or the DS9 menus.\n",
    "\n",
    "This and other demo notebooks can be found on the SpaceTelescope github site: https://github.com/spacetelescope/imexam/\n",
    "\n",
    "\n",
    "Communication with the DS9 display window is done through the XPA. More information on the XPA access points which are available can be found here: http://ds9.si.edu/doc/ref/xpa.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Ok, now on to the good stuff!</h3>\n",
    "In this example I have my local environment using the qt5agg backend, with the environment variable QT_API='pyqt'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import imexam"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Starts up a DS9 window with no options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a=imexam.connect() # allow time for the window to start before you proceed to the next cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Allow DS9 to start and accept the network connections before executing the following cell"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.load_fits('iacs01t4q_flt.fits') #display fits image in ds9"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.scale()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "a.grab()  # if you are running on OSX, then this function shouldn't be available"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### In order to interact directly with the DS9 window, we have to start up a loop which looks for mouse and keyboard press events. In order to get out of this loop, press the \"q\" key </h3>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.imexam()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# all of the plots are customizable; the parameters are stored in regular dictionaries\n",
    "a.eimexam()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#maybe we want to change the colormap on the DS9 display? You can see the available maps:\n",
    "a.cmap()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.cmap(color='heat')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#You can customize the plotting parameters (or any function in the imexam loop)\n",
    "a.set_plot_pars('e','title','This is my favorite galaxy')\n",
    "a.set_plot_pars('e','ncontours',4)\n",
    "a.set_plot_pars('e','cmap','YlOrRd') #see http://matplotlib.org/users/colormaps.html\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#lets see how the plot changed\n",
    "a.imexam()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.unlearn() #you can always go back to the default plot settings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### If you want to pull the data array from the display and do some other calculations with it, you can ask for it: </h3>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data=a.get_data()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#you can also get the header, which will be returned as a string\n",
    "header=a.get_header()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(header)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quick photometry can be pulled with the \"a\" key and uses the photutils package to do the work. More information on photutils can be found at http://photutils.readthedocs.org/en/latest/\n",
    "\n",
    "You can also look at the example notebook with DS9 photometry which uses photutils"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#any numpy array can be displayed in the viewer\n",
    "import numpy as np\n",
    "data=np.random.rand(100) * np.ones((100,100))\n",
    "a.view(data)\n",
    "a.zoomtofit()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#or you can use astropy nddata arrays (which really are numpy arrays with meta data)\n",
    "from astropy.nddata import NDData\n",
    "array = np.random.random((12, 12, 12))  # a random 3-dimensional array\n",
    "ndd = NDData(array)\n",
    "a.view(ndd.data[3])\n",
    "a.zoom()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.close() #close the ds9 window"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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": 1
}
