backtracks package#

Module contents#

backtracks.backtracks module#

class backtracks.backtracks.System(target_name: str, candidate_file: str, nearby_window: float = 0.5, fileprefix='./', ndim=11, **kwargs)[source]#

Bases: object

Class for describing a star system with a companion candidate.

Parameters:

  • target_name (str) – Target name which will be resolved by SIMBAD into Gaia DR3 ID

  • candidate_file (str) – .csv file containing the candidate companion coordinates in Orbitize! format

  • nearby_window (float) – Default 0.5 [degrees]

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • ndim (int) – Number of dimensions that need to be fit. Default: 11

  • **relax_pm_priors (bool) – Instead of using normal distribution based on nearby Gaia data, set a wide uniform prior on pm_ra and pm_dec based on the Gaia data over the interval (-10sigma, +10 sigma) mas/yr.

  • **relax_par_priors (bool) – Instead of using the Bailer-Jones inverse gamma prior on parallax based on Gaia data, set a wide uniform prior on parallax over the interval (1e-2, host_star_plx) mas.

  • **rv_host_method (str) – {‘normal’,’uniform’} Uses Gaia DR3 retrieved RV and normal distribution as Host star RV prior as default if not defined.

  • **rv_host_params (tuple of floats) – (lower_limit,upper_limit) for uniform rv_host_method, (mu,sigma) for normal rv_host_method. [km/s]

  • **unif (float) – Sets bounds for uniform prior around estimated candidate companion location. Defaults to 5e-3 if not defined. [degrees]

  • **ref_epoch_idx (int) – ID of datapoint at which to pin stationary tracks. Defaults to 0 if not defined. Follows order of candidate_file datapoints.

  • **query_file (str) – Name of the FITS file with the Gaia query output. This file is created when running backtracks for the first time on a target_name. Adding the filename will skip the query of the Gaia archive.

calc_chisq(param)[source]#

Function to calculate the chi2 for correlated (e.g., GRAVITY) and uncorrelated datapoints given certain model parameters.

Parameters:

param (np.array of float) – set of parameters describing 5D position of background star and 6D position of host star.

Returns:

Total chi2 given the observed datapoints and a set of model parameters.

fit(dlogz=0.5, npool=4, dynamic=False, nlive=200, mpi_pool=False, resume=False, sample_method='unif')[source]#

Function that fits the data using dynesty.

Parameters:

  • dlogz (float) – Dynesty cumulative log-evidence stop criterium. Default: 0.5

  • npool (int) – Number of CPU threads to assign to pool. Default: 4

  • dynamic (bool) – Sets option to dynamically allocate live points to improve posterior estimation. Default: False

  • nlive (int) – Constant number of live points to set in non-dynamic case. Default: 200

  • mpi_pool (bool) – Sets option to use MPI multithreading. Default: False

  • resume (bool) – Sets option to resume from a previous result. Default: False

  • sample_method – Default: ‘unif’ for uniform sampling within bounds. See Dynesty documentation for more sampling options.

Returns:

samples of fit

Return type:

results (object)

fmodel(param)[source]#

Function that models the offset of the background star with respect to the host star at the observed epochs.

Parameters:

param (np.array of float) – set of parameters describing 5D position of background star and 6D position of host star.

Returns:

RA and DEC offsets at given observed epochs.

generate_plots(days_backward: float = 1095.0, days_forward: float = 1095.0, step_size: float = 10.0, plot_radec: bool = False, plot_stationary: bool = False, fileprefix: str = './', filepost: str = '.pdf') → Tuple[Figure, Figure, Figure, Figure, Figure][source]#

Function to plot various fitting results, corner plot and diagnostic plot.

Parameters:

  • days_backward (float) – Days backward from the reference point at which to start tracks

  • days_forward (float) – Days forward from the reference point at which to end tracks

  • step_size (float) – Step size with which tracks are generated.

  • plot_radec (bool) – Option to plot RA vs time and DEC vs time in panels. Default: False for Sep vs time, PA vs time.

  • plot_stationary (bool) – Option to overplot a track corresponding to an infinitely far stationary background star. Default: False.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

data and model tracks, posterior cornerplot, dynesty summary, parallax prior, gaia neighbourhood

