ysoisochrone.utils

Module Contents

Functions

unc_log10	Propagates uncertainties from the linear scale to the logarithmic scale (base 10).
unc_linear_from_log	Propagates uncertainties from the logarithmic scale (base 10) back to the linear scale.
assign_unc_teff	assign the Teff uncertainties
assign_unc_lumi	assign the luminosity uncertainties
get_likelihood_p2016	Calculates the likelihood function lfunc given the input log temperature and luminosity. L is the likelihood function see eq. 1 in Pasucci+2016 NOTE in Pascucci+2016, eq. 1 appears using Teff and Lbol in linear space but the code actually uses logTeff and logLbol, so the prior is log-uniform for both. This gives more accurate results than the linear-uniform for Teff and Lbol because linearly uniform priors would create a bias for hotter and brighter stars. Both the shape of the initial mass function of stars and their evolutionary timescales imply that the occurrence of stars decreases as a function of Teff and L. Therefore a log-uniform prior as adopted here is more accurate.
_normalize_pdf	Normalize a non-negative array for numerical stability. method: ‘maxone’ (default), ‘sumone’, or ‘none’
_eval_1d_prior_on_grid	Evaluate a 1D prior on an arbitrary grid (x_grid).
download_file_simple	Downloads a file from a given URL and saves it to the specified path.
download_file	Downloads a file from a given URL and saves it to the specified path with a customizable progress bar.
extract_tarball	Extracts a tarball file into a specified directory.
load_builtin_matrix	Load a .mat grid that is shipped with the ysoisochrone package.
download_baraffe_tracks	Downloads the Baraffe BHAC15 tracks file and saves it to the specified directory.
read_baraffe_file	Reads the original BHAC15 tracks file and parses the mass, age, and logtlogl.
download_feiden_trk_tracks	Downloads (all .trk files and [optional]) the tarball from the specified GitHub folder and saves them to the given directory. The tarball is extracted after downloading.
read_feiden_trk_file	Reads all the Feiden track files (*.trk) in the given directory, extracts the age and stellar parameters, and organizes the data into numpy arrays.
download_feiden_iso_tracks	Downloads all .iso files and the tarball from the specified GitHub folder and saves them to the given directory. The tarball is extracted after downloading.
read_feiden_iso_file	Reads all the Feiden track files (*.iso) in the given directory, extracts the age and stellar parameters, and organizes the data into numpy arrays.
download_parsec_v1p2_tracks	Downloads the PARSECv1p2 tracks tarball from the specified link and saves it to the given directory. The tarball is extracted after downloading.
read_parsec_v1p2_dat_file	Reads all the PARSECv1p2 track files (*.DAT) in the given directory, extracts the mass, age, and stellar parameters (log(Teff), log(L)). Organizes the data into numpy arrays.
download_parsec_v2p0_tracks	Downloads the PARSEC v2.0 tracks zip file and extracts it to the given directory.
read_parsec_v2p0_tab_file	Reads all the PARSECv2.0 track files (*.TAB) in the given directory, extracts the mass, age, and stellar parameters (log(Teff), log(L)). Organizes the data into numpy arrays.
download_mist_v1p2_eep_tracks	Downloads the MIST v1.2 tracks tarball and extracts it to the given directory.
download_mist_v1p2_iso_tracks	Downloads the MIST v1.2 tracks tarball and extracts it to the given directory.
read_mist_v1p2_iso_file	Reads the MISTv1p2 isochrone file in the given directory, extracts the star mass, log(Teff), and log(L/Lo). Organizes the data into numpy arrays.
create_meshgrid_legacy	Creates a meshgrid for log_age and masses, and populates it with Teff and luminosity. The choice of the grid is adopted in Pascucci+2016, which worked fine with Feiden and Baraffe tacks But this choice cannot be adopted for older targets beyond 50 Myrs.
create_meshgrid	Creates a meshgrid for log_age and masses, and populates it with Teff and luminosity.
save_as_mat	Saves the extracted data into a .mat file.
compare_grids	Compares the Python and IDL-generated grids by interpolating the Python grid onto the sparser IDL grid and plotting the differences.
find_zams_index	Finds the index corresponding to the Zero-Age Main Sequence (ZAMS) for a given stellar track.
find_zams_curve	Find the Zero-Age Main Sequence (ZAMS) curve and mask the isochrone data beyond the ZAMS.

