chandra_aca.star_probs

Functions related to probabilities for star acquisition and guide tracking.

Current default acquisition probability model: grid-* (latest grid model) This can be changed by setting the module configuration value conf.default_model to an available model or model glob in the chandra_models repository.

The grid-local-quadratic-2023-05 model definition and fit values based on:

The grid-floor-2020-02 model definition and fit values based on:

class chandra_aca.star_probs.Conf[source]
default_model

Default acquisition probability model. This can be a specific model name or a glob pattern (e.g. 'grid-*' for latest grid model).

class chandra_aca.star_probs.ConfigItem(defaultvalue='', description=None, cfgtype=None, module=None, aliases=None)[source]
rootname = 'chandra_aca.star_probs'

Rootname sets the base path for all config files.

chandra_aca.star_probs.acq_success_prob(date=None, t_ccd=-10.0, mag=10.0, color=0.6, spoiler=False, halfwidth=120, model=None)[source]

Get acquisition success probability.

Return probability of acquisition success for given date, temperature, star properties and search box size.

Any of the inputs can be scalars or arrays, with the output being the result of the broadcasted dimension of the inputs.

The default probability model is defined by conf.default_model in this module. Allowed values for the model name are ‘sota’, ‘spline’, or a grid model specified by ‘grid-<name>-<date>’ (e.g. ‘grid-floor-2018-11’).

Parameters:

  • date – Date(s) (scalar or np.ndarray, default=NOW)

  • t_ccd – CCD temperature(s) (degC, scalar or np.ndarray, default=-10C)

  • mag – Star magnitude(s) (scalar or np.ndarray, default=10.0)

  • color – Star color(s) (scalar or np.ndarray, default=0.6)

  • spoiler – Star spoiled (boolean or np.ndarray, default=False)

  • halfwidth – Search box halfwidth (arcsec, default=120)

  • model – probability model name: ‘sota’ | ‘spline’ | ‘grid-*’

Returns:

Acquisition success probability(s)

chandra_aca.star_probs.binom_ppf(k, n, conf, n_sample=1000)[source]

Compute percent point function (inverse of CDF) for binomial.

Here the percentage is with respect to the “p” (binomial probability) parameter not the “k” parameter. The latter is what one gets with scipy.stats.binom.ppf().

This function internally generates n_sample samples of the binomal PMF in order to compute the CDF and finally interpolate to get the PPF.

The following example returns the 1-sigma (0.17 - 0.84) confidence interval on the true binomial probability for an experiment with 4 successes in 5 trials.

Example:

>>> binom_ppf(4, 5, [0.17, 0.84])
array([ 0.55463945,  0.87748177])
Parameters:
k

int, number of successes (0 < k <= n)

n

int, number of trials

conf

float or array of floats, percent point values

n_sample

number of PMF samples for interpolation

Returns:
percent point function values corresponding to conf
chandra_aca.star_probs.binomial_confidence_interval(n_success, n_trials, coverage=0.682689)[source]

Binomial confidence interval calculation using the Jeffreys prior.

It returns a tuple with the ratio, the lower error, and the upper error.

This is an equal-tailed Bayesian interval with a Jeffreys prior (Beta(1/2,1/2)).

“Statistical Decision Theory and Bayesian Analysis” 2nd ed. Berger, J.O. (1985) Springer, New York

This function is based on:

“Confidence Intervals for a binomial proportion and asymptotic expansions”, Lawrence D. Brown, T. Tony Cai, and Anirban DasGupta Ann. Statist. Volume 30, Number 1 (2002), 160-201. http://projecteuclid.org/euclid.aos/1015362189

Parameters:
n_successnumpy array

The number of ‘successes’

n_trialsnumpy array

The number of trials

coveragefloat

The coverage of the confidence interval. The default corresponds to the coverage of ‘1-sigma’ gaussian errors (0.682689).

Returns:
ratiotuple

ratio of successes to trials, lower bound, upper bound

