Module `resokit.core`

Module with main ResoKit System classes.

class resokit.core.MetaData(data=NOTHING)[source]

Bases: Mapping

Implements an inmutable dict-like to store the metadata.

Also provides attribute like access to the keys.

Example

>>> metadata = MetaData({"a": 12, "b": 2})
>>> metadata.a
12

>>> metadata["a"]
12

class resokit.core.ResokitDataFrame(data, source, metadata=NOTHING)[source]

Bases: object

Initialize a ResoKit DataFrame class.

Parameters:

data (pd.DataFrame or pd.Series) – DataFrame containing the data.
source (str) – Source of the dataset. Either ‘eu’ or ‘nasa’ or ‘binary’ or ‘user’.
metadata (dict) – Metadata of the dataset.

set_column(name: str, value: Any, silent: bool = False) → ResokitDataFrame[source]

Set the value of a column in the associated DataFrame.

Parameters:

name (str) – Name of the column to set. It is created if non existing.
value (Any) – The value to be set at the column. May be any object supported by the setting method df[name] = value of a df DataFrame.
silent (bool, optional. Default: False) – Whether to not print a warning message when setting a column.

Returns:

A copy of the ResokitDataFrame with the column set.

Return type:

ResokitDataFrame

plot(x: str, y: str, error_x: bool = False, error_y: bool = False, ax: Axes | None = None, label: str = '', **plot_kwargs) → Axes[source]

Plot the x vs y data of the ResokitDataFrame.

Parameters:

x (str) – Name of the column to use as x-axis.
y (str) – Name of the column to use as y-axis.
error_x (bool, optional. Default: False.) – Whether to plot the x error bars.
error_y (bool, optional. Default: False.) – Whether to plot the y error bars.
ax (plt.Axes, optional. Default: None.) – Matplotlib Axes to plot on. If None, get and use the current Axes.
label (str, optional. Default: "".) – Label for the data plotted.
plot_kwargs (dict) – Additional keyword arguments for the plt.errorbar() function.

Returns:

ax – Matplotlib axes object with the plot.

Return type:

Matplotlib Axes

to_dict() → dict[source]

Convert metadata to a dictionary.

This method constructs a dictionary with the data inside the metadata attribute.

Returns:: metadata – Dictionary with the metadata.
Return type:: dict

to_dataframe(columns=None, copy=False) → DataFrame[source]

Convert data to pandas data frame.

This method constructs a data frame with the data inside the data attribute.

Parameters:

columns (list, optional. Default: None.) – Specific columns to return. If None, return all columns.
copy (bool, optional. Default: False.) – Whether to return a copy of the DataFrame, or the original.

Returns:

df – Data frame with the requested columns.

Return type:

DataFrame

copy() → ResokitDataFrame[source]

Create and return copy of the ResokitDataFrame.

Returns:: Copy of the ResokitDataFrame.
Return type:: ResokitDataFrame

resokit.core.df_to_resokit(df: DataFrame, source: str, drop: bool = True, copy: bool = False, sort_by: str | bool = True, return_df: bool = False, rename_index: bool = False, metadata: dict | None = None) → ResokitDataFrame | DataFrame[source]

Convert ExoplanetEU or NASA data to ResokitDataFrame.

This function converts a DataFrame from ExoplanetEU or NASA to a ResokitDataFrame. The columns are renamed according to the default mapping, and the DataFrame is sorted by the specified column.

Parameters:

df (pd.DataFrame) – Input dataset.
source (str) – Source of the dataset. Either ‘eu’ or ‘nasa’.
drop (bool, optional. Default: True.) – Whether to drop columns not in the mapping.
copy (bool, optional. Default: False.) – Whether to edit a copy of the DataFrame, instead of the original. Despite this, the output will be a ResokitDataFrame, unless return_df=True.
sort_by (str, bool, optional. Default: True.) – Column to sort the data by. If False or None, do not sort the data. If True, sort by period (“P”).
return_df (bool, optional. Default: False.) – Whether to return the a pandas Data frame instead of the ResokitDataFrame.
rename_index (bool, optional. Default: True.) – Whether to rename the index column to “name” of the object/body.
metadata (dict, optional. Default: None.) – Metadata to be added to the ResokitDataFrame.

Returns:

DataFrame in ResokitDataFrame format.

Return type:

ResokitDataFrame

class resokit.core.StaticBody(data, source, metadata=NOTHING, *, is_star: bool)[source]

Bases: ResokitDataFrame

StaticBody class.

This class defines the basic object structure; for a star or a planet. This class should not be instantiated directly.

data

