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.
We start by importing the species toolkit.
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.
species.SpeciesInit()
Initiating species v0.3.1... [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]
<species.core.setup.SpeciesInit at 0x13db6c0b8>
A Database object is now created, which can be used for importing data from the chosen data folder into the database.
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.
database.add_photometry('vlm-plx')
Downloading Database of Ultracool Parallaxes (307 kB)... [DONE] Adding Database of Ultracool Parallaxes... [DONE]
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.
database.add_companion('51 Eri b')
database.add_companion('beta Pic b')
database.add_companion('PZ Tel B')
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 Adding filter: LCO/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 filter: Paranal/SPHERE.IRDIS_D_K12_2... [DONE] Adding object: beta Pic b - Distance (pc) = 19.75 +/- 0.13 - LCO/VisAO.Ys: - Apparent magnitude = 15.53 +/- 0.34 - Flux (W m-2 um-1) = 4.27e-15 +/- 1.36e-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 - Paranal/SPHERE.IRDIS_D_K12_1: - Apparent magnitude = 12.57 +/- 0.00 - Flux (W m-2 um-1) = 4.56e-15 +/- 1.26e-17 - Paranal/SPHERE.IRDIS_D_K12_2: - Apparent magnitude = 12.21 +/- 0.00 - Flux (W m-2 um-1) = 4.92e-15 +/- 9.05e-18 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: 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
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.
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.
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.
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')]
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.
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='J - H',
label_y='M$_\mathregular{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.1 - 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.
from IPython.display import Image
Image('color_mag.png')