API

ysoisochrone.utils.unc_log10(x, err_x)

Propagates uncertainties from the linear scale to the logarithmic scale (base 10).

Args:

value: [float]

The value in linear scale (e.g., Teff, Luminosity, etc.).

err_x: [float]

The uncertainty in the linear value.

Returns:

err_log10_x: [float]

The propagated uncertainty in the logarithmic scale (base 10).

ysoisochrone.utils.unc_linear_from_log(log_value, log_uncertainty)

Propagates uncertainties from the logarithmic scale (base 10) back to the linear scale.

Args:

log_value: [float]

The value in logarithmic scale (e.g., log(Teff), log(L), etc.).

log_uncertainty: [float]

The uncertainty in the logarithmic value.

Returns:

linear_uncertainty: [float]

The propagated uncertainty in the linear scale.

ysoisochrone.utils.assign_unc_teff(teff_ar, sigma_logT_set=None)

assign the Teff uncertainties

Args:

teff_ar: [array]

the array for Teff

Returns:

err_teff_ar: [array]

the array of Teff

ysoisochrone.utils.assign_unc_lumi(lumi_ar, sigma_logL_set=None)

assign the luminosity uncertainties

Args:

lumi_ar: [array]

the array for luminosity

Returns:

err_lumi_ar: [array]

the array of luminosity

ysoisochrone.utils.get_likelihood_p2016(logtlogl_dummy, c_logT, c_logL, sigma_logT, sigma_logL)

Calculates the likelihood function lfunc given the input log temperature and luminosity. L is the likelihood function see eq. 1 in Pasucci+2016 NOTE in Pascucci+2016, eq. 1 appears using Teff and Lbol in linear space but the code actually uses logTeff and logLbol, so the prior is log-uniform for both. This gives more accurate results than the linear-uniform for Teff and Lbol because linearly uniform priors would create a bias for hotter and brighter stars. Both the shape of the initial mass function of stars and their evolutionary timescales imply that the occurrence of stars decreases as a function of Teff and L. Therefore a log-uniform prior as adopted here is more accurate.

Args:

logtlogl_dummy: [array]

Array of log(T) and log(L) values for the evolutionary tracks.

c_logT: [float]

Logarithm of the stellar effective temperature.

c_logL: [float]

Logarithm of the stellar luminosity.

sigma_logT: [float]

Uncertainty in log(Teff).

sigma_logL: [float]

Uncertainty in log(Luminosity).

Output:

Returns:

lfunc: [2D array]

The likelihood function values for each combination of age and mass.

ysoisochrone.utils._normalize_pdf(arr, method='maxone')

Normalize a non-negative array for numerical stability. method: ‘maxone’ (default), ‘sumone’, or ‘none’

ysoisochrone.utils._eval_1d_prior_on_grid(prior_spec, x_grid, normalize='maxone', name='prior')

Evaluate a 1D prior on an arbitrary grid (x_grid).

prior_spec can be:

• callable: f(x) -> pdf (array-like or scalar)

• dict with keys:

  ‘grid’: 1D array of x locations (must be monotonic), ‘pdf’: 1D array of non-negative values, ‘extrapolate’: ‘edge’ (default) or ‘zero’ ‘normalize’: override normalization (default ‘maxone’)

Returns an array of shape x_grid.shape with non-negative values.

ysoisochrone.utils.download_file_simple(url, save_path)

Downloads a file from a given URL and saves it to the specified path.

Args:

url: [str]

URL of the file to download.

save_path: [str]

Local path to save the file.

ysoisochrone.utils.download_file(url, save_path)

Downloads a file from a given URL and saves it to the specified path with a customizable progress bar.

Args:

url: [str]

URL of the file to download.

save_path: [str]

Local path to save the file.

