API documentation

Full catalog

class proseco.catalog.ACATable(data=None, **kwargs)

Container ACACatalogTable class that has merged guide / acq / fid catalogs as attributes and other methods relevant to the merged catalog.

classmethod empty()

Return a minimal ACACatalogTable which satisfies API requirements. Currently this means that it has an ‘id’ column which can be examined for length.

Returns:

StarsTable of stars (empty)

get_candidates_mask(stars)

Return a boolean mask indicating which stars are acceptable candidates for the parent class.

For ACATable this is the logical OR of the guide and acq values, i.e. for ACA a candidate is shown as OK if it is OK for either guide or acq. This is just used for plotting.

Parameters:

stars – StarsTable of stars

Returns:

bool mask

get_review_table()

Get ACAReviewTable object based on self.

Returns:

ACAReviewTable object

make_report(rootdir='.')

Make summary HTML report for acq and guide selection process and outputs.

Outputs are in <rootdir>/obs<obsid>/{acq,guide}/index.html plus related images in that directory.

Parameters:

rootdir – root directory for outputs

optimize_acqs_fids()

Concurrently optimize acqs and fids in the case where there is not already a good (no spoilers) fid set available.

This updates the acqs and fids tables in place.

Parameters:

• acqs – AcqTable object

• fids – FidTable object

set_attrs_from_kwargs(**kwargs)

Set object attributes from kwargs.

After calling the base class method which does all the real work, then compute the effective T_ccd temperatures.

In this ACATable object:

• t_ccd_eff_{acq,guide} are the effective T_ccd values which are adjusted if the actual t_ccd{acq,guide} values are above ACA.aca_t_ccd_penalty_limit.

• t_ccd_{acq,guide} are the actual (or predicted) values from the call

The downstream AcqTable, GuideTable, and FidTable are initialized with the effective values as t_ccd. Those classes do not have the concept of effective temperature.

Parameters:

kwargs – dict of input kwargs

Returns:

dict

class proseco.catalog.ObcCat(*args, **kwargs)

Slot-based catalog corresponding to OBC 8-element acq and guide catalogs.

Each row is a catalog object (acq, guide, fid, mon) with a dict-like interface (dict or Table Row). This class is a list subclass with special properties:

• Initialized as a length 8 list of dict {‘id’: None, ‘type’: None}

• Each of the 8 items correspond to that ACA slot.

• The default value corresponds to a “empty” slot.

• Setting an entry in a slot that is occupied raises an exception.

• Allows adding an entry to the first/last available slot, doing nothing if the id is already in the catalog.

add(value, descending=False)

Add value to catalog in first/last empty slot, returning the slot.

If value['id'] is already in the catalog then return that slot.

If the catalog already has 8 entries then an IndexError is raised.

Parameters:

• value – dict, Row Catalog entry to add

• descending – bool Direction in which to find the first empty slot (starting from beginning or end of catalog)

Returns:

int Slot in which value was placed

proseco.catalog.get_aca_catalog(obsid=0, **kwargs)

Get a catalog of guide stars, acquisition stars and fid lights.

If obsid is supplied and is a string, then it is taken to be starcheck text with required info. User-supplied kwargs take precedence, however (e.g. one can override the dither from starcheck).

In this situation if the obsid text includes the string --force-catalog anywhere then the final proseco guide and acq catalogs will be forced to match the input starcheck catalog. This can be done by appending this string, e.g. with obs_text + '--force-catalog' in the call to get_aca_catalog.

The input n_guide parameter represents the number of slots available for the combination of guide stars and monitor windows (including both fixed and tracking monitor windows). In most normal situations, n_guide is equal to 8 - n_fid. The n_guide parameter is confusingly named but this is because the actual number of guide stars is not known in advance in the case of auto-conversion from a monitor request to a guide star. In actual practice, what is normally known is how many slots are available for the combination of guide stars and monitor windows, so this makes the call to catalog creation simpler.

NOTE on API:

Keywords that have _acq and/or _guide suffixes are handled with the AliasAttribute in core.py. If one calls get_aca_catalog() with e.g. t_ccd=-10 then that will set the CCD temperature for both acq and guide selection. This is not part of the public API but is a private feature of the implementation that works for now.

Parameters:

• obsid – obsid (int) or starcheck text (str) (default=0)

• att – attitude (any object that can initialize Quat)

• n_acq – desired number of acquisition stars (default=8)

• n_fid – desired number of fid lights (req’d unless obsid spec’d)

• n_guide – desired number of guide stars + monitor windows (req’d unless obsid spec’d)

• monitors – N x 5 float array specifying monitor windows

• man_angle – maneuver angle (deg)

• man_angle_next – maneuver angle to next attitude after this observation (deg, default=180)

• t_ccd_acq – ACA CCD temperature for acquisition (degC)

• t_ccd_guide – ACA CCD temperature for guide (degC)

• t_ccd_penalty_limit – ACA CCD penalty limit for planning (degC). If not provided this defaults to value from the ACA xija thermal model.

• t_ccd_eff_acq – ACA CCD effective temperature for acquisition (degC)

• t_ccd_eff_guide – ACA CCD effective temperature for guide (degC)

• dark – 1024x1024 dark image (e-/sec, default=None => auto-fetch)

• dark_date – Date of dark cal (str, optional)

• duration – duration of observation (sec)

• target_name – name of target (str)

• date – date of acquisition (any DateTime-compatible format)

• dither_acq – acq dither size (2-element sequence (y, z), arcsec)

• dither_guide – guide dither size (2-element sequence (y, z), arcsec)

• detector – ‘ACIS-S’ | ‘ACIS-I’ | ‘HRC-S’ | ‘HRC-I’

• sim_offset – SIM translation offset from nominal [steps] (default=0)

• focus_offset – SIM focus offset [steps] (default=0)

• target_offset – (y, z) target offset including dynamical offset (2-element sequence (y, z), deg)

• dyn_bgd_n_faint – number of faint stars to apply the dynamic background temperature bonus dyn_bgd_dt_ccd (default=0)

• dyn_bgd_dt_ccd – dynamic background T_ccd temperature bonus (default=-4.0, degC)

• stars – table of AGASC stars (will be fetched from agasc if None)

• include_ids_acq – list of AGASC IDs of stars to include in acq catalog

• include_halfws_acq – list of acq halfwidths corresponding to include_ids. For values of 0 proseco chooses the best halfwidth(s).

• exclude_ids_acq – list of AGASC IDs of stars to exclude from acq catalog

• include_ids_fid – list of fiducial lights to include by index. If no possible sets of fids include the id, no fids will be selected.

• exclude_ids_fid – list of fiducial lights to exclude by index

• include_ids_guide – list of AGASC IDs of stars to include in guide catalog

• exclude_ids_guide – list of AGASC IDs of stars to exclude from guide catalog

• img_size_guide – readout window size for guide stars (6, 8, or None). Default value: 8 for ER’s; PROSECO_OR_IMAGE_SIZE environment value if if set, otherwise 8.

• optimize – optimize star catalog after initial selection (default=True)

• verbose – provide extra logging info (mostly calc_p_safe) (default=False)

• print_log – print the run log to stdout (default=False)

• raise_exc – raise exception if it occurs in processing (default=True)

Returns:

ACATable of stars and fids

proseco.catalog.get_effective_t_ccd(t_ccd, t_ccd_penalty_limit=None)

Return the effective T_ccd used for selection and catalog evaluation.

For details see Dynamic ACA limits in baby steps section in: https://occweb.cfa.harvard.edu/twiki/bin/view/Aspect/StarWorkingGroupMeeting2019x02x13

Parameters:

• t_ccd – float Actual (predicted) CCD temperature