chandra_aca.star_probs.clip_and_warn(name, val, val_lo, val_hi, model, tol_lo=0.0, tol_hi=0.0)[source]

Clip val to be in the range val_lo to val_hi.

This also issues a warning if clipping occurs, subject to tol_lo and tol_hi expansions. The name and model are just used in the warning.

Parameters:
name

Value name

val

Value

val_lo

Minimum

val_hi

Maximum

model

Model name

tol_lo

Tolerance below val_lo for issuing a warning (default=0.0)

tol_hi

Tolerance above val_hi for issuing a warning (default=0.0)

Returns:
Clipped value
chandra_aca.star_probs.get_box_delta(halfwidth)[source]

Transform from halfwidth (arcsec) to the box_delta value.

This box_delta value gets added to failure probability (in probit space).

Parameters:
halfwidth

scalar or ndarray of box sizes (halfwidth, arcsec)

Returns:
box deltas
chandra_aca.star_probs.get_default_acq_prob_model_info(verbose=True)[source]

Get info about the default acquisition probability model.

Example:

>>> from chandra_aca import star_probs
>>> star_probs.get_default_acq_prob_model_info()
{'default_model': 'grid-*',
 'call_args': {'file_path': 'chandra_models/aca_acq_prob',
  'version': None,
  'repo_path': 'None',
  'require_latest_version': False,
  'timeout': 5,
  'read_func': '<function _read_grid_func_model at 0x11a443b50>',
  'read_func_kwargs': {'model_name': None}},
 'version': '3.48',
 'commit': '68a58099a9b51bef52ef14fbd0f1971f950e6ba3',
 'data_file_path': '/Users/aldcroft/ska/data/chandra_models/chandra_models/aca_acq_prob/grid-floor-2020-02.fits.gz',
 'repo_path': '/Users/aldcroft/ska/data/chandra_models',
 'md5': '3a47774392beeca2921b705e137338f4',
 'CHANDRA_MODELS_REPO_DIR': None,
 'CHANDRA_MODELS_DEFAULT_VERSION': None,
 'THERMAL_MODELS_DIR_FOR_MATLAB_TOOLS_SW': None}
Parameters:

verbose – bool If False then return trimmed version with no call_args and None values removed.

Returns:

dict of model info

chandra_aca.star_probs.get_grid_axis_values(hdr, axis)[source]

Get grid model axis values from FITS header.

This is an irregularly-spaced grid if hdr has {axis}_0 .. {axis}_<N-1>. Otherwise it is a regularly-spaced grid:

linspace(hdr[f"{axis}_lo"], hdr[f"{axis}_hi"], n_vals)
Parameters:
hdr

FITS header (dict-like)

axis

Axis name (e.g. “mag”)

chandra_aca.star_probs.get_grid_func_model(model=None, version=None, repo_path=None)[source]

Get grid model from the model name.

This reads the model data from the FITS file in the chandra_models repository. The model name can be a glob pattern like grid-*, which will match the grid model with the most recent date. If not provided the DEFAULT_MODEL is used.

The return value is a dict with necessary data to use the model:

"filename": filepath (Path),
"func_no_1p5": RegularGridInterpolator for stars with color != 1.5 (common)
"func_1p5": RegularGridInterpolator for stars with color = 1.5 (less common)
"mag_lo": lower bound of mag axis
"mag_hi": upper bound of mag axis
"t_ccd_lo": lower bound of t_ccd axis
"t_ccd_hi": upper bound of t_ccd axis
"halfw_lo": lower bound of halfw axis
"halfw_hi": upper bound of halfw axis
"info": dict of provenance info for model file
Parameters:
model

Model name (optional), defaults to conf.default_model

version

Version / tag / branch of chandra_models repository (optional)

repo_path

Path to chandra_models repository (optional)

Returns:
dict of model data
chandra_aca.star_probs.grid_model_acq_prob(mag=10.0, t_ccd=-12.0, color=0.6, halfwidth=120, probit=False, model=None)[source]

