{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Color-magnitude diagram: broadband filters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial shows how to create a color-magnitude diagram that includes data of field and young/low-gravity objects, synthetic photometry computed from isochrones and model spectra, and data of directly imaged objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initiating *species*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start by importing the required modules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import species"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we initiate the [species](https://species.readthedocs.io/en/latest/species.html) workflow and create an instance of [Database](https://species.readthedocs.io/en/latest/species.data.html#species.data.database.Database)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Initiating species v0.5.5... [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",
      "Grid interpolation method: linear\n",
      "Creating species_database.hdf5... [DONE]\n",
      "Creating data folder... [DONE]\n"
     ]
    }
   ],
   "source": [
    "species.SpeciesInit()\n",
    "database = species.Database()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding data to the database"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Available magnitudes and spectra of directly imaged planets and brown dwarfs are added to the database with [add_companion](https://species.readthedocs.io/en/latest/species.data.html#species.data.database.Database.add_companion) by setting `name=None`. These data are extracted from the [companion_data](https://github.com/tomasstolker/species/blob/master/species/data/companion_data.json) and [companion_spectra](https://github.com/tomasstolker/species/blob/master/species/data/companion_spectra.json) files in the [data](https://species.readthedocs.io/en/latest/species.data.html) subpackage."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding filter: Magellan/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",
      "Downloading Vega spectrum (270 kB)... [DONE]\n",
      "Adding Vega spectrum... [DONE]\n",
      "Adding object: beta Pic b [DONE]\n",
      "Adding filter: MKO/NSFCam.K..."
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/tomasstolker/applications/species/species/data/database.py:1273: UserWarning: Found 33 fluxes with NaN in the data of GPI_YJHK. Removing the spectral fluxes that contain a NaN.\n",
      "  warnings.warn(\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " [DONE]\n",
      "Adding object: beta Pic c [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_H23_2... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_H23_3... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_K12_1... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_K12_2... [DONE]\n",
      "Adding object: HIP 65426 b [DONE]\n",
      "Adding filter: MKO/NSFCam.J... [DONE]\n",
      "Adding filter: MKO/NSFCam.H... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_B_H... [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: Subaru/CIAO.z... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_B_J..."
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/tomasstolker/applications/species/species/data/filters.py:209: UserWarning: The minimum transmission value of Subaru/CIAO.z is smaller than zero (-1.80e-03). Wavelengths with negative transmission values will be removed.\n",
      "  warnings.warn(\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " [DONE]\n",
      "Adding filter: Keck/NIRC2.H... [DONE]\n",
      "Adding filter: Keck/NIRC2.Ks... [DONE]\n",
      "Adding object: HR 8799 b [DONE]\n",
      "Adding object: HR 8799 c [DONE]\n",
      "Adding object: HR 8799 d [DONE]\n",
      "Adding object: HR 8799 e [DONE]\n",
      "Adding filter: Gemini/GPI.H... [DONE]\n",
      "Adding filter: Gemini/GPI.K1... [DONE]\n",
      "Adding object: HD 95086 b [DONE]\n",
      "Adding object: PDS 70 b [DONE]\n",
      "Adding object: PDS 70 c [DONE]\n",
      "Adding filter: HST/NICMOS1.F090M... [DONE]\n",
      "Adding filter: HST/NICMOS1.F110M... [DONE]\n",
      "Adding filter: HST/NICMOS1.F145M... [DONE]\n",
      "Adding filter: HST/NICMOS1.F160W... [DONE]\n",
      "Adding object: 2M 1207 B [DONE]\n",
      "Adding object: AB Pic B [DONE]\n",
      "Adding object: HD 206893 B [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_B_Ks... [DONE]\n",
      "Adding object: RZ Psc B [DONE]\n",
      "Adding filter: HST/WFPC2-PC.F606W... [DONE]\n",
      "Adding filter: HST/WFPC2-PC.F814W... [DONE]\n",
      "Adding filter: HST/NICMOS2.F171M... [DONE]\n",
      "Adding filter: HST/NICMOS2.F190N... [DONE]\n",
      "Adding filter: HST/NICMOS2.F215N... [DONE]\n",
      "Adding filter: Magellan/VisAO.ip... [DONE]\n",
      "Adding filter: Magellan/VisAO.zp... [DONE]\n",
      "Adding filter: Subaru/CIAO.CH4s... [DONE]\n",
      "Adding filter: Subaru/CIAO.K... [DONE]\n",
      "Adding filter: Subaru/CIAO.Lp... [DONE]\n",
      "Adding object: GQ Lup B [DONE]\n",
      "Adding filter: Paranal/SPHERE.ZIMPOL_R_PRIM... [DONE]\n",
      "Adding filter: Paranal/SPHERE.ZIMPOL_I_PRIM... [DONE]\n",
      "Adding filter: Gemini/NIRI.H2S1v2-1-G0220... [DONE]\n",
      "Adding object: PZ Tel B [DONE]\n",
      "Adding filter: Subaru/CIAO.J... [DONE]\n",
      "Adding filter: Subaru/CIAO.H... [DONE]\n",
      "Adding filter: Subaru/CIAO.Ks... [DONE]\n",
      "Adding filter: Keck/NIRC2.NB_4.05... [DONE]\n",
      "Adding filter: LBT/LMIRCam.M_77K... [DONE]\n",
      "Adding object: kappa And b [DONE]\n",
      "Adding filter: MKO/NSFCam.Ks... [DONE]\n",
      "Adding object: HD 1160 B [DONE]\n",
      "Adding filter: MKO/NSFCam.Kp... [DONE]\n",
      "Adding object: ROXs 12 B [DONE]\n",
      "Adding filter: Keck/NIRC2.J... [DONE]\n",
      "Adding object: ROXs 42 Bb [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_Y23_2... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_Y23_3... [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_J23_3... [DONE]\n",
      "Adding filter: Subaru/IRCS.Lp... [DONE]\n",
      "Adding object: GJ 504 b [DONE]\n",
      "Adding filter: Gemini/GMOS-S.z... [DONE]\n",
      "Adding filter: CFHT/Wircam.Y... [DONE]\n",
      "Adding filter: CFHT/Wircam.J... [DONE]\n",
      "Adding filter: CFHT/Wircam.H... [DONE]\n",
      "Adding filter: CFHT/Wircam.Ks... [DONE]\n",
      "Adding filter: WISE/WISE.W1... [DONE]\n",
      "Adding filter: WISE/WISE.W2... [DONE]\n",
      "Adding object: GU Psc b [DONE]\n",
      "Adding object: 2M0103 ABb [DONE]\n",
      "Adding filter: Gemini/NIRI.J-G0202w... [DONE]\n",
      "Adding filter: Gemini/NIRI.H-G0203w... [DONE]\n",
      "Adding filter: Gemini/NIRI.K-G0204w... [DONE]\n",
      "Adding filter: Gemini/NIRI.Lprime-G0207w... [DONE]\n",
      "Adding object: 1RXS 1609 B [DONE]\n",
      "Adding filter: MKO/NSFCam.Lp... [DONE]\n",
      "Adding object: GSC 06214 B [DONE]\n",
      "Adding object: HD 72946 B [DONE]\n",
      "Adding object: HIP 64892 B [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_D_J23_2... [DONE]\n",
      "Adding object: HD 13724 B [DONE]\n",
      "Adding object: YSES 1 b [DONE]\n",
      "Adding object: YSES 1 c [DONE]\n",
      "Adding object: YSES 2 b [DONE]\n",
      "Adding object: HD 142527 B [DONE]\n",
      "Adding object: CS Cha B [DONE]\n",
      "Adding object: CT Cha B [DONE]\n",
      "Adding object: SR 12 C [DONE]\n",
      "Adding object: DH Tau B [DONE]\n",
      "Adding object: HD 4747 B [DONE]\n",
      "Adding filter: Paranal/SPHERE.IRDIS_B_Y... [DONE]\n",
      "Adding object: HR 3549 B [DONE]\n",
      "Adding filter: HST/ACS_WFC.F775W... [DONE]\n",
      "Adding filter: HST/ACS_WFC.F850LP... [DONE]\n",
      "Adding object: CHXR 73 B [DONE]\n",
      "Adding object: HD 19467 B [DONE]\n",
      "Adding object: b Cen (AB)b [DONE]\n"
     ]
    }
   ],
   "source": [
    "database.add_companion(name=None, verbose=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We also add the photometry and parallaxes of the [Database of Ultracool Parallaxes](http://www.as.utexas.edu/~tdupuy/plx/Database_of_Ultracool_Parallaxes.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Downloading data from 'http://www.as.utexas.edu/~tdupuy/plx/Database_of_Ultracool_Parallaxes_files/vlm-plx-all.fits' to file '/Users/tomasstolker/applications/species/docs/tutorials/data/vlm-plx-all.fits'.\n",
      "100%|████████████████████████████████████████| 314k/314k [00:00<00:00, 130MB/s]"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding Database of Ultracool Parallaxes..."
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " [DONE]\n"
     ]
    }
   ],
   "source": [
    "database.add_photometry('vlm-plx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we add the isochrones from AMES-Cond and AMES-Dusty, which have been retrieved from https://phoenix.ens-lyon.fr/Grids/."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Downloading AMES-Cond isochrones (235 kB)... [DONE]\n",
      "Adding isochrones: ames-cond... [DONE]\n",
      "Database tag: ames-cond\n",
      "Downloading AMES-Dusty isochrones (182 kB)... [DONE]\n",
      "Adding isochrones: ames-dusty... [DONE]\n",
      "Database tag: ames-dusty\n"
     ]
    }
   ],
   "source": [
    "database.add_isochrones('ames')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we need to add the grid with AMES-Cond model spectra. The full grid of spectra is downloaded but spectra with a $T_\\mathrm{eff}$ outside the chosen `teff_range` are not added to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Downloading AMES-Cond model spectra (150 MB)... [DONE]\n",
      "Unpacking AMES-Cond model spectra (150 MB)... [DONE]\n",
      "Wavelength range (um) = 0.5 - 40\n",
      "Spectral resolution = 4000\n",
      "Teff range (K) = 100.0 - 4000.0\n",
      "Adding AMES-Cond model spectra... [DONE]                               \n",
      "Grid points stored in the database:\n",
      "   - Teff = [ 100.  200.  300.  400.  500.  600.  700.  800.  900. 1000. 1100. 1200.\n",
      " 1300. 1400. 1500. 1600. 1700. 1800. 1900. 2000. 2100. 2200. 2300. 2400.\n",
      " 2500. 2600. 2700. 2800. 2900. 3000. 3100. 3200. 3300. 3400. 3500. 3600.\n",
      " 3700. 3800. 3900. 4000.]\n",
      "   - log(g) = [2.5 3.  3.5 4.  4.5 5.  5.5]\n",
      "Number of grid points per parameter:\n",
      "   - teff: 40\n",
      "   - logg: 7\n",
      "Fix missing grid points with a linear interpolation:\n",
      "   - teff = 200.0, logg = 5.5\n",
      "   - teff = 900.0, logg = 2.5\n",
      "Number of stored grid points: 280\n",
      "Number of interpolated grid points: 2\n",
      "Number of missing grid points: 0\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/tomasstolker/applications/species/species/util/data_util.py:380: RuntimeWarning: divide by zero encountered in log10\n",
      "  flux = np.log10(flux)\n"
     ]
    }
   ],
   "source": [
    "database.add_model(model='ames-cond',\n",
    "                   teff_range=(100., 4000.))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also the AMES-Dusty spectra are downloaded and imported into the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Downloading AMES-Dusty model spectra (59 MB)... [DONE]\n",
      "Unpacking AMES-Dusty model spectra (59 MB)... [DONE]\n",
      "Wavelength range (um) = 0.5 - 40\n",
      "Spectral resolution = 4000\n",
      "Teff range (K) = 100.0 - 4000.0\n",
      "Adding AMES-Dusty model spectra... [DONE]                                \n",
      "Grid points stored in the database:\n",
      "   - Teff = [ 500.  600.  700.  800.  900. 1000. 1100. 1200. 1300. 1400. 1500. 1600.\n",
      " 1700. 1800. 1900. 2000. 2100. 2200. 2300. 2400. 2500. 2600. 2700. 2800.\n",
      " 2900. 3000. 3100. 3200. 3300. 3400. 3500. 3600. 3700. 3800. 3900. 4000.]\n",
      "   - log(g) = [3.5 4.  4.5 5.  5.5 6. ]\n",
      "Number of grid points per parameter:\n",
      "   - teff: 36\n",
      "   - logg: 6\n",
      "Fix missing grid points with a linear interpolation:\n",
      "   - teff = 2100.0, logg = 3.5\n",
      "   - teff = 2100.0, logg = 4.5\n",
      "   - teff = 2400.0, logg = 5.0\n",
      "   - teff = 3100.0, logg = 3.5\n",
      "   - teff = 3200.0, logg = 3.5\n",
      "   - teff = 3300.0, logg = 3.5\n",
      "   - teff = 3400.0, logg = 3.5\n",
      "   - teff = 3500.0, logg = 3.5\n",
      "   - teff = 3600.0, logg = 3.5\n",
      "   - teff = 3700.0, logg = 3.5\n",
      "   - teff = 3800.0, logg = 3.5\n",
      "   - teff = 3900.0, logg = 3.5\n",
      "   - teff = 3900.0, logg = 6.0\n",
      "   - teff = 4000.0, logg = 3.5\n",
      "   - teff = 4000.0, logg = 4.0\n",
      "   - teff = 4000.0, logg = 4.5\n",
      "   - teff = 4000.0, logg = 5.5\n",
      "   - teff = 4000.0, logg = 6.0\n",
      "Could not interpolate 24 grid points so storing zeros instead. [WARNING]\n",
      "The grid points that are missing:\n",
      "   - teff = 900.0, logg = 6.0\n",
      "   - teff = 1100.0, logg = 5.5\n",
      "   - teff = 1100.0, logg = 6.0\n",
      "   - teff = 1200.0, logg = 5.5\n",
      "   - teff = 1200.0, logg = 6.0\n",
      "   - teff = 2100.0, logg = 3.5\n",
      "   - teff = 2100.0, logg = 4.0\n",
      "   - teff = 2200.0, logg = 3.5\n",
      "   - teff = 2200.0, logg = 4.0\n",
      "   - teff = 3100.0, logg = 3.5\n",
      "   - teff = 3200.0, logg = 3.5\n",
      "   - teff = 3300.0, logg = 3.5\n",
      "   - teff = 3400.0, logg = 3.5\n",
      "   - teff = 3500.0, logg = 3.5\n",
      "   - teff = 3600.0, logg = 3.5\n",
      "   - teff = 3700.0, logg = 3.5\n",
      "   - teff = 3800.0, logg = 3.5\n",
      "   - teff = 3900.0, logg = 3.5\n",
      "   - teff = 3900.0, logg = 6.0\n",
      "   - teff = 4000.0, logg = 3.5\n",
      "   - teff = 4000.0, logg = 4.0\n",
      "   - teff = 4000.0, logg = 4.5\n",
      "   - teff = 4000.0, logg = 5.5\n",
      "   - teff = 4000.0, logg = 6.0\n",
      "Number of stored grid points: 216\n",
      "Number of interpolated grid points: 3\n",
      "Number of missing grid points: 24\n"
     ]
    }
   ],
   "source": [
    "database.add_model(model='ames-dusty',\n",
    "                   teff_range=(100., 4000.))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are now ready with preparing the HDF5 database. The [list_content](https://species.readthedocs.io/en/latest/species.data.html#species.data.database.Database.list_content) method of the [Database](https://species.readthedocs.io/en/latest/species.data.html#species.data.database.Database) object can be used for printing an overview of all the data that are stored in the database."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Synthetic photometry from isochrones"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Magnitudes from the isochrone data can be extracted with the [get_isochrone](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_isochrone.ReadIsochrone.get_isochrone) function of [ReadIsochrone](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_isochrone.ReadIsochrone). However, in this example, we consistently recompute the synthetic photometry by making use of both the evolutionary tracks and the synthetic spectra."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The isochrones will be iterpolated for three different ages and the synthetic photometry is computed at 100 logarithmically-spaced masses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "ages = [20., 100.]  # (Myr)\n",
    "masses = np.logspace(0., 3., 100)  # (Mjup)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We create instances of [ReadIsochrone](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_isochrone.ReadIsochrone) for both the AMES-Cond and AMES-Dusty isochrones. We note though that the evolutionary data of these two models are actually the same. Only the magnitudes of the isochrones (which we do not use) are different."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "read_iso_cond = species.ReadIsochrone(tag='ames-cond')\n",
    "read_iso_dusty = species.ReadIsochrone(tag='ames-dusty')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The colors and magnitudes are computed by chosing the corresponding model grids from the database. The output is stored in [ColorMagBox](https://species.readthedocs.io/en/latest/species.core.html#species.core.box.ColorMagBox) objects for the three different ages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4019.3207105807364, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4019.3207105807364, 'logg': 4.351948444496957, 'radius': 10.170788710818773, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4164.404431717177, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4164.404431717177, 'logg': 4.329081153206135, 'radius': 10.739016824226589, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.9180307893338338, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.3730414241427, 'logg': 2.9180307893338338, 'radius': 1.4638670830301985, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.9730768802029495, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 502.5270292688421, 'logg': 2.9730768802029495, 'radius': 1.441670727659954, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.0355631548565696, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 504.9233097703563, 'logg': 3.0355631548565696, 'radius': 1.4150903616033272, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.1025651389931803, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 507.4927628068724, 'logg': 3.1025651389931803, 'radius': 1.3865891063317703, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.207337823869265, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 520.0556848108937, 'logg': 3.207337823869265, 'radius': 1.328194511799377, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.3065271787010397, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 534.0174915985033, 'logg': 3.3065271787010397, 'radius': 1.274758290992437, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.3387964574578715, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 543.9916323051601, 'logg': 3.3387964574578715, 'radius': 1.2725698348137873, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.372282732356024, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 556.2475974396231, 'logg': 3.372282732356024, 'radius': 1.2706911157956755, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.407135965646942, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 570.8634694648467, 'logg': 3.407135965646942, 'radius': 1.269118495295348, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.444507945285873, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 586.5355899585918, 'logg': 3.444507945285873, 'radius': 1.2674322258801856, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.484580694074335, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 603.3402910634309, 'logg': 3.484580694074335, 'radius': 1.2656240944588282, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4081.4355631859694, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4081.4355631859694, 'logg': 4.667985184351259, 'radius': 5.914180524946677, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4185.2608377397555, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4185.2608377397555, 'logg': 4.656638159809863, 'radius': 6.199078262481065, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4325.615910494432, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4325.615910494432, 'logg': 4.641153787722841, 'radius': 6.55382759835061, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4512.024881795706, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4512.024881795706, 'logg': 4.610559348746733, 'radius': 7.038423776652953, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4704.664806542345, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4704.664806542345, 'logg': 4.571845570260296, 'radius': 7.623463332054268, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 4915.122843504473, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 4915.122843504473, 'logg': 4.527793777987827, 'radius': 8.265784389535268, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:935: UserWarning: The value of teff is 5129.6908172285885, which is above the upper bound of the model grid (4000.0). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 5129.6908172285885, 'logg': 4.487243459618406, 'radius': 8.971175402210688, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.7961969975244876, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.58438710058044, 'logg': 2.7961969975244876, 'radius': 1.5064919873572373, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.8072667505973876, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.6880174178661, 'logg': 2.8072667505973876, 'radius': 1.5031419477567405, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.820805889271204, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.6648632173275, 'logg': 2.820805889271204, 'radius': 1.4989194659748202, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.8353234638853895, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.640035727038, 'logg': 2.8353234638853895, 'radius': 1.494391837164531, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.855670027860674, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.65383479103104, 'logg': 2.855670027860674, 'radius': 1.4883035183626285, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.879927968286292, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.6892732862044, 'logg': 2.879927968286292, 'radius': 1.4811452905054687, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.905938962678162, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.7272728229761, 'logg': 2.905938962678162, 'radius': 1.473469757406555, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.9339822921321925, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 501.84752531806237, 'logg': 2.9339822921321925, 'radius': 1.465193882836573, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 2.9644919021316207, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 502.20555197078545, 'logg': 2.9644919021316207, 'radius': 1.4561883961908293, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.0026726111414517, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 503.0100115950047, 'logg': 3.0026726111414517, 'radius': 1.4449586973534068, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.0444294083637633, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 503.93545547538565, 'logg': 3.0444294083637633, 'radius': 1.4326823296312547, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.0892038533213797, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 504.92777861412816, 'logg': 3.0892038533213797, 'radius': 1.4195187829174454, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.1490344602161873, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 506.1240352668346, 'logg': 3.1490344602161873, 'radius': 1.4012157774301066, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.2286358747595356, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 506.35983582050795, 'logg': 3.2286358747595356, 'radius': 1.3753758265566598, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.331188032984285, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 505.06156677568043, 'logg': 3.331188032984285, 'radius': 1.3405155245172165, 'distance': 10.0}.\n",
      "  warnings.warn(\n",
      "/Users/tomasstolker/applications/species/species/read/read_isochrone.py:910: UserWarning: The value of logg is 3.4411513507951, which is below the lower bound of the model grid (3.5). Setting the magnitudes to NaN for the following isochrone sample: {'teff': 503.6694754335613, 'logg': 3.4411513507951, 'radius': 1.3031359652909418, 'distance': 10.0}.\n",
      "  warnings.warn(\n"
     ]
    }
   ],
   "source": [
    "boxes = []\n",
    "\n",
    "for item in ages:\n",
    "\n",
    "    modelcolor1 = read_iso_cond.get_color_magnitude(age=item,\n",
    "                                                    masses=masses,\n",
    "                                                    filters_color=('MKO/NSFCam.H', 'MKO/NSFCam.Lp'),\n",
    "                                                    filter_mag='MKO/NSFCam.Lp')\n",
    "\n",
    "    modelcolor2 = read_iso_dusty.get_color_magnitude(age=item,\n",
    "                                                     masses=masses,\n",
    "                                                     filters_color=('MKO/NSFCam.H', 'MKO/NSFCam.Lp'),\n",
    "                                                     filter_mag='MKO/NSFCam.Lp')\n",
    "\n",
    "    boxes.append(modelcolor1)\n",
    "    boxes.append(modelcolor2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some warnings are printed when $T_\\mathrm{eff}$ or $\\log(g)$ from the evolutionary tracks are outside the parameter boundaries of the grid with spectra. Also, some of the chosen masses are below the lowest masses that are available in the evolutionary tracks. Therefore these colors and magnitudes are set to NaN and will be ignored when plotting the isochrones later one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Synthetic photometry from blackbody spectra"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to the isochrones, we also calculate colors and magnitudes for blackbody radiation. We start by creating an instance of [ReadPlanck](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_planck.ReadPlanck) for a wavelength range between 0.5 and 10 $\\mu$m."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "read_planck = species.ReadPlanck(wavel_range=(0.5, 10.))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we use the [get_color_magnitude](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_planck.ReadPlanck.get_color_magnitude) methode to calculate the synthetic photometry for the same filters from before. Here we chose 100 logarithmically-spaced temperatures between 100 and 10000 K. The radius, which only impacts the absolute magnitude, is set to 1 $R_\\mathrm{J}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "color_planck = read_planck.get_color_magnitude(temperatures=np.logspace(2, 4, 100),\n",
    "                                               radius=1.,\n",
    "                                               filters_color=('MKO/NSFCam.H', 'MKO/NSFCam.Lp'),\n",
    "                                               filter_mag='MKO/NSFCam.Lp')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The returned [ColorMagBox](https://species.readthedocs.io/en/latest/species.core.html#species.core.box.ColorMagBox) is added to the list of `boxes`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "boxes.append(color_planck)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Photometry of directly imaged objects"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will also create a list with names and filters of the directly imaged planets and brown dwarfs that we want to show. The [list_companions](https://species.readthedocs.io/en/latest/species.data.html#species.data.database.Database.list_companions) method of [Database](https://species.readthedocs.io/en/latest/species.data.html#species.data.database.Database) can be used to get an overview of all available photometric data in the database. We create a list with object names and filters for the colors and magnitudes that we want to include in the color-magnitude diagram."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "objects = [('HR 8799 b', 'Keck/NIRC2.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('HR 8799 c', 'Keck/NIRC2.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('HR 8799 d', 'Keck/NIRC2.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('HR 8799 e', 'Paranal/SPHERE.IRDIS_D_H23_2', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('kappa And b', 'Subaru/CIAO.H', 'Keck/NIRC2.Lp', 'Keck/NIRC2.Lp'),\n",
    "           ('GSC 06214 B', 'MKO/NSFCam.H', 'MKO/NSFCam.Lp', 'MKO/NSFCam.Lp'),\n",
    "           ('ROXs 42 Bb', 'Keck/NIRC2.H', 'Keck/NIRC2.Lp', 'Keck/NIRC2.Lp'),\n",
    "           ('51 Eri b', 'MKO/NSFCam.H', 'Keck/NIRC2.Lp', 'Keck/NIRC2.Lp'),\n",
    "           ('2M 1207 B', 'Paranal/NACO.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('2M0103 ABb', 'Paranal/NACO.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('1RXS 1609 B', 'Gemini/NIRI.H-G0203w', 'Gemini/NIRI.Lprime-G0207w', 'Gemini/NIRI.Lprime-G0207w'),\n",
    "           ('beta Pic b', 'Paranal/NACO.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('HIP 65426 b', 'Paranal/SPHERE.IRDIS_D_H23_2', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('PZ Tel B', 'Paranal/NACO.H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp'),\n",
    "           ('HD 206893 B', 'Paranal/SPHERE.IRDIS_B_H', 'Paranal/NACO.Lp', 'Paranal/NACO.Lp')]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reading color-magnitude data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The colors and magnitude of the Database of Ultracool Parallaxes are read from the database by creating an object of [ReadColorMagnitude](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_color.ReadColorMagnitude)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "colormag = species.ReadColorMagnitude(library='vlm-plx',\n",
    "                                      filters_color=('MKO/NSFCam.H', 'MKO/NSFCam.Lp'),\n",
    "                                      filter_mag='MKO/NSFCam.Lp')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then extracting the [ColorMagBox](https://species.readthedocs.io/en/latest/species.core.html#species.core.box.ColorMagBox) objects for field and young/low-gravity objects separately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "color_field = colormag.get_color_magnitude(object_type='field')\n",
    "color_young = colormag.get_color_magnitude(object_type='young')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also these [ColorMagBox](https://species.readthedocs.io/en/latest/species.core.html#species.core.box.ColorMagBox) objects are added to the list of `boxes`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "boxes.append(color_field)\n",
    "boxes.append(color_young)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting a color-magnitude diagram"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The color-magnitude diagram is now plotted with the [plot_color_magnitude](https://species.readthedocs.io/en/latest/species.plot.html#species.plot.plot_color.plot_color_magnitude) function. The list with `boxes` is provided as argument of the `boxes` parameter. The list with `objects` is provided separately as argument of `objects`. See the [API documentation](https://species.readthedocs.io/en/latest/species.plot.html#species.plot.plot_color.plot_color_magnitude) of `plot_color_magnitude` for further details on the various parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Plotting color-magnitude diagram..."
     ]
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 288x345.6 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      " [DONE]\n"
     ]
    }
   ],
   "source": [
    "fig = species.plot_color_magnitude(boxes=boxes,\n",
    "                                   objects=objects,\n",
    "                                   mass_labels={'ames-cond': [(3., 'right'), (5., 'right'), (10., 'left'), (20., 'right')],\n",
    "                                                'ames-dusty': [(10., 'right'), (15., 'left'), (20., 'left')]},\n",
    "                                   teff_labels={'planck': [(1500., 'right'), (2000., 'right'), (3000., 'left')]},\n",
    "                                   companion_labels=False,\n",
    "                                   field_range=('late M', 'late T'),\n",
    "                                   label_x=r'H $-$ L$^\\prime$',\n",
    "                                   label_y=r'M$_\\mathregular{L\\prime}$',\n",
    "                                   xlim=(0.3, 4.),\n",
    "                                   ylim=(15., 7.1),\n",
    "                                   offset=(-0.08, -0.09),\n",
    "                                   legend=(0.04, 0.04),\n",
    "                                   output=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The [plot_color_magnitude](https://species.readthedocs.io/en/latest/species.plot.html#species.plot.plot_color.plot_color_magnitude) function returned the [Figure](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure) object of the plot. The functionalities of [Matplotlib](https://matplotlib.org/stable/index.html) can be used for further customization of the plot. For example, the axes of the plot are stored at the `axes` attribute of `Figure`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<Axes: xlabel='H $-$ L$^\\\\prime$', ylabel='M$_\\\\mathregular{L\\\\prime}$'>,\n",
       " <Axes: >]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fig.axes"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}