API Reference

Core Functions

compute_amdk(m, e, di, a)[source]

Compute the angular momentum deficit (AMD) for a planet in a system or for multiple planets.

Parameters:

  • m (float, np.array) – Mass of the planet.

  • e (float, np.array) – Eccentricity of the planet’s orbit.

  • di (float, np.array) – Relative angle (inclination or obliquity) of the planet’s orbit in degrees w.r.t. a reference (e.g. the most massive planet in the system).

  • a (float, np.array) – Semi-major axis of the planet’s orbit.

Returns:

amdk – Angular momentum deficit.

Return type:

float

compute_namd(amdk, m, sqrt_a)[source]

Compute the normalized angular momentum deficit (NAMD) for a given system.

Parameters:

  • amdk (np.array) – Angular momentum deficit for the planets in a system.

  • m (np.array) – Mass of the planets in the system

  • sqrt_a (np.array) – Square root of the semi-major axis of the planets in the system

Returns:

namd – Normalized angular momentum deficit.

Return type:

float

Data Management

download_nasa_confirmed_planets(min_sy_pnum=1, from_scratch=False)[source]

Downloads the NASA Exoplanet Archive confirmed planets table.

Parameters:

  • min_sy_pnum (int, optional) – Minimum number of planets in the system to consider. Defaults to 1.

  • from_scratch (bool, optional) – If True, downloads the entire table. If False, downloads only the rows newer than the latest update date in the current table. Defaults to False.

Returns:

  • df (pandas.DataFrame) – The downloaded table.

  • df_old (pandas.DataFrame) – The previous table, if from_scratch is False. Otherwise, None.

Calculation Tools

solve_a_rs(sma, rstar, ars)[source]

Solve semi-major axis – stellar radius system of equations.

Parameters:

  • sma (Float) – Orbital semi-major axis (AU).

  • rstar (Float) – Stellar radius (r_sun).

  • ars (Float) – sma–rstar ratio.

solve_rprs(rplanet, rstar, rprs)[source]

Solve planet radius – stellar radius system of equations.

Parameters:

  • rplanet (Float) – Planet radius (r_earth).

  • rstar (Float) – Stellar radius (r_sun).

  • rprs (Float) – Planet–star radius ratio.

solve_a_period(period, sma, mstar)[source]

Solve period-sma-mstar system of equations.

Parameters:

  • period (Float) – Orbital period (days).

  • sma (Float) – Orbital semi-major axis (AU).

  • mstar (Float) – Stellar mass (m_sun).

solve_values(row)[source]
solve_relincl(row, df)[source]

Computes the relative inclination of a planet with respect to the most massive planet in the same system.

Parameters:

  • row (pandas.Series) – A row from the planet table.

  • df (pandas.DataFrame) – The planet table.

Returns:

A pandas Series containing the relative inclination and the associated uncertainties.

Return type:

pandas.Series

solve_amdk(row, kind)[source]

Wrapper of the function compute_amdk to compute the angular momentum deficit (AMD) for a planet (or planets) in a system.

Parameters:

  • row (pandas.Series) – A row from the planet table.

  • kind (str) – Which type of AMD to compute. One of ‘rel’ (relative, using the relative inclination) or ‘abs’ (absolute, using the obliquity).

Returns:

A pandas Series containing the angular momentum deficit and the associated mass and sqrt of the semi-major axis.

Return type:

pandas.Series

solve_namd(host, kind)[source]

Wrapper of the functions solve_amdk and compute_namd to compute the normalized angular momentum deficit (NAMD) for a given system.

Parameters:

  • host (pandas.DataFrame) – A DataFrame containing the planet table.

  • kind (str) – Which type of NAMD to compute. One of ‘rel’ (relative, using the relative inclination) or ‘abs’ (absolute, using the obliquity).

Returns:

A pandas Series containing the normalized angular momentum deficit.

Return type:

pandas.Series

solve_amdk_mc(row, kind, Npt, threshold, use_trunc_normal=True)[source]

