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.

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.

Initiating species v0.5.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.init.SpeciesInit at 0x14bbaf2e0>

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 photometric data and parallaxes from the Database of Ultracool Parallaxes are downloaded and added to the database with the add_photometry method of Database.

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, 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', verbose=False)
database.add_companion('beta Pic b', verbose=False)
database.add_companion('PZ Tel B', verbose=False)
Downloading Vega spectrum (270 kB)... [DONE]
Adding Vega spectrum... [DONE]
Adding object: 51 Eri b [DONE]
Adding object: beta Pic b
/Users/tomasstolker/applications/species/species/data/ UserWarning: Found 33 fluxes with NaN in the data of GPI_YJHK. Removing the spectral fluxes that contain a NaN.
Adding object: PZ Tel B [DONE]

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.

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

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

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. The discrete colorbar shows the spectral types of the field dwarfs and the directly imaged objects are labeled individually.

species.plot_color_magnitude(boxes=[colorbox, ],
                             reddening=[(('MKO/NSFCam.J', 'MKO/NSFCam.H'), ('MKO/NSFCam.J', 1.), 'MgSiO3', 0.1, (-0.8, 10.))],
                             label_x=r'$J - H$',
                             xlim=(-1.2, 1.5),
                             ylim=(21., 8.),
                             offset=(-0.08, -0.08),
                             field_range=('late M', 'late T'),
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... [DONE]