Calculate grid model probability.

Calculate a grid model probability of acquisition success for a star with specified mag, t_ccd, color, and search box halfwidth.

This does a 3-d linear interpolation on mag, t_ccd, and halfwidth using a pre-computed gridded model that is stored in a FITS file.

Parameters:
mag

ACA magnitude (float or np.ndarray)

t_ccd

CCD temperature (degC, float or ndarray)

color

B-V color to check for B-V=1.5 => red star (float or np.ndarray)

halfwidth

search box halfwidth (arcsec, default=120, float or ndarray)

probit

if True then return Probit(p_success). Default=False

model

Model name, e.g. ‘grid-floor-2018-11’

Returns:
Acquisition success probability(s)
chandra_aca.star_probs.guide_count(mags, t_ccd, count_9th=False)[source]

Calculate guide star fractional count.

Calculate a guide star fractional count/metric using signal-to-noise scaled mag thresholds.

This uses a modification of the guide star fractional counts that were suggested at the 7-Mar-2018 SSAWG and agreed upon at the 21-Mar-2018 SSAWG. The implementation here does a piecewise linear interpolation between the reference mag - fractional count points instead of the original “threshold interpolation” (nearest neighbor mag <= reference mag). Approved at 16-Jan-2019 SSAWG.

One feature is the slight incline in the guide_count curve from 1.0005 at mag=6.0 to 1.0 at mag=10.0. This does not show up in standard outputs of guide_counts to two decimal places (8 * 0.0005 = 0.004), but helps with minimization.

Parameters:
magsfloat, array

Star magnitude(s)

t_ccdfloat, array

CCD temperature(s)

count_9thbool

Return fractional count of 9th mag or brighter stars

Returns:
float, fractional count
chandra_aca.star_probs.mag_for_p_acq(p_acq, date=None, t_ccd=-10.0, halfwidth=120, model=None)[source]

Calculate star magnitude for a given acquisition probability.

For a given date and t_ccd, find the star magnitude that has an acquisition probability of p_acq. Star magnitude is defined/limited to the range 5.0 - 12.0 mag.

Parameters:
p_acq

acquisition probability (0 to 1.0)

date

observation date (any Chandra.Time valid format)

t_ccd

ACA CCD temperature (deg C)

halfwidth

search box halfwidth (arcsec, default=120)

modelprobability model (see acq_success_prob() for allowed values, default)
returns mag:

star magnitude

chandra_aca.star_probs.model_acq_success_prob(mag, warm_frac, color=0, halfwidth=120)[source]

Call sota_model_acq_prob().

Call sota_model_acq_prob() with same params. This is retained purely for back-compatibility but use is deprecated.

chandra_aca.star_probs.prob_n_acq(star_probs)[source]

Get probability of acquiring n_acq stars.

Given an input array of star acquisition probabilities star_probs, return the probabilities of acquiring exactly n_acq stars, where n_acq is evaluated at values 0 to n_stars. This is returned as an array of length n_stars. In addition the cumulative sum, which represents the probability of acquiring n_acq or fewer stars, is returned.

Parameters:
star_probsarray of star acq probabilities (list or ndarray)
returns n_acq_probs, cum_n_acq_probs:

tuple of ndarray, ndarray

chandra_aca.star_probs.set_acq_model_ms_filter(ms_enabled=False)[source]

Set acq model multiple star filter.

This chooses one of two sets of acquisition model fit parameters based on ms_enabled. The default is False:

  • True: MS filtering enabled (prior to FEB0816 loads), where stars would be rejected if MS flag was set

  • False: MS filtering disabled (including and after FEB0816 loads)

The selected fit parameters are global/module-wide.

chandra_aca.star_probs.sota_model_acq_prob(mag, warm_frac, color=0, halfwidth=120)[source]

Calculate raw SOTA model probability of acquisition success.