• t_ccd_penalty_limit – float, None ACA penalty limit to use (degC). Default = aca_t_ccd_penalty_limit from proseco.characteristics.

Returns:

t_ccd_eff Effective CCD temperature (degC) for use in star selection

proseco.catalog.merge_cats(fids=None, guides=None, acqs=None, mons=None)

Merge fids, guides, and acqs catalogs into one catalog.

The output of this function is a catalog which corresponds to the final “flight” catalog that can be translated directly to appropriate OBC spacecraft commanding, e.g. a DOT ACQ command. The ordering of entries is intended to match the legacy behavior of MATLAB tools.

Parameters:

• fids – FidTable, None (optional) Table of fids

• guides – GuideTable, None (optional) Table of guide stars

• acqs – AcqTable, None (optional) Table of acquisition stars

Returns:

ACACatalogTable Merged catalog

Acquisition

Get a catalog of acquisition stars using the algorithm described in https://docs.google.com/presentation/d/1VtFKAW9he2vWIQAnb6unpK4u1bVAVziIdX9TnqRS3a8

class proseco.acq.AcqTable(data=None, **kwargs)

Catalog of acquisition stars

calc_p_brightest(acq, box_size, man_err=0, bgd=0)

Calculate the probability that the acq star is the brightest candidate in the search box.

This caches the spoiler and imposter stars in the acqs table (the row corresponding to acq). It is required that the first time this is called that the box_size and man_err be the maximum, and this is checked.

Parameters:

• acq – acq stars (AcqTable Row)

• box_size – box size (float, arcsec)

• man_err – maneuver error (float, arcsec, default=0)

• bgd – assume background for imposters (float, e-sec, default=0)

Returns:

probability that acq is the brightest (float)

calc_p_safe(verbose=False)

Calculate the probability of a safing action resulting from failure to acquire at least two (2) acquisition stars.

This uses the probability of 2 or fewer stars => “conservative” p_fail at this man_err. This uses 2 stars instead of 1 or fewer (which is the actual criteria for a safing action). This allows for one star to be dropped for reasons not reflected in the acq model probability and makes the optimization dig a bit deeper in to the catalog beyond the brightest stars.

Returns:

p_safe (float)

classmethod empty()

Return a minimal ACACatalogTable which satisfies API requirements. For AcqTable it should have ‘id’ and ‘halfw’ columns.

Returns:

StarsTable of stars (empty)

get_acq_candidates(stars, max_candidates=20) → StarsTable

Get candidates for acquisition stars from stars table.

This allows for candidates right up to the useful part of the CCD. The p_acq will be accordingly penalized.

Parameters:

• stars – list of stars in the field

• max_candidates – maximum candidate acq stars

Returns:

Table of candidates, indices of rejected stars

get_box_sizes(cand_acqs)

Get the available box sizes for each cand_acq as all those with size <= the largest man_error with non-zero probability. E.g. in the 5-20 deg man angle bin the 80-100” row is 0.1 and the 100-120” row is 0.0. So this will will limit the box sizes to 60, 80, and 100.

An exception to the box size limit is for bright stars. For stars brighter than 8.0 mag (referenced to t_ccd=-10), the box size is allowed to go up to at least 100 arcsec. For stars brighter than 9.0 mag it can go up to at least 80 arcsec. At these bright mags the larger search boxes have no impact on acquisition probability.

This is particularly relevant to man_angle < 5 deg, where the max maneuver error is 60 arcsec. In this case, bright stars can still have 80 or 100 arcsec boxes. In the case of a creep-away observation where the initial bias might be bad, this gives a bit more margin.

Parameters:

cand_acqs – AcqTable of candidate acq stars

Returns:

list of box-size arrays corresponding to cand_acqs table

get_candidates_mask(stars)

Get base filter for acceptable candidates.

This does not include spatial filtering.

Parameters:

stars – StarsTable

Returns:

bool mask of acceptable stars

get_initial_catalog()

Get the initial catalog of up to n_acq candidate acquisition stars. This updates the current AcqTable (self) in place to add selected stars.

TO DO: these should all just be taken from self

Parameters:

• cand_acqs – AcqTable of candidate acquisition stars

• stars – StarsTable of stars in or near the ACA FOV

• dark – dark current image (ndarray, e-/sec)

• dither – dither (float, arcsec)

• t_ccd – CCD temperature (float, degC)

• date – observation date

get_log_p_2_or_fewer()

Return the starcheck acquisition merit function of the probability of acquiring two or fewer stars.

Returns:

log10(probability) (float)

get_obs_info()

Convenience method to return the parts of meta that are needed for test_common OBS_INFO.

Returns:

dict of observation information

get_overlap_penalties()

Get the probability penalties for overlapping boxes.

This is returned as a multiplicative factor on the acquisition success probability. No overlap penalty implies a value of 1.0.

Returns:

list of penalties (float)

has_nearby_spoiler(acq, stars)

Returns True if acq has a nearby star that could spoil acquisition.

Parameters:

• acq – AcqTable Row

• stars – StarsTable

Returns:

bool

in_bad_star_set(acq)

Returns True if acq is in the bad star set.

Parameters:

acq – AcqTable Row

Returns:

bool

make_report(rootdir='.')

Make summary HTML report for acq selection process and outputs.

Output is in <rootdir>/obs<obsid>/acq/index.html plus related images in that directory.

Parameters:

rootdir – root directory for outputs

optimize_acq_halfw(idx, p_safe, verbose=False)

Optimize the box size (halfw) for the acq star idx in the current acqs table. Assume current p_safe.

Parameters:

• idx – acq star index

• p_safe – current value of p_safe

• verbose – include extra information in the run log

Returns improved, p_safe:

whether p_safe was improved and the new value

optimize_acqs_halfw(verbose=False)

Optimize the box_size (halfw) for the acq stars in the current catalog. This cycles through each star and optimizes the box size for that star using the optimize_acq_halfw() method.

Parameters:

verbose – include additional information in the run log

optimize_catalog(verbose=False)

Optimize the current acquisition catalog.

Parameters:

verbose – include additional information in the run log

process_include_ids(cand_acqs, stars)

Ensure that the cand_acqs table has stars that were forced to be included.

Also do validation of include_ids and include_halfws.

Parameters:

• cand_acqs – candidate acquisition stars table

• stars – stars table

select_best_p_acqs(cand_acqs, min_p_acq, acq_indices, box_sizes, force=False)

Find stars with the highest acquisition probability according to the algorithm below. p_acqs is the same-named column from candidate acq stars and it contains a dict keyed by (box_size, man_err). This algorithm uses the assumption of man_err=box_size.

• Loop over box sizes in descending order (160, …, 60)

• Sort in descending order the p_acqs corresponding to that box size (where largest p_acqs come first)

• Loop over the list and add any stars with p_acq > min_p_acq to the list of accepted stars.

• If the list is n_acq long (completely catalog) then stop

This function can be called multiple times with successively smaller min_p_acq to fill out the catalog. The acq_indices and box_sizes arrays are appended in place in this process.

Parameters:

• cand_acqs – AcqTable of candidate acquisition stars

• min_p_acq – minimum p_acq to include in this round (float)

• acq_indices – list of indices into cand_acqs of selected stars

• box_sizes – list of box sizes of selected stars

• force – force-include stars (default=False)

update_idxs_halfws(idxs, halfws)

Update the rows of self to match the specified agasc_ids and half widths. These two input lists must match the length of self and correspond to stars in self.cand_acqs.

Parameters:

• agasc_ids – list of AGASC IDs

• halfws – list of search box half widths

update_p_acq_column(acqs)

