HST/STIS Target Acquisition Simulator¶

Utility to simulate HST/STIS target acquisitions with various “optional parameters” available in the Astronomer’s Proposal Tool (APT) on a user-supplied FITS image.

Warning

To use input data not derived from STIS acquisition images, some pre-processing is required. See Limitations for more details.

Please note that AURA/STScI is not responsible for any damages resulting from the use of this software.

bash$  stistarg --ext 1 --diffuse 7 --display o6fm02q7q_raw.fits
--------------------------------------------------------------------------------
STIS Target Acquisition Simulator
stistarg.pyc v2.3
Python v2.7.12
Run time:  2017-01-20 11:39:04

Input File:      o6fm02q7q_raw.fits[1]
Input Options:   diffuse source, checkbox size = 7
Image Subarray:  (130, 134)

Brightest checkbox flux:  16653
Flux center:              axis1 = 66.0 ; axis2 = 73.0  [Grey X]
Geometric center:         axis1 = 66.0 ; axis2 = 73.0  [Orange X]

(All coordinates are zero-indexed.)
--------------------------------------------------------------------------------

Installation¶

The stistarg package is designed to run in the AstroConda environment. After installation, launch it via:

source activate astroconda

Then, install the stistarg script:

conda install -c sean-lockwood stistarg

Alternatively, you may download and manually install stistarg via:

python setup.py install

Note that this package requires astropy and matplotlib.

Command Line Interface¶

For more information, type stistarg --help

usage: stistarg [-h] [--ext EXT] [--point | --diffuse CHECKBOXSIZE] [--display]
                FILENAME

Simulate HST/STIS onboard target acquisition algorithm on user data.

positional argument:
  FILENAME              Input FITS file

optional arguments:
  -h, --help            show this help message and exit
  --ext EXT             Input FITS extension [default=0]
  --point               Point-source algorithm [default]
  --diffuse CHECKBOXSIZE
                        Diffuse-source algorithm. Specify checkboxsize
                        [odd integer 3-101]
  --display, -d         Display results with matplotlib.pyplot

Version 2.3; Written by Berry & Lockwood

Python API¶

stistarg.stistarg(filename, ext=0, source='point', checkboxsize=3, display=False)¶

HST/STIS Target Acquisition Simulator

Args:	filename (str): FITS file to simulate
Kwargs:	ext (int): FITS extension of filename to use source (str): “point” or “diffuse” checkboxsize (int): size of square checkbox [pixels] to use for diffuse source geometric algorithm display (bool): displays results and pauses execution
Returns:	dict of: checkboxFlux: maxFlux (int) total flux within the brightest checkbox fluxCentroid: (x (float), y (float)) centroid calculated with flux-centroid algorithm geometricCentroid: (x (float), y (float)) centroid calculated with geometric-centroid algorithm checkbox_x: lower-left corner X-coordinate of checkbox checkbox_y: lower-left corner Y-coordinate of checkbox
Note:	stistarg currently supports only the STIS detector format and scale. The capability to use non-STIS data will be added in a future release.

Auxiliary Functions¶

stistarg.findcheckbox(inarray, checkboxsize)¶

Finds the brightest checkbox within the input image sub-array, and returns its location and flux.

Args:	inarray (np.ndarray): input array checkboxsize (int): size of the (square) checkbox
Returns:	maxFluxRow (float): x location of brightest checkbox maxFluxCol (float): y location of brightest checkbox maxFlux (int): maximum flux value

stistarg.calculate_flux_centroid(inarray, x, y, checkboxsize, centroidmode='flux')¶

Calculates a flux-weighted or geometric centroid within a given checkbox of the supplied array.

Warning – Not Implemented:
Args:	inarray (np.ndarray): input array maxfluxrow (int): x location of brightest checkbox maxfluxcol (int): y location of brightest checkbox checkboxsize (int): size of the (square) checkbox
Kwargs:	centroidmode (str): “flux” or “geometric” centroid algorithm
Returns:	rowcentroid (float): x location of centroid using specified centroid algorithm colcentroid (float): y location of centroid using specified centroid algorithm
	Before computing the flux-weighted centroid, this function checks the total flux within the checkbox. If it does not exceed a scaled box-flux threshold, there is not enough flux in the checkbox to perform a meaningful flux-weighted centroid, and the geometric center of the checkbox is computed instead.

stistarg.display_results(arr, flux_x, flux_y, chkx, chky, checkboxsize, geo_x=None, geo_y=None, filename=None, ext=None)¶

Displays the input array annotated with the brightest checkbox and flux/geometric positions.

Args:	arr (np.ndarray): input array flux_x (float): x location using flux-centroid algorithm flux_y (float): y location using flux-centroid algorithm chkx (int): x location of the checkbox chky (int): y location of the checkbox
Kwargs:	geo_x (float): x location using flux-centroid algorithm geo_y (float): y location using flux-centroid algorithm filename (str): filename to be used in image title ext (int): extension number to be used in image title

Limitations¶

This release currently supports only the STIS detector format and scale. The capability to use non–STIS data will be added in a future release. Users wishing to use data from other sources must trim and rescale their input data accordingly. The STIS CCD plate scale is 0.05078 arcsec/pix.

Furthermore, stistarg assumes the use of STIS acquisition image data and trims out the last five columns from the input array before performing calculations (these are normally hot). To skip this behavior, users should pad their data accordingly.

Support¶

For support, please contact the STScI help desk at help<at>stsci<dot>edu.