load_sims.py

read_targets_period_radius_bounds(file_name)

Read the number of simulated targets and bounds for the planet periods and radii from a file.

Parameters:

file_name (str) – The path/name of the file containing a header with simulation parameters.

Returns:

N_sim (int) – The number of simulated systems.
cos_factor (float) – The cosine of the maximum inclination angle (relative to the sky plane) drawn for the reference planes of the simulated systems (between 0 and 1).
P_min (float) – The minimum orbital period (days).
P_max (float) – The maximum orbital period (days).
radii_min (float) – The minimum planet radius (Earth radii).
radii_max (float) – The maximum planet radius (Earth radii).

read_sim_params(file_name)

Read the simulation parameters from a file and output them in a dictionary.

Parameters:: file_name (str) – The path/name of the file containing a header with simulation parameters.
Returns:: param_vals – A dictionary containing the simulation parameters.
Return type:: dict

The full list of possible parameters is defined in param_symbols (also exported by this module).

load_cat_phys(file_name)

Load a table with all the planets in a simulated physical catalog.

Parameters:: file_name (str) – The path/name of the file for the physical catalog (should end with ‘physical_catalog.csv’).
Returns:: cat_phys – A table with the physical properties of all the planets.
Return type:: structured array

The table has the following columns:

target_id: The index of the star in the simulation (e.g. 1 for the first star) which the planet orbits.
star_id: The index of the star based on where it is in the input stellar catalog.
planet_mass: The planet mass (solar masses).
planet_radius: The planet radius (solar radii).
clusterid: A cluster identifier.
period: The orbital period (days).
ecc: The orbital eccentricity.
incl: The orbital inclination (radians) relative to the sky plane.
omega: The argument of periapsis (radians) relative to the sky plane.
asc_node: The argument of ascending node (radians) relative to the sky plane.
mean_anom: The mean anomaly (radians) relative to the sky plane.
incl_invariable: The orbital inclination (radians) relative to the system invariable plane.
asc_node_invariable: The argument of ascending node (radians) relative to the system invariable plane.
star_mass: The stellar mass (solar masses).
star_radius: The stellar radius (solar radii).

load_star_phys(file_name)

Load a table of only the stars with planets in a simulated physical catalog.

Parameters:: file_name (str) – The path/name of the file for the stellar physical catalog (should end with ‘physical_catalog_stars.csv’).
Returns:: star_phys – A table with basic properties of the planet-hosting stars.
Return type:: structured array

The table has the following columns:

target_id: The index of the star in the simulation (e.g. 1 for the first star) which the planet orbits.
star_id: The index of the star based on where it is in the input stellar catalog.
star_mass: The stellar mass (solar masses).
star_radius: The stellar radius (solar radii).
num_planets: The number of planets in the system.

load_planets_stars_phys_separate(file_name_path, run_number)

Load individual files with the properties of all the planets and stars in a simulated physical catalog.

Note

Faster than syssimpyplots.load_sims.load_cat_phys() for large catalogs, but returns individual lists instead of a single table. Each list is ordered in the same way so the planet properties can be matched to each other.

Parameters:

file_name_path (str) – The path to the physical catalog.
run_number (str or int) – The run number appended to the file names for the physical catalog.

Returns:

clusterids_per_sys (list[list]) – The cluster id’s of each system.
P_per_sys (list[list]) – The orbital periods (days) of each system.
radii_per_sys (list[list]) – The planet radii (solar radii) of each system.
mass_per_sys (list[list]) – The planet masses (solar masses) of each system.
e_per_sys (list[list]) – The orbital eccentricities of each system.
inclmut_per_sys (list[list]) – The orbital inclinations (radians) relative to the system invariable plane of each system.
incl_per_sys (list[list]) – The orbital inclinations (radians) relative to the sky plane of each system.
Mstar_all (array[float]) – The stellar mass (solar masses) of each system.
Rstar_all (array[float]) – The stellar radius (solar radii) of each system.

compute_basic_summary_stats_per_sys_cat_phys(clusterids_per_sys, P_per_sys, radii_per_sys, mass_per_sys, e_per_sys, inclmut_per_sys, incl_per_sys, Mstar_all, Rstar_all)

Compute the basic summary statistics per system in a physical catalog.

