Overview

This section expands upon synphot’s overview to only clarify things that are unique in stsynphot. In particular, this package adds functionalities similar to ASTROLIB PYSYNPHOT that are specific to STScI database or supported telescopes, including but not limited to:

• CRDS Database

• Catalogs and Spectral Atlases

• Observation Modes

• IRAF Language Parser

Spectra are constructed from observation modes or catalogs using files from the database (e.g., by multiplying data from individual throughput files together or interpolating between them). Hence, you will be mostly working with compound models built on Empirical1D models.

Quick Guide

The tables below summarize some main functionality of stsynphot. The variables, where appropriate, can be numbers (assumed to be in certain units) or Quantity. These are only for quick reference. Detailed explanations are available in their respective sections in the other parts of this document.

Bandpass

Description	Command
HST observation mode.	bp = band(obsmode)
obsmode specific wavelength set that is optimal for binned data.	bp.binset
obsmode specific collecting area.	bp.area
Number of obsmode components.	len(bp)
obsmode component filenames.	bp.showfiles()
Thermal background (only if applicable).	bp.thermback()

Other Spectrum

Description	Command
Extinction curve from given model at given \(E(B-V)\)	extcurve = ebmvx(extinction_model_name, ebv)
Vega spectrum (preloaded).	sp = Vega
Source spectrum interpolated from catalog.	sp = grid_to_spec(catalog, temperature, metallicity, log_gravity)

Miscellaneous

Description	Command
Show current reference data (graph/component tables, default wavelengths, area).	showref()
Like showref() but returns a dict.	refdict = getref()
Spectrum from IRAF syntax.	sp = parse_spec(iraf_string)

Observing Mode

The throughput calibrations of the HST observatory is represented in a framework consisting of:

• Component throughput files for every optical component (e.g., mirror, filter, polarizer, disperser, and detector).

• A configuration table describing the allowed combinations of the components.

In stsynphot, a particular observing mode is specified by a list of keywords, which might be familiar names of filters, detectors, and gratings. The keywords are used to trace the light path through the observatory via the configuration graph file (a.k.a. the TMG file) which helps translating the keyword list into a list of pointers to data files that contain the individual component throughput functions. The grand throughput function of the requested observing mode is then formed by multiplying together the individual component throughput at each wavelength. The instrument graph (TMG), component lookup (a.k.a. TMC and TMT tables), and component throughput tables are all in FITS format. (See Appendix B: OBSMODE Keywords, Appendix C: TMG, TMC, and TMT Files, and Diaz 2012 for more details on the internal structure and functioning of the configuration graph and component throughput tables.)

To retrieve a particular HST bandpass, you furnish the bandpass generator with a couple of keywords (e.g., "wfc3,uvis2,f555w"). The bandpass generator uses the keywords to trace a path through the graph file, multiplies together the bandpass components it encounters along the way, and returns the evaluated bandpass on a particular wavelength grid. You can also generate bandpass in functional form (see Bandpass). The bandpass can then be convolved with spectral data (see Source Spectrum) to simulate HST observations of particular targets. See Observation Modes for more details.

CRDS Database

The stsynphot package is entirely data driven. That is, no information pertaining to the physical description of instruments or their throughput characteristics is contained within the software, but is instead contained within an external “database.” These data must be available in order to run any stsynphot task. The dataset contains the HST instrument graph, component lookup, and component throughput tables, which are maintained and stored within the Calibration Reference Data System (CRDS) at STScI. New versions of these tables are created whenever new or updated calibration information become available for the supported instruments. Users at STScI have automatic access to the stsynphot dataset on all science computing clusters. Because the dataset is not currently distributed along with this software, off-site users must retrieve and install it separately before they will be able to use stsynphot (see Installation and Setup).

The instrument graph and component lookup tables are contained in the mtab/ subdirectory and are named *_tmg.fits, *_tmc.fits, and *_tmt.fits. The component throughput tables are logically grouped into subdirectories of comp/ corresponding to each of the HST instruments (acs, cos, fgs, foc, fos, hrs, hsp, nicmos, nonhst, ota, stis, wfc3, wfpc, and wfpc2). Component throughput table names contain a three digit suffix indicating their version number. You can determine which tables are new by comparing either their names or creation dates with the corresponding set of tables installed on your machine.

See Appendix C: TMG, TMC, and TMT Files for details on the structure of these tables.

Result Accuracy

Because the stsynphot package is entirely data driven, the accuracy of its results depends entirely on the accuracy of the bandpass sensitivity curves and zero points in the CRDS database; i.e., dependent on the instrument and photometric system under consideration.

As a general rule of thumb, synthetic photometry involving photometric systems that have been defined from the ground, or photometry that is given in VEGAMAG, should only be considered accurate to about 5%. The accuracy is a strong function of wavelength and in particular for the available calibration spectra in calspec sub-directory, the accuracy might be about 5% shortward of 1700 Angstrom, where IUE is used, and around 2% over the STIS range. The accuracy is > 5% at the longer IR wavelengths where the dust ring emission dominates (around 2 micron).

Synthetic photometry with the stable HST instrumentation, flying above the atmosphere, when used in HST instrument natural systems, without reference to VEGAMAG, can achieve accuracy much better than 5%; for example, for ACS broadband filters it can be less or about 1% (De Marchi et al. 2004). For more details, see the Data Analysis section in the Data Handbooks for the respective instruments.

In regards to agreement with ASTROLIB PYSYNPHOT, see Commissioning Report.

Usage for Other Telescopes

Because the tasks in stsynphot package are data driven (see CRDS Database), support for a new telescope could be added without changing the software. The easiest way to construct the necessary data files is to use the existing ones as templates.

You need to provide the following files and store them in $PYSYN_CDBS/mtab directory:

• One instrument graph table (*_tmg.fits).

• One component lookup table (*_tmc.fits).

• Optional: One thermal component lookup table (*_tmt.fits), which is only needed for thermal background calculations (e.g., IR instruments).

For each of the component that appears in the above graph and lookup tables, you need to provide its throughput table (*_syn.fits). These are stored in $PYSYN_CDBS/comp/ins, where ins is your instrument name (e.g., “acs”). Then, you need a copy of your own irafshortcuts.txt and modify it to include a unique “IRAFNAME” to your new comp/ins sub-directory.

For accurate binning, you can also make your own copies of detectors.dat (detector pixel scales) and wavecat.dat (wavelength catalog) and modify them for your own instruments. If your wavelength catalog points to other files, include those files in the same directory as well. For accurate count rate calculation, it is important to set the correct telescope collecting area (see below).

Finally, you can customize stsynphot to use the files you created by utilizing its configuration system (see Installation and Setup). The easiest way to do that is to modify your $HOME/.astropy/config/stsynphot.cfg with the following:

# Graph, optical component, and thermal component tables
graphtable = mtab$my_new_tmg.fits
comptable = mtab$my_new_tmc.fits
thermtable = mtab$my_new_tmt.fits

# Telescope primary mirror collecting area in cm^2
# NOTE: Set this to your actual telescope collecting area!
area = 331830.72404

# Wavelength catalog file
wavecatfile = /my/local/data/wavecat.dat

# Detector parameters file
detectorfile = /my/local/data/detectors.dat

# IRAF shortcuts file for stsynphot.stio.irafconvert()
irafshortcutfile = /my/local/data/irafshortcuts.txt