Update (in-place) the marginalized acquisition probability column ‘p_acq’. This is typically called after a change in catalog or change in the fid set. The acq[‘probs’].p_acq_marg() method will pick up the new fid set. :param acqs: :param acqs:

proseco.acq.box_overlap(y1, z1, halfw1, y2, z2, halfw2)

Return True if boxes overlap, False otherwise.

Parameters:

• y1 – y centroid of first box (float, arcsec)

• z1 – z centroid of first box (float, arcsec)

• halfw1 – half width of first box (float, arcsec)

• y2 – y centroid of second box (float, arcsec)

• z2 – z centroid of second box (float, arcsec)

• halfw2 – half width of second box (float, arcsec)

Returns:

True if boxes overlap, False otherwise

proseco.acq.boxes_overlap(y1: float, z1: float, halfw1: float, cand_acqs: AcqTable, box_sizes: list, acq_indices: list) → int

Check if candidate new acq box overlaps with already selected acq boxes.

This checks for overlaps between the box defined by (y1, z1, halfw1) and the boxes defined by the rows in cand_acqs (yang and zang) and box_sizes with indices in acq_indices.

Parameters:

• y1 – y centroid of first box (float, arcsec)

• z1 – z centroid of first box (float, arcsec)

• halfw1 – half width of first box (float, arcsec)

• cand_acqs – AcqTable of candidate acquisition stars

• box_sizes – list of box sizes of selected stars

• acq_indices – list of indices into cand_acqs of selected stars

Returns:

AGASC ID of the first overlapping box, or 0 if no overlap

proseco.acq.calc_p_brightest_compare(acq, mags, mag_errs)

For given acq star and intruders mag, mag_err, do the probability calculation to see if the acq star is brighter than all of them.

Parameters:

• acq – acquisition star (AcqTable Row)

• mags – iterable of mags

• mag_errs – iterable of mag errors

Returns:

probability that acq stars is brighter than all mags

proseco.acq.calc_p_on_ccd(row, col, box_size)

Calculate the probability that star and initial tracked readout box are fully within the usable part of the CCD.

Note that box_size here is not a search box size, it is normally man_err + dither and reflects the size of the box where the star can land on the CCD. This is independent of the search box size, but does assume that man_err < search box size. This is always valid because this function only gets called in that case (otherwise p_acq is just set to 0.0 in calc_p_safe. Dither does not enter into the man_err < search box size relation because the OBC accounts for dither when setting the search box position.

This uses a simplistic calculation which assumes that p_on_ccd is just the fraction of box area that is within the effective usable portion of the CCD.

Parameters:

• row – row coordinate of star (float)

• col – col coordinate of star (float)

• box_size – box size (ACABox)

Returns:

probability the star is on usable part of CCD (float)

proseco.acq.filter_box_sizes_for_maxmag(mag: float, mag_err: float, box_sizes: ndarray, t_ccd: float) → ndarray

Filter the list of box sizes

First compute the smallest allowed value of MAXMAG for this star, which is the star mag + 3 times the star mag error (clipped to be within 0.5 to 1.5 mag, nominal).

For each box size and t_ccd compute the MAXMAG that keeps the search hits at exactly 50. Then keep the box sizes where MAXMAG is less than the star minimum MAXMAG.

Parameters:

• mag – star mag (float)

• mag_err – star mag error (float)

• box_sizes – ndarray of box sizes (float, arcsec)

• t_ccd – CCD temperature (float, C)

Returns:

ndarray of box sizes (float, arcsec)

proseco.acq.get_acq_catalog(obsid=0, **kwargs)

Get a catalog of acquisition stars using the algorithm described in https://docs.google.com/presentation/d/1VtFKAW9he2vWIQAnb6unpK4u1bVAVziIdX9TnqRS3a8

If obsid corresponds to an already-scheduled obsid then the parameters att, man_angle, t_ccd, date, and dither will be fetched via mica.starcheck if not explicitly provided here.

Parameters:

• obsid – obsid (default=0)

• att – attitude (any object that can initialize Quat)

• n_acq – desired number of acquisition stars (default=8)

• man_angle – maneuver angle (deg)

• t_ccd – ACA CCD temperature (degC)

• date – date of acquisition (any DateTime-compatible format)

• dither – dither size (float or 2-element sequence (dither_y, dither_z), arcsec)

• detector – ‘ACIS-S’ | ‘ACIS-I’ | ‘HRC-S’ | ‘HRC-I’

• sim_offset – SIM translation offset from nominal [steps] (default=0)

• focus_offset – SIM focus offset [steps] (default=0)

• stars – table of AGASC stars (will be fetched from agasc if None)

• include_ids – list of AGASC IDs of stars to include in selected catalog

• include_halfws – list of acq halfwidths corresponding to include_ids. For values of 0 proseco chooses the best halfwidth(s).

• exclude_ids – list of AGASC IDs of stars to exclude from selected catalog

• optimize – optimize star catalog after initial selection (default=True)

• verbose – provide extra logging info (mostly calc_p_safe) (default=False)

• print_log – print the run log to stdout (default=False)

Returns:

AcqTable of acquisition stars

proseco.acq.get_imposter_stars(dark, star_row, star_col, thresh=None, maxmag=11.5, box_size=120, bgd=40, mag_limit=20.0, test=False)

Note: current alg purposely avoids using the actual flight background calculation because this is unstable to small fluctuations in values and often over-estimates background. Using this can easily miss a search hit that the flight ACA will detect. So just use a mean dark current bgd.

Parameters:

• dark – dark current image (ndarray, e-/sec)

• star_row – row of acq star (float)

• star_col – col of acq star (float)

• thresh – PEA search hit threshold for a 2x2 block (e-/sec)

• maxmag – Max mag (alternate way to specify search hit thresh)

• box_size – box size (arcsec)

• bgd – assumed flat background (float, e-/sec)

• mag_limit – Max mag for imposter (using 6x6 readout)

• test – hook for convenience in algorithm testing

Returns:

numpy structured array of imposter stars

proseco.acq.get_intruders(acq, box_size, name, n_sigma, get_func, kwargs)

Get intruders table for name=’spoilers’ or ‘imposters’ from acq. If not already in acq then call get_func(**kwargs) to get it.

Parameters:

• acq – acq stars (AcqTable Row)

• box_size – box size (float, arcsec)

• name – intruder name (‘spoilers’ | ‘imposters’)

• n_sigma – sigma threshold for comparisons

• get_func – function to actually get spoilers or imposters

• kwargs – kwargs to pass to get_func()

Returns:

dict with keys yang, zang, mag, mag_err.

proseco.acq.get_maxmag(box_size: int, t_ccd: float) → float

Get maxmag for given box_size and t_ccd.

This corresponds to the MAXMAG that results in exactly 50 search hits. See https://occweb.cfa.harvard.edu/twiki/bin/view/Aspect/PeaMaxMagTesting.

Maxmag data made with analysis/interpolate-maxmags-contour-plot.ipynb.

Parameters:

• box_size – box size (int, arcsec)

• t_ccd – CCD temperature (float, C)

Returns:

maxmag (float)

proseco.acq.get_p_man_err(man_err, man_angle)

Probability for given man_err given maneuver angle man_angle.

Parameters:

• man_err – maneuver error (float, arcsec)

• man_angle – maneuver angle (float, deg)

Returns:

probability of man_error for given man_angle

proseco.acq.get_spoiler_stars(stars, acq, box_size)

Get acq spoiler stars, i.e. any star in the specified box_size (which would normally be an extended box including man_err).

OBC adjusts search box position based on the difference between estimated and target attitude (which is the basis for yang/zang in catalog). Dither is included in the adjustment, so the only remaining term is the maneuver error, which is included via the man_err box extension. Imagine a 500 arcsec dither pattern. OBC adjusts search box for that, so apart from actual man err the box will be centered on the acq star.

See this ref for information on how well the catalog mag errors correlate with observed. Answer: not exactly, but probably good enough. Plots all the way at the bottom are key:

http://nbviewer.jupyter.org/url/cxc.harvard.edu/mta/ASPECT/
       ipynb/ssawg/2018x03x21/star-mag-uncertainties.ipynb

TO DO: consider mag uncertainties at the faint end related to background subtraction and warm pixel corruption of background.

Parameters:

• stars – StarsTable of stars for this field

• acq – acquisition star (AcqTable Row)

• box_size – box size (float, arcsec)

Returns:

numpy structured array of spoiler stars

proseco.acq.load_maxmags() → dict

Load maxmags from disk.

Maxmag data made with analysis/interpolate-maxmags-contour-plot.ipynb

Guide

class proseco.guide.GuideTable(data=None, **kwargs)

drop_excess_bonus_stars(guides)

Drop excess dynamic background faint “bonus” stars if necessary.

For dyn bgd with dyn_bgd_n_faint > 0, candidates fainter then the nominal faint limit can be selected. However, only at most dyn_bgd_n_faint of these bonus faint stars are allowed in the final catalog.

This method removes faint bonus stars (in-place within guides) in excess of the allowed dyn_bgd_n_faint number. It is assumed that the catalog order is by star preference (‘stage’, ‘mag’), so bonus stars that come first are kept.

Parameters:

guides – Table of guide stars

exclude_overlaps(stage_cands)

Review the stars selected at any stage and exclude stars that overlap in tracking space with another. Overlap is defined as being within 12 pixels.

get_candidates_mask(stars)

Get base filter for acceptable candidates.

This does not include spatial filtering.

Parameters:

stars – StarsTable

Returns:

bool mask of acceptable stars

get_img_size(n_fids=None)

Get guide image readout size from img_size and n_fids.

If img_size is None (typical case) then this uses the default rules defined in core.get_img_size(), namely 8x8 for all guide stars unless overridden by the PROSECO_OR_IMAGE_SIZE environment variable.

This requires that the fids attribute has been set, normally by providing the table as an arg to get_guide_catalog().

Parameters

n_fidsint or None

Number of fids in the catalog

Returns

int

Guide star image readout size to be used in a catalog

get_initial_guide_candidates()

Create a candidate list from the available stars in the field.

As the initial list of candidates is created this:

1. Runs get_candidate_mask to limit the “ok” mask to the list of candidates to only those that at least mee the minimum filter (based fields of the AGASC).

2. Sets the “ok” mask to limit to stars that are on the CCD (with minimum edge padding but no dither padding)

3. Adds a column (‘offchip’) to the table of all stars to mark those that aren’t on the CCD at all (offchip = True).

4. Makes one more position filter of the possible candidate stars that limits to those stars that are on the CCD with edge minimum padding, readout window padding, and padding for dither.

5. Filters the supplied star table (self.stars) using the filters in 1), 2) and 4), to produce a candidate list.

