Running species

This tutorial shows what a typical workflow with species looks like. We will compare the colors and magnitudes of a few directly imaged companions with those of field dwarfs from the Database of Ultracool Parallaxes.

Initiating species

We start by importing the species toolkit.

[1]:
import species

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.

[2]:
species.SpeciesInit()
Initiating species v0.4.0... [DONE]
Creating species_config.ini... [DONE]
Database: /Users/tomasstolker/applications/species/docs/tutorials/species_database.hdf5
Data folder: /Users/tomasstolker/applications/species/docs/tutorials/data
Working folder: /Users/tomasstolker/applications/species/docs/tutorials
Creating species_database.hdf5... [DONE]
Creating data folder... [DONE]
[2]:
<species.core.init.SpeciesInit at 0x14f635430>

Adding a photometric library

A Database object is now created, which can be used for importing data from the chosen data folder into the database.

[3]:
database = species.Database()

The photometric data and parallaxes from the Database of Ultracool Parallaxes are downloaded and added to the database with the add_photometry method of Database.

[4]:
database.add_photometry('vlm-plx')
Downloading Database of Ultracool Parallaxes (307 kB)... [DONE]
Adding Database of Ultracool Parallaxes... [DONE]

Adding companion data

A library of distances and magnitudes of directly imaged companions are available in the species package (see species.data.companions), which can be added to the Database with the add_companion method (alternatively, photometric data of individual objects can be manually imported with add_object). In this example, we add the distance and magnitudes of 51 Eri b, beta Pic b, and PZ Tel B to the database. This will automatically download the filter profiles and a flux calibrated spectrum of Vega. These are required for the flux calibration of the companion magnitudes.

[5]:
database.add_companion('51 Eri b')
database.add_companion('beta Pic b')
database.add_companion('PZ Tel B')
Getting SPHERE_YJH spectrum of 51 Eri b... [DONE]
IMPORTANT: Please cite Samland et al. 2017, A&A, 603, 57
           when making use of this spectrum in a publication
Downloading Vega spectrum (270 kB)... [DONE]
Adding Vega spectrum... [DONE]
Adding filter: MKO/NSFCam.J... [DONE]
Adding filter: MKO/NSFCam.H... [DONE]
Adding filter: MKO/NSFCam.K... [DONE]
Adding filter: Paranal/SPHERE.IRDIS_B_H... [DONE]
Adding filter: Paranal/SPHERE.IRDIS_D_H23_2... [DONE]
Adding filter: Paranal/SPHERE.IRDIS_D_K12_1... [DONE]
Adding filter: Keck/NIRC2.Lp... [DONE]
Adding filter: Keck/NIRC2.Ms... [DONE]
Adding object: 51 Eri b
   - Distance (pc) = 29.78 +/- 0.12
   - MKO/NSFCam.J:
      - Apparent magnitude = 19.04 +/- 0.40
      - Flux (W m-2 um-1) = 7.52e-17 +/- 2.83e-17
   - MKO/NSFCam.H:
      - Apparent magnitude = 18.99 +/- 0.21
      - Flux (W m-2 um-1) = 3.12e-17 +/- 6.07e-18
   - MKO/NSFCam.K:
      - Apparent magnitude = 18.67 +/- 0.19
      - Flux (W m-2 um-1) = 1.42e-17 +/- 2.49e-18
   - Paranal/SPHERE.IRDIS_B_H:
      - Apparent magnitude = 19.45 +/- 0.29
      - Flux (W m-2 um-1) = 2.06e-17 +/- 5.57e-18
   - Paranal/SPHERE.IRDIS_D_H23_2:
      - Apparent magnitude = 18.41 +/- 0.26
      - Flux (W m-2 um-1) = 5.66e-17 +/- 1.37e-17
   - Paranal/SPHERE.IRDIS_D_K12_1:
      - Apparent magnitude = 17.55 +/- 0.14
      - Flux (W m-2 um-1) = 4.64e-17 +/- 6.00e-18
   - Keck/NIRC2.Lp:
      - Apparent magnitude = 16.20 +/- 0.11
      - Flux (W m-2 um-1) = 1.79e-17 +/- 1.81e-18
   - Keck/NIRC2.Ms:
      - Apparent magnitude = 16.10 +/- 0.50
      - Flux (W m-2 um-1) = 8.47e-18 +/- 4.04e-18
   - Spectrum:
      - Database tag: SPHERE_YJH
      - Filename: ./data/companion_data/51erib_sphere_yjh.dat
      - Data shape: (33, 3)
      - Wavelength range (um): 1.01 - 1.64
      - Mean flux (W m-2 um-1): 3.50e-17
      - Mean error (W m-2 um-1): 1.06e-17
   - Spectral resolution:
      - SPHERE_YJH: 25.0
Getting GPI_YJHK spectrum of beta Pic b... [DONE]
IMPORTANT: Please cite Chilcote et al. 2017, AJ, 153, 182
           when making use of this spectrum in a publication
