{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Running *species*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial shows what a typical workflow with *species* looks like. The colors and magnitudes of a few directly imaged objects are compared with the field dwarfs from the [Database of Ultracool Parallaxes](http://www.as.utexas.edu/~tdupuy/plx/Database_of_Ultracool_Parallaxes.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initiating *species*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start by importing the *species* toolkit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import species"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, the configuration file (*species_config.ini*) is read from the working folder. Since the file does not exist, it is created with default values for the path of the HDF5 database and the location where the external data is stored. The database and data folder are also created since this is the first time that we run *species* with the current configuration file. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Initiating species v0.1.0... [DONE]\n",
      "Creating species_config.ini... [DONE]\n",
      "Database: /Users/tomasstolker/applications/species/docs/tutorials/species_database.hdf5\n",
      "Data folder: /Users/tomasstolker/applications/species/docs/tutorials/data\n",
      "Working folder: /Users/tomasstolker/applications/species/docs/tutorials\n",
      "Creating species_database.hdf5... [DONE]\n",
      "Creating data folder... [DONE]\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<species.core.setup.SpeciesInit at 0x12b8385f8>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "species.SpeciesInit()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding a photometric library"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `Database` object is now created which can be used for importing data from the chosen data folder into the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "database = species.Database()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The photometry and parallaxes from the Database of Ultracool Parallaxes are downloaded and added to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Downloading Database of Ultracool Parallaxes (307 kB)... [DONE]\n",
      "Adding Database of Ultracool Parallaxes... [DONE]\n"
     ]
    }
   ],
   "source": [
    "database.add_photometry('vlm-plx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding companion data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The distance and magnitudes of 51 Eri b, beta Pic b, and PZ Tel B are added to the database. This will automatically download the filter transmission profiles and a flux calibrated spectrum of Vega. These are required for the flux calibration of the magnitudes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding filter: MKO/NSFCam.J... [DONE]\n",
      "Downloading Vega spectrum (270 kB)... [DONE]\n",
      "Adding Vega spectrum... [DONE]\n",
      "Adding filter: MKO/NSFCam.H... [DONE]\n",
      "Adding filter: MKO/NSFCam.K... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_H23_2... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_K12_1... [DONE]\n",
      "Adding filter: Keck/NIRC2.Lp... [DONE]\n",
      "Adding filter: Keck/NIRC2.Ms... [DONE]\n",
      "Adding object: 51 Eri b... [DONE]\n",
      "Adding filter: LCO/VisAO.Ys... [DONE]\n",
      "Adding filter: Paranal/NACO.J... [DONE]\n",
      "Adding filter: Gemini/NICI.ED286... [DONE]\n",
      "Adding filter: Paranal/NACO.H... [DONE]\n",
      "Adding filter: Paranal/NACO.Ks... [DONE]\n",
      "Adding filter: Paranal/NACO.NB374... [DONE]\n",
      "Adding filter: Paranal/NACO.Lp... [DONE]\n",
      "Adding filter: Paranal/NACO.NB405... [DONE]\n",
      "Adding filter: Paranal/NACO.Mp... [DONE]\n",
      "Adding object: beta Pic b... [DONE]\n",
      "Adding filter: Paranal/SPHERE.ZIMPOL_R_PRIM... [DONE]\n",
      "Adding filter: Paranal/SPHERE.ZIMPOL_I_PRIM... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_H23_3... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_K12_2... [DONE]\n",
      "Adding filter: Gemini/NIRI.H2S1v2-1-G0220... [DONE]\n",
      "Adding object: PZ Tel B... [DONE]\n"
     ]
    }
   ],
   "source": [
    "database.add_companion('51 Eri b')\n",
    "database.add_companion('beta Pic b')\n",
    "database.add_companion('PZ Tel B')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reading color-magnitude data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The colors and magnitudes are read from the database by first creating an object of `ReadColorMagnitude`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "colormag = species.ReadColorMagnitude(library='vlm-plx',\n",
    "                                      filters_color=('MKO/NSFCam.J', 'MKO/NSFCam.H'),\n",
    "                                      filter_mag='MKO/NSFCam.J')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The data is read by selecting the object type of the isolated brown dwarfs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "colorbox = colormag.get_color_magnitude(object_type='field')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A list of directly imaged objects is created with the filter names for the colors and magnitudes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "objects = [('51 Eri b', 'MKO/NSFCam.J', 'MKO/NSFCam.H', 'MKO/NSFCam.J'),\n",
    "           ('beta Pic b', 'Paranal/NACO.J', 'Paranal/NACO.H', 'Paranal/NACO.J'),\n",
    "           ('PZ Tel B', 'Paranal/NACO.J', 'Paranal/NACO.H', 'Paranal/NACO.J')]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting a color-magnitude diagram"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `ColorMagBox` object is provided in a list to `plot_color_magnitude`. The list with directly imaged objects are also included."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Plotting color-magnitude diagram: color_mag.png... [DONE]\n"
     ]
    }
   ],
   "source": [
    "species.plot_color_magnitude(colorbox=[colorbox, ],\n",
    "                             objects=objects,\n",
    "                             label_x='J - H [mag]',\n",
    "                             label_y='M$_\\mathregular{J}$ [mag]',\n",
    "                             companion_labels=True,\n",
    "                             field_range=('late M', 'late T'),\n",
    "                             legend=None,\n",
    "                             output='color_mag.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's have a look at the result. The plot is stored in the working folder. The discrete colorbar shows the spectral types of the field dwarfs and the directly imaged objects are labeled individually."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "[encoded data, 42624 characters]\n",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import Image\n",
    "Image('color_mag.png')"
   ]
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
