general.py

a_from_P(P, Mstar)

Compute the semi-major axis using Kepler’s third law.

Note

Assumes that the planet mass is negligible compared to the stellar mass.

Parameters:

P (float or array[floats]) – The orbital period (days).
Mstar (float or array[floats]) – The stellar mass (solar masses).

Returns:

a – The semi-major axis (AU).

Return type:

float or array[floats]

P_from_a(a, Mstar)

Compute the orbital period using Kepler’s third law.

Note

Assumes that the planet mass is negligible compared to the stellar mass.

Parameters:

a (float or array[floats]) – The semi-major axis (AU).
Mstar (float or array[floats]) – The stellar mass (solar masses).

Returns:

P – The orbital period (days).

Return type:

float or array[floats]

M_from_R_rho(R, rho=5.51)

Compute the planet mass from the radius and constant mean density.

Parameters:

R (float or array[floats]) – The planet radius (Earth radii).
rho (float or array[floats], default=5.51) – The planet density (g/cm^3). Default value is that of Earth.

Returns:

M – The planet mass (Earth masses).

Return type:

float or array[floats]

rho_from_M_R(M, R)

Compute the planet mean density (total mass divided by volume).

Parameters:

M (float or array[floats]) – The planet mass (Earth masses).
R (float or array[floats]) – The planet radius (Earth radii).

Returns:

rho – The planet mean density (g/cm^3).

Return type:

float or array[floats]

tdur_circ(P, Mstar, Rstar)

Compute the transit duration assuming a circular orbit with zero impact parameter.

Parameters:

P (float or array[floats]) – The orbital period (days).
Mstar (float or array[floats]) – The stellar mass (solar masses).
Rstar (float or array[floats]) – The stellar radius (solar radii).

Returns:

tdur – The transit duration (hrs).

Return type:

float or array[floats]

AMD(mu, a, e, im)

Compute the AMD (angular momentum deficit) of a planet(s).

Note

Uses units of G*M_star = 1.

Parameters:

mu (float or array[floats]) – The planet/star mass ratio.
a (float or array[floats]) – The semi-major axis (AU).
e (float or array[floats]) – The orbital eccentricity.
im (float or array[floats]) – The inclination relative to the system invariable plane (radians).

Returns:

amd_pl – The AMD of the planet(s).

Return type:

float or array[floats]

NAMD(m, a, e, im)

Compute the NAMD (normalized angular momentum deficit) of a planetary system.

First defined in Chambers 2001, the NAMD of a system is the AMD divided by the angular momentum of the same system with circular and coplanar orbits.

Parameters:

m (float or array[floats]) – The planet masses (Earth masses).
a (float or array[floats]) – The semi-major axes (AU).
e (float or array[floats]) – The orbital eccentricities.
im (float or array[floats]) – The inclinations relative to the system invariable plane (radians).

Returns:

normed_AMD – The NAMD of the system (unitless).

Return type:

float

photoevap_boundary_Carrera2018(R, P)

Evaluate whether a planet is above or below the ‘photo-evaporation’ valley defined by Eq. 5 in Carrera et al. (2018).

Parameters:

R (float) – The planet radius (Earth radii).
P (float) – The orbital period (days).

Returns:

above_boundary – Whether the planet is above (1) or below (0) the boundary.

Return type:

1 or 0

incl_mult_power_law_Zhu2018(k, sigma_5=0.8, alpha=-3.5)

Compute the Rayleigh scale of the mutual inclination distribution for a given planet multiplicity using the power-law relation.

Note

Default values for the power-law parameters sigma_5 and alpha are set to best-fit values from Zhu et al. (2018).

Parameters:

k (float or array[floats]) – The planet multiplicity.
sigma_5 (float or array[floats], default=0.8) – The normalization (Rayleigh scale of the mutual inclination distribution at k=5) (degrees).
alpha (float or array[floats], default=-3.5) – The power-law index.

Returns:

sigma_k – The Rayleigh scale (degrees) of the mutual inclination distribution for multiplicity k.

Return type:

float or array[floats]

cdf_normal(x, mu=0.0, std=1.0)

Compute the cumulative distribution function (CDF; i.e. the integral between -inf and x of) the normal distribution at x given a mean and standard deviation.

Note

Can deal with array inputs for x, mu, and std as long as they are the same shape.

Parameters:

x (float or array[floats]) – The position to evaluate the CDF (between -inf and inf).
mu (float or array[floats], default=0.) – The mean of the normal distribution.
std (float or array[floats], default=1.) – The standard deviation of the normal distribution.

Returns:

cdf_x – The CDF at x.

Return type:

float or array[floats]

cdf_empirical(xdata, xeval)