6. Filters the candidate list to remove any that are spoiled by bad pixel.

7. Filters the candidate list to remove any that are in the bad stars list.

8. Filters the candidates to remove any that have a spoiler in a NxN box centered on the star brighter than M magnitudes fainter than the candidate (N is 5 and M is -4 from the box_spoiler section of guide characteristics). This check uses the has_spoiler_in_box method and is the first of many spoiler checks. This spoiler check is not stage dependent.

9. Filters the candidates to remova any that are spoiled by the fid trap (using check_fid_trap method).

10. Puts any force include candidates from the include_ids parameter back in the candidate list if they were filtered out by an earlier filter in this routine.

11. Filters/removes any candidates that are force excluded (in exclude_ids).

12. Uses the local dark current around each candidate to calculate an “imposter mag” describing the brightest 2x2 in the region the star would dither over. This is saved to the candidate star table.

in_bad_star_list(cand_guides)

Mark star bad if candidate AGASC ID in bad star list.

Parameters:

cand_guides – Table of candidate stars

Returns:

boolean mask where True means star is in bad star list

make_report(rootdir='.')

Make summary HTML report for guide selection process and outputs.

Output is in <rootdir>/obs<obsid>/guide/index.html plus related images in that directory.

Parameters:

rootdir – root directory for outputs

process_include_ids(cand_guides, stars)

Ensure that the cand_guides table has stars that were forced to be included.

Parameters:

• cand_guides – candidate guide stars table

• stars – stars table

process_monitors_post()

Post-processing of monitor windows.

• Clean up fake stars from stars and cand_guides

• Restore the dark current map

• Set type, sz, res, dim columns for relevant entries to reflect status as monitor or guide-from-monitor in the guides catalog.

reject(reject)

Add a reject dict to self.reject_info

run_search_stages()

Run search stages as necessary to select up to the requested number of guide stars.

This routine first force selects any guide stars supplied as include_ids, marking these as selected in stage 0 in the ‘stage’ column in the candidate table, and then runs search stages.

In each “search stage”, checks are run on each candidate to exclude candidates that do not meet the selection criteria in the stage. Candidates that satisfy the stage requirements are marked with the allowed stage of selection (by its integer id) in the ‘stage’ column in the candidate table.

The run_search_stages method loops over the search stages until at least the n_guide requested stars are marked with a stage >= 0 or until all stage checks have been exhausted. This run_search_stages routine then sorts the candidates by selected stage and magnitude and returns up to the n requested guide stars as the selected stars.

search_stage(stage)

Review the candidates with the criteria defined in stage and return a mask that marks the candidates that are “ok” for this search stage. This is used to then annotate the candidate table when called from run_search_stages to mark the stars that could be selected in a stage. As candidate stars are “rejected” in the stage, details of that rejection are also added to self.reject_info .

Additionally, candidate stars that do not pass a check in the stage get their error bitmask in ‘stat_{n_stage}’ marked up with the error.

Candidates are not removed from the tble in this routine; the length of the candidate table should not change after get_initial_guide_candidates (called before this routine). Instead, as mentioned, this routine marks up informational columns in the table and returns a mask of the “ok” stars in the stage.

Details:

In each stage, the dictionary of characteristics for the stage is used to run the checks to see which candidates would be allowed. For example, the Stage 1 dictionary looks like:

{"Stage": 1,
  "SigErrMultiplier": 3,
  "ASPQ1Lim": 0,
  "MagLimit": [5.6, 10.2],
  "DoBminusVcheck": 1,
  "Spoiler": {
   "BgPixThresh": 25,
   "RegionFrac": .05,
   },
  "Imposter": {
   "CentroidOffsetLim": .2,
   }}

In each stage these checks are run:

1. Candidate star magnitude is checked to see if it is within the range plus error. For stage 1 for example , each candidate star is checked to see if it is within the 5.6 to 10.2 mag range, minus padding for error (SigErrMultiplier * cand[‘mag_err’]).

2. Candidates with ASPQ1 > stage ASPQ1Lim are marked for exclusion.

3. Candidates with local dark current that suggests that the candidate centroid could be shifted more that CentroidOffsetLim (in arcsecs) are marked for exclusion. The value of the local dark current was previously saved during “get_initial_guide_candidates” as “imp_mag”.

4. check_mag_spoilers is used to mark candidate stars that have spoilers that are too close for the magnitude delta to the candidate as defined by the “line” used by that check. The “line” basically works as a check that requires a minimum position separation for a delta magnitude. A candidate star with a spoiler of the same magnitude would require that spoiler star to be Intercept (9 pixels) away. A candidate star with a spoiler with no separation would require the spoiler to be 18 mags fainter:

(9 pixels +
(cand['mag'] - spoiler['mag'] + SigErrMultiplier * mag_err_sum) * 0.5 pix / dmag)

The parameters of the check are not stage dependent, but the mag err there is defined as SigErrMultiplier * mag_err_sum (MAG_ACA_ERR of candidate and spoiler added in quadrature).

5. check_spoil_contrib is used to mark candidate stars that have spoilers that contribute too much light onto either the the 8x8 image window or to the 8 background pixels. “Too much” is defined by the Spoiler parameters of the stage, where in stage 1 a candidate star will be excluded if either:

• the sum of the light from spoiler stars in the 8x8 contribute more than

  (candidate star magnitude in counts) * (RegionFrac).

• the sum of the light from spoiler stars on any background pixel is greater that the BgPixThresh percentile of the current dark current.

6. check_column_spoilers marks candidates for exclusion if they have column spoilers defined as spoilers between the candidate and the readout register, within characterstics.col_spoiler_pix_sep (10 columns), and 4.5 mags brighter (minus error) than the candidate. The error is the stage-dependent term where it is set as SigErrMultiplier * (the candidate MAG_ACA_ERR and the spoiler MAG_ACA_ERR added in quadrature).

7. Candidates are then screened for “bad” color (COLOR1 == 0.700) if DoBMinusVCheck is set for the stage.

Parameters:

stage – dictionary of search stage parameters

Returns:

bool mask of the length of self.meta.cand_guides with true set for “ok” stars

select_catalog(stage_cands)

For the candidates selected at any stage (stage-assigned candidates?) select the first combination that satisfies the most number of extra tests. Here the extra tests are just the 3 checks for guide stars that are too tightly clustered.

proseco.guide.check_column_spoilers(cand_stars, ok, stars, n_sigma)

For each candidate, check for stars ‘MagDiff’ brighter and within ‘Separation’ columns between the star and the readout register, i.e. Column Spoilers.

Parameters:

• cand_stars – Table of candidate stars

• ok – mask on cand_stars describing still “ok” candidates

• stars – Table of AGASC stars

• n_sigma – multiplier used when checking mag with MAG_ACA_ERR

Returns:

bool mask on cand_stars marking column spoiled stars, list of debug reject dicts

proseco.guide.check_fid_trap(cand_stars, fids, dither)

Search for guide stars that would cause the fid trap issue and mark as spoilers.

Parameters:

• cand_stars – candidate star Table

• fids – fid Table

• dither – dither ACABox

Returns:

mask on cand_stars of fid trap spoiled stars, list of rejection info dicts

proseco.guide.check_mag_spoilers(cand_stars, ok, stars, n_sigma)

Use the slope-intercept mag-spoiler relationship to exclude all stars that have a “mag spoiler”. This is basically equivalent to the “direct catalog search” for spoilers in SAUSAGE, but does not forbid all stars within 7 pixels (spoilers must be faint to be close).

The n-sigma changes by stage for the mags/magerrs used in the check.

Parameters:

• cand_stars – Table of candidate stars

• ok – mask on cand_stars describing those that are still “ok”

• stars – Table of AGASC stars in this field

• n_sigma – multiplier use for MAG_ACA_ERR when reviewing spoilers

Returns:

bool mask of length cand_stars marking mag_spoiled stars, list of reject debug dicts

proseco.guide.check_single_cluster(cand_guide_set, threshold, n_minus)

Confirm that a set of stars satisfies the minimum separation threshold when n_minus stars are removed from the set. For example, for a threshold of 1000, n_minus of 1, and an input set of candidates stars with 5 candidates, confirm that, for any 4 of the 5 stars (5 minus n_minus = 1), one pair of those stars is separated by at least 1000 arcsecs.

Returns:

bool (True for check passing threshold)

proseco.guide.check_spoil_contrib(cand_stars, ok, stars, regfrac, bgthresh)

Check that there are no spoiler stars contributing more than a fraction of the candidate star to the candidate star’s 8x8 pixel region or more than bgthresh to any of the background pixels.

Parameters:

• cand_stars – candidate star Table

• ok – mask on cand_stars of candidates that are still ‘ok’

• stars – Table of agasc stars for this field

• regfrac – fraction of candidate star mag that may fall on the 8x8 due to spoilers A sum above this fraction will mark the cand_star as spoiled

• bgthresh – background pixel threshold (in e-/sec). If spoilers contribute more than this value to any background pixel, mark the cand_star as spoiled.

Returns:

reg_spoiled, bg_spoiled, rej - two masks on cand_stars and a list of reject debug dicts

proseco.guide.dist2(g1, g2)

Calculate squared distance between a pair of stars in a star table.

This local version of the method uses a cache.

proseco.guide.get_ax_range(rc, extent)

Given a float pixel row or col value and an “extent” in float pixels, generally 4 + 1.6 for 8” dither and 4 + 5.0 for 20” dither, return a range for the row or col that is divisible by 2 and contains at least the requested extent.

Parameters:

• rc – row or col float value (edge pixel coords)

• extent – half of desired range from n (should include pixel dither)

Returns:

tuple of range as (minus, plus)

proseco.guide.get_guide_catalog(obsid=0, **kwargs)

Get a catalog of guide stars

If obsid corresponds to an already-scheduled obsid then the parameters att, t_ccd, date, and dither will be fetched via mica.starcheck if not explicitly provided here.

Parameters:

• obsid – obsid (default=0)

• att – attitude (any object that can initialize Quat)

• t_ccd – ACA CCD temperature (degC)

• date – date of acquisition (any DateTime-compatible format)

• dither – dither size 2-element tuple: (dither_y, dither_z) (float, arcsec)

• n_guide – number of guide stars to attempt to get

• fids – selected fids (used for guide star exclusion)

• stars – astropy.Table of AGASC stars (will be fetched from agasc if None)

• include_ids – list of AGASC IDs of stars to include in guide catalog

• exclude_ids – list of AGASC IDs of stars to exclude from guide catalog

• dark – ACAImage of dark map (fetched based on time and t_ccd if None)

• print_log – print the run log to stdout (default=False)

Returns:

GuideTable of acquisition stars

proseco.guide.get_imposter_mags(cand_stars, dark, dither)

Get “pseudo-mag” of max pixel value in each candidate star region

Parameters:

• cand_stars – Table of candidate stars

• dark – full CCD dark map

• dither – observation dither to be used to determine pixels a star could use

Returns:

np.array pixmags, np.array pix_r, np.array pix_c all of length cand_stars

proseco.guide.get_pixmag_for_offset(cand_mag, offset)

Determine the magnitude an individual bad pixel would need to spoil the centroid of the candidate star by offset. This just constructs the worst case as the bad pixel 3 pixels away (edge of box). The offset in this case would be offset = spoil_cnts * 3 * 5 / (spoil_cnts + cand_counts), where 3 is the distance to the edge pixel in pixels and 5 is the conversion to arcsec. Solving for spoil_cnts gives: spoil_cnts = mag_to_count_rate(cand_mag) * (offset / (15 - offset))

Parameters:

• cand_mag – candidate star magnitude

• offset – centroid offset in arcsec

Returns:

‘magnitude’ of bad pixel needed to for offset

proseco.guide.has_spoiler_in_box(cand_guides, stars, halfbox=5, magdiff=-4)

Check each candidate star for spoilers that would fall in a box centered on the star. Mark candidate spoiled if there’s a spoiler in the box and brighter than magdiff fainter than the candidate’s mag.

Parameters:

• cand_guides – Table of candidate stars

• stars – Table of AGASC stars in the field

• halfbox – half of the length of a side of the box used for check (pixels)