ysoisochrone.utils.extract_tarball(tar_file_path, extract_dir)

Extracts a tarball file into a specified directory.

Args:

tar_file_path: [str]

Path to the tarball file.

extract_dir: [str]

Directory to extract the tarball contents into.

ysoisochrone.utils.load_builtin_matrix(filename)

Load a .mat grid that is shipped with the ysoisochrone package.

Args:

filename: [str]

Name of the .mat file in the ysoisochrone/data directory, e.g. ‘Feiden_B_AgeMassGrid_YSO_matrix.mat’.

Output:

data: [dict]

Dictionary as returned by scipy.io.loadmat.

ysoisochrone.utils.download_baraffe_tracks(save_dir='isochrones_data')

Downloads the Baraffe BHAC15 tracks file and saves it to the specified directory.

Args:

save_dir: [str, optional]

The directory where the file should be saved. Defaults to ‘isochrones_data’.

Output:

Downloads the file and saves it in the specified directory.

Raises:

ValueError: If the file could not be downloaded.

ysoisochrone.utils.read_baraffe_file(file_path)

Reads the original BHAC15 tracks file and parses the mass, age, and logtlogl.

Args:

file_path: [str]

Path to the original BHAC15 tracks file.

Returns:

data_points: [np.array]

Array of [log_age, mass, teff, luminosity] data points.

ysoisochrone.utils.download_feiden_trk_tracks(save_dir='isochrones_data', download_original_trks=False)

Downloads (all .trk files and [optional]) the tarball from the specified GitHub folder and saves them to the given directory. The tarball is extracted after downloading.

Args:

save_dir: [str, optional]

The directory where the files should be saved. Defaults to ‘isochrones_data’.

download_original_trks: [bool, optional] default = False

If true, download the original trk files provided on their gibhub page, otherwise, only download the tgz file and then untar it

Output:

Downloads (all .iso files and) the tarball from the GitHub folder, saves them, and extracts the tarball.

ysoisochrone.utils.read_feiden_trk_file(feiden_dir)

Reads all the Feiden track files (*.trk) in the given directory, extracts the age and stellar parameters, and organizes the data into numpy arrays.

Args:

feiden_dir: [str]

Directory where the Feiden track files are stored.

Returns:

data_points: [list]

List of [mass, log_age, Teff, log(L/Lo)] for each star across all .trk files.

ysoisochrone.utils.download_feiden_iso_tracks(save_dir='isochrones_data')

Downloads all .iso files and the tarball from the specified GitHub folder and saves them to the given directory. The tarball is extracted after downloading.

Args:

save_dir: [str, optional]

The directory where the files should be saved. Defaults to ‘isochrones_data’.

Output:

Downloads all .iso files and the tarball from the GitHub folder, saves them, and extracts the tarball.

ysoisochrone.utils.read_feiden_iso_file(feiden_dir)

Reads all the Feiden track files (*.iso) in the given directory, extracts the age and stellar parameters, and organizes the data into numpy arrays.

Args:

feiden_dir: [str]

Directory where the Feiden track files are stored.

Returns:

data_points: [list]

List of [mass, log_age, log(Teff), log(L/Lo)] for each star across all .iso files.

ysoisochrone.utils.download_parsec_v1p2_tracks(save_dir='isochrones_data')

Downloads the PARSECv1p2 tracks tarball from the specified link and saves it to the given directory. The tarball is extracted after downloading.

Args:

save_dir: [str, optional]

The directory where the files should be saved. Defaults to ‘isochrones_data’.

Output:

Downloads the tarball from the provided link, saves it, and extracts the tarball.

ysoisochrone.utils.read_parsec_v1p2_dat_file(parsec_dir)

Reads all the PARSECv1p2 track files (*.DAT) in the given directory, extracts the mass, age, and stellar parameters (log(Teff), log(L)). Organizes the data into numpy arrays.

Args:

parsec_dir: [str]

Directory where the PARSECv1p2 track files are stored.

Returns:

data_points: [list]

List of [mass, log_age, Teff, log(L/Lo)] for each star across all .DAT files.