Note

The input parameters should be returned by the function syssimpyplots.load_sims.load_planets_stars_phys_separate() and requires the individual lists to be ordered in the same way.

Parameters:

clusterids_per_sys (list[list]) – A list of lists with the cluster id’s for each system.
P_per_sys (list[list]) – A list of lists with the orbital periods (days) for each system.
radii_per_sys (list[list]) – A list of lists with the planet radii (solar radii) for each system.
mass_per_sys (list[list]) – A list of lists with the planet masses (solar masses) for each system.
e_per_sys (list[list]) – A list of lists with the orbital eccentricities for each system.
inclmut_per_sys (list[list]) – A list of lists with the orbital inclinations (radians) relative to the system invariable plane for each system.
incl_per_sys (list[list]) – A list of lists with the orbital inclinations (radians) relative to the sky plane for each system.
Mstar_all (array[float]) – The stellar mass (solar masses) for each system.
Rstar_all (array[float]) – The stellar radius (solar radii) for each system.

Returns:

sssp_per_sys_basic – A dictionary containing planetary and stellar properties for each system.

Return type:

dict

The output is a dictionary containing the following fields:

Mmax: The maximum planet multiplicity of any system.
Mtot_all: The planet multiplicity of each system (1-d array).
clustertot_all: The number of planet clusters in each system (1-d array).
pl_per_cluster_all: The number of planets in each cluster (1-d array).
P_all: The orbital periods (days) of each system (2-d array).
clusterids_all: The cluster id’s of each system (2-d array).
e_all: The orbital eccentricities of each system (2-d array).
inclmut_all: The orbital inclinations (radians) relative to system invariable plane of each system (2-d array).
incl_all: The orbital inclinations (radians) relative to the sky plane of each system (2-d array).
radii_all: The planet radii (Earth radii) of each system (2-d array).
mass_all: The planet masses (Earth masses) of each system (2-d array).
Mstar_all: The stellar mass (solar masses) of each system (1-d array).
Rstar_all: The stellar radius (solar radii) of each system (1-d array).
mu_all: The planet/star mass ratios of each system (2-d array).
a_all: The semi-major axes (AU) of each system (2-d array).
AMD_all: The AMDs (units of G*Mstar=1) of each system (2-d array).
AMD_tot_all: The total AMD (units of G*Mstar=1) of each system (1-d array).

Warning

For the 2-d arrays, each row is padded with zeros (or negative ones), since different systems have different numbers of planets.

load_cat_phys_separate_and_compute_basic_summary_stats_per_sys(file_name_path, run_number)

Load a physical catalog and compute the basic summary statistics per system.

Wrapper for the functions syssimpyplots.load_sims.load_planets_stars_phys_separate() and syssimpyplots.load_sims.compute_basic_summary_stats_per_sys_cat_phys().

Parameters:

file_name_path (str) – The path to the physical catalog.
run_number (str or int) – The run number appended to the file names for the physical catalog.

Returns:

sssp_per_sys_basic – A dictionary containing planetary and stellar properties for each system. See the documentation for syssimpyplots.load_sims.compute_basic_summary_stats_per_sys_cat_phys() for a description of the dictionary fields.

Return type:

dict

compute_summary_stats_from_cat_phys(cat_phys=None, star_phys=None, file_name_path=None, run_number='', load_full_tables=False, compute_ratios=<function compute_ratios_adjacent>, match_observed=True)

Compute detailed summary statistics per system in a simulated physical catalog.

Note

This function can be used by either passing a cat_phys and star_phys for the physical catalog, or by passing a file_name_path and run_number from which to load the physical catalog. If the latter, will load the individual files with the planet and star properties using syssimpyplots.load_sims.load_planets_stars_phys_separate().

Parameters:

cat_phys (structured array, default=None) – A table with the physical properties of all the planets.
star_phys (structured array, default=None) – A table with the basic properties of the planet-hosting stars.
file_name_path (str, default=None) – The path to the physical catalog.
run_number (str or int, default='') – The run number appended to the file names for the physical catalog.
load_full_tables (bool, default=False) – Whether to load full tables of the physical catalogs. Required to be True if also want to match the physical planets to the observed planets.
compute_ratios (func, default=compute_ratios_adjacent) – The function to use for computing ratios; can be either syssimpyplots.general.compute_ratios_adjacent() or syssimpyplots.general.compute_ratios_all().
match_observed (bool, default=True) – Whether to match the physical planets to the observed planets. If True, the output will also contain a field det_all.

