Reference Data

Reference data has its history in IRAF SYNPHOT:

synphot> lpar refdata
(area = 45238.93416) Telescope area in cm^2
(grtbl = "mtab$*_tmg.fits") Instrument graph table
(cmptbl = "mtab$*_tmc.fits") Instrument component table
(mode = "a")

In stsynphot, this is managed via its configuration system (stsynphot.config.conf). Its overview and setup are explained in Installation and Setup. As you can see in its stsynphot.cfg file, the reference data management has been expanded to include the following:

  • rootdir, which is used in the absence of PYSYN_CDBS environment variable

  • graphtable, the instrument graph table

  • comptable, the instrument component table

  • thermtable, the instrument thermal component table

  • waveset_array, default wavelength set (mostly for backward compatibility)

  • waveset, description string for waveset_array

  • area, the telescope collecting area in \(\text{cm}^{2}\)

  • clear_filter, the string value indicating a clear filter in graph and component tables

  • wavecatfile, the file containing wavelength bins for all supported instruments

  • detectorfile, the file containing pixel scales and sizes for all supported instruments

  • irafshortcutfile, the file containing IRAF-style alias for data sub-directories relative to rootdir

For the same telescope, most of the above configurable items are set-and-forget, except for graph and component tables, which can be updated from time to time as component throughput curves are revised. Leaving their filenames as wildcards (*) ensures that you pick up the latest versions. If you need to use specific tables (e.g., to reproduce an older result), you can also set them to specific filenames. It is also possible to provide your data for other telescopes.

For backward compatibilty, showref() and getref() convenience functions are provided:

>>> import stsynphot as stsyn
>>> stsyn.showref()  
graphtable: /my/local/dir/trds/mtab/0bf2050hm_tmg.fits
comptable : /my/local/dir/trds/mtab/0ac1951am_tmc.fits
thermtable: /my/local/dir/trds/mtab/tae17277m_tmt.fits
area      : 45238.93416
waveset   : Min: 500, Max: 26000, Num: 10000, Delta: None, Log: True
 [stsynphot.config]
>>> stsyn.getref()  
{'area': 45238.93416,
 'comptable': '/my/local/dir/trds/mtab/0ac1951am_tmc.fits',
 'graphtable': '/my/local/dir/trds/mtab/0bf2050hm_tmg.fits',
 'thermtable': '/my/local/dir/trds/mtab/tae17277m_tmt.fits',
 'waveset': 'Min: 500, Max: 26000, Num: 10000, Delta: None, Log: True'}

To change a configurable item’s value, use the machinery of Astropy configuration system. Examples shown are only for graphtable but they are similar for others (in fact, usually all the graph and component tables are changed together):

>>> stsyn.conf.graphtable = '/path/to/my_new_tmg.fits'  # Entire session
>>> stsyn.conf.reload('graphtable')  # Reload from stsynphot.cfg
'mtab$*_tmg.fits'
>>> stsyn.conf.reload()  # Reload everything
>>> stsyn.conf.reset('graphtable')  # Reset to software default
>>> stsyn.conf.reset()  # Reset everything
>>> with stsyn.conf.set_temp('graphtable', '/path/to/my_new_tmg.fits'):
...     pass  # graphtable will only change inside this block

Graph and Component Tables

The HST bandpass for available observation modes are defined by graphtable and comptable. In addition, for IR instruments, thermal component is defined by thermtable. These files are described in detail in Appendix C.

The tables decide which throughput files will be used for a particular observation mode. They can be displayed using showfiles(). A bandpass that does not rely on the tables does not have this feature. For example:

>>> bp_hst = stsyn.band('wfc3,ir,f105w')  
>>> bp_hst.showfiles()  
/my/local/dir/trds/comp/wfc3/wfc3_ir_primary_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_secondary_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_pom_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_csm_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_fold_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_mir1_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_mir2_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_mask_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_rcp_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_f105w_004_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_win_001_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_qe_003_syn.fits
/my/local/dir/trds/comp/wfc3/wfc3_ir_cor_004_syn.fits  [...]

>>> from synphot import SpectralElement
>>> bp_nonhst = SpectralElement.from_filter('johnson_v')  
>>> bp_nonhst.showfiles()  
AttributeError: 'SpectralElement' object has no attribute 'showfiles'

Area

Some calculations require the telescope collecting area; e.g., flux conversion involving count/OBMAG or Bandpass Unit Response calculation. When an area is required, you may use the area value from stsynphot configuration for convenience, as it is always set to the telescope collecting area.

For ObservationSpectralElement constructed with band(), it also has its own area property, which is usually the same as the configuration value except when overwritten by the value (in \(\text{cm}^{2}\)) of PRIMAREA keyword in the graph table’s primary header. This behavior is retained from ASTROLIB PYSYNPHOT to be backward compatible. When in doubt, always provide the desired telescope area explicitly by passing it into the area keyword, where applicable.

Wavelength Catalog

Every HST observation mode has an optimally binned wavelength set (binset), which ensures proper coverage and resolution, for constructing an Observation. The binset is set according to a pre-defined wavelength catalog in wavecatfile and can be accessed via binset. For example:

>>> from synphot import Observation
>>> obs = Observation(stsyn.Vega, bp_hst, binset=bp_hst.binset)  
>>> bp_hst.binset  
<Quantity [  7000.,  7001.,  7002.,...,  17998., 17999., 18000.] Angstrom>
>>> obs.binset  
<Quantity [  7000.,  7001.,  7002.,...,  17998., 17999., 18000.] Angstrom>

For more details on how the catalog works, see the wavetable module. In most cases, there is no need to modify the catalog file as you can simply use Numpy or other methods to generate your own wavelength array to be used as binset should the catalog is insufficient.

Wavelength Table

The wavelength table is a feature inherited from IRAF SYNPHOT, in which it is known as wavetab. It is used to specify the name of a file containing a list of wavelength values that determine the wavelength grid to be used in calculations and plotting. In synphot and stsynphot, this has been replaced by various alternatives such as waveset, binset, or simply providing sampling of your choice in __call__().

Nevertheless, for backward compatibility, the waveset_array is provided and its default consists of 10000 points covering approximately 500 to 26000 Angstrom (sufficient for most HST calculations), spaced logarithmically with logspace() such that:

\[\log \lambda = \log \lambda_{\text{min}} + (\log \lambda_{\text{max}} - \log \lambda_{\text{min}}) \frac{i}{N}\]

where

  • \(N\) is the number of data points

  • \(i\) is the index value, starting from 0

  • \(\lambda_{\text{min}}\) and \(\lambda_{\text{max}}\) are the wavelength limits