• magdiff – magnitude difference threshold

Returns:

mask on cand_guides set to True if star spoiled by another star in the pixel box, and a list of dicts with reject debug info

proseco.guide.run_select_checks(cand_guide_set)

Run boolean checks on a combination of candidate guide stars. Returns a sum of the status of the checks and the number of checks run.

Presently this runs three checks to confirm that the set of stars is not too tightly packed.

Returns:

tuple (status sum, number of tests run)

proseco.guide.spoiled_by_bad_pixel(cand_guides, dither)

Mark star bad if spoiled by a bad pixel in the bad pixel list (not hot)

Parameters:

• cand_guides – Table of candidate stars

• dither – dither ACABox

Returns:

boolean mask on cand_guides where True means star is spoiled by bad pixel, list of dicts of reject debug info

Fid

Get a catalog of fid lights.

class proseco.fid.FidTable(data=None, **kwargs)

get_cand_fid_sets()

Get a list of candidate fid-sets that can be selected given the list of candidate fids that are available. It also ensure that the fid sets are compatible with the specified n_fid.

get_fid_candidates()

Get all fids for this detector that are on the CCD (with margin) and are not impacted by a bad pixel.

This also finds fid spoiler stars and computes the spoiler_score.

Result is updating self.cand_fids.

is_excluded(fid)

Return True if fid id is in exclude_ids_fid manual list

Parameters:

fid – FidTable Row of candidate fid light

near_hot_or_bad_pixel(fid)

Return True if fid has a bad pixel too close

Parameters:

fid – FidTable Row of candidate fid light

off_ccd(fid)

Return True if fid is outside allowed CCD region.

Parameters:

fid – FidTable Row of candidate fid

set_initial_catalog()

Set initial fid catalog (fid set) if possible to the first set which is “perfect”:

• No field stars spoiler any of the fid lights

• Fid lights are not search spoilers for any of the current acq stars

If not possible then the table is still zero length and we will need to fall through to the optimization process.

set_slot_column()

Set the slot column.

set_spoilers_score(fid)

Get stars within FID.spoiler_margin (50 arcsec) + dither. Starcheck uses 25” but this seems small: 20” (4 pix) positional err + 4 pixel readout halfw + 2 pixel PSF width of spoiler star.

This sets the ‘spoilers’ column value to a table of spoilers stars (usually empty).

If also sets the ‘spoiler_score’ to 1 if there is a yellow spoiler (4 <= star_mag - fid_mag < 5) or 4 for red spoiler (star_mag - fid_mag < 4). The spoiler score is used later to choose an acceptable set of fids and acq stars.

Parameters:

fid – fid light (FidTable Row)

spoils(fid, acq, box_size)

Return true if fid could be within acq search box.

Includes: - 20” (4 pix) positional err on fid light - 4 pixel readout halfw for fid light - 2 pixel PSF of fid light that could creep into search box - Acq search box half-width - Dither amplitude (since OBC adjusts search box for dither)

Parameters:

• fid – fid light (FidTable Row)

• acq – acq star (AcqTable Row)

• box_size – box size (arcsec)

Returns:

True if fid could be within acq search box

proseco.fid.get_fid_catalog(obsid=0, **kwargs)

Get a catalog of fid lights.

This is the initial selection and only returns a catalog that is “perfect”:

• No fids are spoiled by a star

• No fids spoil an acq star (via acqs)

If no such fid catalog is available this function returns a zero-length FidTable. In this case a subsequent concurrent optimization of fid lights and acq stars is peformed.

Parameters:

• detector – ‘ACIS-S’ | ‘ACIS-I’ | ‘HRC-S’ | ‘HRC-I’

• focus_offset – SIM focus offset [steps] (default=0)

• sim_offset – SIM translation offset from nominal [steps] (default=0)

• acqs – AcqTable catalog. Optional but needed for actual fid selection.

• stars – stars table. Defaults to acqs.stars if available.

• dither_acq – acq dither size (2-element sequence (y, z), arcsec)

• dither_guide – guide dither size (2-element sequence (y, z), arcsec)

• include_ids – fid ids to force include. If no possible sets of fids include the id (aka index), no fids will be selected.

• exclude_ids – fid ids to exclude

• n_fid – number of desired fid lights

• print_log – print log to stdout (default=False)

Returns:

fid catalog (FidTable)

proseco.fid.get_fid_positions(detector: str, focus_offset: float, sim_offset: float, t_ccd: float | None = None, date: CxoTime | str | float | int | ndarray | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None) → tuple

Calculate the fid light positions for all fids for detector.

This is adapted from the Matlab MissionScheduling/stars/StarSelector/@StarSelector/private/fidPositions.m:

%Convert focus steps to meters
table = characteristics.Science.Sim.focus_table;
xshift = interp1(table(:,1),table(:,2),focus,'*linear');
if(isnan(xshift))
    error('Focus is out of range');
end

%find translation from sim offset
stepsize = characteristics.Science.Sim.stepsize;
zshift = SIfield.fidpos(:,2)-simoffset*stepsize;

yfid=-SIfield.fidpos(:,1)/(SIfield.focallength-xshift);
zfid=-zshift/(SIfield.focallength-xshift);

This function also applies a temperature-dependent fid offset if t_ccd and date are supplied and the PROSECO_ENABLE_FID_OFFSET env var is "True" or not set.

Parameters:

• detector – ‘ACIS-S’ | ‘ACIS-I’ | ‘HRC-S’ | ‘HRC-I’

• focus_offset – SIM focus offset [steps]

• sim_offset – SIM translation offset from nominal [steps]

• t_ccd – CCD temperature (C)

• date – date (CxoTime compatible)

Returns:

yang, zang where each is a np.array of angles [arcsec]

Core

class proseco.core.ACACatalogTable(data=None, **kwargs)

Base class for representing ACA catalogs in star selection. This can apply to acq, guide and fid entries.

Features: - Inherits from astropy Table - Logging - Serialization to/from pickle - Predefined formatting for nicer representations

classmethod empty()

Return a minimal ACACatalogTable which satisfies API requirements. Currently this means that it has an ‘id’ column which can be examined for length.

Returns:

StarsTable of stars (empty)

property exception

Return string traceback of a top-level caught exception, or “” (empty string) if no exception has been caught. Mostly for use in Matlab interface.

classmethod from_pickle(obsid, rootdir='.')

Construct table from pickle file in

<rootdir>/obs<obsid>/<name>.pkl

Parameters:

• obsid – Obsid

• rootdir – root directory (default=’.’)

Returns:

catalog table

get_catalog_for_plot()

Return value of catalog for plot_stars() call for this object

For ACACatalogTable this is the self Table object but with the possibility of changing all the type column values to self.catalog_type (e.g. ‘ACQ’).

has_column_spoiler(cand, stars, mask=None)

Returns True if cand has a column spoiler downstream toward readout register which is: - at least 4.5 mag brighter (ACA.col_spoiler_mag_diff) - within 10 pixels in column (ACA.col_spoiler_pix_sep)

Also records a log entry for detected spoilers

Parameters:

• cand – object with ‘row’, ‘col’, and ‘mag’ items

• stars – StarsTable

• mask – boolean mask of stars to check (default=None => no mask)

Returns:

bool

log(data, **kwargs)

Add a log event to self.log_info[‘events’] include data (which is typically, but not required to be, a string).

pformat(*args, **kwargs)

Return a list of lines for the formatted string representation of

the table.

If no value of max_lines is supplied then the height of the screen terminal is used to set max_lines. If the terminal height cannot be determined then the default is taken from the configuration item astropy.conf.max_lines. If a negative value of max_lines is supplied then there is no line limit applied.

