Curating¶

Sometimes, you might have good reason to want to replace some of the values in a Population with better ones. Maybe you prefer one reference over another, maybe you have some unpublished measurements you want to include, or maybe you just want to experiment with changing some values. This page mostly discusses curating the data inside an Exoplanet population, but some of the methods might generally apply to other populations.

In [1]:

import exoatlas as ea

ea.version()

import exoatlas as ea ea.version()

Out[1]:

'0.7.0'

Changes are Temporary¶

Please note, the changes made with update_reference or update_values will take place only within the current Python session. The underlying standardized data file is unchanged. The bottom of this page shows instructions for saving and loading a curated population.

Using Different References in an Exoplanet Population¶

The main data in the Exoplanets population come from the NASA Exoplanet Archive Planetary Systems Composite Parameters table. There is one entry in this population for each planet in the archive.

In [2]:

e = ea.Exoplanets()
e

e = ea.Exoplanets() e

Out[2]:

✨ Exoplanets | 5926 elements ✨

If we want to see all individual references for each planet, which is a much larger table containing many more rows than there are planets, we'll need to load a .individual_references population. It might take a while.

In [3]:

e.load_individual_references()

e.load_individual_references()

(loading individual references may take up to a few minutes)

Out[3]:

✨ Individual References | 38509 elements ✨

Once that's loaded, there's a secret sneaky internal population that we can access through the .individual_references attribute, containing every reference for every planet in the archive.

In [4]:

e.individual_references

e.individual_references

Out[4]:

✨ Individual References | 38509 elements ✨

Now, let's say we want to update what reference is being used to provide the period (and related) values for a particular planet. First, we can check what the options are with .display_individual_references.

In [5]:

e.display_individual_references(planets="HD189733b", keys="period")

e.display_individual_references(planets="HD189733b", keys="period")

Out[5]:

QTable length=22

is_being_used	name	period_reference	period	period_uncertainty_lower	period_uncertainty_upper	period_lower_limit	period_upper_limit
			d	d	d
str2	str29	str44	float64	float64	float64	float64	float64
🗺️	HD 189733 b	Stassun et al. 2017	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Morello et al. 2014	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Di Gloria et al. 2015	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Baluev et al. 2015	2.2185752	-7.7e-08	7.7e-08	nan	nan
🏷️	HD 189733 b	Kokori et al. 2023	2.218574944	-3e-08	3e-08	nan	nan
🏷️	HD 189733 b	Ivshina + Winn 2022	2.218575143	-6.3e-08	6.3e-08	nan	nan
🏷️	HD 189733 b	Southworth 2010	2.21857578	-8e-07	8e-07	nan	nan
🏷️	HD 189733 b	Cegla et al. 2016	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Torres et al. 2008	nan	nan	nan	nan	nan
...	...	...	...	...	...	...	...
🏷️	HD 189733 b	Bouchy et al. 2005	2.219	-0.0005	0.0005	nan	nan
🏷️	HD 189733 b	Bonomo et al. 2017	2.2185752	-7.7e-08	7.7e-08	nan	nan
🏷️	HD 189733 b	Sing et al. 2016	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Paredes et al. 2021	2.218	-0.0009	0.001	nan	nan
🏷️	HD 189733 b	Boyajian et al. 2015	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Stassun et al. 2017	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Agol et al. 2010	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Barstow et al. 2017	nan	nan	nan	nan	nan
🏷️	HD 189733 b	ExoFOP-TESS TOI	2.21857480391	-1.7654e-07	1.7654e-07	nan	nan

Then, we can update the population to use one of those options instead of the default.

In [6]:

e.update_reference(planets="HD189733b", references="Ivshina + Winn 2022")

e.update_reference(planets="HD189733b", references="Ivshina + Winn 2022")

Finally, we can confirm that our change took effect, by checking the references again.

In [7]:

e.display_individual_references(planets="HD189733b", keys="period")

e.display_individual_references(planets="HD189733b", keys="period")

Out[7]:

QTable length=22

is_being_used	name	period_reference	period	period_uncertainty_lower	period_uncertainty_upper	period_lower_limit	period_upper_limit
			d	d	d
str2	str29	str44	float64	float64	float64	float64	float64
🗺️	HD 189733 b	Ivshina + Winn 2022	2.218575143	-6.3e-08	6.3e-08	nan	nan
🏷️	HD 189733 b	Morello et al. 2014	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Di Gloria et al. 2015	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Baluev et al. 2015	2.2185752	-7.7e-08	7.7e-08	nan	nan
🏷️	HD 189733 b	Kokori et al. 2023	2.218574944	-3e-08	3e-08	nan	nan
🏷️	HD 189733 b	Ivshina + Winn 2022	2.218575143	-6.3e-08	6.3e-08	nan	nan
🏷️	HD 189733 b	Southworth 2010	2.21857578	-8e-07	8e-07	nan	nan
🏷️	HD 189733 b	Cegla et al. 2016	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Torres et al. 2008	nan	nan	nan	nan	nan
...	...	...	...	...	...	...	...
🏷️	HD 189733 b	Bouchy et al. 2005	2.219	-0.0005	0.0005	nan	nan
🏷️	HD 189733 b	Bonomo et al. 2017	2.2185752	-7.7e-08	7.7e-08	nan	nan
🏷️	HD 189733 b	Sing et al. 2016	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Paredes et al. 2021	2.218	-0.0009	0.001	nan	nan
🏷️	HD 189733 b	Boyajian et al. 2015	nan	nan	nan	nan	nan
🏷️	HD 189733 b	Stassun et al. 2017	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Agol et al. 2010	2.21857567	-1.5e-07	1.5e-07	nan	nan
🏷️	HD 189733 b	Barstow et al. 2017	nan	nan	nan	nan	nan
🏷️	HD 189733 b	ExoFOP-TESS TOI	2.21857480391	-1.7654e-07	1.7654e-07	nan	nan

