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:

https://github.com/sot/aca_stats/blob/master/fit_acq_model-2020-02-binned-poly-binom-floor.ipynb
SSAWG review: 2020-01-29

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]¶

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, where 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 and issue 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 which 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 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 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_ccdsfloat, 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]¶

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() with same params. This is retained purely for back-compatibility but use is deprecated.

chandra_aca.star_probs.prob_n_acq(star_probs)[source]¶

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]¶

Choose 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 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:

https://github.com/sot/aca_stats/blob/master/fit_acq_prob_model-2018-04-poly-spline-tccd.ipynb

chandra_aca.star_probs¶

Page Contents

Previous topic

Next topic

This Page

Navigation

chandra_aca.star_probs¶