The same applies for max_width except the configuration item is astropy.conf.max_width.

Parameters

max_linesint or None

Maximum number of rows to output

max_widthint or None

Maximum character width of output

show_namebool

Include a header row for column names. Default is True.

show_unitbool

Include a header row for unit. Default is to show a row for units only if one or more columns has a defined value for the unit.

show_dtypebool

Include a header row for column dtypes. Default is True.

htmlbool

Format the output as an HTML table. Default is False.

tableidstr or None

An ID tag for the table; only used if html is set. Default is “table{id}”, where id is the unique integer id of the table object, id(self)

alignstr or list or tuple or None

Left/right alignment of columns. Default is right (None) for all columns. Other allowed values are ‘>’, ‘<’, ‘^’, and ‘0=’ for right, left, centered, and 0-padded, respectively. A list of strings can be provided for alignment of tables with multiple columns.

tableclassstr or list of str or None

CSS classes for the table; only used if html is set. Default is None.

Returns

lineslist

Formatted table as a list of strings.

plot(ax=None, **kwargs)

Plot the catalog and background stars.

Parameters:

• ax – matplotlib axes object for plotting to (optional)

• kwargs – other keyword args for plot_stars

pprint(*args, **kwargs)

Print a formatted string representation of the table.

If no value of max_lines is supplied then the height of the screen terminal is used to set max_lines. If the terminal height cannot be determined then the default is taken from the configuration item astropy.conf.max_lines. If a negative value of max_lines is supplied then there is no line limit applied.

The same applies for max_width except the configuration item is astropy.conf.max_width.

Parameters

max_linesint or None

Maximum number of lines in table output.

max_widthint or None

Maximum character width of output.

show_namebool

Include a header row for column names. Default is True.

show_unitbool

Include a header row for unit. Default is to show a row for units only if one or more columns has a defined value for the unit.

show_dtypebool

Include a header row for column dtypes. Default is False.

alignstr or list or tuple or None

Left/right alignment of columns. Default is right (None) for all columns. Other allowed values are ‘>’, ‘<’, ‘^’, and ‘0=’ for right, left, centered, and 0-padded, respectively. A list of strings can be provided for alignment of tables with multiple columns.

process_include_ids(cand_stars, stars)

Ensure that the candidate acqs/guides table has stars that were forced to be included.

Updates cand_stars in place.

Parameters:

• cand_stars – candidate acquisition or guide stars table

• stars – stars table

set_stars(acqs=None, filter_near_fov=True) → None

Set the object stars attribute to an appropriate StarsTable object.

If acqs is defined that will be a previously computed AcqTable with stars already available, so use that.

Parameters:

• acqs – AcqTable for same observation

• filter_near_fov – include only stars in or near ACA FOV

to_pickle(rootdir='.')

Write the catalog table as pickle to:

<rootdir>/obs<obsid>/<name>.pkl

Parameters:

rootdir – root directory (default=’.’)

property warnings

Return list of warnings in the event log. This returns just the string message without context.

class proseco.core.AliasAttribute

Descriptor to define class attributes which can be accessed via either <name> or <name>_<subclass>.

For instance the dither attribute is found in both AcqTable and GuideTable, but in general these can be different for the two cases.

The get_aca_catalog() function handles this by accepting dither_acq and dither_guide. In order to be able to generically pass the same commmon kwargs to get_acq_catalog and get_guide_catalog, we define the AliasAttribute to allow set/get of either dither or dither_acq (or dither_guide).

The <subclass> name is the lower case version of everything before Table in the subclass name, so GuideTable => ‘guide’.

class proseco.core.BaseCatalogTable(data=None, **kwargs)

Base class for representing star catalogs or ACA (guide/acq/fid) catalogs.

Features: - Inherits from astropy Table - Predefined formatting for nicer representations - Indexing on ‘id’ column

property bad_stars

Back-compatibility property for bad_stars_mask

property bad_stars_mask

Mask of stars that are not acceptable candidates for the parent class. This basically applies to guide and acq, though ACACatalog uses a hybrid of those two.

This is mostly used for plotting, corresponding to the bad_stars arg of plot_stars where bad stars are plotting in a distinctive color.

get_candidates_mask(stars)

Return a boolean mask indicating which stars are acceptable candidates for the parent class. This basically applies to guide and acq, though ACACatalog uses a hybrid of those two.

This is used directly in selection of candidates. For the base class all stars are considered acceptable.

Parameters:

stars – StarsTable of stars

Returns:

bool mask

get_id(id, mon=False)

Return row corresponding to id in id column.

Parameters:

• id – int row id column value

• mon – bool return ID for corresponding MON star (default=False)

Returns:

table Row

get_id_idx(id, mon=False)

Return row corresponding to id in id column.

Parameters:

• id – int row id column value

• mon – bool return ID for corresponding MON star (default=False)

Returns:

table row index (int)

plot(ax=None, **kwargs)

Plot the catalog and background stars.

Parameters:

• ax – matplotlib axes object for plotting to (optional)

• kwargs – other keyword args for plot_stars

class proseco.core.StarsTable(data=None, **kwargs)

Table of stars for use in proseco.

This is meant to be created only with available class methods:

• from_agasc() : calls agasc.get_agasc_cone()

• from_stars() : init from the results of a call to get_agasc_cone()

• from_agasc_ids() : calls agasc.get_stars()

• empty() : empty catalog, then use add_* methods to add stars

add_agasc_id(agasc_id)

Add a AGASC star to the current StarsTable.

Parameters:

agasc_id – AGASC ID of the star to add

add_fake_constellation(n_stars=8, size=1500, mag=7.0, **attrs)

Add a fake constellation of up to 8 stars consisting of a cross and square:

      *
    *   *
  *       *
    *   *
      *

yangs = [1,  0, -1,  0, 0.5,  0.5, -0.5, -0.5] * size
zangs = [0,  1,  0, -1, 0.5, -0.5,  0.5, -0.5] * size

Additional star table attributes can be specified as keyword args. All attributes are broadcast as needed.

Example:

>>> stars = StarsTable.empty()
>>> stars.add_fake_constellation(n_stars=4, size=1000, mag=7.5, ASPQ1=[0, 1, 0, 20])
>>> stars['id', 'yang', 'zang', 'mag', 'ASPQ1']
<StarsTable length=4>
  id    yang     zang     mag   ASPQ1
int32 float64  float64  float32 int16
----- -------- -------- ------- -----
  100  1000.00     0.00    7.50     0
  101     0.00  1000.00    7.50     1
  102 -1000.00     0.00    7.50     0
  103     0.00 -1000.00    7.50    20

Parameters:

• n_stars – number of stars (default=8, max=8)

• size – size of constellation [arcsec] (default=2000)

• mag – star magnitudes (default=7.0)

• **attrs – other star table attributes

add_fake_star(**star)

Add a star to the current StarsTable.

The input kwargs must have at least: - One of yang/zang, ra/dec, or row/col - mag - mag_err (defaults to 0.1)

Mag_err is set to 0.1 if not provided. Yang/zang, ra/dec, and row/col RA/DEC_PMCORR, MAG_ACA, MAG_ACA_ERR will all be set according to the primary inputs unless explicitly provided. All the rest will be set to default “good”” values that will preclude initial exclusion of the star.

Parameters:

**star – keyword arg attributes corresponding to StarTable columns

classmethod empty(att=(0, 0, 0))

Return an empty StarsTable suitable for generating synthetic tables.

Parameters:

att – any Quat-compatible attitude

Returns:

StarsTable of stars (empty)

classmethod from_agasc(att, date=None, radius=1.2, logger=None)