Compute the empirical cumulative distribution function (CDF) at xeval given a sample.

Note

Is designed to deal with either scalar or array inputs of xeval.

Parameters:

xdata (array) – The sample of data points.
xeval (float or array[floats]) – The position to evaluate the CDF.

Returns:

cdf_at_xeval – The CDF at xeval.

Return type:

float or array[floats]

calc_f_near_pratios(sssp_per_sys, pratios=[2.0, 1.5, 1.3333333333333333, 1.25], pratio_width=0.05)

Compute the intrinsic fraction of planets ‘near’ a period ratio with another planet for any period ratio in the given list of period ratios.

‘Near’ is defined as a period ratio between pr and pratio*(1+pratio_width) for pratio in pratios.

Note

Defaults to calculating the fraction of all planets near a mean-motion resonance (MMR), defined by res_ratios.

Parameters:

sssp_per_sys (dict) – The dictionary of summary statistics for a physical catalog of planets.
pratios (list, default=res_ratios) – The list of period ratios to consider.
pratio_width (float, default=res_width) – The fractional width to be considered ‘near’ a period ratio.

Returns:

f_mmr – The fraction of planets being ‘near’ at least one of the period ratios.

Return type:

float

compute_ratios_adjacent(x, inverse=False, avoid_div_zeros=False)

Compute an array of the adjacent ratios (e.g. x[j+1]/x[j]) of the terms in the input array x.

Parameters:

x (array[float]) – The input values.
inverse (bool, default=False) – Whether to take the inverse ratios (i.e. x[j]/x[j+1] instead of x[j+1]/x[j]).
avoid_div_zeros (bool, default=False) – Whether to avoid dividing by zeros. If True, will avoid computing ratios where the denominator is zero, and insert either ‘inf’ (when the numerator is non-zero) or ‘nan’ (when the numerator is also zero). If False, the computed ratios will still have the same results, but will produce RuntimeWarning messages.

Returns:

ratios_adj – The ratios of adjacent pairs in x.

Return type:

array[float]

Note

Will return an empty array if there are fewer than two elements in the input array.

compute_ratios_all(x, inverse=False, avoid_div_zeros=False)

Compute an array of all the unique ratios (x[j]/x[i] for all j > i) of the terms in the input array x.

Parameters:

x (array[float]) – The input values.
inverse (bool, default=False) – Whether to take the inverse ratios (i.e. x[j]/x[i] for all j < i instead of for all j > i).
avoid_div_zeros (bool, default=False) – Whether to avoid dividing by zeros (WARNING: not implemented yet!).

Returns:

ratios_all – The ratios of all pairs in x.

Return type:

array[float]

Note

Will return an empty array if there are fewer than two elements in the input array.

bounds_3rd_order_mmr_neighborhood_of_1st_order_mmr(i)

Calculate the ‘neighborhood’ of a 1st order MMR ((i+1)/i), as bounded by the nearest 3rd order MMRs.

Parameters:: i (int) – The index specifying the 1st order MMR (i in (i+1)/i, where the allowed values are i=1,2,3...).
Returns:: bounds – The lower and upper bounds corresponding to the nearest 3rd order MMRs.
Return type:: list

bounds_3rd_order_mmr_neighborhood_of_2nd_order_mmr(i)

Calculate the ‘neighborhood’ of a 2nd order MMR ((n+1)/n, where n=2*i-1), as bounded by the nearest 3rd order MMRs.

Parameters:: i (int) – The index specifying the 2nd order MMR (i such that n=2*i-1 in (n+1)/n; this transformation maps i=1,2,3... to the allowed values of n (odd integers)).
Returns:: bounds – The lower and upper bounds corresponding to the nearest 3rd order MMRs.
Return type:: list

pratio_is_in_any_1st_order_mmr_neighborhood(pratios, i_max=5)

Calculate which period ratios in pratios are within any ‘neighborhood’ of a 1st order MMR, as bounded by the 3rd order MMRs.

Parameters:

pratios (array[floats]) – The period ratios (must be all greater than or equal to 1).
i_max (int, default=5) – The highest 1st order MMR index to consider (i.e. i in (i+1)/i).

Returns:

bools_in_1st_order_mmr_neighborhood (array[bool]) – A boolean array indicating which period ratios are within the neighborhood of a 1st order MMR.
i_of_1st_order_mmr (array[ints]) – An array indicating the 1st order MMR index (i.e. i in (i+1)/i) each period ratio is within the neighborhood of, if any (otherwise 0).

pratio_is_in_any_2nd_order_mmr_neighborhood(pratios, i_max=5)