Returns:

sssp_per_sys (dict) – A dictionary containing the planetary and stellar properties for each system (2-d and 1-d arrays).
sssp (dict) – A dictionary containing the planetary and stellar properties of all planets (1-d arrays).

The outputs are two dictionaries. sssp_per_sys contains the following fields:

det_all: The detection flags (1=detected, 0=undetected) of the planets in each system (2-d array). Only returned if match_observed=True.
Mtot_all: The number of planets in each system (1-d array).
clusterids_all: The cluster id’s of each system (2-d array).
P_all: The orbital periods (days) of each system (2-d array).
a_all: The semi-major axes (AU) of each system (2-d array).
radii_all: The planet radii (Earth radii) of each system (2-d array).
mass_all: The planet masses (Earth masses) of each system (2-d array).
mu_all: The planet/star mass ratios of each system (2-d array).
e_all: The orbital eccentricities of each system (2-d array).
inclmut_all: The orbital inclinations (radians) relative to the system invariable plane of each system (2-d array).
incl_all: The orbital inclinations (radians) relative to the sky plane of each system (2-d array).
AMD_all: The AMDs (units of G*Mstar=1) of each system (2-d array).
Rm_all: The period ratios of each system (2-d array).
radii_ratio_all: The planet radius ratios of each system (2-d array).
N_mH_all: The planet spacings in mutual Hill radii of each system (2-d array).
dynamical_mass: The ‘dynamical mass’ of each system (1-d array).
radii_partitioning: The ‘radius partitioning’ of each multi-planet system (1-d array).
radii_monotonicity: The ‘radius monotonicity’ of each multi-planet system (1-d array).
gap_complexity: The ‘gap complexity’ of each system with 3+ planets (1-d array).

sssp contains the following fields:

Mstar_all: The stellar mass (solar masses) of each system (1-d array).
Rstar_all: The stellar radius (solar radii) of each system (1-d array).
clustertot_all: The number of planet clusters in each system (1-d array).
AMD_tot_all: The total AMD (units of G*Mstar=1) of each system (1-d array).
pl_per_cluster_all: The number of planets in each cluster (1-d array).
P_all: The orbital periods (days) of all planets (1-d array).
radii_all: The radii (Earth radii) of all planets (1-d array).
mass_all: The masses (Earth masses) of all planets (1-d array).
e_all: The orbital eccentricities of all planets (1-d array).
inclmut_all: The orbital inclinations (radians) of all planets relative to the system invariable planes (1-d array).
incl_all: The orbital inclinations (radians) of all planets relative to the sky plane (1-d array).
radii_above_all: The radii (Earth radii) of all planets above the photo-evaporation boundary* (1-d array).
radii_below_all: The radii (Earth radii) of all planets below the photo-evaporation boundary* (1-d array).
Rm_all: The orbital period ratios (1-d array).
radii_ratio_all: The planet radii ratios (1-d array).
N_mH_all: The planet spacings in mutual Hill radii (1-d array).
radii_ratio_above_all: The planet radii ratios for all planets above the photo-evaporation boundary* (1-d array).
radii_ratio_below_all: The planet radii ratios for all planets below the photo-evaporation boundary* (1-d array).
radii_ratio_across_all: The planet radii ratios for all planets across the photo-evaporation boundary* (1-d array).

Note

*The photo-evaporation boundary is defined by the function syssimpyplots.general.photoevap_boundary_Carrera2018().

Warning

For the 2-d arrays, each row is padded with zeros (or negative ones), since different systems have different numbers of planets.

load_cat_obs(file_name)

Load a table with all the planets in a simulated observed catalog.

Parameters:: file_name (str) – The path/name of the file for the observed catalog (should end with ‘observed_catalog.csv’).
Returns:: cat_obs – A table with the observed properties of all the planets.
Return type:: structured array

The table has the following columns:

target_id: The index of the star in the simulation (e.g. 1 for the first star) which the planet orbits.
star_id: The index of the star based on where it is in the input stellar catalog.
period: The observed orbital period (days).
period_err: The uncertainty in observed orbital period (days).
depth: The observed transit depth.
depth_err: The uncertainty in observed transit depth.
duration: The observed transit duration (days).
duration_err: The uncertainty in observed transit duration (days).
star_mass: The stellar mass (solar masses).
star_radius: The stellar radius (solar radii).

load_star_obs(file_name)

Load a table of only the stars with observed planets in a simulated observed catalog.

Parameters:: file_name (str) – The path/name of the file for the stellar physical catalog (should end with ‘observed_catalog_stars.csv’)
Returns:: star_obs – A table with the basic properties of the observed planet-hosting stars.
Return type:: structured array

The table has the same columns as those returned by the function syssimpyplots.load_sims.load_star_phys().

load_planets_stars_obs_separate(file_name_path, run_number)

Load individual files with the properties of all the planets and stars in a simulated observed catalog.

Note

Faster than syssimpyplots.load_sims.load_cat_obs() for large catalogs, but returns individual lists instead of a single table. Each list is ordered in the same way (low to high observed multiplicity) so the planet properties can be matched to each other.

Parameters:

file_name_path (str) – The path to the observed catalog.
run_number (str or int) – The run number appended to the file names for the observed catalog.

Returns:

P_per_sys (list[list]) – The observed orbital periods (days) of each system.
D_per_sys (list[list]) – The observed transit depths of each system.
tdur_per_sys (list[list]) – The observed transit durations (days) of each system.
Mstar_per_sys (array[float]) – The stellar mass (solar masses) of each system.
Rstar_per_sys (array[float]) – The stellar radius (solar radii) of each system.

count_planets_from_loading_cat_obs_stars_only(file_name_path=None, run_number='', Rstar_min=0.0, Rstar_max=10.0, Mstar_min=0.0, Mstar_max=10.0, teff_min=0.0, teff_max=10000.0, bp_rp_min=-5.0, bp_rp_max=5.0)

Count the number of observed planets in each system (and the resulting observed multiplicity distribution), given a set of stellar cuts.

Note

Loads an ‘observed_catalog_stars.csv’ file (using syssimpyplots.load_sims.load_star_obs()) and a table of cleaned Kepler target stars (using syssimpyplots.compare_kepler.load_Kepler_stars_cleaned()).

Parameters:

file_name_path (str, default=None) – The path to the observed catalog.
run_number (str or int, default='') – The run number appended to the file names for the observed catalog.
Rstar_min (float, default=0.) – The minimum stellar radius (solar radii) to include in the sample.
Rstar_max= (float, default=10.) – The maximum stellar radius (solar radii) to include in the sample.
Mstar_min (float, default=0.) – The minimum stellar mass (solar masses) to include in the sample.
Mstar_max (float, default=10.) – The maximum stellar mass (solar masses) to include in the sample.
teff_min (float, default=0.) – The minimum stellar effective temperature (K) to include in the sample.
teff_max (float, default=1e4) – The maximum stellar effective temperature (K) to include in the sample.
bp_rp_min (float, default=-5.) – The minimum Gaia DR2 bp-rp color to include in the sample.
bp_rp_max (float, default=5.) – The maximum Gaia DR2 bp-rp color to include in the sample.

Returns:

Mtot_obs (array[int]) – The number of observed planets in each system.
Nmult_obs (array[int]) – The observed multiplicity distribution (number of observed systems at each multiplicity order).

compute_summary_stats_from_cat_obs(cat_obs=None, star_obs=None, file_name_path=None, run_number='', P_min=0.0, P_max=300.0, Rstar_min=0.0, Rstar_max=10.0, Mstar_min=0.0, Mstar_max=10.0, teff_min=0.0, teff_max=10000.0, bp_rp_min=-5.0, bp_rp_max=5.0, i_stars_custom=None, compute_ratios=<function compute_ratios_adjacent>)

Compute detailed summary statistics per system in a simulated observed catalog.

Note

This function can be used by either passing a cat_obs and star_obs for the observed catalog, or by passing a file_name_path and run_number from which to load the observed catalog. If the latter, will load the individual files with the planet and star properties using syssimpyplots.load_sims.load_planets_stars_obs_separate().

Parameters:

cat_obs (structured array, default=None) – A table with the observed properties of the planets.
star_obs (structured array, default=None) – A table with the basic properties of the observed planet-hosting stars.
file_name_path (str, default=None) – The path to the observed catalog.
run_number (str or int, default='') – The run number appended to the file names for the observed catalog.
P_min (float, default=0.) – The minimum orbital period to include in the sample.
P_max (float, default=300.) – The maximum orbital period to include in the sample.
Rstar_min (float, default=0.) – The minimum stellar radius (solar radii) to include in the sample.
Rstar_max (float, default=10.) – The maximum stellar radius (solar radii) to include in the sample.
Mstar_min (float, default=0.) – The minimum stellar mass (solar masses) to include in the sample.
Mstar_max (float, default=10.) – The maximum stellar mass (solar masses) to include in the sample.
teff_min (float, default=0.) – The minimum stellar effective temperature (K) to include in the sample.
teff_max (float, default=10.) – The maximum stellar effective temperature (K) to include in the sample.
bp_rp_min (float, default=-5.) – The minimum Gaia DR2 bp-rp color to include in the sample.
bp_rp_max (float, default=5.) – The maximum Gaia DR2 bp-rp color to include in the sample.
i_stars_custom (array[int], default=None) – An array of indices for the stars in the Kepler stellar catalog to be included in the sample.
compute_ratios (func, default=compute_ratios_adjacent) – The function to use for computing ratios; can be either syssimpyplots.general.compute_ratios_adjacent() or syssimpyplots.general.compute_ratios_all().

Returns:

sss_per_sys (dict) – A dictionary containing the planetary and stellar properties for each observed system (2-d and 1-d arrays).
sss (dict) – A dictionary containing the planetary and stellar properties of all observed planets (1-d arrays).

The outputs are two dictionaries. sss_per_sys contains the following fields:

Mstar_obs: The stellar mass (solar masses) of each system (1-d array).
Rstar_obs: The stellar radius (solar radii) of each system (1-d array).
teff_obs: The stellar effective temperature (K) of each system (1-d array).
bp_rp_obs: The Gaia DR2 bp-rp color (mag) of each system (1-d array).
e_bp_rp_obs: The extinction in bp-rp color interpolated from a model, of each system (1-d array).
cdpp4p5_obs: The 4.5 hr duration combined differential photometric precision of each system (1-d array).
Mtot_obs: The observed number of planets in each system (1-d array).
P_obs: The observed orbital periods (days) of each system (2-d array).
D_obs: The observed transit depths of each system (2-d array).
tdur_obs: The observed transit durations of each system (2-d array).
tdur_tcirc_obs: The observed transit durations normalized by the durations of the circular orbits of each system (2-d array).
radii_obs: The observed planet radii (Earth radii) of each system (2-d array).
Rm_obs: The observed period ratios of each system (2-d array).
D_ratio_obs: The observed transit depth ratios of each system (2-d array).
xi_obs: The observed period-normalized transit duration ratios (‘xi’ values) of each system (2-d array).
xi_res_obs: The observed ‘xi’ values of planet-pairs near a resonance* (2-d array).
xi_res32_obs: The observed ‘xi’ values of planet-pairs near the 3:2 resonance (2-d array).
xi_res21_obs: The observed ‘xi’ values of planet-pairs near the 2:1 resonance (2-d array).
xi_nonres_obs: The observed ‘xi’ values of planet-pairs not near any resonances* (2-d array).
radii_star_ratio: The observed sum of planet/star radius ratios of each system (1-d array).
radii_partitioning: The observed ‘radius partitioning’ of each multi-planet system (1-d array).
radii_monotonicity: The observed ‘radius monotonicity’ of each multi-planet system (1-d array).
gap_complexity: The observed ‘gap complexity’ of each system with 3+ planets (1-d array).

sss contains the following fields:

Mstar_obs: The stellar mass (solar masses) of each system, repeated for each planet in the system (1-d array).
Rstar_obs: The stellar radius (solar radii) of each system, repeated for each planet in the system (1-d array).
teff_obs: The stellar effective temperature (K) of each system, repeated for each planet in the system (1-d array).
bp_rp_obs: The Gaia DR2 bp-rp color (mag) of each system, repeated for each planet in the system (1-d array).
e_bp_rp_obs: The extinction in bp-rp color interpolated from a model, of each system, repeated for each planet in the system (1-d array).
cdpp4p5_obs: The 4.5 hr duration combined differential photometric precision of each system, repeated for each planet in the system (1-d array).
Nmult_obs: The observed multiplicity distribution (1-d array).
P_obs: The observed periods (days) of all observed planets (1-d array).
D_obs: The observed transit depths of all observed planets (1-d array).
tdur_obs: The observed transit duration (hrs) of all observed planets (1-d array).
tdur_tcirc_obs: The observed transit durations normalized by the durations of the circular orbits, of all observed planets (1-d array).
tdur_tcirc_1_obs: The observed transit durations normalized by the durations of the circular orbits, of all observed single planets (1-d array).
tdur_tcirc_2p_obs: The observed transit durations normalized by the durations of the circular orbits, of all observed multi-planets (1-d array).
radii_obs: The observed radii (Earth radii) of all observed planets (1-d array).
D_above_obs: The observed transit depths of all planets above the photo-evaporation boundary** (1-d array).
D_below_obs: The observed transit depths of all planets below the photo-evaporation boundary** (1-d array).
Rm_obs: The observed period ratios (1-d array).
D_ratio_obs: The observed transit depth ratios (1-d array).
xi_obs: The observed ‘xi’ values (1-d array).
xi_res_obs: The observed ‘xi’ values of all planet-pairs near a resonance* (1-d array).
xi_res32_obs: The observed ‘xi’ values of all planet-pairs near the 3:2 resonance (1-d array).
xi_res21_obs: The observed ‘xi’ values of all planet-pairs near the 2:1 resonance (1-d array).
xi_nonres_obs: The observed ‘xi’ values of all planet-pairs not near any resonances* (1-d array).
D_ratio_above_obs: The observed transit depth ratios of all planets above the photo-evaporation boundary** (1-d array).
D_ratio_below_obs: The observed transit depth ratios of all planets below the photo-evaporation boundary** (1-d array).
D_ratio_across_obs: The observed transit depth ratios of all planets across the photo-evaporation boundary** (1-d array).

Note

*As defined by res_ratios and res_width in general.py.

**The photo-evaporation boundary defined by the function syssimpyplots.general.photoevap_boundary_Carrera2018().

Warning

For the 2-d arrays, each row is padded with zeros (or negative ones), since different systems have different numbers of observed planets.
The observed transit durations (tdur_obs, and thus also fields involving tdur_tcirc_obs and xi_obs) can be zero!

combine_sss_or_sssp_per_sys(s1, s2)

Combine two dictionaries of summary statistics (e.g., two simulated catalogs).

Note

Requires both dictionaries to have the exact same fields.

Parameters:

s1 (dict) – A dictionary of summary statistics.
s2 (dict) – A dictionary of summary statistics.

Returns:

scombined – The combined dictionary of summary statistics.

Return type:

dict

load_cat_phys_multiple_and_compute_combine_summary_stats(file_name_path, run_numbers=range(1, 11), load_full_tables=False, compute_ratios=<function compute_ratios_adjacent>, match_observed=True)

Load multiple simulated physical catalogs and compute detailed summary statistic for all the catalogs combined.

Parameters:

file_name_path (str) – The path to the physical catalogs.
run_numbers (range or list[int], default=range(1,11)) – The range of catalog run numbers over which we want to load and combine.
load_full_tables (bool, default=False) – Whether to load full tables of the physical catalogs. Required to be True if also want to match the physical planets to the observed planets.
compute_ratios (func, default=compute_ratios_adjacent) – The function to use for computing ratios; can be either syssimpyplots.general.compute_ratios_adjacent() or syssimpyplots.general.compute_ratios_all().
match_observed (bool, default=True) – Whether to match the physical planets to the observed planets. If True, the output will also contain a field det_all.

Returns:

sssp_per_sys (dict) – A dictionary containing the planetary and stellar properties for each system (2-d and 1-d arrays).
sssp (dict) – A dictionary containing the planetary and stellar properties of all planets (1-d arrays).

The fields of sssp_per_sys and sssp are the same as those returned by syssimpyplots.load_sims.compute_summary_stats_from_cat_phys().