Running species

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.

Initiating species

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.1.4... [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 0x12d606550>

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.

database = species.Database()

The photometry and parallaxes from the Database of Ultracool Parallaxes are downloaded and added to the database.

database.add_photometry('vlm-plx')

Downloading Database of Ultracool Parallaxes (307 kB)... [DONE]
Adding Database of Ultracool Parallaxes... [DONE]

Adding companion data

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.

database.add_companion('51 Eri b')
database.add_companion('beta Pic b')
database.add_companion('PZ Tel B')

Adding filter: MKO/NSFCam.J... [DONE]
Downloading Vega spectrum (270 kB)... [DONE]
Adding Vega spectrum... [DONE]
Adding filter: MKO/NSFCam.H... [DONE]
Adding filter: MKO/NSFCam.K... [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... [DONE]
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 object: beta Pic b... [DONE]
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... [DONE]

Reading color-magnitude data

The colors and magnitudes are read from the database by first creating an object of ReadColorMagnitude.

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

The data is read by selecting the object type of the isolated brown dwarfs.

colorbox = colormag.get_color_magnitude(object_type='field')

A list of directly imaged objects is created with the filter names for the colors and magnitudes.

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

The ColorMagBox object is provided in a list to plot_color_magnitude. The list with directly imaged objects are also included.

species.plot_color_magnitude(boxes=[colorbox, ],
                             objects=objects,
                             label_x='J - H [mag]',
                             label_y='M$_\mathregular{J}$ [mag]',
                             companion_labels=True,
                             field_range=('late M', 'late T'),
                             legend=None,
                             output='color_mag.png')

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')