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.

Example output on o6fm02q7q_raw.fits[1]
bash$  stistarg --ext 1 --diffuse 7 --display o6fm02q7q_raw.fits
--------------------------------------------------------------------------------
STIS Target Acquisition Simulator
stistarg.pyc v2.2
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.2; 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
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.

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
Warning – Not Implemented:
 

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.