mr-plotter is a user-friendly tool designed to produce paper-quality mass–radius diagrams based on a broad selection of state-of-the-art models of planetary interiors and atmospheres.
It allows you to contextualize new planets, infer their possible internal structures, and explore population-level correlations through flexible color-coding based on planetary and stellar properties available in different catalogs.
If your favorite model is not yet implemented, if you encounter any usage issues, or if you have suggestions for improvement, feel free to contact me. The code is open to contributors 🙂. For interactive mass–radius diagrams with sliders, check out MARDIGRAS.
Simply clone or download the repository to your local machine. Most dependencies are widely used, but if any are missing, you can install them by navigating to the project directory and running:
pip install -r requirements.txtIf you encounter any installation issues, please open an issue here.
Create a configuration file named my_config_file.ini inside the config folder, and run:
python mr-plotter.py my_config_file.iniThe configuration file should contain all the information required to generate the plot, which will be saved in the output folder. All available parameters (both mandatory and optional) are described in the Configuration file section.
Since September 2024 (v1+), mr-plotter can also be used from a Jupyter Notebook (mr-plotter.ipynb). As in the terminal workflow, simply select a configuration file (config_file) and run all cells.
If so, don’t worry about the large number of available parameters. In most cases, you will only need a few. To get familiar with the main options and gain a first hands-on experience with mr-plotter, we encourage you to check the Usage examples section, which illustrates the package workflow in several key scenarios. All example configuration files can be found in the config folder. Enjoy 🙂.
In this example, we contextualize the planet TOI-244 b using data from the NEA catalog. We also include several theoretical mass–radius models for rocky planets, water worlds, and gas dwarfs from Zeng et al. (2019).
python mr-plotter.py example1_toi244.iniWe can also contextualize multiple planets within the same diagram. In the following example, a faint appearance is used to better highlight the planets HD 21520 b, TOI-469 b, TOI-469 d, and LHS 1140 c. In this case, we use the Exoplanet.eu catalog and include planet names in the legend to avoid excessively overloading the figure.
python mr-plotter.py example1_misc.ini
Example 2: Colouring my worlds and including steam water atmospheres
We now include a color code based on the stellar host metallicity. We also include three theoretical mass–radius models derived from the equations of Turbet et al. (2020). These models consider a steam water atmosphere over a rocky composition. As shown, a small amount of steam (0.3–5% in mass) forming an extended hydrosphere can naturally explain the composition of the emerging population of low-density super-Earths. These models are valid up to a 5% water mass fraction (WMF). Above this value, the models from Aguichine et al. (2021) are more appropriate, as they cover a validity range between 10% and 100% core mass fraction (CMF) and WMF. We also include models from Aguichine et al. (2021): 30% CMF & 10% WMF (400 K), and 30% CMF & 20% WMF (400 K).
python mr-plotter.py example2_met.iniWe then run the same example using a color code based on the received stellar insolation flux. In both cases, we customize the planet marker sizes using the size_catalog_planets parameter, and control the color scale limits via the color_min and color_max parameters.
python mr-plotter.py example2_insol.ini
Wait! do you see what I’m seeing? Low-density super-Earths appear to be hosted by metal-poor stars and tend to receive relatively low insolation fluxes! If you are interested in this result, see Sect. 5.3 of this work.
Early interior models traditionally focused on end-member compositions (e.g. Earth-like, 50% water). However, it is now known that planetary radii are also sensitive to secondary parameters, such as equilibrium temperature, system age, and host star properties. In recent years, interior structure models have increasingly been used to precisely infer ranges of bulk compositions, in part thanks to tools such as smint. This has led to the publication of planetary radii in the form of large multidimensional grids spanning wide regions of parameter space, with intermediate values obtained via interpolation. In this example, we illustrate two such evolutionary models.
First, an interior model adapted to steam worlds from Aguichine et al. (2025):
python mr-plotter.py example3_evolmodels_aguichine.iniSecond, an interior model adapted to gas dwarfs from Tang et al. (2025):
python mr-plotter.py example3_evolmodels_aguichine_tang.ini
These models provide grids of radii as functions of planet mass, composition, equilibrium temperature, age, and host star properties (spectral type and envelope metallicity). Thanks to interpolation, mass–radius relations can be generated for any value, and not only for the discrete grid points. The interpolation scheme implemented here follows that of MARDIGRAS. While extrapolation is technically possible, it is not recommended. A full list of input parameters and their respective validity ranges can be found in the [MODELS] section.
As an illustrative case, the planet TOI-270 d has measured properties (mass, radius, equilibrium temperature, but unknown age) that are compatible with a 50% steam envelope, a 0.5% H₂-He envelope at 1×Solar metallicity, or any intermediate configuration. Its transmission spectrum was recently obtained with JWST (Benneke et al. 2024), revealing a high-metallicity atmosphere (~50%).
mr-plotter can also generate two-column figures. In this example, we contextualize the dense super-Earth K2-229 b by including several interior structure models and reference curves.
Specifically, we show:
- a set of isodensity curves
- the maximum mantle collisional stripping model from Marcus et al. (2010)
- the BICEPS model from Haldemann et al. (2024) for different pure-iron compositions (C0 and C1)
- the pioneering mass–radius relations for pure-rock and pure-water compositions from Seager et al. (2007)
python mr-plotter.py example4.ini
In this example, we illustrate how mr-plotter can be used to visualize empirical mass–radius relations for small, intermediate, and giant planets, together with observational prioritization metrics such as the Transmission and Emission Spectroscopy Metrics (TSM and ESM). We include the empirical relations derived by Parc et al. (2024). The planetary sample is taken from the PlanetS catalog (Otegi et al. 2020; Parc et al. 2024), which also served as the basis for deriving these relations.
python mr-plotter.py example5_TSM.iniThe same visualization can be produced using the ESM. The transition between small and intermediate planets is marked by the 20% water composition line at 650 K from Luo et al. (2024), while the boundary between intermediate and giant planets is defined by the 138 M⊕ iso-mass line, following Parc et al. (2024).
python mr-plotter.py example5_ESM.ini
Some parameters, such as discovery year, discovery facility, or discovery technique, are naturally categorical rather than numerical. Since v1+, mr-plotter allows these quantities to be used for group-based color coding. In this example, we first generate a mass–radius diagram of small planets, color-coded by discovery year:
python mr-plotter.py example6_year.iniThis representation highlights the rapid pace of recent exoplanet discoveries. We then produce the same diagram by distinguishing between the three main space-based planet-hunting missions: Kepler, K2, and TESS:
python mr-plotter.py example6_facility.iniThis visualization clearly illustrates the remarkable legacy of TESS, driven by its continuous monitoring of the bright sky. It also demonstrates how to generate dark, poster-ready and presentation-ready mass–radius diagrams suitable for conferences and outreach.
Finally, this example shows how to contextualize an individual planet (in this case L 98-59 d) using:
- a custom color not present in the original color map (left panel), and
- a color assigned according to a non-numerical category (right panel; L 98-59 d was discovered by TESS)
| 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 can be used to color mr-plots can be found here.
2 For non-numerical color codes (e.g. disc_facility), the groups to display and their associated colors must be defined (see how here).
The package can access catalog data locally from different folders inside catalog_data. Although we try to keep these catalogs up to date, we recommend downloading the most recent versions from the original sources:
- NEA Planetary Systems (.csv format)
- Exoplanet.eu catalog (.csv format)
- PlanetS catalog (VOTable format)
NEA data can also be accessed via the TAP protocol (see how).
Note: When selecting the NEA option, the Planetary Systems catalog is used by default. Alternatively, the
Planetary Systems Composite Data catalog can also be selected (see how).
This section allows you to manually include one or more planets that are not present in the selected catalog, or to highlight specific objects of interest.
| Parameter | Possible values | Description |
|---|---|---|
| m_p1 | Any ( |
Mass of planet 1 |
| m_p1_err_up | Any ( |
Upper uncertainty on the mass of planet 1 |
| m_p1_err_down | Any ( |
Lower uncertainty on the mass of planet 1 |
| r_p1 | Any ( |
Radius of planet 1 |
| r_p1_err_up | Any ( |
Upper uncertainty on the radius of planet 1 |
| r_p1_err_down | Any ( |
Lower uncertainty on the radius of planet 1 |
| c_p11 | Any color or value | Color or value associated with planet 1 |
| name_p1 | Any string | Name of planet 1 (e.g. TOI-244 b) |
| dis_x_p12 | Any ( |
Horizontal offset of the planet label (X-axis) |
| dis_y_p12 | Any ( |
Vertical offset of the planet label (Y-axis) |
| ... | ... | Additional planets can be added following the same naming pattern |
1 If color_coding = none, provide a valid color name (e.g. blue). If color_coding = st_met, pl_insol, etc., provide the corresponding numerical value for the planet so it can be color-coded consistently with catalog planets. 2 If not specified, the planet name(s) will be displayed in the legend instead of directly on the plot.
In this section, we list all theoretical and empirical models implemented in mr-plotter and show how to include them in your plots. Some models are activated using a single option, while others require a combination of parameters (e.g. composition, temperature). Below, we illustrate both cases using the models from Zeng et al. (2016, 2019) as an example of single-option models, and Aguichine et al. (2021) as an example of multi-parameter models. For all other models, detailed tables listing the available options, allowed 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 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
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
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
Aguichine et al. (2025). Evolutionary models for steam worlds with Earth-like interiors | Usage | Example
Tang et al. (2025). Evolutionary models for gas-rich planets with Earth-like cores. | Usage | Example
mr-plotter is designed with a graphical setup that produces paper-quality figures out of the box. However, you may want to customize specific aspects of the plot, such as X- and Y-axis limits, marker sizes, color maps, or other stylistic options. All these customizations can be handled through [OPTIONAL_CONFIG]. A complete list of available parameters is provided in this table, many of which are illustrated in the Usage examples section.
mr-plotter has been developed by Amadeo Castro-González, with contributions from Artem Aguichine, Katharine Hesse, Jorge Lillo-Box, and Léna Parc. A summary of the main updates can be found in the changelog.
If you use mr-plotter, please give credit to this work:
@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},
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}
}Please also include the following sentence in the acknowledgements section of your paper:
This work made use of \texttt{mr-plotter} (available at \url{https://github.com/castro-gzlz/mr-plotter}).
In addition, please give appropriate credit to the exoplanet catalog(s) used:
- NASA Exoplanet Archive (Christiansen et al. 2025),
- Exoplanet.eu (Schneider et al. 2011),
- PlanetS (Otegi et al. 2020; Parc et al. 2024).
Finally, please cite the relevant interior and evolutionary models used in your analysis. Direct links to the ADS entries of all implemented models are provided in Section [MODELS].