Return type:

tuple of figures

generate_stationary_plot(days_backward: float = 1095.0, days_forward: float = 1095.0, step_size: float = 10.0, plot_radec: bool = False, fileprefix: str = './', filepost: str = '.pdf') → Figure[source]#

Function to plot an infinitely far stationary scenario track with the data.

Parameters:

  • days_backward (float) – Days backward from the reference point at which to start tracks

  • days_forward (float) – Days forward from the reference point at which to end tracks

  • step_size (float) – Step size with which tracks are generated.

  • plot_radec (bool) – Option to plot RA vs time and DEC vs time in panels. Default: False for Sep vs time, PA vs time.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig_track (figure)

load_results(fileprefix: str = './')[source]#

Function to load fitting results in a dict from a .pkl to allow resuming.

Parameters:

fileprefix (str) – Prefix to filename. Default “./” for current folder.

loglike(param)[source]#

Function to calculate Log likelihood for correlated (e.g., GRAVITY) and uncorrelated datapoints given certain model parameters.

Parameters:

param (np.array of float) – set of parameters describing 5D position of background star and 6D position of host star.

Returns:

Loglikelihood values given the observed datapoints and a set of model parameters. Returns -np.inf if a parameter is nan or inf.

prior_transform(u)[source]#

Transforms samples u drawn from the unit cube to those drawn from our prior for each variable.

Parameters:

u (np.array of float) – samples of unit cube (0 to 1).

Returns:

tuple of np.array containing samples drawn from all prior distributions

query_astrometry(nearby_window: float = 0.5)[source]#

Queries Simbad for Gaia DR3 stars properties within a certain angular search box around the host star, as well as the properties of the host star itself.

Parameters:

nearby_window (float) – Dimensions of search box around host star to find background star population. Default 0.5 [degrees]

Returns:

tuple of tables. nearby star properties, host star ID and host star properties.

save_results(fileprefix='./')[source]#

Function to save fitting results in a dict to a .pkl to allow resuming.

Parameters:

fileprefix (str) – Prefix to filename. Default “./” for current folder.

set_initial_position()[source]#

Calculates and sets attributes for the RA and DEC coordinates at ICRS Epoch 2016.0 assuming the object is a stationary background star.

set_prior_attr()[source]#

Gathers and sets attributes for the priors for background star proper motion (from neighbourhood statistics) and distance (from healpix).

backtracks.plotting module#

backtracks.plotting.diagnostic(backtracks, fileprefix='./', filepost='.pdf')[source]#

Function to plot the dynesty run summary plot.

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig (figure)

backtracks.plotting.neighborhood(backtracks, fileprefix='./', filepost='.pdf')[source]#

Function to plot the best fitting background star parameters on top of the Gaia priors.

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig (figure)

backtracks.plotting.plx_prior(backtracks, fileprefix='./', filepost='.pdf')[source]#

Function to plot the parallax prior (in mas).

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig (figure)

backtracks.plotting.posterior(backtracks, fileprefix='./', filepost='.pdf')[source]#

Function to plot a cornerplot of the posteriors of the fit to a moving background star scenario.

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig (figure)

Notes

  • Only the five parameters of the background star are plotted.

backtracks.plotting.stationtrackplot(backtracks, ref_epoch, days_backward=1095.0, days_forward=1095.0, step_size=10.0, plot_radec=False, fileprefix='./', filepost='.pdf')[source]#

Function to plot an infinitely far stationary scenario track with the data.

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • ref_epoch (float) – Julian Date (UTC) as a reference point for the tracks

  • days_backward (float) – Days backward from the reference point at which to start tracks

  • days_forward (float) – Days forward from the reference point at which to end tracks

  • step_size (float) – Step size with which tracks are generated.

  • plot_radec (bool) – Option to plot RA vs time and DEC vs time in panels. Default: False for Sep vs time, PA vs time.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig (figure)

backtracks.plotting.tickform(x, pos)[source]#

Function to reformat tick values.

Parameters:

  • x (float) – tick value

  • pos (int) – index of tick

Returns:

Reformatted tick value with 4 decimal places.

