{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactively inspecting Target Pixel Files and Lightcurves"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One of the most common questions we get at the Kepler/K2 Guest Observer Office is \"I see a noise blip in my K2 lightcurve.  Is it real or instrumental?\"  Answering the question usually entails ticking through our (long, incomplete) mental list of conceivable, sometimes exotic instrumental artifacts.  Space-craft induced periodic motion.  Rolling band.  Cosmic Rays.  Collateral cosmic rays.  Smear.  Sudden pixel sensitivity dropouts.  Fine-guidance-sensor cross talk.  Regular cross talk. [Sweater fuzzy](https://twitter.com/gully_/status/941707161058586624).\n",
    "\n",
    "In this tutorial we introduce and explain the `tpf.interact()` tool that accomplishes the goal of interactively inspecting the TPFs and lightcurve simultaneously."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `.interact()`\n",
    "\n",
    "Using interact should be as simple as downloading a Kepler Target Pixel File (TPF) and running the method `.interact()`.  This method can only be run in a Jupyter Notebook at the moment, and is limited to lightcurves with fewer than 30000 cadences."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 1 File(s)\n",
      "INFO: Found cached file ./mastDownload/K2/ktwo249928278-c15_lc/ktwo249928278-c15_lpd-targ.fits.gz with expected size 6996829. [astroquery.query]\n"
     ]
    }
   ],
   "source": [
    "from lightkurve import KeplerTargetPixelFile\n",
    "tpf = KeplerTargetPixelFile.from_archive(249928278, campaign=15) # WASP 104 for example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default lightcurves comes from the default \"pipeline\" mask, typically only a few pixels centered on the target photocenter, depending on factors like the target brightness and its expected PSF size.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "scrolled": false
   },
   "source": [
    "```python\n",
    "tpf.interact()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![TPF Interact demo](images/tpf_interact.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can move the large bottom left slider to change the location of the verical red bar, which indicates which cadence is being shown in the TPF postage stamp image.  You can also hit the play button to automatically play-though all the cadences.  The left-and-right arrow keys on your keyboard will tick through the cadences one-by-one, if the widget slider is active (i.e. it's the most recent thing you clicked on).  The slider beneath the TPF postage stamp image controls the screen stretch, which defaults to logarithmic scaling initialized to 1% and 95% lower and upper limits respectively.\n",
    "\n",
    "You can move your cursor over individual data points to show hover-over tool-tips indicating additional information about that datum.  Currently the tool tips list the cadence, time, flux, and quality flags.  The tools on the right hand side of the plots enable zooming, panning, and toggling-off tool-tips."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Passing in a preprocessed lightcurve"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may wish to visualize a custom-processed lightcurve adjacent to its TPF postage stamp representation.  You can pass-in a lightcurve as an optional keyword argument like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def my_custom_lc_cleaner(tpf):\n",
    "    '''Returns a custom lightcurve that uses local background subtraction'''\n",
    "    \n",
    "    # Define the background as the outermost ring of non-NaN pixels\n",
    "    aper_mask = tpf.pipeline_mask * False\n",
    "    aper_mask[1:-1, 1:-1] = True\n",
    "    back_mask = ~aper_mask & ~np.all(np.isnan(tpf.flux), axis=0)\n",
    "    \n",
    "    # Estimate the background level by the outer ring of pixels\n",
    "    lc_aper = tpf.to_lightcurve(aperture_mask=aper_mask) / aper_mask.sum()\n",
    "    lc_back = tpf.to_lightcurve(aperture_mask=back_mask) / back_mask.sum()\n",
    "    \n",
    "    lc_bg_sub = lc_aper - lc_back.flux\n",
    "    \n",
    "    # Remove outliers\n",
    "    lc_cln= lc_bg_sub.remove_outliers()\n",
    "    \n",
    "    return lc_cln"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "lc_cln = my_custom_lc_cleaner(tpf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "tpf.interact(lc=lc_cln)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![preprocessed lightcurve interaction](images/tpf_interact_preprocessed_lc.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Your clean lightcurve may have a different number of cadences than your target pixel file, for example if you dropped outliers.  The TPF will show all of the available cadences by default, with missing spaces in the lightcurve."
   ]
  }
 ],
 "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}