Mister plotter (mr-plotter) is a user-friendly Python tool developed to create paper-quality mass-radius diagrams based on a wide range of state-of-the-art models of planetary interiors and atmospheres.
It can be used to contextualize your favorite planets and infer their possible internal structures. It can also be used to search for correlations at a population level thanks to its color-coding option based on any property collected in the NASA Exoplanet Archive, PlanetS, and Exoplanet.eu catalogs.
If your favorite model is not yet included in mr-plotter, you have any usage problems, or you came up with an improvement, don't hesitate to contact me at acastro@cab.inta-csic.es. Mister plotter is open to contributors 😃
For an interactive manipulation of mass-radius diagrams with sliders check out MARDIGRAS!
Just clone or download this folder on your computer. All the dependencies are widely used, so you probably already have them installed. However, if this is not the case, you can just enter the folder via the terminal and type
pip install -r requirements.txt
If you have any problems with the installation, you can drop an issue here.
You just need to create a configuration file my_config_file.ini inside the config folder and then type
python mr-plotter.py my_config_file.ini
The file my_config_file.ini should contain all the necessary information to make your plot, which will be saved into the output folder. In the Configuration file section we describe all the parameters (mandatory and optional) that can be used in the configuration files.
Since September 2024 (v1+), mr-plotter can also be used via Jupyter notebook (mr-plotter.ipynb). Similarly to the terminal version, you just need to select a configuration file (config_file) and run all cells.
If so, please don't be overwhelmed by the large number of parameters. In most cases you will only use a few! To get familiarized with the main options and have a first contact with mr-plotter, we invite you to take a look at the Usage examples section, which illustrates the operation of the package in different key scenarios. You can find all the example configuration files inside the config folder. Enjoy 😃.
In this example, we contextualize a new planet (TOI-244 b; Castro-González et al. 2023) in the NEA catalog and include several theoretical models for rocky planets, water worlds, and gas dwarfs from Zeng et al. (2019).
python mr-plotter.py example1_toi244.ini
We can also contextualize different planets in the same plot. In this example, we use a faint appearance to better see the planets HD 21520 b (Nies et al. 2024), TOI-469 b&d (Damasso et al. 2023; Egger et al. 2024), and LHS 1140 c (Lillo-Box et al. 2020; Cardieux et al. 2024). In this case, we have used the Exoplanet.eu catalog and included the planet names in the legend to avoid excessively overloading the figure.
python mr-plotter.py example1_misc.ini
Example 2: Colourig my worlds and including steam water atmospheres
We now include a color code according to the stellar host metallicity. We also include three models based on Turbet et al. (2020) equations. These models consider a steam water atmosphere over a rocky composition. As we can see, a small amount of steam water (0.3%-5% in mass) forming an extensive hydrosphere can explain very well the composition of the emerging group of low-density super-Earths. These models are valid up to a 5% water mass fraction (WMF). Above this value, you might want to use the models from Aguichine et al. (2021), which have a validity range between 10% and 100% core mass fractions (CMF) and WMF. In this example, we also include two models from Aguichine et al. (2021): 30% CMF & 10 WMF (400K), and 30% CMF & 20% WMF (400K).
python mr-plotter.py example2_met.ini
We now run the same example by including a color code based on the received stellar insolation flux. We note that in both examples we customized the size of the planets through the size_catalog_planets keyword and the maximum and minimum values of the color map through the color_min and color_max keywords.
python mr-plotter.py example2_insol.ini
Wait! Do you see what I'm seeing? All low-density super-Earths are hosted by metal-poor stars and tend to receive relatively low insolation fluxes! If you are interested in this result I invite you to look at Sect. 5.3 of An unusually low-density super-Earth transiting the bright early-type M-dwarf GJ 1018 (TOI-244).
Example 3: The PlanetS catalog, empirical relations, and color coding based on homogeneous Transmission and Emission Spectroscopy metrics (TSM and ESM)
In this example, we use the PlanetS catalog (Otegi et al. 2020; Parc et al. 2024). This catalog contains published planets characterized robustly and accurately (relative error in mass < 25% and relative error in radius < 8%). It collects many parameters from the NEA, stellar parameters from Gaia DR3, and also includes homogeneous calculations of
python mr-plotter.py example3_TSM.ini
Of course, we can do the same for the ESM! In this case, we use the updated empirical relationships for small, intermediate, and giant planets derived by Parc et al. (2024).
python mr-plotter.py example3_ESM.ini
There are several parameters such as the discovery year, facility, or technique, that you might want to separate by groups. This is now possible to implement in mr-plotter (v1+). In this example, we first build the mass-radius diagram of small planets colored according to their discovery year.
python mr-plotter.py example4_year.ini
It's amazing to see the exciting era we live in, right?! We can also make the same plot by differentiating between the three main space-based planet-hunting missions: Kepler, K2, and TESS.
python mr-plotter.py example4_facility.ini
This plot evidences the invaluable legacy that TESS is providing thanks to its incessant monitoring of the bright sky. This example also shows how to make dark poster-ready and presentation-ready diagrams for conferences!
In this example, we can also see how to contextualize a planet (in this case L 98-59 d; Demangeon et al. 2021) with a new color not included in the color map (left panel), and a color following the non-numerical color code (right panel; L 98-59 d was discovered by TESS).
mr-plotter can also produce paper-ready two-column plots. In this example, we contextualize the dense super-Earth K2-229 b (Santerne et al. 2018) by including the maximum mantle collisional stripping model by Marcus et al. (2010), the BICEPS model (Haldemann et al. 2024) for different pure-iron compositions (C0 and C1 compositions), and some isodensity curves. We also show how to implement the pioneer M-R relations for pure-rock and pure-water compositions from Seager et al. (2007). The procedure to include any other model from the literature is very similar to that shown in this and previous examples. In Section [MODELS] you can find the complete set of models implemented in mr-plotter.
python mr-plotter.py example5.ini
[CATALOG_DATA] | Include data from the NASA Exoplanet Archive, Exoplanet.eu, or PlanetS catalogs.
| Parameter | Possible values | Description |
|---|---|---|
| catalog | NEA, Exoplanet.eu, or PlanetS | Exoplanet catalog to visualize |
| precision_mass | From 0 to 100 (%) | Minimum precision in mass |
| precision_radius | From 0 to 100 (%) | Minimum precision in radius |
| color_coding | none, st_met, pl_insol, st_teff, sy_kmag, etc1,2 | Color coding of the plot |
1 The full list of parameters that you can use to color your mr-plots can be found here.
2 If a non-numerical color code is chosen (e.g. disc_year, disc_facility, etc), the grups to display and their colors have to be defined (see how here).
The package can access the catalog data locally from different folders inside catalog_data. We try to maintain the catalogs updated, but we recommend downloading the most recent ones from:
NEA Planetary Systems (in .csv format)
Exoplanet.eu catalog (in .csv format)
PlanetS catalog (in VOTable format)
The NEA data can be also accessed through a TAP protocol (see how). We note that when selecting the NEA option, the Planetary Systems catlog will be considered by default. However, it is also possible to use the Planetary Systems Composite Data catalog (see how).
| Option | Possible values | Description |
|---|---|---|
| m_p1 | Any ( |
Mass of your planet 1 |
| m_p1_err_up | Any ( |
Upper uncertainty on the mass of your planet 1 |
| m_p1_err_down | Any ( |
Lower uncertainty on the mass of your planet 1 |
| r_p1 | Any ( |
Radius of your planet 1 |
| r_p1_err_up | Any ( |
Upper uncertainty on the radius of your planet 1 |
| r_p1_err_down | Any ( |
Lower uncertainty on the radius of your planet 1 |
| c_p11 | Any color/value | Color of your planet 1 |
| name_p1 | Any name | Name of your planet 1 (e.g. TOI-244 b) |
| dis_x_p12 | Any ( |
Location of a text box in terms of distance from the planet (X-axis) |
| dis_y_p12 | Any ( |
Location of a text box in terms of distance from the planet (Y-axis) |
| .... | .... | .... |
1 If color_coding = none, type a color (e.g. blue). If color_coding = st_met, pl_insol,...etc, type the corresponding value for your planet so it can be color-coded as the rest of the catalog planets.
2 If not defined, the name of the planet(s) will be included in the legend of the plot.
In this section, we list the complete set of models implemented in mr-plotter. Their inclusion into your mr-plots is really easy! You just need to select as many Possible values as models you want to visualize separated by commas, as in these examples: Example1, Example2, etc. In some cases, a model is simply defined by one Option, and in others it is defined by a combination of a few Options. In the following, we show an example of both kinds of operation: the models from Zeng et al. 2016,2019 (single option) and Aguichine et al. 2021 (several options). For the remaining models, their corresponding tables with the Options, Possible values, and Descriptions can be accessed through the corresponding hyperlinks.
Zeng et al. (2016) and Zeng et al. (2019). Rocky planets, water worlds, and gas dwarfs | Example
| Option | Possible values | Description |
|---|---|---|
| models_zeng | zeng_2019_earth_like, zeng_2019_pure_rock, etc1 | Models from Zeng et al. (2016, 2019) |
1 In this table we include all the Possible values corresponding to the Zeng et al. (2016, 2019) models.
Aguichine et al. (2021). Rocky planets with extensive atmospheres of steam and supercritical water | Example
| Option | Possible values | Description |
|---|---|---|
| x_core_aguich2021 | From 0.0 to 0.9 in steps of 0.1 | Core mass fraction |
| x_H2O_aguich2021 | From 0.1 to 1.0 in steps of 0.1 | Water mass fraction of the hydrosphere |
| Tirr_aguich2021 | From 400 (K) to 1300 (K) in steps of 100 (K) | Equilibrium temperature of your planet |
| colors_aguich2021 | Any color | Colors of each model |
Seager et al. (2007). 100% iron, 100% silicates, and 100% condensed water models | Usage | Example
Marcus et al. (2010). Maximum collisional stripping of planetary mantles | Usage | Example
Lopez & Fortney et al. (2014). Rocky planets with H2/He atmospheres | Usage | Example
Dorn et al. (2015). TBD.
Otegi et al. (2020). Empirical mass-radius relationships based on the PlanetS catalog | Usage | Example
Turbet et al. (2020). Rocky planets with atmospheres of steam and supercritical water | Usage | Example
Haldemann et al. (2024). Iron core + silicate mantle + volatile-rich envelope | Usage | Example
Luo et al. (2024). TBD.
Parc et al. (2024). Revised empirical mass-radius relationships based on the PlanetS catalog | Usage | Example
Isodensity curves. Mass-radius relations corresponding to a constant density | Usage | Example
mr-plotter has been designed to have a default graphic configuration able to generate paper-quality plots. However, there are some particular aspects such as the X- and Y-axis limits, size of the data points, color map, etc, that you might want to modify at your ease. This is also possible with [OPTIONAL_CONFIG]! Check out all the available options in this table (most of them were used in the Usage examples section).
Mister plotter has been developed by Amadeo Castro-González with relevant contributions from Jorge Lillo-Box, Artem Aguichine, Léna Parc, and Katharine Hesse. Check out the changelog with the major updates!
If you use mr-plotter, please give credit to the work where we present it:
@ARTICLE{2023A&A...675A..52C,
author = {{Castro-Gonz{\'a}lez}, A. and {Demangeon}, O.~D.~S. and {Lillo-Box}, J. and {Lovis}, C. and {Lavie}, B. and {Adibekyan}, V. and {Acu{\~n}a}, L. and {Deleuil}, M. and {Aguichine}, A. and {Zapatero Osorio}, M.~R. and {Tabernero}, H.~M. and {Davoult}, J. and {Alibert}, Y. and {Santos}, N. and {Sousa}, S.~G. and {Antoniadis-Karnavas}, A. and {Borsa}, F. and {Winn}, J.~N. and {Allende Prieto}, C. and {Figueira}, P. and {Jenkins}, J.~M. and {Sozzetti}, A. and {Damasso}, M. and {Silva}, A.~M. and {Astudillo-Defru}, N. and {Barros}, S.~C.~C. and {Bonfils}, X. and {Cristiani}, S. and {Di Marcantonio}, P. and {Gonz{\'a}lez Hern{\'a}ndez}, J.~I. and {Curto}, G. Lo and {Martins}, C.~J.~A.~P. and {Nunes}, N.~J. and {Palle}, E. and {Pepe}, F. and {Seager}, S. and {Su{\'a}rez Mascare{\~n}o}, A.},
title = "{An unusually low-density super-Earth transiting the bright early-type M-dwarf GJ 1018 (TOI-244)}",
journal = {\aap},
keywords = {planets and satellites: individual: TOI-244 b, planets and satellites: detection, planets and satellites: composition, stars: individual: GJ 1018, techniques: radial velocities, techniques: photometric, Astrophysics - Earth and Planetary Astrophysics},
year = 2023,
month = jul,
volume = {675},
eid = {A52},
pages = {A52},
doi = {10.1051/0004-6361/202346550},
archivePrefix = {arXiv},
eprint = {2305.04922},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2023A&A...675A..52C},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
and add the following sentence within the acknowledgements section:
This work made use of \texttt{mr-plotter} (available in \url{https://github.com/castro-gzlz/mr-plotter})
Please also give credit to the catalog(s) used: Nasa Exoplanet Archive (Akeson et al. 2013), Exoplanet.eu (Schneider et al. 2011), and PlanetS (Otegi et al. 2020; Parc et al. 2024), as well as to the interior models: The ADS site of each work can be accessed by clicking on the hyperlinks of Section [MODELS].