backtracks.plotting.trackplot(backtracks, ref_epoch, days_backward=1095.0, days_forward=1095.0, step_size=10.0, plot_radec=False, plot_stationary=False, fileprefix='./', filepost='.pdf')[source]#

Function to plot a fitted (non-stationary) background star scenario track with the data.

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • ref_epoch (float) – Julian Date (UTC) as a reference point for the tracks

  • days_backward (float) – Days backward from the reference point at which to start tracks

  • days_forward (float) – Days forward from the reference point at which to end tracks

  • step_size (float) – Step size with which tracks are generated.

  • plot_radec (bool) – Option to plot RA vs time and DEC vs time in panels. Default: False for Sep vs time, PA vs time.

  • plot_stationary (bool) – Option to overplot a track corresponding to an infinitely far stationary background star. Default: False.

  • fileprefix (str) – Prefix to filename. Default “./” for current folder.

  • filepost (str) – Postfix to filename. Default “.pdf” for outputting pdf files.

Returns:

Figure object corresponding to the saved plot.

Return type:

fig (figure)

backtracks.utils module#

class backtracks.utils.HostStarPriors(mean, cov)[source]#

Bases: object

Class to draw values from multivariate normal distribution using pseudoinverse.

Parameters:

  • mean (np.array of float) – M array of mean values of multivariate normal

  • cov (np.array of float) – M by M array of covariance matrix of multivariate normal

Notes

  • This class is a stripped down version of MultivariateGaussianLogPrior in pints (BSD3-clause)

transform_normal_multivariate(x)[source]#

This function returns values drawn from the multivariate normal when given numbers between 0 and 1.

Parameters:

x (np.array of float) – N by M array of values between 0 and 1 used to draw values from the distribution

Returns:

(M np.arrays of length N)

Return type:

tuple

backtracks.utils.iso2mjd(yrs)[source]#

This function converts iso times to Modified Julian Dates in UTC

Parameters:

yrs (str) – array with iso epochs (YYYYMMDD)

Returns:

Returns Modified Julian Dates in UTC.

backtracks.utils.pol2car(sep, pa, seperr, paerr, corr=nan)[source]#

This function converts Separation, PA, and their errors to deltaRA, deltaDEC and their errors.

Parameters:

  • sep (np.array of float) – array of separation values in mas

  • pa (np.array of float) – array of position angle values in degrees

  • seperr (np.array of float) – array of separation error values in mas

  • paerr (np.array of float) – array of position angle error values in degrees

  • corr (np.array of float) – array of correlation values [-1,1] default: nan

Returns:

(ra [mas], dec [mas], raerr [mas], decerr [mas], corr2 [-])

Return type:

tuple of float

backtracks.utils.radec2seppa(ra, dec, mod180=False)[source]#

This function is reproduced here from the orbitize! package, written by S. Blunt et al and distributed under the BSD 3-Clause License Convenience function for converting from right ascension/declination to separation/ position angle.

Parameters:

  • ra (np.array of float) – array of RA values, in mas

  • dec (np.array of float) – array of Dec values, in mas

  • mod180 (Bool) – if True, output PA values will be given in range [180, 540) (useful for plotting short arcs with PAs that cross 360 during observations) (default: False)

Returns:

(separation [mas], position angle [deg])

Return type:

tuple of float

backtracks.utils.radecdists(backtracks, days, param)[source]#

Function that calculates the offset between companion and host star at a certain set of Epochs assuming background star tracks.

Parameters:

  • backtracks (class) – backtracks.System class which carries the needed methods and attributes.

  • days (np.array of float) – Array of Julian days (Terrestrial Time) at which to calculate the offsets.

  • param (np.array of float) – Array of host star and background star parameters.

Returns:

RA and DEC offsets from host star position at Epochs.

Return type:

tuple of arrays

References

  • Bangert, J., Puatua, W., Kaplan, G., Bartlett, J., Harris, W., Fredericks, A., & Monet, A. (2011) User’s Guide to NOVAS Version C3.1 (Washington, DC: USNO).

  • Barron, E. G., Kaplan, G. H., Bangert, J., Bartlett, J. L., Puatua, W., Harris, W., & Barrett, P. (2011) Bull. AAS, 43, 2011.

  • NOVAS website