Updating Values in an Exoplanet Population¶

If we have some custom values we'd like to apply to a planet, we can update its data with the .update_value wrapper.

In [8]:

import astropy.units as u

e.update_values(
    planets="HD189733b", radius=1 * u.R_jupiter, radius_uncertainty=0.1 * u.R_jupiter
)

import astropy.units as u e.update_values( planets="HD189733b", radius=1 * u.R_jupiter, radius_uncertainty=0.1 * u.R_jupiter )

['hd189733b'] | radius: 12.66617 earthRad > 1.0 jupiterRad
['hd189733b'] | radius_uncertainty_lower: -0.11209 earthRad > -0.1 jupiterRad
['hd189733b'] | radius_uncertainty_upper: 0.11209 earthRad > 0.1 jupiterRad

In [9]:

e["HD189733"].radius()

e["HD189733"].radius()

Out[9]:

$[11.208981] \; \mathrm{R_{\oplus}}$

Curating Your Own Exoplanet Population¶

You might want to be able to regularly curate many changes to the default exoplanet parameters from the NASA Exoplanet Archive, and also be able to reapply those changes even when downloading newly updated archive data. In general, that might look like the following:

• Write a function called something like curate_population(), that makes the changes you want by serialling combining .update_reference and .update_values. You might consider saving this function in a local module and importing it whenever you need it.
• Generate an Exoplanets population (or some subset of it), and apply your function to it. This function will change the population in-place; if you want to access the unmodified parameters, you'll need to create a new population.
• If you want to save and reuse your curation, use the population_to_save.save(filename) method to save your curated population out to a local file and loaded_population = Population(filename) to load it back in.

In [10]:

import exoatlas as ea

import exoatlas as ea

In [11]:

def curate_population(x):
    """
    Curate the values in an exoplanet population by
    making small changes to the values being used.

    Parameters
    ----------
    x : exoatlas.populations.Exoplanets
        An exoplanet population that needs to be curated.

    Returns
    -------
    Nothing, but the population `x` has been modified
    in place with updated values and/or reference choices.
    """

    # (down)load the individual references
    x.load_individual_references()

    # update the reference for a planet's period/epoch
    x.update_reference(planets="HD189733b", references="Ivshina + Winn 2022")

    # update another value
    x.update_values(
        planets="HD189733b",
        radius=1 * u.R_jupiter,
        radius_uncertainty=0.1 * u.R_jupiter,
    )

def curate_population(x): """ Curate the values in an exoplanet population by making small changes to the values being used. Parameters ---------- x : exoatlas.populations.Exoplanets An exoplanet population that needs to be curated. Returns ------- Nothing, but the population `x` has been modified in place with updated values and/or reference choices. """ # (down)load the individual references x.load_individual_references() # update the reference for a planet's period/epoch x.update_reference(planets="HD189733b", references="Ivshina + Winn 2022") # update another value x.update_values( planets="HD189733b", radius=1 * u.R_jupiter, radius_uncertainty=0.1 * u.R_jupiter, )

In [12]:

e = ea.TransitingExoplanets()
e = e[e.distance() < 50 * u.pc]
curate_population(e)

e = ea.TransitingExoplanets() e = e[e.distance() < 50 * u.pc] curate_population(e)

(loading individual references may take up to a few minutes)

['hd189733b'] | radius: 12.66617 earthRad > 1.0 jupiterRad
['hd189733b'] | radius_uncertainty_lower: -0.11209 earthRad > -0.1 jupiterRad
['hd189733b'] | radius_uncertainty_upper: 0.11209 earthRad > 0.1 jupiterRad

In [13]:

e.save("curated-population.ecsv")

e.save("curated-population.ecsv")

        Saved ✨ Transiting Exoplanets | 229 elements ✨ to curated-population.ecsv.
        It can be reloaded with `x = Population('curated-population.ecsv')`
        

In [14]:

curated_and_saved = ea.Population("curated-population.ecsv")
curated_and_saved["HD189733"].radius()

curated_and_saved = ea.Population("curated-population.ecsv") curated_and_saved["HD189733"].radius()

Out[14]:

$[11.208981] \; \mathrm{R_{\oplus}}$

🔔 Problems: 🔔¶

Please note there are still a couple of problems that need solving:

• A curated population that has been saved out to a file and then reloaded via Population(filename) will (currently) always load in as a Population object. It therefore won't have any of the special powers of the speciality predefined populations like Exoplanets.
• Sometimes (?) trying to due curation with update_reference gobbles up bonkers memory, presumably something to do with trying to index large tables many times. This might potentially be solvable with some more careful memory management or index-resetting? Curating mostly works, but sometimes it feels like there's a monster lurking underneath.

If any of these problems are catastrophic for you, please open an issue and we'll try to fix it!*

Now that you are confident your population is carefully curated, you can zoom along to play with Filtering, Visualizing, or Observing!