Extracting data of directly imaged companions#

In this tutorial, we will add photometric data, parallaxes, 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.

from species import SpeciesInit
from species.data.database import Database
from species.read.read_object import ReadObject

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

species v0.7.4

Working folder: /Users/tomasstolker/applications/species/docs/tutorials
Creating species_config.ini... [DONE]

Configuration settings:
   - Database: /Users/tomasstolker/applications/species/docs/tutorials/species_database.hdf5
   - Data folder: /Users/tomasstolker/applications/species/docs/tutorials/data
   - Magnitude of Vega: 0.03
Creating species_database.hdf5... [DONE]
Creating data folder... [DONE]

Multiprocessing: mpi4py installed
Process number 1 out of 1...
<species.core.species_init.SpeciesInit at 0x10f0218d0>

Adding companion data to the database#

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

database = Database()

Next, we use the add_companion method of Database to add all companion data that are available in the companion_data and companion_spectra files. This includes filter names, magnitudes, and parallaxes 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)
Adding companion: ['beta Pic b', 'beta Pic c', 'HIP 65426 b', '51 Eri b', 'HR 8799 b', 'HR 8799 c', 'HR 8799 d', 'HR 8799 e', 'HD 95086 b', 'PDS 70 b', 'PDS 70 c', '2M 1207 B', 'AB Pic B', 'HD 206893 B', 'RZ Psc B', 'GQ Lup B', 'PZ Tel B', 'kappa And b', 'HD 1160 B', 'ROXs 12 B', 'ROXs 42 Bb', 'GJ 504 b', 'GJ 758 B', 'GU Psc b', '2M0103 ABb', '1RXS 1609 B', 'GSC 06214 B', 'HD 72946 B', 'HIP 64892 B', 'HD 13724 B', 'YSES 1 b', 'YSES 1 c', 'YSES 2 b', 'HD 142527 B', 'CS Cha B', 'CT Cha B', 'SR 12 C', 'DH Tau B', 'HD 4747 B', 'HR 3549 B', 'CHXR 73 B', 'HD 19467 B', 'b Cen (AB)b', 'VHS 1256 B']
Downloading data from 'https://archive.stsci.edu/hlsps/reference-atlases/cdbs/current_calspec/alpha_lyr_stis_011.fits' to file '/Users/tomasstolker/applications/species/docs/tutorials/data/alpha_lyr_stis_011.fits'.
100%|████████████████████████████████████████| 288k/288k [00:00<00:00, 149MB/s]
Adding spectrum: VegaReference: Bohlin et al. 2014, PASP, 126
URL: https://ui.adsabs.harvard.edu/abs/2014PASP..126..711B/abstract
/Users/tomasstolker/applications/species/species/data/database.py:1356: UserWarning: Found 33 fluxes with NaN in the data of GPI_YJHK. Removing the spectral fluxes that contain a NaN.
/Users/tomasstolker/applications/species/species/data/filter_data/filter_data.py:227: 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 = 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.63 +/- 0.06
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.63 +/- 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)

Get object

Object name: beta Pic b
Include photometry: True
Include spectra: False

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.5841803431418238, 'Magellan/VisAO.Ys': 0.9826820974261752, 'Paranal/NACO.H': 1.6588090664617747, 'Paranal/NACO.J': 1.265099894847529, 'Paranal/NACO.Ks': 2.144954491491888, 'Paranal/NACO.Lp': 3.8050282724280526, 'Paranal/NACO.Mp': 4.780970919324577, 'Paranal/NACO.NB374': 3.744805012092439, 'Paranal/NACO.NB405': 4.055862923806052}
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.88473179e-15, 9.54189511e-16]), 'Magellan/VisAO.Ys': array([4.21442946e-15, 1.34143128e-15]), 'Paranal/NACO.H': array([5.38576426e-15, 6.96392162e-16]), 'Paranal/NACO.J': array([6.78430595e-15, 1.32039804e-15]), 'Paranal/NACO.Ks': array([3.97213973e-15, 4.03121161e-16]), 'Paranal/NACO.Lp': array([1.55661222e-15, 8.60653603e-17]), 'Paranal/NACO.Mp': array([7.69564549e-16, 8.52286898e-17]), 'Paranal/NACO.NB374': array([1.65829270e-15, 3.53922391e-16]), 'Paranal/NACO.NB405': array([1.57733391e-15, 7.26645888e-17])}
spectrum = None
parallax = [50.9307  0.1482]
distance = 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']