Series containing the data. Inherited from ResokitDataFrame.

Type:: pd.Series

source

Source of the dataset. Either ‘eu’ or ‘nasa’ or ‘binary’ or ‘user’. Inherited from ResokitDataFrame.

Type:: str

metadata

Metadata of the dataset. Inherited from ResokitDataFrame.

Type:: dict

is_star

Flag indicating if the object is a star.

Type:: bool

name

Name of the object.

Type:: str

web_page

Web page of the object.

Type:: str

set_attr(attr: str, value: Any) → StaticBody[source]

Set an attribute of the StaticBody and return a new instance.

Parameters:

attr (str) – Attribute to set.
value (any) – Value to set.

Returns:

A new StaticBody with the updated attribute.

Return type:

StaticBody

class resokit.core.StaticPlanet(data, source, metadata=NOTHING)[source]

Bases: StaticBody

StaticPlanet class representing a static planet.

data

Pandas Series containing the data.

Type:: pd.Series

source

Source of the dataset. Either ‘eu’ or ‘nasa’ or ‘user’.

Type:: str

metadata

Metadata of the dataset.

Type:: dict

name

Name of the planet.

Type:: str

web_page

Web page of the planet.

Type:: str

user_defined_

Flag indicating if the planet is user-defined.

Type:: bool

suffix_

Suffix for the planet name.

Type:: str

get_item(items: List[str] | str, error: bool = False, silent: bool = False) → Series[source]

Return the specified items of the planet.

Parameters:

items (list, str) – Items to return.
error (bool, optional. Default: False.) – Whether to return the error columns.
silent (bool, optional. Default: False.) – Whether to suppress warnings for missing columns.

Returns:

Series – Series with the requested items.

Return type:

pandas Series

estimate_mass(new_planet: bool = False, **kwargs) → float | Tuple[float, float, float] | StaticPlanet[source]

Calculate the mass of the planet using a power-law approximation.

Equation:: \(mass = \dfrac{1}{C} \times radius^{1/S}\)

Note

To use the errors, set err_method to 1 or 2. Be aware that the planet must have radius_err_min and radius_err_max columns.

Parameters:

new_planet (bool, optional. Default: False.) – Whether to return a new planet with the estimated mass.
kwargs (dict) – Keyword arguments for the resokit.utils.mass_radius.estimate_mass_single() function.

Returns:

mass, mass_err_min, mass_err_max – Estimated mass, and its minimum and maximum errors, in Jupiter masses. If err_method=0, the errors are 0.0. If err_method=-1 (default), the errors are not returned.

Return type:

tuple[float, float, float]

estimate_radius(new_planet: bool = False, **kwargs) → float | Tuple[float, float, float] | StaticPlanet[source]

Calculate the radius of a planet using a power-law approximation.

Equation:: \(radius = C \times mass^S\)

Note

To use the errors, set err_method to 1 or 2. Be aware that the planet must have mass_err_min and mass_err_max columns.

Parameters:

new_planet (bool, optional. Default: False.) – Whether to return a new planet with the estimated radius.
kwargs (dict) – Keyword arguments for the resokit.utils.mass_radius.estimate_radius_single() function.

Returns:

radius (float) – Estimated radius in Jupiter radii.
radius_err_min (float) – Minimum error in Jupiter radii. If err_method=0, the error is 0.0.
radius_err_max (float) – Maximum error in Jupiter radii. If err_method=0, the error is 0.0.

plot(x: str, y: str, error_x: bool = False, error_y: bool = False, ax: Axes | None = None, label: bool | str = True, **plot_kwargs: dict) → Axes[source]

Plot the x vs y data of the planet.

Note

The parameters error_x and error_y link each error to the input parameter x and y, respectively. The error columns must be named as x_err_min, x_err_max, y_err_min, and y_err_max.

Parameters:

x (str) – Name of the column to use as x-axis.
y (str) – Name of the column to use as y-axis.
error_x (bool, optional. Default: False.) – Whether to plot the x error bars.
error_y (bool, optional. Default: False.) – Whether to plot the y error bars.
ax (plt.Axes, optional. Default: None.) – Matplotlib Axes to plot on. If None, get and use the current Axes.
label (bool, str, optional. Default: True.) – String to use as the label. If True, use the planet name.
plot_kwargs (dict) – Additional keyword arguments for the plt.errorbar() function.

Returns:

ax – Matplotlib Axes with the plot.

Return type:

Matplotlib Axes

class resokit.core.StaticStar(data, source, metadata=NOTHING)[source]

Bases: StaticBody

StaticStar class representing a static star.

data

Series containing the data.