Compute the absolute or relative angular momentum deficit (AMD) for a given planet using a Monte Carlo approach.

Parameters:

  • row (pandas.Series) – A row from the planet table.

  • kind (str) – Which type of AMD to compute. One of ‘rel’ (relative, using the relative inclination) or ‘abs’ (absolute, using the obliquity).

  • Npt (int) – Number of Monte Carlo samples.

  • threshold (int) – Minimum number of valid samples required.

  • use_trunc_normal (bool) – If True, use a truncated normal distribution to sample the parameters. If False, use a normal distribution with rejection sampling.

Returns:

A pandas Series containing the absolute or relative AMD, the associated mass and sqrt of the semi-major axis.

Return type:

pandas.Series

solve_namd_mc(host, kind, Npt, threshold, use_trunc_normal, full=False)[source]

Wrapper of the functions solve_amdk_mc and compute_namd to compute the normalized angular momentum deficit (NAMD) for a given system using a Monte Carlo approach.

Parameters:

  • host (pandas.DataFrame) – A DataFrame containing the system table.

  • kind (str) – Which type of NAMD to compute. One of ‘rel’ (relative, using the relative inclination) or ‘abs’ (absolute, using the obliquity).

  • Npt (int) – Number of Monte Carlo samples.

  • threshold (int) – Minimum number of valid samples required.

  • use_trunc_normal (bool) – If True, use a truncated normal distribution to sample the parameters. If False, use a normal distribution with rejection sampling.

  • full (bool) – If True, return the full array of NAMD values. Otherwise, return only the 16th, 50th and 84th percentiles.

Returns:

A pandas Series containing the normalized angular momentum deficit results.

Return type:

pandas.Series

Logging

This module was directly inspired by the log module in the PAOS package.

addLogFile(fname='exonamd.log')[source]

Adds a new log file for logging.

Parameters:

fname (str, optional) – The filename for the log file. Defaults to ‘exonamd.log’.

Return type:

None

setLogLevel(level='INFO')[source]

Configures the logging level for the logger.

Parameters:

level (str, optional) – The logging level to set. Defaults to ‘INFO’. Possible values include ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’, etc.

Return type:

None

disableLogging(name='exonamd')[source]

Disables the logger for the given module name.

Parameters:

name (str, optional) – The module name to disable logging for. Defaults to ‘exonamd’.

Return type:

None

enableLogging(name='exonamd')[source]

Enables the logger for the given module name.

Parameters:

name (str, optional) – The module name to enable logging for. Defaults to ‘exonamd’.

Return type:

None

Visualization

simple_plot(df, kind, title='', which='namd', ylabel='Frequency', xlabel=None, scale='linear', bins=50, out_path=None, figsize=None, xlim=(None, None))[source]
pop_plot(df, kind, title='', which='namd', yscale='log', xoffs=0.3, out_path=None, replace_nan=False)[source]
plot_host_namd(df, hostname, kind, Npt=100000, threshold=1000, out_path=None)[source]

Plot the NAMD for a given host.

Parameters:

  • df (pd.DataFrame) – The NAMD database. If None, the function reloads the database from disk.

  • hostname (str) – The hostname to plot.

  • kind (str) – Which type of NAMD to plot. One of ‘rel’ (relative NAMD) or ‘abs’ (absolute NAMD).

  • Npt (int) – Number of Monte Carlo samples.

  • threshold (int) – Minimum number of valid samples required.

  • out_path (str) –

Return type:

None

plot_sample_namd(df, title, kind='rel', out_path=None)[source]

Plot the sample NAMD against the multiplicity.

If df is None, the function reloads the database from disk.

Parameters:

  • df (pd.DataFrame) – The NAMD database.

  • title (str) – The title of the plot.

  • kind (str) – Which type of NAMD to plot. One of ‘rel’ (relative NAMD) or ‘abs’ (absolute NAMD).

  • out_path (str) – The path to save the plot.

Return type:

None

Main Interface