ysoisochrone.utils.download_parsec_v2p0_tracks(save_dir='isochrones_data')

Downloads the PARSEC v2.0 tracks zip file and extracts it to the given directory.

Args:

save_dir: [str, optional]

The directory where the files should be saved. Defaults to ‘isochrones_data/PARSECv2p0’.

Output:

Downloads the PARSEC v2.0 zip file from the specified URL, saves it, and extracts its contents.

ysoisochrone.utils.read_parsec_v2p0_tab_file(parsec_dir)

Reads all the PARSECv2.0 track files (*.TAB) in the given directory, extracts the mass, age, and stellar parameters (log(Teff), log(L)). Organizes the data into numpy arrays.

Args:

parsec_dir: [str]

Directory where the PARSECv2.0 track files are stored.

Returns:

data_points: [list]

List of [mass, log_age, Teff, log(L/Lo)] for each star across all .TAB files.

ysoisochrone.utils.download_mist_v1p2_eep_tracks(save_dir='isochrones_data')

Downloads the MIST v1.2 tracks tarball and extracts it to the given directory.

Args:

save_dir: [str, optional]

The directory where the files should be saved. Defaults to ‘isochrones_data/MIST_v1p2’.

Output:

Downloads the MIST v1.2 tarball from the specified URL, saves it, and extracts its contents.

ysoisochrone.utils.download_mist_v1p2_iso_tracks(save_dir='isochrones_data')

Downloads the MIST v1.2 tracks tarball and extracts it to the given directory.

Args:

save_dir: [str, optional]

The directory where the files should be saved. Defaults to ‘isochrones_data/MIST_v1p2’.

Output:

Downloads the MIST v1.2 tarball from the specified URL, saves it, and extracts its contents.

ysoisochrone.utils.read_mist_v1p2_iso_file(mist_iso_file)

Reads the MISTv1p2 isochrone file in the given directory, extracts the star mass, log(Teff), and log(L/Lo). Organizes the data into numpy arrays.

Args:

mist_iso_file: [str]

The file where the MISTv1p2 isochrone file is stored.

Returns:

data_points: [list]

List of [star_mass, log_age, Teff, log(L/Lo)] for each entry in the iso file.

ysoisochrone.utils.create_meshgrid_legacy(data_points, min_age=0.5, max_age=50.0, min_mass=0.015, max_mass=1.4, interpolation_method='linear')

Creates a meshgrid for log_age and masses, and populates it with Teff and luminosity. The choice of the grid is adopted in Pascucci+2016, which worked fine with Feiden and Baraffe tacks But this choice cannot be adopted for older targets beyond 50 Myrs.

Args:

data_points: [np.array]

Array of [mass, log_age, teff, log_luminosity] data points.

min_age: [float, optional] unit: Myrs

The minimum age that we will cut in this grid. Default = 0.5 Myrs

max_age: [float, optional] unit: Myrs

The maximum age that we will cut in this grid. Default = 50 Myrs because we are mainly interested in YSOs in this package. We set up a max_age so that we avoid the problem of dealing with the post-main-sequence targets (their luminosity rises up again and will overlay on the pre-main-sequence phase). NOTE will add the feature to automatiaclly capture the turn-over point in the future.

min_mass: [float, optional] unit: Msolar

The minimum mass to include in the grid. Default = 0.015 Msolar

max_mass: [float, optional] unit: Msolar

The maximum mass to include in the grid. Default = 1.4 Msolar

interpolation_method: [str]

The interpolation method used in griddata. Default ‘linear’.

Returns:

log_masses_i: [np.array]

1D array of the axis grid of log mass.

log_age_i: [np.array]

1D array of the axis grid of log age.

logtlogl_grid: [np.array]

2D array of [log(Teff), log(Luminosity)] values mapped onto the grid.

log_age_grid: [np.array]

2D meshgrid of log age values.

log_masses_grid: [np.array]

2D meshgrid of log mass values.

ysoisochrone.utils.create_meshgrid(data_points, min_age=0.5, max_age=1000.0, min_mass=0.0, max_mass=7.5, interpolation_method='linear')