Getting GRAVITY spectrum of beta Pic b... [DONE]
IMPORTANT: Please cite Gravity Collaboration et al. 2020, A&A, 633, 110
           when making use of this spectrum in a publication
Adding filter: Magellan/VisAO.Ys... [DONE]
Adding filter: Paranal/NACO.J... [DONE]
Adding filter: Gemini/NICI.ED286... [DONE]
Adding filter: Paranal/NACO.H... [DONE]
Adding filter: Paranal/NACO.Ks... [DONE]
Adding filter: Paranal/NACO.NB374... [DONE]
Adding filter: Paranal/NACO.Lp... [DONE]
Adding filter: Paranal/NACO.NB405... [DONE]
Adding filter: Paranal/NACO.Mp... [DONE]
Adding object: beta Pic b
   - Distance (pc) = 19.75 +/- 0.13
   - Magellan/VisAO.Ys:
      - Apparent magnitude = 15.53 +/- 0.34
      - Flux (W m-2 um-1) = 4.25e-15 +/- 1.35e-15
   - Paranal/NACO.J:
      - Apparent magnitude = 14.11 +/- 0.21
      - Flux (W m-2 um-1) = 6.87e-15 +/- 1.34e-15
   - Gemini/NICI.ED286:
      - Apparent magnitude = 13.18 +/- 0.15
      - Flux (W m-2 um-1) = 6.99e-15 +/- 9.69e-16
   - Paranal/NACO.H:
      - Apparent magnitude = 13.32 +/- 0.14
      - Flux (W m-2 um-1) = 5.47e-15 +/- 7.08e-16
   - Paranal/NACO.Ks:
      - Apparent magnitude = 12.64 +/- 0.11
      - Flux (W m-2 um-1) = 4.04e-15 +/- 4.10e-16
   - Paranal/NACO.NB374:
      - Apparent magnitude = 11.25 +/- 0.23
      - Flux (W m-2 um-1) = 1.69e-15 +/- 3.61e-16
   - Paranal/NACO.Lp:
      - Apparent magnitude = 11.30 +/- 0.06
      - Flux (W m-2 um-1) = 1.59e-15 +/- 8.79e-17
   - Paranal/NACO.NB405:
      - Apparent magnitude = 10.98 +/- 0.05
      - Flux (W m-2 um-1) = 1.61e-15 +/- 7.42e-17
   - Paranal/NACO.Mp:
      - Apparent magnitude = 11.10 +/- 0.12
      - Flux (W m-2 um-1) = 7.86e-16 +/- 8.70e-17
   - Spectrum:
      - Database tag: GPI_YJHK
      - Filename: ./data/companion_data/betapicb_gpi_yjhk.dat
      - Data shape: (185, 3)
      - Wavelength range (um): 0.95 - 2.40
      - Mean flux (W m-2 um-1): 5.40e-15
      - Mean error (W m-2 um-1): 6.44e-16
   - GRAVITY spectrum:
      - Object: Unknown
      - Database tag: GRAVITY
      - Filename: ./data/companion_data/BetaPictorisb_2018-09-22.fits
      - Data shape: (237, 3)
      - Wavelength range (um): 1.97 - 2.49
      - Mean flux (W m-2 um-1): 4.65e-15
      - Mean error (W m-2 um-1): 1.00e-16
   - GRAVITY covariance matrix:
      - Object: Unknown
      - Database tag: GRAVITY
      - Filename: ./data/companion_data/BetaPictorisb_2018-09-22.fits
      - Data shape: (237, 237)
   - Spectral resolution:
      - GPI_YJHK: 40.0
      - GRAVITY: 500.0