Get AGASC stars in the ACA FOV. This uses the proseco-AGASC, so only stars within 3-sigma of 11.5 mag or those nearby a potential guide/acq star are included.

This uses an AGASC file path defined by the AGASC_HDF_FILE env var or the latest version of proseco_agasc in the default AGASC directory. The AGASC directory can be set with the AGASC_DIR env var.

Parameters:

• att – any Quat-compatible attitude

• date – DateTime compatible date for star proper motion (default=NOW)

• radius – star cone radius [deg] (default=1.2)

• logger – logger object (default=None)

Returns:

StarsTable of stars

classmethod from_agasc_ids(att, agasc_ids, date=None, logger=None)

Get AGASC stars in the ACA FOV using a list of AGASC IDs.

Parameters:

• att – any Quat-compatible attitude

• agasc_ids – sequence of AGASC ID values

• date – DateTime compatible date for star proper motion (default=NOW)

• logger – logger object (default=None)

Returns:

StarsTable of stars

classmethod from_stars(att, stars, logger=None, copy=True) → StarsTable

Return a StarsTable from an existing AGASC stars query. This just updates columns in place.

If stars is a StarsTable, the attitude of that object stars.att must match att to within 0.001 arcsec in pitch, yaw, and roll.

Parameters:

• att – any Quat-compatible attitude

• stars – Table of stars

• logger – logger object (default=None)

• copy – copy stars table columns

Returns:

StarsTable of stars

get_catalog_for_plot()

Return value of catalog for plot_stars() call for this object

For StarsTable this is None (no catalog).

plot(ax=None, **kwargs)

Plot the star field.

Parameters:

• ax – matplotlib axes object for plotting to (optional)

• kwargs – other keywords for plot_stars

proseco.core.bin2x2(arr)

Bin 2-d arr in 2x2 blocks. Requires that arr has even shape sizes

proseco.core.calc_spoiler_impact(star, stars, dark_bgd=40, debug=False)

Calculate the centroid shift and relative image brightness change for star when nearby stars are included. The assumption is that star has ASPQ1 > 0 so it is known to have some spoiler.

The returned norm_frac is the ratio of the summed (mouse-bitten) counts in the original image over the spoiled image, so a value less than 1.0 is a problem since it indicates a high background.

Parameters:

• star – object with row, col, mag keys/cols

• stars – StarsTable

Returns:

d_yang, d_zang, norm_frac

proseco.core.get_dim_res(halfws)

Get ACA search command dim and res corresponding to halfws

From DM11, where dim is a 6-bit uint and res is a 1-bit uint with 0 => “L” and 1 => H”.

Define the search region (dim) for any image data slot to be a square centered at the commanded angular Z and Y coordinates. When the high resolution flag (H) (res) in command word 3 is true (=1), the half width of the square, in arc seconds, is (20 + 5D) where D is the dimension field in command word 2. When the H flag is false (=0), the half width, is (20 + 40D) arc seconds.

Parameters:

halfws – array of int Half-widths (arcsec)

Returns:

tuple (int array, int array) ACA search DIM and RES entries corresponding to halfws

proseco.core.get_image_props(ccd_img, c_row, c_col, bgd=None)

Do a pseudo-read and compute the background-subtracted magnitude of the image. Returns the 8x8 image and mag.

Parameters:

• ccd_image – full-frame CCD image (e.g. dark current, with or without stars).

• c_row – int row at center (readout row-4 to row+4)

• c_col – int col at center

• bgd – background to subtract at each pixel. If None then compute flight bgd.

Returns:

8x8 image (ndarray), image mag

proseco.core.get_img_size(n_fids)

Get guide image readout size from n_fids.

This is the core definition for the default rule specifying the guide star image size.

ER’s (observations with no fids) always get 8x8.

OR’s (observations with fids) default to 8x8. This can be globally overridden by setting the PROSECO_OR_IMAGE_SIZE environment variable to “4”, “6” or “8”. As a reminder the img_size_guide parameter of get_aca_catalog can also be set.

Parameters

n_fidsint

Number of fids in the catalog

Returns

int

Guide star image readout size to be used in a catalog (6 or 8)

proseco.core.get_kwargs_from_starcheck_text(obs_text, include_cat=False, force_catalog=False)

Get proseco kwargs using the exact catalog from the starcheck output text obs_text. Mostly copied from annie/annie (should move into mica.starcheck one day).

Parameters:

• obs_text – text copied from starcheck output

• include_cat – include the original catalog in returned kwargs

• force_catalog – force proseco catalog to match the original catalog

Returns:

dict of keyword args corresponding to proseco args

proseco.core.get_monitors(obsid, cat)

Generate a list of monitor requests for an existing catalog

Parameters:

• obsid – int, obsid

• cat – starcheck catalog from get_catalog

Returns:

list of monitor requests

proseco.core.includes_for_obsid(obsid)

Return a dict with the include_ids_acq, include_halfws_acq and include_ids_guide lists for the as-run flight catalog of obsid. Useful for forcing catalog.

Example:

>>> from proseco import get_aca_catalog
>>> from proseco.core import includes_for_obsid
>>> obsid = 8008
>>> aca = get_aca_catalog(obsid, **includes_for_obsid(obsid))

Parameters:

obsid – int, obsid

proseco.core.pea_reject_image(img)

Check if PEA would reject image (too narrow, too peaky, etc)

proseco.core.table_to_html(tbl)

Make an HTML representation of a table

Parameters:

tbl – astropy Table

Returns:

str

Diff

class proseco.diff.CatalogDiff(text, is_html=False)

Represent an ACA catalog diff as either HTML or plain text

write(out_file)

Write output to out_file

Parameters:

out_file – str, Path Output file

proseco.diff.catalog_diff(cats1, cats2, style='html', names=None, labels=None, formats=None, sort_name='id', section_lines=True, n_context=3)

Return the diff of ACA catalogs cats1 and cats2.

The output is returned in a CatalogDiff object that will display the formatted diff in Jupyter notebook, or return the diff text via the text attribute. The difference text can be written to file with the CatalogDiff.write method

Parameters:

• cats1 – Table, list of Table First ACA catalog(s)

• cats2 – Table, list of Table Second ACA catalog(s)

• style – str Diff style, either ‘html’, ‘content’, or ‘unified’

• names – list, str Column names in output as list or space-delimited str. Default = ‘idx id slot type sz dim res halfw’

• labels – list, None Label for catalog used in banner at top of lines

• formats – dict, None Dict of column names and format specifiers e.g. {‘mag’: ‘6.3f’}

• sort_name – str Column name for sorting catalog within sections (default=’id’)

• section_lines – bool Add separator lines between types (default=True)

• n_context – int Number of context lines for unified, context diffs (default=3)

Returns:

CatalogDiff

proseco.diff.get_catalog_lines(cat, names=None, section_lines=True, sort_name='id', formats=None)

Get list of lines representing catalog suitable for diffing.

This function sorts the catalog into fids, guides, monitors,and acquisition stars and outputs the table into a separate list of lines. In addition:

• Translate HRC fid ids 7-10 and 11-14 to 1-4. Values in the range 7-14 come from starcheck, but proseco uses 1-4.

• Optionally add a banner at the top with a label identifying the catalog, e.g. with the obsid. This banner is useful for diffing all the catalogs from a load, and helps to ensure that the diff algorithm stays on track.

• Guide stars that are BOT are labeled as GU*, and conversely acq stars that are BOT are labeled as AC*. This gives some visibility into BOT stars while keeping the diffs clean.

Parameters:

• cat – Table Star catalog

• names – str, list Column names in the output lines for diffing

• section_lines – bool Add separator lines between types (default=True)

• formats – dict, None Dict of column names and format specifiers

Returns:

list