coPsi

coPsi#

This is the API for the coPsi module.

class coPsi.coPsi.AnyObjectHandler(*args: Any, **kwargs: Any)#

Fancy legend

Adds black borders to the lines in the legend.

class coPsi.coPsi.iStar(inco=(85.0, 0.5, 0.0, 90.0, 'gauss'), lam=(0, 0.5, - 180.0, 180.0, 'gauss'), Prot=(3.5, 0.5, 0.0, 10.0, 'gauss'), Rs=(1.0, 0.1, 0.5, 2.0, 'gauss'), vsini=(4.5, 0.5, 0.0, 10.0, 'gauss'), cosi=(0, 0.1, - 1.0, 1.0, 'uniform'), Teff=(6250, 100, 3000, 9000, 'gauss'), figsize=(10, 6))#

Stellar inclination.

The variables in the constructor are tuples like (\(\mu,\sigma,a,b\),’distribution’) used to create distributions, where \(\mu\) is the mean/median, \(\sigma\) is the standard deviation, \(a\) is the lower boundary, and \(b\) is the upper boundary. ‘distribution’ is the type of distribution, which can be ‘gauss’, ‘uniform’, and ‘tgauss’ (truncated gaussian).

Parameters:

  • inco (tuple) – The orbital inclination (deg).

  • incs (tuple) – The stellar inclination (deg).

  • lam (tuple) – The projected obliquity (deg).

  • Prot (tuple) – Stellar rotation period (days).

  • vsini (tuple) – Projected stellar rotation speed (km/s).

  • cosi (tuple) – Cosine of stellar inclination. Used in stellarInclination.

  • Rs (tuple) – Stellar radius (\(R_\odot\)).

  • parameters (list) – List of parameters for which we can create distributions.

  • stepParameters (list) – List of parameters to step in for MCMC.

  • labels (dict) – Dictionary to map labels for parameters.

  • cLouden (dict) – Dictionary with coefficients for stellarInclinationLouden.

coPsi()#

Calculate \(\psi\).

\(\psi\) and \(\cos \psi\) are calculated from

\[\cos \psi = \sin i_\star \sin i_{\rm o} \cos \lambda + \cos i_\star \cos i_{\rm o} \, ,\]

where \(\lambda\) is the projected obliquity, \(i_\star\) is the stellar inclination, and \(i_{\rm o}\) is the orbital incliation.

Distributions for \(\psi\) and \(\cos \psi\) can be accessed through coPsi.iStar.dist[‘psi’] respectively coPsi.iStar.dist[‘cosp’].

createDistributions(N=2000)#

Create distributions for parameters

Function that creates distributions for the parameters given the values in the tuples of iStar(). If a distribution (from an MCMC for instance) is set in place of the tuple, this (these) distribution will be used instead. The length of these distributions will be used for those, where we do create a distribution.

Parameters:

N (int) – Number of draws for distributions.

diagnostics(z, par='Parameter', ax=None, lev=0.68)#

Diagnostics and KDE plot

This function calculates and prints the median and confidence intervals (from hpd). It also creates a plot of the KDE distribution with the confidence levels highlighted.

Provide either the name of the parameter from parameters or give a distribution directly. In the latter case the desired label can be provdided in par.

Parameters:

  • z (str, array) – The name of the parameter or sequence of real values/distribution.

  • par (str) – Parameter to plot and calculate confidence levels for. Optional, default ‘Parameter’.

  • ax (matplotlib.axes._subplots.AxesSubplot) – Axis in which to plot the KDE. Optional, default None, figure and axis will be created.

  • lev (float) – Confidence level (0 < lev < 1), optional. The default is 0.68.

getConfidence(z, lev=0.68)#

Calculate confidence level.

Parameters:

  • z (array) – Sequence of real values.

  • lev (float) – Confidence level (0 < lev < 1), optional. The default is 0.68.

Returns:

Median value, upper uncertainty, lower uncertainty.

Return type:

float, float, float

getKDE(z, **kwargs)#

KDE for distribution

Calculates the kernel density estimation (KDE) using statsmodel.nonparametric.KDEUnivariate().

Parameters:

z (array) – Distribution for which to calculate KDE.

Returns:

KDE support, KDE density

Return type:

array, array

hpd(data, lev=0.68)#

The Highest Posterior Density.

The Highest Posterior Density (credible) interval of data at level lev.

Parameters:

  • data (array) – Sequence of real values.

  • lev (float) – Confidence level (0 < lev < 1), optional. The default is 0.68.

Returns:

()

Return type:

tuple

plotLouden(teffs=[5700, 6700, 1000], inclinations=[90, 45, 30, 15], ax=None, oblDist='single', Teff=None, sTeff=0, vsini=None, svsini=0.0, usetex=False, font=12, ymax=25, xmax=6700)#

Plot Louden relations.

Plot the \(T_{\rm eff}\), \(v \sin i_\star\) from Louden et al. (2021). Compare by providing values for \(T_{\rm eff}\),:math:v sin i_star.

