Resokit.query Tutorial

This tutorial is a guide to use ResoKit.query package. ResoKit.query includes tools to make ASQL or SQL queries to the EU and NASA datasets with optimized structure.

In this brief tutorial we show how to use it.

Import ResoKit and the necessary packages

[1]:

import resokit.query as rquery

Query system

The main function query_system performs a specific query to either NASA or EU, to retrieve a system (or planet) from the online database.

This function does not support non-exact matches, so the system (or planet) input name must be the same as in the database.

Lest load the Kepler 55 system from NASA database.

[2]:

k55 = rquery.query_system("nasa", "Kepler-55")
k55

 Querying nasa database with query: SELECT * FROM ps WHERE (hostname='Kepler-55') AND default_flag=1 AND pl_controv_flag=0
Executing the query...
Query executed successfully.

[2]:

StaticSystem: 'Kepler-55'
 Star:
  Kepler-55
 Planets:
  Kepler-55 d
  Kepler-55 e
  Kepler-55 f
  Kepler-55 b
  Kepler-55 c
from 'nasa' data source.

The query result is cached during the session, so it can be re-used if necessary.

[3]:

k55 = rquery.query_system("nasa", "Kepler-55")
k55

 Querying nasa database with query: SELECT * FROM ps WHERE (hostname='Kepler-55') AND default_flag=1 AND pl_controv_flag=0
Using cached previous identic query.

[3]:

StaticSystem: 'Kepler-55'
 Star:
  Kepler-55
 Planets:
  Kepler-55 d
  Kepler-55 e
  Kepler-55 f
  Kepler-55 b
  Kepler-55 c
from 'nasa' data source.

Query a Planet

If, instead of a whole system, only a planet is needed, we can set the parameter planet_name instead of star_name.

[4]:

k55c = rquery.query_system("nasa", planet_name="Kepler-55 c")
k55c

 Querying nasa database with query: SELECT * FROM ps WHERE (pl_name='Kepler-55 c') AND default_flag=1 AND pl_controv_flag=0
Executing the query...
Query executed successfully.

[4]:

StaticSystem: 'Kepler-55'
 Star:
  Kepler-55
 Planet:
  Kepler-55 c
from 'nasa' data source.

Here, a system with the star and only the specified planet is created.

Raw dataframe

Instead of a resokit StaticSystem, it is possible to retrieve the raw pandas DataFrame (without the ResoKit structure) obtained from the query, setting the parameter raw=True.

[5]:

k55_raw = rquery.query_system("nasa", star_name="Kepler-55", raw=True)
k55_raw

 Querying nasa database with query: SELECT * FROM ps WHERE (hostname='Kepler-55') AND default_flag=1 AND pl_controv_flag=0
Using cached previous identic query.

[5]:

	pl_name	pl_letter	hostname	hd_name	hip_name	tic_id	gaia_id	default_flag	pl_refname	sy_refname	...	sy_jmagerr1	sy_jmagerr2	sy_jmagstr	sy_hmag	sy_hmagerr1	sy_hmagerr2	sy_hmagstr	sy_kmag	sy_kmagerr1	sy_kmagerr2
0	Kepler-55 b	b	Kepler-55	NaN	NaN	TIC 164884002	Gaia DR2 2105930840143687680	1	<a refstr=STEFFEN_ET_AL__2013 href=https://ui....	<a refstr=STASSUN_ET_AL__2019 href=https://ui....	...	0.031	-0.031	13.970±0.031	13.359	0.03	-0.03	13.359±0.030	13.289	0.049	-0.049
1	Kepler-55 c	c	Kepler-55	NaN	NaN	TIC 164884002	Gaia DR2 2105930840143687680	1	<a refstr=STEFFEN_ET_AL__2013 href=https://ui....	<a refstr=STASSUN_ET_AL__2019 href=https://ui....	...	0.031	-0.031	13.970±0.031	13.359	0.03	-0.03	13.359±0.030	13.289	0.049	-0.049
2	Kepler-55 d	d	Kepler-55	NaN	NaN	TIC 164884002	Gaia DR2 2105930840143687680	1	<a refstr=ROWE_ET_AL__2014 href=https://ui.ads...	<a refstr=STASSUN_ET_AL__2019 href=https://ui....	...	0.031	-0.031	13.970±0.031	13.359	0.03	-0.03	13.359±0.030	13.289	0.049	-0.049
3	Kepler-55 f	f	Kepler-55	NaN	NaN	TIC 164884002	Gaia DR2 2105930840143687680	1	<a refstr=ROWE_ET_AL__2014 href=https://ui.ads...	<a refstr=STASSUN_ET_AL__2019 href=https://ui....	...	0.031	-0.031	13.970±0.031	13.359	0.03	-0.03	13.359±0.030	13.289	0.049	-0.049
4	Kepler-55 e	e	Kepler-55	NaN	NaN	TIC 164884002	Gaia DR2 2105930840143687680	1	<a refstr=ROWE_ET_AL__2014 href=https://ui.ads...	<a refstr=STASSUN_ET_AL__2019 href=https://ui....	...	0.031	-0.031	13.970±0.031	13.359	0.03	-0.03	13.359±0.030	13.289	0.049	-0.049

