Photometric data of directly imaged planets

In this tutorial, we will add photometric data, distances, and spectra of directly imaged planets and brown dwarfs to the database and use the reading functionalities to easily access those data.

Getting started

We start by importing the required Python packages.

import species

The species HDF5 database is initiated by creating an instance of the SpeciesInit class.

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]
<species.core.init.SpeciesInit at 0x14abebaf0>

Adding companion data to the database

To add data to the database, we first create an instance of Database.

database = species.Database()

Next, we use the add_companion method of Database to add all companion data that is available in the species toolkit. This includes filter names, magnitudes, and distances of most directly imaged planets and brown dwarfs, as well as spectra for some objects. We set the argument of name to None such that all data are added instead of selecting a single companion.

Running this method will also download the relevant filter profiles from the SVO Filter Profile Service and a flux-calibrated spectrum of Vega. The magnitudes that are available in the toolkit are converted into fluxes and both stored in the database. We set verbose to False to not print a overview of all the filter and companion data that are being added.

database.add_companion(name=None, verbose=False)
Downloading Vega spectrum (270 kB)... [DONE]
Adding Vega spectrum... [DONE]
/Users/tomasstolker/applications/species/species/data/ UserWarning: The minimum transmission value of Subaru/CIAO.z is smaller than zero (-1.80e-03). Wavelengths with negative transmission values will be removed.

To get an overview of the companion data that are stored in the database, one can use the list_companions method of Database. This will also return a list with the companion names, which could for example be iterated when using the reading functionalities below.

Reading companion data

For reading data of individual companions/objects, we can use the reading functionalities of the toolkit. We start by creating an instance of ReadObject with the object name as stored in the database given as argument.

read_obj = species.ReadObject('beta Pic b')

We can check for which filters there is photometric data available with the list_filters method of ReadObject.

filter_list = read_obj.list_filters()
Available photometric data for beta Pic b:
   - Gemini/NICI.ED286
   - Magellan/VisAO.Ys
   - Paranal/NACO.H
   - Paranal/NACO.J
   - Paranal/NACO.Ks
   - Paranal/NACO.Lp
   - Paranal/NACO.Mp
   - Paranal/NACO.NB374
   - Paranal/NACO.NB405
['Gemini/NICI.ED286', 'Magellan/VisAO.Ys', 'Paranal/NACO.H', 'Paranal/NACO.J', 'Paranal/NACO.Ks', 'Paranal/NACO.Lp', 'Paranal/NACO.Mp', 'Paranal/NACO.NB374', 'Paranal/NACO.NB405']

Let’s now extract the photometric data of the NACO \(M'\) filter. The get_photometry method returns an array with the apparent magnitude, magnitude error, flux density (W m\(^{-2}\) \(\mu\)m\(^{-1}\)), and flux density error.

mp_phot = read_obj.get_photometry('Paranal/NACO.Mp')

Similarly, we can use the get_spectrum method to return a dictionary with available spectra. In this case a GPI spectrum in the \(YJHK\) bands from Chilcote et al. 2017 and a GRAVITY spectrum in the \(K\) band from Gravity Collaboration et al. 2020.

spec_dict = read_obj.get_spectrum()
dict_keys(['GPI_YJHK', 'GRAVITY'])

Other methods for ReadObject are get_distance for returning the distance and get_absmag for calculating the absolute magnitude and uncertainty.

distance = read_obj.get_distance()
print(f'Distance (pc) = {distance[0]:.2f} +/- {distance[1]:.2f}')
Distance (pc) = 19.75 +/- 0.13
abs_mag = read_obj.get_absmag('Paranal/NACO.Mp')
print(f'Apparent magnitude = {mp_phot[0]:.2f} +/- {mp_phot[1]:.2f}')
print(f'Absolute magnitude = {abs_mag[0]:.2f} +/- {abs_mag[1]:.2f}')
Apparent magnitude = 11.10 +/- 0.12
Absolute magnitude = 9.62 +/- 0.12

Extracting an ObjectBox with data

Instead of using the ReadObject functionalities, we can also use the get_object method of Database to extract an ObjectBox with the companion data from the database. The inc_phot and inc_spec parameters are either a boolean or a list of filter names / spectra. In this example, we will include all photometric data.

object_box = database.get_object('beta Pic b', inc_phot=True, inc_spec=False)
Getting object: beta Pic b... [DONE]

We can inspect the content of the ObjectBox with the open_box method. Let’s have a look!

Opening ObjectBox...
name = beta Pic b
filters = ['Gemini/NICI.ED286', 'Magellan/VisAO.Ys', 'Paranal/NACO.H', 'Paranal/NACO.J', 'Paranal/NACO.Ks', 'Paranal/NACO.Lp', 'Paranal/NACO.Mp', 'Paranal/NACO.NB374', 'Paranal/NACO.NB405']
mean_wavel = {'Gemini/NICI.ED286': 1.5841804, 'Magellan/VisAO.Ys': 0.9826820974261752, 'Paranal/NACO.H': 1.6588092, 'Paranal/NACO.J': 1.2650998, 'Paranal/NACO.Ks': 2.1449544, 'Paranal/NACO.Lp': 3.8050284, 'Paranal/NACO.Mp': 4.780971, 'Paranal/NACO.NB374': 3.744805, 'Paranal/NACO.NB405': 4.0558634}
magnitude = {'Gemini/NICI.ED286': array([13.18,  0.15]), 'Magellan/VisAO.Ys': array([15.53,  0.34]), 'Paranal/NACO.H': array([13.32,  0.14]), 'Paranal/NACO.J': array([14.11,  0.21]), 'Paranal/NACO.Ks': array([12.64,  0.11]), 'Paranal/NACO.Lp': array([11.3 ,  0.06]), 'Paranal/NACO.Mp': array([11.1 ,  0.12]), 'Paranal/NACO.NB374': array([11.25,  0.23]), 'Paranal/NACO.NB405': array([10.98,  0.05])}
flux = {'Gemini/NICI.ED286': array([6.98948226e-15, 9.68707404e-16]), 'Magellan/VisAO.Ys': array([4.24517648e-15, 1.35121790e-15]), 'Paranal/NACO.H': array([5.47258430e-15, 7.07618199e-16]), 'Paranal/NACO.J': array([6.86840623e-15, 1.33676609e-15]), 'Paranal/NACO.Ks': array([4.04416805e-15, 4.10431111e-16]), 'Paranal/NACO.Lp': array([1.58988155e-15, 8.79048273e-17]), 'Paranal/NACO.Mp': array([7.85616914e-16, 8.70064771e-17]), 'Paranal/NACO.NB374': array([1.69319029e-15, 3.61370437e-16]), 'Paranal/NACO.NB405': array([1.61004054e-15, 7.41713169e-17])}
distance = [19.75  0.13]
spectrum = None

Each Box is a Python object and the items in a box can be extracted as attributes. For example, to get the list of filter names:

['Gemini/NICI.ED286', 'Magellan/VisAO.Ys', 'Paranal/NACO.H', 'Paranal/NACO.J', 'Paranal/NACO.Ks', 'Paranal/NACO.Lp', 'Paranal/NACO.Mp', 'Paranal/NACO.NB374', 'Paranal/NACO.NB405']