Type:: pd.Series

source

Source of the dataset. Either ‘eu’ or ‘nasa’ or ‘binary’ or ‘user’.

Type:: str

metadata

Metadata of the dataset.

Type:: dict

name

Name of the star.

Type:: str

web_page

Web page of the star.

Type:: str

user_defined_

Flag indicating if the star is user-defined.

Type:: bool

plot(x: str, y: str, error_x: bool = False, error_y: bool = False, ax: Axes | None = None, label: bool | str = True, **plot_kwargs: dict) → Axes[source]

Plot the x vs y data of the star.

Parameters:

x (str) – Name of the column to use as x-axis.
y (str) – Name of the column to use as y-axis.
error_x (bool, optional. Default: False.) – Whether to plot the x error bars.
error_y (bool, optional. Default: False.) – Whether to plot the y error bars.
ax (plt.Axes, optional. Default: None.) – Matplotlib Axes to plot on. If None, get and use the current Axes.
label (bool, str, optional. Default: True.) – String to use as the label. If True, use the star name.
plot_kwargs (dict) – Additional keyword arguments for the plt.errorbar() function.

Returns:

ax – Matplotlib Axes with the plot.

Return type:

Matplotlib Axes

class resokit.core.StaticBinaryStar(star0: StaticStar, star1: StaticStar, data, name: str = 'unnamed', metadata=NOTHING)[source]

Bases: object

StaticBinaryStar class.

star0

StaticStar instance for the primary star.

Type:: StaticStar. Mandatory.

star1

StaticStar instance for the secondary star.

Type:: StaticStar. Mandatory.

data

Data of the binary system.

Type:: Union[pd.DataFrame, pd.Series]. Mandatory.

name

Name of the binary system.

Type:: str, optional. Default: ‘unnamed’.

metadata

Metadata of the dataset.

Type:: dict, optional. Default: {}.

web_page

Web page of the binary system.

Type:: str

suffix_

Suffix for the binary system name.

Type:: str

alternate_name

Alternative name of the binary system.

Type:: str

disc_method

Detection method of the binary system.

Type:: str

dist

Distance to the binary system, in parsecs.

Type:: float

a

Semi-major axis of the binary system, in AU.

Type:: float

e

Eccentricity of the binary system.

Type:: float

imut

Inclination of the mutual orbit, in degrees.

Type:: float

nplanets

Number of planets in the binary system.

Type:: int

planet_HW_crit

Holman & Wiegert (1999) criterion for the binary system.

Type:: float

total_mass_

Total mass of the binary system, in solar masses.

Type:: float

known_orbit_

Whether the orbit is known.

Type:: bool

star(indices: int | str | List[str | int]) → StaticStar[source]

Return the star(s) of the binary system, by given index or name.

Parameters:: indices (int, str, list) – Which star(s) to return. If ‘all’, return both stars. If an int, return the star with the given index. If a str, return the star with the given name. If a list, return the stars with the given indexes or names.
Returns:: star – StaticStar instance for the star, or list of stars.
Return type:: StaticStar, list

set_attr(attr: str, value: Any, in_star: None | int = None) → StaticBinaryStar[source]

Set an attribute of the StaticBinaryStar and return a new instance.

Parameters:

attr (str) – Attribute to set.
value (any) – Value to set.
in_star (int, optional (default: None)) – Index of the star to modify (0 or 1). If None, modifies the binary system.

Returns:

A new instance with the updated attribute.

Return type:

StaticBinaryStar

to_dict() → dict[source]: Return the metadata as a new dictionary.

to_dataframe() → DataFrame[source]: Return the binary data as a new DataFrame.

copy() → StaticBinaryStar[source]: Return a copy of the StaticBinaryStar.

class resokit.core.StaticSystem(star: StaticStar | StaticBinaryStar, planets: Any, name: str = 'unnamed', metadata=NOTHING, is_circumbinary: bool = False)[source]

Bases: object

StaticSystem class representing a static system.

Contains a star and a list of planets.

star

StaticStar instance.

Type:: StaticStar

planets

List or tuple of StaticPlanet instances, or a single StaticPlanet.

Type:: list[StaticPlanet], tuple[StaticPlanet], StaticPlanet

name

Name of the system.

Type:: str

metadata

Metadata of the dataset.

Type:: dict

web_page

Web page(s) of the system.

Type:: list[str]

n_planets_

Number of planets in this static system.

Type:: int

source_

Source of the data.

Type:: str

user_defined_

Flag indicating if the system is user-defined.

Type:: bool

planet_names_

List of planet names.

Type:: list[str]