5 rows × 354 columns

Manual query

Sometimes, a more complex or advance query is needed.

This package provides two functions to help performing this task:

build_query: Assist in the elaboration of a query string.
execute_query: Performs the given query to the specified database.

It is important to know that these queries must follow the each database column-name structure.

For example, if we want to query all systems with semimajor-axis lower than \(0.01\,au\) of the EU database, we first create the query with:

[6]:

my_query = rquery.build_query("eu", conditions="semi_major_axis < 0.01")
my_query

[6]:

'SELECT * FROM exoplanet.epn_core WHERE semi_major_axis < 0.01'

And the, we execute it with:

[7]:

result = rquery.execute_query("eu", my_query)
result

Executing the query...
Query executed successfully.

[7]:

	granule_uid	granule_gid	obs_id	dataproduct_type	target_name	target_class	time_min	time_max	time_sampling_step_min	time_sampling_step_max	...	star_metallicity	star_mass	star_radius	star_age	star_teff	magnetic_field	detected_disc	ra	dec	external_link
0	2S 0918-549 b	exoplanet_catalog	9455	ci	2S 0918-549 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	NaN	NaN	NaN	False		140.110341	-55.206809	http://exoplanet.eu/catalog/2s_0918_549_b--9455
1	4FGL J1408.6-2917 b	exoplanet_catalog	9100	ci	4FGL J1408.6-2917 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	NaN	NaN	NaN	False		211.851208	-29.806389	http://exoplanet.eu/catalog/4fgl_j1408.6_2917_...
2	4U 0513-40 b	exoplanet_catalog	9741	ci	4U 0513-40 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	NaN	NaN	NaN	False		78.527458	-40.043611	http://exoplanet.eu/catalog/4u_0513_40_b--9741
3	4U 0614+09 b	exoplanet_catalog	9739	ci	4U 0614+09 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	NaN	NaN	NaN	False		94.280652	9.137088	http://exoplanet.eu/catalog/4u_0614_09_b--9739
4	4U 1543-62 b	exoplanet_catalog	9077	ci	4U 1543-62 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	NaN	NaN	NaN	False		236.977500	-62.568333	http://exoplanet.eu/catalog/4u_1543_62_b--9077
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
134	XTE J0929-314 b	exoplanet_catalog	9076	ci	XTE J0929-314 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	0.00002	NaN	NaN	False		142.334125	-31.384222	http://exoplanet.eu/catalog/xte_j0929_314_b--9076
135	ZTF J0038+2030 b	exoplanet_catalog	7860	ci	ZTF J0038+2030 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	0.505	0.01429	8.0	10900.0	False		9.729167	20.507222	http://exoplanet.eu/catalog/ztf_j0038_2030_b--...
136	ZTF J1230-2655 b	exoplanet_catalog	10892	ci	ZTF J1230-2655 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	0.650	0.01230	NaN	10000.0	False		187.569125	-26.930928	http://exoplanet.eu/catalog/ztf_j1230_2655_b--...
137	ZTF J1406+1222 Ab	exoplanet_catalog	9281	ci	ZTF J1406+1222 Ab	exoplanet	NaN	NaN	NaN	NaN	...	NaN	1.400	0.00002	NaN	NaN	False		211.734058	12.378722	http://exoplanet.eu/catalog/ztf_j1406_1222_ab-...
138	ZTF J1828+2308 b	exoplanet_catalog	10893	ci	ZTF J1828+2308 b	exoplanet	NaN	NaN	NaN	NaN	...	NaN	0.610	0.01310	NaN	15900.0	False		277.203208	23.143997	http://exoplanet.eu/catalog/ztf_j1828_2308_b--...

139 rows × 136 columns

The result is given as a raw pandas DataFrame.