Adding filter: Paranal/SPHERE.ZIMPOL_R_PRIM... [DONE]
Adding filter: Paranal/SPHERE.ZIMPOL_I_PRIM... [DONE]
Adding filter: Paranal/SPHERE.IRDIS_D_H23_3... [DONE]
Adding filter: Paranal/SPHERE.IRDIS_D_K12_2... [DONE]
Adding filter: Gemini/NIRI.H2S1v2-1-G0220... [DONE]
Adding object: PZ Tel B
   - Distance (pc) = 47.13 +/- 0.13
   - Paranal/SPHERE.ZIMPOL_R_PRIM:
      - Apparent magnitude = 17.84 +/- 0.31
      - Flux (W m-2 um-1) = 1.83e-15 +/- 5.29e-16
   - Paranal/SPHERE.ZIMPOL_I_PRIM:
      - Apparent magnitude = 15.16 +/- 0.12
      - Flux (W m-2 um-1) = 1.09e-14 +/- 1.20e-15
   - Paranal/SPHERE.IRDIS_D_H23_2:
      - Apparent magnitude = 11.78 +/- 0.19
      - Flux (W m-2 um-1) = 2.54e-14 +/- 4.47e-15
   - Paranal/SPHERE.IRDIS_D_H23_3:
      - Apparent magnitude = 11.65 +/- 0.19
      - Flux (W m-2 um-1) = 2.43e-14 +/- 4.27e-15
   - Paranal/SPHERE.IRDIS_D_K12_1:
      - Apparent magnitude = 11.56 +/- 0.09
      - Flux (W m-2 um-1) = 1.15e-14 +/- 9.58e-16
   - Paranal/SPHERE.IRDIS_D_K12_2:
      - Apparent magnitude = 11.29 +/- 0.10
      - Flux (W m-2 um-1) = 1.14e-14 +/- 1.05e-15
   - Paranal/NACO.J:
      - Apparent magnitude = 12.47 +/- 0.20
      - Flux (W m-2 um-1) = 3.11e-14 +/- 5.76e-15
   - Paranal/NACO.H:
      - Apparent magnitude = 11.93 +/- 0.14
      - Flux (W m-2 um-1) = 1.97e-14 +/- 2.55e-15
   - Paranal/NACO.Ks:
      - Apparent magnitude = 11.53 +/- 0.07
      - Flux (W m-2 um-1) = 1.12e-14 +/- 7.25e-16
   - Paranal/NACO.Lp:
      - Apparent magnitude = 11.04 +/- 0.22
      - Flux (W m-2 um-1) = 2.02e-15 +/- 4.12e-16
   - Paranal/NACO.NB405:
      - Apparent magnitude = 10.94 +/- 0.07
      - Flux (W m-2 um-1) = 1.67e-15 +/- 1.08e-16
   - Paranal/NACO.Mp:
      - Apparent magnitude = 10.93 +/- 0.03
      - Flux (W m-2 um-1) = 9.19e-16 +/- 2.54e-17
   - Gemini/NICI.ED286:
      - Apparent magnitude = 11.68 +/- 0.14
      - Flux (W m-2 um-1) = 2.78e-14 +/- 3.60e-15
   - Gemini/NIRI.H2S1v2-1-G0220:
      - Apparent magnitude = 11.39 +/- 0.14
      - Flux (W m-2 um-1) = 1.06e-14 +/- 1.37e-15

Reading color-magnitude data

The colors and magnitudes from the Database of Ultracool Parallaxes are read from the database in the working folder by first creating an instance of ReadColorMagnitude.

[6]:
colormag = species.ReadColorMagnitude(library='vlm-plx',
                                      filters_color=('MKO/NSFCam.J', 'MKO/NSFCam.H'),
                                      filter_mag='MKO/NSFCam.J')

The data of the field dwarfs are now read with the get_color_magnitude method. This returns a ColorMagBox with the requested data.

[7]:
colorbox = colormag.get_color_magnitude(object_type='field')

We also create a list with the color and magnitude filter names that we want to extract for the directly imaged companions.

[8]:
objects = [('51 Eri b', 'MKO/NSFCam.J', 'MKO/NSFCam.H', 'MKO/NSFCam.J'),
           ('beta Pic b', 'Paranal/NACO.J', 'Paranal/NACO.H', 'Paranal/NACO.J'),
           ('PZ Tel B', 'Paranal/NACO.J', 'Paranal/NACO.H', 'Paranal/NACO.J')]

Plotting a color-magnitude diagram

We will now combine the selected data in a color-magnitude diagram. The ColorMagBox is provided in a list to the plot_color_magnitude function. The list with directly imaged objects is provided as argument of objects. We also add a reddening vector to show how the color changes for a size distribution of enstatite grains with a geometric mean radius of 0.1 \(\mu\)m and an extinction in the \(J\) band of 1 mag.

[9]:
species.plot_color_magnitude(boxes=[colorbox, ],
                             objects=objects,
                             reddening=[(('MKO/NSFCam.J', 'MKO/NSFCam.H'), ('MKO/NSFCam.J', 1.), 'MgSiO3', 0.1, (-0.8, 10.))],
                             label_x=r'$J$ - $H$',
                             label_y=r'M$_J$',
                             xlim=(-1.2, 1.5),
                             ylim=(21., 8.),
                             offset=(-0.08, -0.08),
                             companion_labels=True,
                             field_range=('late M', 'late T'),
                             legend=None,
                             output='color_mag.png')
Downloading optical constants (87 kB)... [DONE]
Unpacking optical constants... [DONE]
Adding optical constants of MgSiO3... [DONE]
Adding optical constants of Fe... [DONE]
Downloading log-normal dust cross sections (231 kB)... [DONE]
Adding log-normal dust cross sections:
   - Data shape (n_wavelength, n_radius, n_sigma): (67, 20, 20)
   - Wavelength range: 0.4 - 10.0 um
   - Mean geometric radius range: 0.001 - 10.0 um
   - Geometric standard deviation range: 1.0 - 10.0
Downloading power-law dust cross sections (231 kB)... [DONE]
Adding power-law dust cross sections
   - Data shape (n_wavelength, n_radius, n_exponent): (132, 50, 50)
   - Wavelength range: 0.4 - 10.0 um
   - Maximum grain radius range: 0.01 - 100.0 um
   - Power-law exponent range: -10.0 - 10.0
Plotting color-magnitude diagram: color_mag.png... [DONE]

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.

[10]:
from IPython.display import Image
Image('color_mag.png')
[10]:
../_images/tutorials_running_species_26_0.png