Return the star (or binary) and/or planets by given indices.

For this function, the star (or binary) is index 0, and the planets starts from 1.

Parameters:

indices (int, Iterable[int], Iterable[str], str) – Indices for slicing star and planets. If “all”, return all bodies. Instead of index numbers, the bodies names can be used.
only_index (bool, default=False) – Return only the index of the bodies.

Returns:

bodies – A copy of a system’s star StaticStar or planet StaticPlanet or binary star StaticBinaryStar or list of them.

Return type:

StaticStar or StaticPlanet or StaticBinaryStar or list

planet(indices: int | str | Iterable[int | str], only_index: bool = False) → StaticPlanet | List[StaticPlanet][source]

Slice the planets by given indices.

The planets are indexed from 0 to n_planets - 1.

Parameters:

indices (int, Iterable[int], Iterable[str], str) – Indices for slicing planets. If “all”, return all planets. Instead of index numbers, the planets names can be used.
only_index (bool, default=False) – Return only the index of the planets.

Returns:

planet – A copy of a system’s planet StaticPlanet or list of StaticPlanet objects.

Return type:

StaticPlanet or list[StaticPlanet]

get_item(items: str | List[str], error: bool = False) → Series | DataFrame[source]

Retrieve specific attributes of the system (star(s) and/or planets).

Parameters:

items (str, list[str]) – Names of the desired attributes.
error (bool, optional. Default: False.) – Whether to return the error columns. Only available for standard ResokitDataFrame objects.

Returns:

data – Pandas Series or DataFrame with the requested items.

Return type:

pandas series or pandas dataframe

estimate_period(which: str | int | List[int] = 'all', err_method: int = -1, jacobi: bool = False, deep_estimate: bool = False, force: bool = False, new_system: bool = False) → Tuple[float, float, float] | DataFrame | StaticSystem[source]

Estimate the period of selected planets in the system.

Calculate the period of the planet using the third Kepler’s law.

Equation:: \(P = 2 \pi \sqrt{\dfrac{a^3}{G (m_\star + m_p)}}\)

Parameters:

which (str, int, list[int], optional. Default: 'all'.) – Which planets to estimate the period. If ‘all’, estimate all planets period. If an int, estimate the period of the planet with the given index. For example: 0 will estimate the period of the first planet; 1 will estimate the period of the second planet. If a list of integers, estimate the period of the planets with the given indices. If str, estimate the period of the planet with the given name or given suffix.
err_method (int, optional. Default: -1.) – Method to estimate the error. See py:func:resokit.utils.calc_period_with_errors for more details. The planet must have “a” and “mass” errors” columns, and the star must have “mass” errors columns. The options are: -1: Nothing. Do not estimate the error. 0 : No propagation. Return both errors as 0.0. 1 : Extremes. Estimate the period at the extreme values of each parameter and retrieve the errors from the difference. 2 : Extended propagation. Assume each parameters follows a normal distribution with sigma = max(err_max, err_min). 3 : Centred propagation. Assume each parameters follows a normal distribution with sigma = (err_min + err_max) / 2.
jacobi (bool, optional. Default: False.) – Whether to use the Jacobi criterion to estimate the period. Involves using the accumulated inner mass (star + inner planets) instead of just the star mass. Doesn’t involve considering the semi-major axis of the planets from another reference frame.
deep_estimate (bool, optional. Default: False.) – Whether to estimate the missing parameters (masses) to calculate the period.
force (bool, optional. Default: False.) – Whether to force the estimation of the period, even if it already exists. If False, return the existing period if it exists.
new_system (bool, optional. Default: False.) – Whether to return a new system with the estimated semi-major axis instead of the values.

Returns:

period, period_err_min, period_err_max – Estimated period, and its minimum and maximum errors, in days.

Return type:

tuple or DataFrame

estimate_semi_major_axis(which: str | int | List[int] = 'all', err_method: int = -1, jacobi: bool = False, deep_estimate: bool = False, force: bool = False, new_system: bool = False) → Tuple[float, float, float] | DataFrame | StaticSystem[source]

Estimate the semi-major axis of selected planets in the system.

Equation:: \(a = \left(\dfrac{G (m_\star + m_p)} {4 \pi^2 P^2}\right)^{1/3}\)

Parameters:

which (str, int, list[int], optional. Default: 'all'.) – Which planets to estimate the semi-major axis. If ‘all’, estimate all planets semi-major axis. If an int, estimate the semi-major axis of the planet with the given index. For example: 0 will estimate the semi-major axis of the first planet; 1 will estimate the semi-major axis of the second planet. If a list of integers, estimate the semi-major axis of the planets with the given indices. If str, estimate the semi-major axis of the planet with the given name or given suffix.
err_method (int, optional. Default: -1.) – Method to estimate the error. See py:func:resokit.utils.calc_semi_major_axis_with_errors for more details. The planet must have “P” and “mass” errors” columns, and the star must have “mass” errors columns. The options are: -1: Nothing. Do not estimate the error. 0 : No propagation. Return both errors as 0.0. 1 : Extremes. Estimate the semi-major axis at the extreme values of each parameter and retrieve the errors from the difference. 2 : Extended propagation. Assume each parameters follows a normal distribution with sigma = max(err_max, err_min). 3 : Centred propagation. Assume each parameters follows a normal distribution with sigma = (err_min + err_max) / 2.
jacobi (bool, optional. Default: False.) – Whether to use the Jacobi criterion to estimate the semi-major axis. Involves using the accumulated inner mass (star + inner planets) instead of just the star mass. Doesn’t involve considering the semi-major axis of the planets from another reference frame.
deep_estimate (bool, optional. Default: False.) – Whether to estimate the missing parameters (masses) to calculate the semi-major axis.
force (bool, optional. Default: False.) – Whether to force the estimation of the semi-major axis, even if it already exists. If False, return the existing semi-major axis if it exists.
new_system (bool, optional. Default: False.) – Whether to return a new system with the estimated semi-major axis instead of the values.

Returns:

a, a_err_min, a_err_max – Estimated semi-major axis, and its minimum and maximum errors, in AU.

Return type:

tuple or DataFrame

estimate_mass(which: str | int | List[int] = 'all', force: bool = False, new_system: bool = False, **kwargs) → Tuple[float, float, float] | DataFrame | StaticSystem[source]

Estimate the mass of selected planets in the system.

Equation:: \(mass = \frac{1}{C} \times radius^{1/S}\)

Parameters:

which (str, int, list[int], optional. Default: 'all'.) – Which planets to estimate the mass. If ‘all’, estimate all planets mass. If an int, estimate the planet with the given index. For example: 0 will estimate the mass of the first planet; 1 will estimate the mass of the second planet. If a list of integers, estimate the mass of the planets with the given indices. If str, estimate the mass of the planet with the given name or given suffix.
force (bool, optional. Default: False.) – Whether to force the estimation of the mass, even if it already exists. If False, return the existing mass if it exists.
model (str, optional. Default: "ck17") – Model to use for the mass-radius power-law relation. ‘ck17’: Chen & Kipping (2017) [trivariate] ‘o20’: Otegi et al. (2020) [density|bivariate] ‘e23’: Edmondson et al. (2023) ‘m24’: Müller et al. (2024) [bivariate]
multivariate (float, tuple, optional. Default: 0.5) – Probability of using the (first, second, …) branch if the estimation falls in a multivariate region. For bivariate models (‘o20’, ‘m24’), it must be a float between 0 and 1. For trivariate model “ck17”, it must be a tuple of two floats between 0 and 1, where the sum of them must be lower equal than 1.
err_method (int, optional. Default: -1) – Which method implement for error calculation. Method -1: Do not calculate errors. Return only the mass. Method 0: Do not calculate errors. Return both as 0.0. Method 1: (Naive) Error propagation with the power-law approximation, using the radius error as the maximum of the two extremes. Warning: May return excessively large errors for multivariate sections. Method 2: Evaluate the radius extremes and calculate each mass extreme with the power-law approximation. Method 3: Returns the approximate model error as value errors.
new_system (bool, optional. Default: False.) – Whether to return a new system with the estimated mass instead of the values.
**kwargs (dict) – Additional keyword arguments for the resokit.utils.mass_radius.estimate_mass() function.

Note

If err_method=-1, only the mass is returned. If err_method=0, the errors are 0.0.

Note

To use the errors, the planet must have “radius” error columns.

Returns:: mass, mass_err_min, mass_err_max – Estimated mass, and its minimum and maximum errors, in Jupiter masses.
Return type:: tuple or DataFrame

estimate_radius(which: str | int | List[int] = 'all', force: bool = False, new_system: bool = False, **kwargs) → Tuple[float, float, float] | DataFrame | StaticSystem[source]

Estimate the radius of selected planets in the system.

Equation:: \(radius = C \times mass^S\)

Parameters:

which (str, int, list[int], optional. Default: 'all'.) – Which planets to estimate the radius. If ‘all’, estimate all planets radius. If an int, estimate the planet with the given index. For example: 0 will estimate the radius of the first planet; 1 will estimate the radius of the second planet. If a list of integers, estimate the radius of the planets with the given indices. If str, estimate the radius of the planet with the given name or given suffix.
force (bool, optional. Default: False.) – Whether to force the estimation of the radius, even if it already exists. If False, return the existing radius if it exists.
model (str, optional. Default: "ck17") – Model to use for the mass-radius power-law relation. ‘ck17’: Chen & Kipping (2017) ‘o20’: Otegi et al. (2020) [density|bivariate] ‘e23’: Edmondson et al. (2023) ‘m24’: Müller et al. (2024)
bivariate (float, optional. Default: 0.5) – Probability of using the lower branch if the estimation falls in a bivariate region. Must be a number between 0 and 1. Only used if model is ‘o20’.
err_method (int, optional. Default: -1) – Which method implement for error calculation. Method -1: Do not calculate errors. Return only the radius. Method 0: Do not calculate errors. Return both as 0.0. Method 1: (Naive) Error propagation with the power-law approximation, using the mass error as the maximum of the two extremes. Method 2: Evalaute the mass extremes and calculate each radius extreme. Method 3: Returns the approximate model error as value errors.
new_system (bool, optional. Default: False.) – Whether to return a new system with the estimated radius instead of the values.
**kwargs (dict) – Additional keyword arguments for the resokit.utils.mass_radius.estimate_radius() function.

Note

If err_method=-1, only the radius is returned. If err_method=0, the errors are 0.0.

Note

To use the errors, the planet must have “radius” error columns.

Returns:: radius, radius_err_min, radius_err_max – Estimated radius, and its minimum and maximum errors, in Jupiter radii.
Return type:: tuple or DataFrame

estimate_hill_radius(which: str | int | List[int] = 'all', err_method: int = -1, jacobi: bool = False, deep_estimate: bool = False, circular: bool = False) → Tuple[float, float, float] | DataFrame | StaticSystem[source]

Calculate the Hill radius of selected planets in the system.

Equation:: \(r_H = a (1 - e) \left(\dfrac{m_p} {3 (m_\star + m_p)}\right)^{1/3}\)

Parameters:

which (str, int, list[int], optional. Default: 'all'.) – Which planets to calculate the Hill radius. If ‘all’, calculate the Hill radius of all planets. If an int, calculate the Hill radius of the planet with the given index. For example: 0 will calculate the Hill radius of the first planet; 1 will calculate the Hill radius of the second planet. If a list of integers, calculate the Hill radius of the planets with the given indices. If str, estimate the period of the planet with the given name or given suffix.
err_method (int, optional. Default: -1.) – Method to estimate the error. See py:func:resokit.utils.hill_radius.calc_hill_radius_with_errors for more details. The planet must have “a”, “e” and “mass” error columns, and the star must have “mass” errors columns. The options are: -1: Nothing. Do not estimate the error. 0 : No propagation. Return both errors as 0.0. 1 : Extremes. Estimate the semi-major axis at the extreme values of each parameter and retrieve the errors from the difference. 2 : Extended propagation. Assume each parameters follows a normal distribution with sigma = max(err_max, err_min). 3 : Centred propagation. Assume each parameters follows a normal distribution with sigma = (err_min + err_max) / 2.
jacobi (bool, optional. Default: False.) – Whether to use the Jacobi criterion to estimate the Hill radius. Involves using the accumulated inner mass (star + inner planets) instead of just the star mass. Doesn’t involve considering the semi-major axis of the planets from another reference frame.
deep_estimate (bool, optional. Default: False.) – Whether to estimate the missing parameters (masses and semi-major axis) to calculate the Hill radius. If the mass and semi-major axis are missing, they will be estimated; otherwise, the existing values will be used.
circular (bool, optional. Default: False.) – Whether to assume the unknown eccentricities are 0.0.

Returns:

rhill, rhill_err_min, rhill_err_max – Hill radius, and its minimum and maximum errors, in AU.

Return type:

tuple or DataFrame

plot(x: str, y: str, error_x: bool = False, error_y: bool = False, ax: Axes | None = None, label: bool | str | Iterable[str] = True, plot_kwargs: dict | None = None) → Axes[source]

Plot the x vs y data of the system.

Uses plt.errorbar() internally.

Note

Crossed attributes (e.g., x=’star_mass’, y=’mass’) are not allowed yet.

Note

To use the error bars, the planets (star) must have the corresponding error columns.

Parameters:

x (str) – Name of the column to use as x-axis.
y (str) – Name of the column to use as y-axis.
error_x (bool, optional. Default: False.) – Whether to plot the x error bars.
error_y (bool, optional. Default: False.) – Whether to plot the y error bars.
ax (plt.Axes, optional. Default: None.) – Matplotlib Axes to plot on. If None, get and use the current Axes.
label (bool, str, Iterable, optional. Default: True.) – Whether to add a label with the planet (or star) names. If str, use the string as the label. If Iterable, use the list of strings as the label.
plot_kwargs (dict) – Additional keyword arguments for the plt.errorbar() function.

Returns:

ax – Matplotlib Axes with the plot.

Return type:

Matplotlib Axes

Plot consecutive triplets of planets in the period ratio space.

Systems triplets are shown in the plane: \(P_{i+1}/P_i\) vs. \(P_{i+2}/P_{i+1}\).

Note

Only available for planets yet.

Parameters:

which (int, str, optional. Default: 'all'.) – Which triplets to plot. If ‘all’, plot all possible triplets. If an int, plot the triplet with the given index. For example: 0 will plot the first triplet: (0, 1, 2); 1 will plot the second triplet: (1, 2, 3).
error (bool, optional. Default: False.) – Whether to plot the error bars. Only available if the planets have period ratio error columns.
ax (plt.Axes, optional. Default: None.) – Matplotlib Axes to plot on. If None, get and use the current Axes.
label (str, list, bool, optional. Default: True.) – Label for the data plotted. If True, will (try to) concatenate each three planets suffixes to create triplets labels.
draw_mmr (bool, float, optional. Default = True) – If True, draws the 2-body-mmrs and 3-body-mmrs curves in the area. If label is not False, it will write the mmrs labels as well. If draw_mmr is a float, this argument is set as the displacement factor: xmax = xlim_max = max(2b-MMR) * (1 + factor). Default factor: 0.05
**kwargs (dict) – Additional keyword arguments for the plt.errorbar() function.

Returns:

ax – Matplotlib Axes with the plot.

Return type:

Matplotlib Axes

remove_planet(index: int | str, verbose: bool = True) → StaticSystem[source]

Remove a planet from the system.

Parameters:

index (int, str) – Index or suffix (1 char) or name of the planet to remove.
verbose (bool, optional. Default: True.) – Whether to print a message when removing the planet.

Returns:

A new :py:class`StaticSystem` instance without the removed planet.

Return type:

StaticSystem

add_planet(planet: StaticPlanet, sort: bool | str = True, verbose: bool = True) → StaticSystem[source]

Add a planet to the system.

Parameters:

planet (StaticPlanet) – StaticPlanet instance to add.
sort (bool, str, optional. Default: True.) – Whether to sort the planets by period. If str, sort by the specified column.
verbose (bool, optional. Default: True.) – Whether to print a message when adding the planet.

Returns:

A new :py:class`StaticSystem` instance.

Return type:

StaticSystem

swap_planets(i: int | str, j: int | str, verbose: bool = True) → StaticSystem[source]

Switch the position of two planets in the system.

Parameters:

i (int, str) – Index or suffix (1 char) or name of the first planet to switch.
j (int, str) – Index or suffix (1 char) or name of the second planet to switch.
verbose (bool, optional. Default: True.) – Whether to print a message when switching the planets.

Returns:

A new :py:class`StaticSystem` instance with the switched planets.

Return type:

StaticSystem

replace_planet(index: int | str, planet: StaticPlanet, verbose: bool = True) → StaticSystem[source]

Replace a planet in the system with a new one.

Parameters:

index (int, str) – Index or suffix (1 char) or name of the planet to change.
planet (StaticPlanet) – StaticPlanet instance to add.
verbose (bool, optional. Default: True.) – Whether to print a message when changing the planet.

Returns:

A new :py:class`StaticSystem` instance with the changed planet.

Return type:

StaticSystem

Return the period ratio of the specified pair of planets.

This function can also estimate the approximate fraction corresponding to each period ratio.

Parameters:

pair (int, list, tuple, str, optional. Default: 'all'.) – Which pair of planets to consider. Either ‘all’ or a list/tuple of planet names/indexes. If pair=(i,j), then the period ratio is \(P_j/P_i\), and remember that the first planet is 0.
verbose (bool, optional. Default: False.) – Whether to print the steps of the calculation if a single pair, and fraction_arg is not 0.
error (bool, optional. Default: False.) – Whether to return the error of the period ratio, instead of the period ratio itself. Only meaningful if there are errors.
use_binary (bool, optional. Default: True.) – Whether to use the binary period ratio (include the star). If False, only the planets are considered.
fraction_kwargs (dict, optional. Default: None) – Dictionary with arguments for the resokit.utils.float_to_fraction() function. If None, no fraction conversion is done. Parameters can be: - max_iter - max_error - as_fraction - stop_func See resokit.utils.float_to_fraction() for more information.