Notes

  • The NOVAS function app_star does the heavy lifting here and assumes a geocentric observer location. It takes into account gravitational lensing by solar system bodies, stellar aberration, 3D motion and parallax.

  • For Proxima Centauri you may expect a 33 uas offset throughout a day due to an additional small parallax component (up to 1 Earth radius offset of the observer w.r.t. geocenter). topo_star (not implemented in backtracks) would have to be used to account for this effect.

  • The default ephemeris file in backtracks is DE405 (valid from 1599 DEC 09 to 2201 FEB 20). To extend time coverage use DE430/DE440.

  • Additional JPL Ephemeris files are found here and here

backtracks.utils.seppa2radec(sep, pa)[source]#

This function is reproduced here from the orbitize! package, written by S. Blunt et al and distributed under the BSD 3-Clause License Convenience function to convert sep/pa to ra/dec

Parameters:

  • sep (np.array of float) – array of separation in mas

  • pa (np.array of float) – array of position angles in degrees

Returns:

(ra [mas], dec [mas])

Return type:

tuple

backtracks.utils.transform_errors(x1, x2, x1_err, x2_err, x12_corr, transform_func, nsamps=100000)[source]#

This function is reproduced here from the orbitize! package, written by S. Blunt et al and distributed under the BSD 3-Clause License Transform errors and covariances from one basis to another using a Monte Carlo approach

Parameters:

  • x1 (float) – planet location in first coordinate (e.g., RA, sep) before transformation

  • x2 (float) – planet location in the second coordinate (e.g., Dec, PA) before transformation)

  • x1_err (float) – error in x1

  • x2_err (float) – error in x2

  • x12_corr (float) – correlation between x1 and x2

  • transform_func (function) – function that transforms between (x1, x2) and (x1p, x2p) (the transformed coordinates). The function signature should look like: x1p, x2p = transform_func(x1, x2)

  • nsamps – number of samples to draw more the Monte Carlo approach. More is slower but more accurate.

backtracks.utils.transform_gengamm(x, L=1350.0, alpha=1, beta=2)[source]#

This function draws distances in parsec from the generalized gamma distribution (GGD) when given values between 0 and 1.

Parameters:

  • x (np.array of float) – array of unit size values (0 to 1) used to draw values from the distribution

  • L (float) – scale parameter of the GGD [parsec]

  • alpha (float) – shape parameter

  • beta (float) – shape parameter

Returns:

Values drawn from generalized gamma distribution in parsec

References

  • Bailer-Jones, C. A. L. et al 2021 AJ 161 147 (DR3 distances; The GGD used as basis for this PPF is defined by Equation 3)

  • Bailer-Jones, C. A. L. et al 2018 AJ 156 58 (DR2 distances; Special case of GGD)

  • Stacy, E. W. (1962). A Generalization of the Gamma Distribution. The Annals of Mathematical Statistics, 33(3), 1187–1192.

Notes

  • The exponentially decreasing space density (EDSD) of Bailer-Jones et al 2018 (DR2) is equivalent to the GGD with alpha=1 and beta=2.

  • Parameters L, alpha and beta are equivalent to parameters a, p and d-1 from the original paper by Stacy (1962).

backtracks.utils.transform_normal(x, mu, sigma)[source]#

This function draws values from the normal distribution when given values between 0 and 1.

Parameters:

  • x (np.array of float) – array of unit size values (0 to 1) used to draw values from the distribution

  • mu (float) – mean of the normal distribution

  • sigma (float) – standard deviation of the normal distribution

Returns:

Values drawn from normal distribution

backtracks.utils.transform_uniform(x, a, b)[source]#

This function draws values from the uniform distribution when given values between 0 and 1.

Parameters:

  • x (np.array of float) – array of unit size values (0 to 1) used to draw values from the distribution

  • a (float) – lower limit of the uniform distribution

  • b (float) – upper limit of the uniform distribution

Returns:

Values drawn from uniform distribution

backtracks.utils.utc2tt(jd_utc)[source]#

This function converts Julian Dates in UTC to Julian Dates in TT (Terrestrial Time)

Parameters:

jd_utc (float) – array with Julian Dates

Returns:

Returns Julian Dates that are the TT equivalent of the input UTC JD.