Creates a meshgrid for log_age and masses, and populates it with Teff and luminosity.

Args:

data_points: [np.array]

Array of [mass, log_age, teff, log_luminosity] data points.

min_age: [float, optional] unit: Myrs

The minimum age that we will cut in this grid. Default = 0.5 Myrs

max_age: [float, optional] unit: Myrs

The maximum age that we will cut in this grid. Default = 1000 Myrs because we are mainly interested in YSOs in this package. We set up a max_age so that we avoid the problem of dealing with the post-main-sequence targets (their luminosity rises up again and will overlay on the pre-main-sequence phase).

min_mass: [float, optional] unit: Msolar

The minimum mass to include in the grid. Default = 0.0 Msolar

max_mass: [float, optional] unit: Msolar

The maximum mass to include in the grid. Default = 7.5 Msolar

interpolation_method: [str]

The interpolation method used in griddata. Default ‘linear’.

Returns:

log_masses_i: [np.array]

1D array of the axis grid of log mass.

log_age_i: [np.array]

1D array of the axis grid of log age.

logtlogl_grid: [np.array]

2D array of [log(Teff), log(Luminosity)] values mapped onto the grid.

log_age_grid: [np.array]

2D meshgrid of log age values.

log_masses_grid: [np.array]

2D meshgrid of log mass values.

ysoisochrone.utils.save_as_mat(masses, log_age, logtlogl, save_path)

Saves the extracted data into a .mat file.

Args:

masses: [np.array]

Array of masses (M/Ms).

log_age: [np.array]

Array of log age values.

logtlogl: [np.array]

2D array of Teff and L/Ls values.

save_path: [str]

Path to save the .mat file.

ysoisochrone.utils.compare_grids(loaded_data_py, loaded_data_idl, gridnames=['Python', 'IDL'], plot=True)

Compares the Python and IDL-generated grids by interpolating the Python grid onto the sparser IDL grid and plotting the differences.

Args:

loaded_data_py: [dict]

Dictionary containing the Python-generated grid data (masses, log_age, logtlogl).

loaded_data_idl: [dict]

Dictionary containing the IDL-generated grid data (masses, log_age, logtlogl).

gridnames: [list of strings, optional]

The names of the grid names, default is Python and IDL

plot: [bool, optional]:

Whether to plot the differences

Output:

A visual comparison of the Python and IDL grids with difference and normalized difference plots.

ysoisochrone.utils.find_zams_index(teff_track, lum_track, age_track, massive_stars=True, log_age_max_preset=8.5, last_point=False)

Finds the index corresponding to the Zero-Age Main Sequence (ZAMS) for a given stellar track.

Args:

teff_track: [array]

Array of effective temperatures (Teff) for the stellar track.

lum_track: [array]

Array of luminosities (L/Lo) for the stellar track.

age_track: [array]

Array of stellar ages for the track.

massive_stars: [bool, optional]

Whether this is a track for massive stars The ZAMS condition for massive stars and solar-mass stars are different

log_age_max_preset: [float, optional]

The maximum age that will be considered in the track This is only used for massive stars Default is 1.0e8.5 yrs (logage = 8.5).

last_point: [bool, optional]

Whether to simply use the last point in the trk as the ZAMS point. This is often used for very-low-mass stars

Returns:

zams_idx: [int]

The index corresponding to the ZAMS for the given track.

ysoisochrone.utils.find_zams_curve(isochrone)

Find the Zero-Age Main Sequence (ZAMS) curve and mask the isochrone data beyond the ZAMS.

Args:

isochrone: object of Isochrone class

Contains the isochrone evolutionary track data (including Teff, Luminosity, and Masses).

Returns:

teff_zams: [array]

Array of effective temperatures (Teff) corresponding to ZAMS for each mass track.

lum_zams: [array]

Array of luminosities (L/Lo) corresponding to ZAMS for each mass track.

mask_pms: [2D boolean array]

Boolean mask that is True for pre-main-sequence (PMS) data and False for post-ZAMS data.