Mister plotter (mr-plotter) is a user-friendly Python tool that creates paper-ready mass-radius diagrams with your favorite theoretical models. It also includes the ability to color-code diagrams based on any published stellar or planetary property collected in the NASA Exoplanet Archive.
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 me 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.
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 parameters 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 diferent key scenarios through didactic examples. You can find all the example configuration files inside the config folder. Enjoy 😃.
Section [NEA_DATA] | Include data from the Nasa Exoplanet Archive (NEA)
| Parameter | Possible values | Description |
|---|---|---|
| web_or_local | web or local | Download the data from the Nasa Exoplanet Archive (web) or pick it up from the NEA_data folder (local)1 |
| ps_or_composite | ps or composite | Indicates which table to use: Planetary Systems (ps) or Planetary Systems Composite Data (composite)2 |
| precision_mass | From 0 to 100 (%) | Minimum precision in mass to plot NEA planets |
| precision_radius | From 0 to 100 (%) | Minimum precision in radius to plot NEA planets |
| color_coding | none, st_met, pl_insol, st_teff, sy_kmag, etc3 | Color coding of the plot |
1 If web, it will connect to the NEA through a TAP protocol, which might last a bit (i.e., a couple of minutes). If local, you should have a comma-separated table downloaded from the NEA inside the NEA_data folder. Please don't change the default name of the downloaded tables. If you have several tables, mr-plotter wil automatically select the most recently downloaded.
2 If you want to use the composite data in your research, please read this first.
3 All possible values: none (None), disc_year (Discovery year), pl_orbper (Orbital period in days), pl_orbsmax (Semi-major axis in AU), pl_orbeccen (Eccentricity), pl_insol (Insolation Flux in
| 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_p1 | Any color or any number1 | Color for your planet 1 |
| name_p1 | Any name (e.g. TOI-244 b) | Name of your planet 1 to be plotted inside a box next to the planet location2 |
| dis_x_p1 | Any ( |
Location of the text box in terms of the distance from the planet (X-axis)2 |
| dis_y_p1 | Any ( |
Location of the text box in terms of the distance from the planet (Y-axis)2 |
| .... | .... | .... |
1 If color_coding = none, type a color (e.g. blue). If color_coding = st_met, pl_insol,...etc, just type the corresponding value for your planet so it can be color-coded as the rest of the NEA planets.
2 These options should be only specified if you want to include text boxes next to your planets with their names.
| 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 Zeng et al. (2016, 2019) models for rocky planets, water worlds, and gas dwarfs.
| Option | Possible values | Description |
|---|---|---|
| age_lf2014 | 100Myr, 1Gyr, 10Gyr | Age of the system |
| opacity_lf2014 | solar or enhanced | Opacity of the star |
| Seff_lf2014 | 0.1, 10, 1000 ( |
Insolation received by the planet |
| H_He | 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, and 20 (%) | H/He mass fraction of the planet |
| colors_lf2014 | Any color | Colors of each curve |
Note: To plot several Lopez & Fortney et al. (2014) models you can include as many values as you want, separated by commas, similar to example4.ini.
| Option | Possible values | Description |
|---|---|---|
| M_turb2020 | Any ( |
Mass of your planet |
| R_turb2020 | Any ( |
Radius of your planet |
| Seff_turb2020 | > 1.1 ( |
Insolation flux received by your planet |
| WMFs_turb2020 | From 0 to 0.05 | Water mass fractions (WMFs) of steam water |
| Core_turb2020 | earth, rock, or iron | Internal core composition over which the steam water resides |
| colors_turb2020 | Any color | Colors of each model |
Note: To plot several Turbet et al. (2020) models you can include as many values as you want, separated by commas, similar to example2.ini.
| 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 |
Note: To plot several Aguichine et al. (2021) models you can include as many values as you want, separated by commas, similar to example4.ini.
| Option | Possible values | Description |
|---|---|---|
| models_marcus | marcus_2010_maximum_collision_stripping | Maximum collision stripping model from Marcus et al. (2010) |
| Option | Possible values | Description |
|---|---|---|
| density | Any ( |
Density |
| colors_density | Any color | Colors of each curve |
Note: To plot several curves you can include as many values as you want, separated by commas, similar to example5.ini.
| Option | Possible values | Description |
|---|---|---|
| n_cols | one or two | Make the plot in one-column or two-column. Default: one |
| color_min | Any | Minimum value for the color coding. Default: median of the 5% minimum values |
| color_max | Any | Maximum value for the color coding. Default: median of the 5% maximum values |
| log_x | True or False | Logarithmic scale on the |
| log_y | True of False | Logarithmic scale on the |
| xlim | Any, Any | Limits of the plot on the |
| ylim | Any, Any | Limits of the plot on the |
| size_NEA_planets | Any | Size of NEA planets. Default: 120 |
| size_my_planets | Any | Size of my planets. Default: 200 |
| low_density_superEarths | True or False | Plot the low-density super-Earths region shown in Castro-González et al. (2023). Default: False |
| shade_below_pure_iron | True or False | Include a grey shade below the 100% iron model by Zeng et al. (2019). Default: True |
| loc_legend | best, upper left, center, etc | Location of the legend. Default: lower right |
| cmap | Any matplotlib colormap | Color map for the color-coded diagrams. Default: rainbow |
In this example, we contextualize a new planet (TOI-244 b) in the mass-radius diagram of known planets, and include several theoretical models for rocky planets, water worlds, and gas dwarfs from Zeng et al. (2019).
python mr-plotter.py example1.ini
Example 2: Colourig my worlds and including steam water models
In this example, we include three models computed from Turbet et al. (2020) equations, which consider a steam water atmosphere over a canonical rocky composition. As we can see, a small amount of steam water (0.3%-5% in mass) forming an extense hydrosphere would be enough to explain the composition of the emerging group of low-density super-Earths. Besides, we include a color code according to the stellar host metallicity. Wait! Do you see what I'm seeing? All low-density super-Earths are hosted by metal-poor stars! For more insights on this, take a look at our paper An unusually low-density super-Earth transiting the bright early-type M-dwarf GJ 1018 (TOI-244).
python mr-plotter.py example2.ini
In this example, we plot the iconic system LHS 1140. The color code now indicates the received insolation flux, spanning from 1 to 2 Earth fluxes, which roughly correspond to fluxes received by planets in the habitable zone (HZ) of their stars. LHS 1140 b stands out as one of the only well-characterized HZ planets in the rocky domain. In this plot we have used the summer color map, but any matplotlib color map can be easily selected.
python mr-plotter.py example3.ini
Althogh in the original paper where mr-plotter was presented we have only used the Zeng et al. (2016, 2019) and Turbet et al. (2020) models, we have included additional models from the literature. For example, if you have a puffy sub-Neptune planet, you might want to consider the H/He atmosphere models by Lopez & Fortney (2014). You might also want to discuss the possibility that your (highly irradiated) planet has a water-rich composition, but perhaps it is less dense than the density corresponding to a 5% water mass fraction (WMF), where Turbet et al. (2020) models are no longer valid. In this case, you might want to use Aguichine et al. (2021) mass-radius relationships, which are valid for any WMF. In this example, we use the K2-3 system to illustrate how these two sets of models can be used through mr-plotter.
python mr-plotter.py example4.ini
In this example, we include the model by Marcus et al. (2010) corresponding to the maximum density curve for a planet subjected to mantle stripping. We highlight the earth-sized, mercurian-density planet K2-229 b, which having the size of the Earth and density of Mercury, is located just above that curve. Besides, we illustrate how to include isodensity curves as well as how to prepare paper-ready plots in two-column format.
python mr-plotter.py example5.ini
If your favorite model is not yet included in mr-plotter, you have any issues when using the package, or you think it can be improved in any way, don't hesitate to contact me at acastro@cab.inta-csic.es.
A. Castro-González, J. Lillo-Box, and A. Aguichine.
If you use mr-plotter, please give credit to the following paper:
@ARTICLE{2023arXiv230504922C,
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 {Lo Curto}, G. 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 = {arXiv e-prints},
keywords = {Astrophysics - Earth and Planetary Astrophysics},
year = 2023,
month = may,
eid = {arXiv:2305.04922},
pages = {arXiv:2305.04922},
doi = {10.48550/arXiv.2305.04922},
archivePrefix = {arXiv},
eprint = {2305.04922},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2023arXiv230504922C},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
Please also give credit to the models used:
@ARTICLE{2010ApJ...712L..73M,
author = {{Marcus}, Robert A. and {Sasselov}, Dimitar and {Hernquist}, Lars and {Stewart}, Sarah T.},
title = "{Minimum Radii of Super-Earths: Constraints from Giant Impacts}",
journal = {\apjl},
keywords = {planetary systems, planets and satellites: formation, Astrophysics - Earth and Planetary Astrophysics},
year = 2010,
month = mar,
volume = {712},
number = {1},
pages = {L73-L76},
doi = {10.1088/2041-8205/712/1/L73},
archivePrefix = {arXiv},
eprint = {1003.0451},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2010ApJ...712L..73M},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@ARTICLE{2014ApJ...792....1L,
author = {{Lopez}, Eric D. and {Fortney}, Jonathan J.},
title = "{Understanding the Mass-Radius Relation for Sub-neptunes: Radius as a Proxy for Composition}",
journal = {\apj},
keywords = {planets and satellites: composition, planets and satellites: formation, planets and satellites: interiors, planets and satellites: physical evolution, Astrophysics - Earth and Planetary Astrophysics},
year = 2014,
month = sep,
volume = {792},
number = {1},
eid = {1},
pages = {1},
doi = {10.1088/0004-637X/792/1/1},
archivePrefix = {arXiv},
eprint = {1311.0329},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2014ApJ...792....1L},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@ARTICLE{2016ApJ...819..127Z,
author = {{Zeng}, Li and {Sasselov}, Dimitar D. and {Jacobsen}, Stein B.},
title = "{Mass-Radius Relation for Rocky Planets Based on PREM}",
journal = {\apj},
keywords = {planets and satellites: composition, planets and satellites: general, planets and satellites: interiors, Astrophysics - Earth and Planetary Astrophysics},
year = 2016,
month = mar,
volume = {819},
number = {2},
eid = {127},
pages = {127},
doi = {10.3847/0004-637X/819/2/127},
archivePrefix = {arXiv},
eprint = {1512.08827},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2016ApJ...819..127Z},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@ARTICLE{2019PNAS..116.9723Z,
author = {{Zeng}, Li and {Jacobsen}, Stein B. and {Sasselov}, Dimitar D. and {Petaev}, Michail I. and {Vanderburg}, Andrew and {Lopez-Morales}, Mercedes and {Perez-Mercader}, Juan and {Mattsson}, Thomas R. and {Li}, Gongjie and {Heising}, Matthew Z. and {Bonomo}, Aldo S. and {Damasso}, Mario and {Berger}, Travis A. and {Cao}, Hao and {Levi}, Amit and {Wordsworth}, Robin D.},
title = "{Growth model interpretation of planet size distribution}",
journal = {Proceedings of the National Academy of Science},
keywords = {Astrophysics - Earth and Planetary Astrophysics, Physics - Geophysics},
year = 2019,
month = may,
volume = {116},
number = {20},
pages = {9723-9728},
doi = {10.1073/pnas.1812905116},
archivePrefix = {arXiv},
eprint = {1906.04253},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2019PNAS..116.9723Z},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@ARTICLE{2020A&A...638A..41T,
author = {{Turbet}, Martin and {Bolmont}, Emeline and {Ehrenreich}, David and {Gratier}, Pierre and {Leconte}, J{\'e}r{\'e}my and {Selsis}, Franck and {Hara}, Nathan and {Lovis}, Christophe},
title = "{Revised mass-radius relationships for water-rich rocky planets more irradiated than the runaway greenhouse limit}",
journal = {\aap},
keywords = {planets and satellites: terrestrial planets, planets and satellites: composition, planets and satellites: atmospheres, planets and satellites: individual: TRAPPIST-1, planets and satellites: interiors, methods: numerical, Astrophysics - Earth and Planetary Astrophysics, Physics - Atmospheric and Oceanic Physics, Physics - Geophysics},
year = 2020,
month = jun,
volume = {638},
eid = {A41},
pages = {A41},
doi = {10.1051/0004-6361/201937151},
archivePrefix = {arXiv},
eprint = {1911.08878},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2020A&A...638A..41T},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@ARTICLE{2021ApJ...914...84A,
author = {{Aguichine}, Artyom and {Mousis}, Olivier and {Deleuil}, Magali and {Marcq}, Emmanuel},
title = "{Mass-Radius Relationships for Irradiated Ocean Planets}",
journal = {\apj},
keywords = {Exoplanets, Hydrosphere, Planetary interior, Planetary theory, Exoplanet astronomy, Exoplanet structure, Computational methods, 498, 770, 1248, 1258, 486, 495, 1965, Astrophysics - Earth and Planetary Astrophysics},
year = 2021,
month = jun,
volume = {914},
number = {2},
eid = {84},
pages = {84},
doi = {10.3847/1538-4357/abfa99},
archivePrefix = {arXiv},
eprint = {2105.01102},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2021ApJ...914...84A},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}