API documentation

class stardate.Star(iso_params, prot=None, prot_err=None, Av=None, Av_err=None, savedir='.', filename='samples')

The star object.

Creates the star object which will be set up with stellar parameters and instructions for saving the MCMC results.

Parameters:

• iso_params (dict) – A dictionary containing all available photometric and spectroscopic parameters for a star, as well as its parallax. All parameters should also have associated uncertainties. This dictionary should be similar to the standard one created for isochrones.py.
• prot (Optional[float]) – The rotation period of the star in days.
• prot_err (Optional[float]) – The uncertainty on the stellar rotation period in days.
• Av (Optional[float]) – The v-band extinction (if known).
• Av_err (Optional[float]) – The v-band extinction uncertainty (if known).
• savedir (Optional[str]) – The name of the directory where the samples will be saved. Default is the current working directory.
• filename (Optional[str]) – The name of the h5 file which the posterior samples will be saved in.

Av_results(burnin=0)

The Av samples.

The posterior samples for V-band extinction, optionally with a specified number of burn in steps thrown away.

Parameters:burnin (Optional[int]) – The number of samples to throw away. Default is 0. Returns:The median Av, its 16th and 84th percentile lower and upper uncertainties and the Av samples.

age_results(burnin=0)

The age samples.

The posterior samples for age, optionally with a specified number of burn in steps thrown away.

Parameters:burnin (Optional[int]) – The number of samples to throw away. Default is 0. Returns:The median age, its 16th and 84th percentile lower and upper uncertainties and the age samples. Age is log10(Age/yrs).

distance_results(burnin=0)

The ln(distance) samples.

The posterior samples for distance (in natural log, parsecs), optionally with a specified number of burn in steps thrown away.

Parameters:burnin (Optional[int]) – The number of samples to throw away. Default is 0. Returns:The median ln(distance), its 16th and 84th percentile lower and upper uncertainties and the ln(distance) samples.

eep_results(burnin=0)

The EEP samples.

The posterior samples for Equivalent Evolutionary Point, optionally with a specified number of burn in steps thrown away.

Parameters:burnin (Optional[int]) – The number of samples to throw away. Default is 0. Returns:The median EEP, its 16th and 84th percentile lower and upper uncertainties and the EEP samples.

feh_results(burnin=0)

The metallicity samples.

The posterior samples for metallicity, optionally with a specified number of burn in steps thrown away.

Parameters:burnin (Optional[int]) – The number of samples to throw away. Default is 0. Returns:The median metallicity, its 16th and 84th percentile lower and upper uncertainties and the metallicity samples.

fit(inits=[329.58, 9.5596, -0.0478, 260, 0.0045], nwalkers=50, max_n=100000, thin_by=100, burnin=0, iso_only=False, gyro_only=False, optimize=False, rossby=True, model='praesepe', seed=None, save_samples=False)

Run MCMC on a star using emcee.

Explore the posterior probability density function of the stellar parameters using MCMC (via emcee).

Parameters:

• inits (Optional[array-like]) – A list of initial values to use for EEP, age (in log10[yrs]), feh, distance (in pc) and Av.
• nwalkers (Optional[int]) – The number of walkers to use with emcee. The default is 50.
• max_n (Optional[int]) – The maximum number of samples to obtain (although not necessarily to save – see thin_by). The default is 100000.
• thin_by (Optional[int]) – Only one in every thin_by samples will be saved. The default is 100. Set = 1 to save every sample (note this substantially slows down the MCMC process because of the additional I/O time.
• burnin (Optional[int]) – The number of SAVED samples to throw away when accessing the results. This number cannot exceed the number of saved samples (which is max_n/thin_by). Default = 0.
• iso_only (Optional[bool]) – If true only the isochronal likelihood function will be used.
• gyro_only (Optional[bool]) – If true only the gyrochronal likelihood function will be used. Beware: this may not do what you might assume it does… In general this setting is not currently very useful!
• optimize (Optional[bool]) – If True, initial parameters will be found via optimization. Default is False.
• rossby (Optional[bool]) – If True, magnetic braking will cease after Ro = 2. Default is True.
• model (Optional[bool]) – The gyrochronology model to use. The default is “praesepe” (the Praesepe-based model). Can also be “angus15” for the Angus et al. (2015) model.
• seed (Optional[int]) – The random number seed. Set this if you want to regenerate exactly the same samples each time.
• save_samples (Optional[bool]) – saving samples is the computational bottleneck. If you want to save time and don’t need to save the samples using the HDF5 backend, set this to False.

mass_results(burnin=0)

The mass samples.

The posterior samples for mass, calculated from the EEP, age and feh samples, optionally with a specified number of burn in steps thrown away.

Parameters:burnin (Optional[int]) – The number of samples to throw away. Default is 0. Returns:The median mass, its 16th and 84th percentile lower and upper uncertainties and the mass ‘samples’ in units of Solar masses.

run_mcmc()

Runs the MCMC.

Runs the MCMC using emcee. Saves progress to the file specified as <filename.h5> in the <savedir> directory. Samples are saved to this file after every <thin_by> samples are obtained. And only one sample in every <thin_by> is saved. Sampling continues until either max_n samples are obtained or convergence is acheived (this usually takes much more than the default 100,000 maximum number of samples. Convergence is achieved if both 1) the change in autocorrelation time is extremely small (less than 0.01) and 2) if 100 or more independent samples have been obtained.

Returns:the emcee sampler object. Return type:sampler

stardate.lhf.lnprob(lnparams, *args)

The ln-probability function.

Calculates the logarithmic posterior probability (likelihood times prior) of the model given the data.

Parameters:

• lnparams (array) – The parameter array containing Equivalent Evolutionary Point (EEP), age in log10(yrs), metallicity, distance in ln(pc) and V-band extinction. [EEP, log10(age [yrs]), [Fe/H], ln(distance [pc]), A_v].
• *args – The arguments – mod, period, period_err, iso_only, gyro_only, rossby and model. mod is the isochrones starmodel object which is set up in stardate.py. period and period_err are the rotation period and rotation period uncertainty (in days). iso_only should be true if you want to use ONLY isochrone fitting and not gyrochronology. rossby is true if you want to use the van Saders + (2016) weakened magnetic braking law. Set to false to turn this off. model is “angus15” for the Angus + (2015) gyro model or “praesepe” for the Praesepe gyro model.

Returns:

The log-posterior probability of the model given the data and the

log-prior.

stardate.lhf.gyro_model_rossby(params, Ro_cutoff=2, rossby=True, model='praesepe')

Predict a rotation period from parameters EEP, age, feh, distance, Av.

Parameters:

• params (array) – The stellar parameters: EEP, log10(age), [Fe/H], distance and Av.
• Ro_cutoff (float, optional) – The critical Rossby number after which stars retain their rotation period. This is 2.16 in van Saders et al. (2016) and 2.08 in van Saders et al. (2018). We adopt a default value of 2.
• rossby (Optional[bool]) – If True (default), the van Saders (2016) weakened magnetic braking law will be implemented. If false, the gyrochronology relation will be used unmodified.
• model (Optional[str) – The gyrochronology model. If “praesepe”, the Praesepe-based gyro model will be used (default) and if “angus15”, the Angus et al. (2015) model will be used.

Returns:

The log10(rotation period) and the period standard deviation in dex.

stardate.lhf.calc_bv(mag_pars)

Calculate a B-V colour from stellar parameters.

Calculate B-V colour from stellar parameters [EEP, log10(age, yrs), feh, distance (in parsecs) and extinction] using MIST isochrones.

Parameters:mag_pars (list) – A list containing EEP, log10(age) in years, metallicity, distance in parsecs and V-band extinction, Av, for a star. Returns:B-V color.

stardate.lhf.convective_overturn_time(*args)

Estimate the convective overturn time.

Estimate the convective overturn time using equation 11 in Wright et al. (2011): https://arxiv.org/abs/1109.4634 log tau = 1.16 - 1.49log(M/M⊙) - 0.54log^2(M/M⊙)

Parameters:args – EITHER mass (float): Mass in Solar units OR eep (float): The Equivalent evolutionary point of a star (355 for the Sun), age (float): The age of a star in log_10(years) and feh (float): the metallicity of a star. Returns:The convective overturn time in days.