Returns:

ratios – Float with period ratio of the pair of planets, or pandas Data frame with all the period ratios.

Return type:

float, pd.DataFrame

set_attr(attr: str, value: Any, in_star: None | int = None, in_planet: None | int | str = None, in_binary: None | bool = None, verbose: bool = True) → StaticSystem[source]

Set an attribute of the StaticSystem and return a new instance.

Note

If in_star, in_planet, and in_binary are all None, the attribute of the system is changed.

Parameters:

attr (str) – Attribute to set.
value (any) – Value to set.
in_star (bool, int, optional (default: None)) – If not None, modify the attribute of the star. If the system has a binary star, the star can be selected with the index (0, 1).
in_planet (int, str, optional (default: None)) – If not None, modify the attribute of the planet. The planet can be selected with the index or the name or suffix.
in_binary (bool, optional (default: None)) – If not None, modify the attribute of the binary system.
verbose (bool, optional (default: True)) – Whether to print a message when changing the attribute.

Returns:

A new instance with the updated attribute.

Return type:

StaticSystem

to_dict() → dict[source]: Return the metadata as a new dictionary.

to_dataframe(add_star: bool | None = True, columns: list | None = None) → DataFrame[source]

Combine and return system objects data as a new pandas DataFrame.

Parameters:

add_star (bool, optional. Default: True.) – Whether to include the star data in the DataFrame as a row (same level as the planets). If False, the star data is included in the planets DataFrame as repeated rows. If None, do not include any star data.
columns (list, optional. Default: None.) – Subset of columns to include in the DataFrame.

Returns:

df – Pandas Data frame with the data.

Return type:

DataFrame

to_rebound(sim: Simulation | None = None, fillna: bool = True, units: bool | Tuple[float, float] = True, verbose: bool = True) → Simulation[source]

Return a REBOUND simulation with the system data.

Creates or updates a REBOUND simulation with the system data.

Note

The unknown orbital elements that cant be estimated with fillna (for example, the eccentricity of a single planet) are set to 0.0; independently of the fillna value.

Note

The REBOUND simulation is created with the heliocentric orbits. If the system is a circumbinary, the stars are added as the first two particles, and the planets are added after them, with the binary center of mass as the origin.

Note

The simulation units are not changed. The user has to ensure the consistency of the units after the simulation is created. (eg. if the user provides the units in [Kg, m], then sim.units = (‘kg’, ‘m’, <time_unit>) has to be set after the simulation is created).

Note

If a binary system is provided, the second star will not have radius (unless this attribute has been set manually).

Note

The mean anomaly (M) is randomly generated between 0 and 2*pi.

Parameters:

sim (rebound.Simulation, optional. Default: None.) – REBOUND simulation to add the system data. If None, create a new simulation.
fillna (bool, optional. Default: True.) – Whether to fill missing data with estimations.
units (bool, tuple, optional. Default: True.) – Whether to use AU, Msun units. If False, use m, Kg units. If tuple, use the given units. The tuple must be (unit_mass, unit_length). The user has to ensure the consistency of the units after the simulation is created.
verbose (bool, optional. Default: True.) – Whether to print a message when creating the simulation.

copy() → StaticSystem[source]: Return a copy of the StaticSystem.

resokit.core.resokit_to_system(resokit_data: ResokitDataFrame, binary_star: None | StaticBinaryStar = None, circumbinary: bool = False, verbose: bool = False) → StaticSystem[source]

Convert a ResokitDataFrame to a StaticSystem.

Parameters:

resokit_data (ResokitDataFrame) – ResokitDataFrame instance with the data.
binary_star (StaticBinaryStar, optional. Default: None.) – StaticBinaryStar instance to use as the binary star.
circumbinary (bool, optional. Default: False.) – Whether the system is circumbinary.
verbose (bool, optional. Default: True.) – Whether to print a message when creating the system.

Returns:

StaticSystem instance.

Return type:

StaticSystem

resokit.core.binary_row_to_binary_star(binary_row: Series, source='user', metadata=None) → StaticBinaryStar[source]

Convert a binary row to a StaticBinaryStar.

Parameters:

binary_row (pd.Series) – Pandas Series with the binary data.
source (str, optional. Default: 'user'.) – Source of the data.
metadata (dict, optional. Default: {}.) – Additional metadata about the star.

Returns:

StaticBinaryStar instance.

Return type:

StaticBinaryStar

Module resokit.core

Module `resokit.core`