Parameters:

  • teffs (list) – Grid values for \(T_{\rm eff}\) - [start,end,npoints]. Optional, [5700,6700,1000].

  • inclinations (list) – Values to plot for \(i_\star\). Optional, default [90,45,30,15].

  • ax (matplotlib.axes._subplots.AxesSubplot) – Axis in which to plot the KDE. Optional, default None, figure and axis will be created.

  • oblDist (str) – The assumed obliquity distribution - ‘single’ or ‘two’. Optional, default ‘single’.

  • Teff (float) – \(T_{\rm eff}\). Optional, default None.

  • sTeff (float) – Error on \(T_{\rm eff}\). Optional, default 0.

  • vini (float) – \(v \sin i_\star\). Optional, default None.

  • svini (float) – Error on \(v \sin i_\star\). Optional, default 0.

  • usetex (bool) – Whether to use LaTeX in plots. Optional, default False.

  • font (float) – Fontsize for labels. Optional, default 12.

  • ymax (float) – Maximum value for \(v \sin i_\star\). Optional, default 25.

  • xmax (float) – Maximum value for \(T_{\rm eff}\). Optional, default 6700.

savePosterior(post='cosp', path='./', name='name', format='.csv', xcol=None, ycol=None)#

Save posteriors

Save the posteriors for the stellar inclination, obliquity, and projected obliquity in a .csv file.

Parameters:

  • post (str) – The posterior to save. Optional, default ‘cosp’. Options are ‘cosp’, ‘incs’, ‘lam’.

  • path (str) – Path to save the file. Optional, default ‘./’.

  • name (str) – Name of the file. Optional, default ‘name’.

  • format (str) – Format of the file. Optional, default ‘.csv’. Options are ‘.csv’, ‘.npy’.

stellarInclination(ndraws=10000, nwalkers=100, nproc=1, moves=None, path='./', plot_corner=True, plot_vsini=True, save_df=True, save_corner=True, save_vsini=True, save_convergence=False, plot_convergence=True)#

Stellar inclination (properly)

Here the stellar inclination is calculated following Masuda and Winn (2020), where we perform a Monte Carlo Markov Chain (MCMC) sampling of the posterior for \(i_\star\). emcee (Foreman-Mackey et al., 2013) is used for the sampling.

Parameters:

  • ndraws (int) – Number of draws for the MCMC. Optional, default 10000.

  • nwalkers (int) – Number of walkers for MCMC. Optional, default 10000.

  • nproc (int) – Number of CPUs for multiprocessing. Optional, default 1.

  • moves (int) – emcee.moves object. Optional, default None.

  • path (str) – Path to store results. Optional, default ‘./’.

  • plot_corner (bool) – Whether to create a corner (Foreman-Mackey, 2016) plot. Optional, default True.

  • plot_vsini (bool) – Whether to plot the distribution of the resulting \(v\) against the input value for \(v \sin i_\star\). Optional, default True.

  • save_df (bool) – Whether to save the results in a .csv file. Optional, default True.

  • save_corner (bool) – Whether to save the corner plot. Optional, default True.

  • save_vsini (bool) – Whether to save the vsini plot. Optional, default True.

  • save_convergence (bool) – Whether to save the convergence plot. Optional, default False.

  • plot_covergence (bool) – Whether to plot the autocorrelation for the MCMC. Optional, default True.

stellarInclinationDirectly(convert=True)#

Stellar inclination directly.

Calculate the stellar inclination from the simple relation

\[i_\star = \frac{P_{\rm rot} v \sin i_\star}{2 \pi R_\star} \, ,\]

where \(P_{\rm rot}\) is the stellar rotation period obliquity, \(R_\star\) is the stellar radius, and \(v \sin i_\star\) is the projected stellar rotation speed.

Note

This assumes that rotation speed at the equator, \(v\), and the projected rotation speed, \(v \sin i_\star\), are independent, which they are not.

Distribution for \(i_\star\) can be accessed through coPsi.iStar.dist[‘incs’].

Parameters:

convert (bool, optional. Default True.) – Whether to convert stellar radius from \(R_\odot\) to km and \(P_{\rm rot}\) from days to seconds.

stellarInclinationLouden(oblDist='two')#

Stellar inclination relation

Calculate stellar inclination using relation from Louden et al. (2021).

Parameters:

oblDist (str) – The assumed obliquity distribution - ‘single’ or ‘two’. Optional, default ‘two’.

coPsi.coPsi.lnprob(positions, **pars)#

Likelihood

The likelihood function for iStar.stellarInclination(). Defined similar to the one in Hjorth et al. (2021):

\[\mathcal{L} = \mathcal{N}(x_{R_\star};\mu_{R_\star},\sigma_{R_\star}) + \mathcal{N}(x_{P_{\rm rot}};\mu_{P_{\rm rot}},\sigma_{P_{\rm rot}}) + \mathcal{N}(v u;\mu_{v \sin i_\star},\sigma_{v \sin i_\star}) \, ,\]

with \(u=\sqrt{ 1 - \mathcal{U}(x_{\cos i_\star};a=-1,b=1) }\) and where \(x_i\) is the drawn value for parameter \(i= R_\star,P_{\rm rot},\cos i_\star\). \(\mathcal{L}\) and \(\mathcal{U}\) denote a gaussian respectively uniform prior. Other options are also available see coPsi.priors.