Calculate which period ratios in pratios are within any ‘neighborhood’ of a 2nd order MMR, as bounded by the 3rd order MMRs.

Parameters:

pratios (array[floats]) – The period ratios (must be all greater than or equal to 1).
i_max (int, default=5) – The highest 2nd order MMR index to consider (i.e. i such that n=2*i-1 in (n+1)/n).

Returns:

bools_in_2nd_order_mmr_neighborhood (array[bool]) – A boolean array indicating which period ratios are within the neighborhood of a 2nd order MMR.
i_of_2nd_order_mmr (array[ints]) – An array indicating the 2nd order MMR index (i.e. `i such that n=2*i-1 in (n+1)/n) each period ratio is within the neighborhood of, if any (otherwise 0).

zeta(pratios, n=2, order=1)

Compute the ‘zeta_{n,order}’ statistic (proximity to any MMR of a given order) for each period ratio in pratios as defined in Lissauer et al. (2011) and Fabrycky et al. (2014).

Parameters:

pratios (array[floats]) – The period ratios (must be all greater than 1).
n (int, default=2) – The number of MMR orders being simultaneously considered. For example, n=2 indicates that the 1st and 2nd order MMRs are being considered, with their neighborhood boundaries set by the 3rd order MMRs.
order (int, default=1) – The MMR order for which ‘zeta’ is computed. For example, order=1 will compute ‘zeta’ as the proximity to any 1st order MMR.

Returns:

zeta_n_order – The ‘zeta_{n,order}’ values corresponding to the period ratios in pratios.

Return type:

array[floats]

Note

The output values of ‘zeta_{n,order}’ are always bounded by [-1,1] assuming the period ratios are all within a ‘neighborhood’ of an MMR for the n and order being considered. For n=1, all period ratios in (1,3] (for order=1) and all period ratios in (1,5] (for order=2) belong to a neighorhood. For n=2, use syssimpyplots.general.pratio_is_in_any_1st_order_mmr_neighborhood() and syssimpyplots.general.pratio_is_in_any_2nd_order_mmr_neighborhood() to figure out which period ratios are within the relevant neighborhoods.

zeta_2_order(pratios)

Compute the ‘zeta_{2,order}’ statistic (proximity to any 1st or 2nd order MMR) for each period ratio in pratios.

Wrapper for the function syssimpyplots.general.zeta().

Note

Will first calculate whether each period ratio in pratios belongs to a neighborhood of a 1st or 2nd order MMR (as bounded by the 3rd order MMRs), and then calculate either ‘zeta_{2,1}’ or ‘zeta_{2,2}’, respectively. Will consider up to i_max=20 indices of each of the 1st and 2nd order MMRs; for even higher orders, will return NaN.

Parameters:

pratios (array[floats]) – The period ratios (must all be in the range (1,4]).

Returns:

zeta_2_1or2 (array[floats]) – The ‘zeta_{2,order}’ values corresponding to the period ratios in pratios, where order = 1 or 2.
bools_in_1st, bools_in_2nd (array[bools]) – Arrays of booleans indicating which values in zeta_2_1or2 belong to order = 1 or 2, respectively.

split_colors_per_cdpp_bin(stars_cleaned, nbins=10)

Return the indices of the bluer and redder stars that split the stellar sample into two samples based on the histogram of combined differential photometric precision (CDPP) values.

Note

Uses log-uniform bins for the histograms.

Parameters:

stars_cleaned (structured array) – A table of stars, including columns for 4.5hr CDPP (rrmscdpp04p5) and Gaia DR2 bp-rp color (bp_rp).
nbins (int, default=10) – The number of bins to use.

Returns:

bins (array[floats]) – The bin edges.
i_blue_per_bin (array[floats]) – The indices corresponding to the rows of bluer stars in each bin.
i_red_per_bin (array[floats]) – The indices corresponding to the rows of redder stars in each bin.

linear_fswp_bprp(bprp, bprp_med, fswp_med=0.5, slope=0.0)

Evaluate the fraction of stars with planets (fswp) at a number of bp-rp colors using a linear relation.

Note

The fswp cannot be negative or greater than one.

Parameters:

bprp (array[floats]) – The bp-rp colors at which to evaluate the fswp.
bprp_med (float) – The median bp-rp color (or some normalization point).
fswp_med (float, default=0.5) – The fswp at bprp_med (normalization).
slope (float, default=0.) – The slope of the linear relation.

Returns:

fswp_bprp – The fswp at each bp-rp color.

Return type:

array[floats]

linear_alphaP_bprp(bprp, bprp_med, alphaP_med=0.5, slope=0.0)

Evaluate the period power-law index at a number of bp-rp colors using a linear relation.

Parameters:

bprp (array[floats]) – The bp-rp colors at which to evaluate the fswp.
bprp_med (float) – The median bp-rp color (or some normalization point).
alphaP_med (float, default=0.5) – The period power-law index at bprp_med (normalization).
slope (float, default=0.) – The slope of the linear relation.

Returns:

alphaP_bprp – The period power-law index at each bp-rp color.

Return type:

array[floats]

bin_Nmult(Nmult_obs, m_geq=5)

Bins the higher orders of the input multiplicity distribution.

Parameters:

Nmult_obs (array[ints]) – The multiplicity distribution for consecutive multiplicity orders (i.e. number of systems with 1,2,3,… planets).
m_geq (int, default=5) – The multiplicity order at and above which to bin together.

Returns:

Nmult_obs – The multiplicity distribution with multiplicity orders greater than or equal to m_geq binned together. For the default m_geq=5, this is the number of systems with 1,2,3,4,5+ planets.

Return type:

array[ints]

Shannon_entropy(p)

Compute the Shannon entropy.

Note

Assumes base-natural log, although any choice is valid.

Parameters:: p (array[floats]) – An array of probabilities (values between 0 and 1).
Returns:: H – The Shannon entropy.
Return type:: float

disequilibrium(p)

Compute the disequilibrium of a system.

Parameters:: p (array[floats]) – An array of probabilities (values between 0 and 1).
Returns:: D – The disequilibrium.
Return type:: float

LMC_complexity(K, p)

Compute the Lopez-Ruiz, Mancini, and Calbet (1995) complexity, which is the product of Shannon entropy and disequilibrium.

Parameters:

K (float) – The normalization constant.
p (array[floats]) – An array of probabilities (values between 0 and 1).

Returns:

C – The LMC complexity.

Return type:

float

Pearson_correlation_coefficient(x, y): Compute the Pearson correlation coefficient of two variables.

Spearman_correlation_coefficient(x, y)

Compute the Spearman correlation coefficient of two variables.

This is the Pearson correlation coefficient applied to the ranks of the variables.

radii_star_ratio(r, Rstar)

Compute the sum of planet/star radius ratios for a system.

Parameters:

r (array[floats]) – The planet radii.
Rstar (float) – The stellar radius.

Returns:

mu – The sum of the planet/star radius ratios.

Return type:

float

partitioning(x)

Compute the ‘partitioning’ of a quantity x for the system.

For example, if x is an array of planet masses, this is the ‘mass partitioning’ quantity.

Parameters:: x (array[floats]) – The partitions of the quantity.
Returns:: Q – The partitioning metric for the quantity (between 0 and 1).
Return type:: float

monotonicity_GF2020(x)

Compute the ‘monotonicity’ (a measure of the degree of ordering) of a quantity x for the system, defined in Gilbert and Fabrycky (2020).

For example, if x is an array of planet radii, this is the ‘radius monotonicity’ quantity.

Parameters:: x (array[floats]) – The array of quantities.
Returns:: M – The monotonicity of the quantity.
Return type:: float

gap_complexity_GF2020(P)

Compute the ‘gap complexity’ metric of a planetary system, as defined in Gilbert and Fabrycky (2020).

Parameters:: P (array[floats]) – The array of orbital periods (days). Does not have to be sorted.
Returns:: C – The gap complexity of the system.
Return type:: float

Cmax_table_GF2020(n)

Return the value of ‘C_max’, based on the number of gaps n (i.e. the number of planets minus 1) in the system.

This is a normalization used in the gap complexity metric, with the values computed by Gilbert and Fabrycky (2020).

Note

The table of ‘C_max’ only goes up to n=9; for greater numbers of gaps, use the approximation function syssimpyplots.general.Cmax_approx_GF2020().

Cmax_approx_GF2020(n): Compute an approximation for the value of ‘C_max’ based on the number of gaps, defined in Gilbert and Fabrycky (2020).

dispersion_W2022(x, x_norm=1.0)

Compute the ‘dispersion’ of a quantity ‘x’ for the system, defined as the variance of the log10(x) values (Weiss et al. 2022).

For example, if x is an array of planet radii, this is the ‘radius dispersion’ quantity.

Parameters:

x (array[floats]) – The quantities (must be all positive).
x_norm (float) – The normalization unit for ‘x’.

Returns:

σ_sq – The ‘dispersion’ of the quantity.

Return type:

float

class MidPointLogNorm(*args: Any, **kwargs: Any): Set the midpoint of a colormap on a log scale, taken from: https://stackoverflow.com/questions/48625475/python-shifted-logarithmic-colorbar-white-color-offset-to-center (in a post by ImportanceOfBeingErnest)