This is for a star with mag magnitude and a CCD warm fraction warm_frac. This is not typically used directly since it does not account for star properties like spoiled or color=0.7.

Uses the empirical relation:

P_fail_probit = offset(mag) + scale(mag) * warm_frac + box_delta(halfwidth)
P_acq_fail = Normal_CDF()
P_acq_success = 1 - P_acq_fail

This is based on the dark model and acquisition success model presented in the State of the ACA 2013, and subsequently updated to use a Probit transform and separately fit B-V=1.5 stars. It was updated in 2017 to include a fitted dependence on the search box halfwidth. See:

https://github.com/sot/skanb/blob/master/pea-test-set/fit_box_size_acq_prob.ipynb https://github.com/sot/aca_stats/blob/master/fit_acq_prob_model-2017-07-sota.ipynb

Parameters:
mag

ACA magnitude (float or np.ndarray)

warm_frac

N100 warm fraction (float or np.ndarray)

color

B-V color to check for B-V=1.5 => red star (float or np.ndarray)

halfwidth

search box halfwidth (arcsec, default=120)

Returns:
Acquisition success probability(s)
chandra_aca.star_probs.spline_model_acq_prob(mag=10.0, t_ccd=-12.0, color=0.6, halfwidth=120, probit=False)[source]

Calculate spline model acq probability.

Calculate poly-spline-tccd model (aka ‘spline’ model) probability of acquisition success for a star with specified mag, t_ccd, color, and search box halfwidth.

The model definition and fit values based on:

See also:

Parameters:

  • mag – ACA magnitude (float or np.ndarray)

  • t_ccd – CCD temperature (degC, float or ndarray)

  • color – B-V color to check for B-V=1.5 => red star (float or np.ndarray)

  • halfwidth – search box halfwidth (arcsec, default=120, float or ndarray)

  • probit – if True then return Probit(p_success). Default=False

Returns:

Acquisition success probability(s)

chandra_aca.star_probs.t_ccd_warm_limit(mags, date=None, colors=0, halfwidths=120, min_n_acq=5.0, cold_t_ccd=-16, warm_t_ccd=-5, model=None)[source]

Find the warmest CCD temperature which meets the min_n_acq acquisition stars criterion.

This returns a value between cold_t_ccd and warm_t_ccd. At the cold end the result may be below min_n_acq, in which case the star catalog may be rejected.

The min_n_acq argument can be specified in one of two ways:

  • Scalar float value: expected number of acquired stars must exceed threshold.

    Expected number is the sum of the individual probabilities.

  • Tuple (n, prob): computed probability of acquiring n or fewer stars

    must not exceed prob.

Parameters:
mags

list of star ACA mags

date

observation date (any Chandra.Time valid format)

colors

list of star B-V colors (optional, default=0.0)

halfwidths

list of acq box halfwidths(optional, default=120)

min_n_acq

float or tuple (see above)

cold_t_ccd

coldest CCD temperature to consider (default=-16 C)

warm_t_ccd

warmest CCD temperature to consider (default=-5 C)

model

probability model (see acq_success_prob() for allowed values, default)

Returns:
(t_ccd, n_acq | prob_n_or_fewer) tuple with CCD temperature upper limit:
  • number of expected ACQ stars at that temperature (scalar min_n_acq)
  • probability of acquiring n or fewer stars (tuple min_n_acq)
chandra_aca.star_probs.t_ccd_warm_limit_for_guide(mags, min_guide_count=4.0, warm_t_ccd=-5.0, cold_t_ccd=-16.0)[source]

Solve for the warmest temperature that still gets the min_guide_count.

This returns a value between cold_t_ccd and warm_t_ccd. At the cold end the result may be below min_n_acq, in which case the star catalog may be rejected.

Parameters:
mags

list of star ACA mags

min_guide_count

float minimum fractional guide count

warm_t_ccd

warmest CCD temperature to consider (default=-5 C)

cold_t_ccd

coldest CCD temperature to consider (default=-16 C)

Returns:
t_ccd