Section 14. Cross Instrument Files
14.1 Image Photometry Table (IMPHTTAB) Reference File Format (<uniqname>_imp.fits)
Description: This table replaces direct calls to Synphot functions to compute the photometric keyword values for the image header that were made by the pipeline calibration software for WFPC2, ACS and STIS. The keywords computed by these calls include: PHOTFLAM, PHOTBW, and PHOTPLAM.
The Image Photometry Table (IMPHTTAB) reference file needs to support at least one parameterized attribute of the obsmode to completely describe the observation. The primary selection column common to all instruments would be the obsmode string, which is commonly stored in the PHOTMODE keyword. Additional columns would then provide the values for the photometric keywords as appropriate for the parameterization listed in the obsmode string. The values extracted from this table are given in Table 14-1.
Table 14-1 Values extracted from IMPHTTAB
Keyword |
Synphot Call |
Description |
|---|---|---|
PHOTFLAM |
Synphot.bandpar.uresp |
Inverse sensitivity (erg cm-2 s-1 Ang-1) |
PHOTPLAM |
Synphot.bandpar.pivwv |
Pivot wavelength (Ang) |
PHOTBW |
Synphot.bandpar.bandw |
rms bandwidth (Ang) |
Format: In order to support parameterization, the values for each keyword are stored in separate extensions where each value can be parameterized separately. The values returned by each extension corresponds to the EXTNAME header keyword value for that extension. For example, ‘jref$t9999999q_imp.fits[photflam,1]’ contains the PHOTFLAM values, while extension ‘jref$t9999999q_imp.fits[photbw,1]’ contains the PHOTBW values.
14.1.2 Primary Header
The primary header contains the keyword PHOTZPZT and any other photometry related keyword values that do not change with obsmode.
The required keywords in the primary header SYNSWVER,GRAPHTAB, and COMPTAB document the (py)synphot software version, Graph Table (TMG), and Component Table (TMC) used to produce the data values, respectively. The ORIGIN will document that it was generated by PyFITS rather than by the STSDAS/TABLES package. The name of the ISR which defines the table format and conventsions will also need to go into the primary header as a comment. A sample PRIMARY header would be:
Selection Criteria: Tables are selected by INSTRUMENT. The selection of the appropriate row will be performed using the value of OBSMODE.
Restrictions: None
The header of this file looks like the following:
SIMPLE = T / Fits standard
BITPIX = 16 / Bits per pixel
NAXIS = 0 / Number of axes
EXTEND = T / File may contain extensions
DATE = '2007-09-25T19:35:48' / Date FITS file was generated
IRAF-TLM= '15:40:03 (25/09/2007)' / Time of last modification
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy
COMMENT and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H
COMMENT = created by C.Pavlovsky Aug 2007
COMMENT = data provided by R.Bohlin and J.Mack
ORIGIN = 'STScI-STSDAS/TABLES' / Tables version 2002-02-22
FILENAME= 't9999999z_imp.fits' / name of file
NEXTEND = 3 / number of extensions in file
PHOTZPT = -21.1 / Photometric zero-point for STMAG system
PARNUM = 2 / Number of parameterized variables
PAR1NAME= 'MJD' / Name of 1st parameterized variable, if any
PAR2NAME= 'FR' / Name of 2nd parameterized variable, if any
DBTABLE = 'IMPHTTAB'
INSTRUME= 'acs '
DETECTOR= 'hrc '
SYNSWVER= 1.0 / Version of synthetic photometry software
GRAPHTAB= 'mtab$scf1549pm_tmg.fits' / the HST Graph table
COMPTAB = 'mtab$scg1705am_tmc.fits' / the HST components table
USEAFTER= 'September 25 2007'
PEDIGREE= 'inflight 30/05/2006 08/07/2006'
DESCRIP = 'photometry keywords reference file'
HISTORY Initial delivery of ACS photmetry keywords tables
14.1.3 Table column definitions
The column names would conform to the following conventions for the minimum required columns for the table:
Table 14-2 Column Definitions for IMPHTTAB table
Column Name |
Data Type |
Description |
|---|---|---|
OBSMODE |
CH*4 |
Observational Mode |
DATACOL |
CH*4 |
name of the column to be use for determining the return value of an OBSMODE |
<result> |
— |
Values calculated for a Synphot Call. Default column for noparameterization |
NELEM<n> |
— |
Columns describing how to reshape the 1D array into a <n>-D array for interpolation of the final value |
PAR<n>VALUES |
— |
Fixed-width column with dependent values for the parameterized component |
<result><n> |
— |
Columns with values needed to perfom inetplation to compute the result given <n> numbers of parameterized commponents <n>-D array for interpoaltion of the final value |
The name of the ‘’’<result>’’’ columns corresponds to the same name as EXTNAME; for example, in the PHOTFLAM extension, the table would have ‘’’PHOTFLAM’’’ and ‘’’PHOTFLAM<n>’’’ columns. This will allow the table to be self-documenting regarding what values are stored in each table. The default value for a non parameterized call are found in the ‘’’<result>’’’ column, whereas the ‘’’<result><n>’’’ columns contain the values necessary to perform interpolation to compute the result given ‘’<n>’’ number of parameterized components.
The ‘’’DATACOL’’’ column provides the name of the column to be used for determining the return value for any given ‘’’OBSMODE’’’. This allows anyone reading the table to understand what column was interpolated to get the final result. For example, an ACS F555W observation would get PHOTFLAM by interpolating on the ‘’’PHOTFLAM1’’’ column, while an ACS FR686N (ramp-filter) observation would get PHOTFLAM from the ‘’’PHOTFLAM2’’’ column, given that both cases would also include time-dependence.
14.1.4.1 Parameterization of Results
For most observations, there is the the need to provide some parameterization of the results based on at least 1 additional term beyond the basic OBSMODE used to define the observation. Time- and/or temperature- dependent changes requires such parameterization to be supported by this table.
where the maximum value of ‘’<n>’’ represents the maximum number of parameterized components for all modes included in this table. This format only requires that those columns used to cover the full set of OBSMODE options be present. Thus, if an instrument has only parameterization for ramp-filters and no time-dependence, then it would only contain ‘’’<result>’’’, ‘’’<result>1’’’, ‘’’NELEM1’’’, ‘’’PAR1VALUES’’’, and ‘’’DATACOL’’’. However, for an instrument which supports time-dependence and ramp-filters, it would contain ‘’’<result>2’’’, ‘’’NELEM2’’’, and ‘’’PAR2VALUES’’’ as well.
This allows the table to support varying numbers of parameterized components from one row to the next. This becomes necessary in order to support parameterization for ramp-filters and direct filters (F555W, for example) in the same table. The ‘’’PAR<n>VALUES’’’ columns provide the dependent values for the parameterized component, such as the Julian-dates at which the MJD parameter was defined. If a row only has 1 parameter defined, then ‘’’PAR1VALUES’’’ will be defined as with 1-D arrays in each cell with as many entries as that parameter defines, yet ‘’’PAR2VALUES’’’ will be set to all zeros. This insures that each column can be defined as a fixed-width column regardless of how many parameterized components are used by that detector. Each column would be defined to support the entry with the maximum number of elements. For example, if the PAR1VALUES column corresponds to ramp filters, the size allocated for that column would be based on the maximum number of elements used to specify the throughput for any of the ramp filters, such that if all but 1 ramp filter used 11 points and the last filter used 33, then the column would need to be defined to hold 33 elements.
The ‘’’<result><n>’’’ columns will be defined as fixed-width columns which will contain arrays in each cell, with ‘’’<result>1’’’ columns (like ‘’’PHOTFLAM1’’’) containing 1-D arrays in each cell, ‘’’<result>2’’’ columns (like ‘’’PHOTFLAM2’’’) containing 2-D arrays and so on. Arrays of all zeros will be used for those rows which do not have that many parameterized components. Each column will only be setup as a 1-D array regardless of how many dimensions may be folded into that array with the ‘’’NELEM<n>’’’ columns describing how to reshape that 1-D (flattened) array into a <n>-D array for interpolation of the final value. The size of each results column would then be determined by multiplying together the maximum number of parameters needed for each component. For example, if the MJD parameter only ever uses 4 dates and the ramp filter with the most wavelengths specified in the component table has 20 wavelengths, then the column ‘’’PHOTFLAM2’’’ would have 80 elements for all rows, even if a row only requires 11 wavelengths for that particular ramp filter. This would be similar to the ‘’’NELEM’’’ and ‘’’WAVELENGTH’’’ columns used in the current STIS PHOTTAB table.
Additional columns could be included in the table as required for each instruments. The current STIS photometry table serves as an example which contains many additional columns required to support the use of the table for spectroscopic data. In this case, the ‘’’OPT_ELEM’’’ and ‘’’CENWAVE’’’ columns would be combined into a single ‘’’OBSMODE’’’ column, and the ‘’’THROUGHPUT’’’ column would be renamed ‘’’PHOTFLAM’’’ in the PHOTFLAM extension.
14.1.4.1.1 Aperture Dependence
This table provides the photometry keyword values appropriate for performing photometry on an HST image. The header values of the photometry keywords assume that the measured counts represent the total flux from the object, not just the flux from some aperture. The Data Handbook for each instrument confirms this assumption, and provides the user with the information necessary for converting their counts as measured through a given aperture into total counts. As a result, even though synphot and pysynphot support parameterization by aperture for HST imaging modes, this table will only provide the results for an ‘’infinite’’ aperture corresponding to the total flux for each object and not provide any support for parameterization based on aperture size.
14.1.4.2 Default Parameter Values
Default values for the parameterized keywords need to be defined in order to support the case where the user does not specify any value on input or for those cases where there is no parameterization for the obsmode. The ‘’’<result>’’’ column, or ‘’’PHOTFLAM’’’ column in the PHOTFLAM extension, would hold this scalar default value.
14.1.5 Sample Table Data
This specification for the photometry table supports up to 3 variations of the basic table; a table without any parameterization, a table with 1 parameterized variable, and a table with 2 parameterized variables. Each has their own set of columns and column definitions. A sample set of a couple rows from each type of table provided here can help clarify exactly how the column definitions affect the actual data that gets stored in the tables and how that data gets interpreted.
14.1.5.1 No Parameterization Case
This is the simplest case for a IMPHTTAB reference file: a basic table for the PHOTFLAM values for an instrument which requires no parameterization for any obsmode. The initial table for WFC3 UVIS data would probably use this format, and is shown here as a theoretical case strictly for illustrative purposes. The column definitions, as reported by the Tables task ‘tlcol’ would be:
OBSMODE CH*20 %-20s ""
DATACOL CH*12 %-12s ""
PHOTFLAM D %10.6g flam
PEDIGREE CH*30 %-30s ""
DESCRIP CH*67 %-67s ""
This would result in rows which, if printed using the Tables task ‘tprint’, would look like:
# row OBSMODE DATACOL PHOTFLAM PEDIGREE DESCRIP
# flam
1 wfc3,uvis1,f487n PHOTFLAM 7.0097E-18 INFLIGHT 04/10/1997 15/09/2000 Combined Component Efficiencies
14.1.5.2 Parameterization of One Variable
A table for the PHOTFLAM values for an instrument which requires parameterization of one variable, typically date, represents the next style of table. This example, strictly for illustrative purposes, shows how a table for ACS WFC imaging supporting only ramp-filters, and NOT time-dependence, would look. The column definitions, as reported by the Tables task ‘tlcol’ would be:
OBSMODE CH*25 %-25s ""
DATACOL CH*12 %-12s ""
PHOTFLAM D %10.6g flam
PHOTFLAM1 D[11] %10.6g flam
PAR1VALUES D[11] %10.6g angstroms
NELEM1 S %4d ""
PEDIGREE CH*30 %-30s ""
DESCRIP CH*67 %-67s ""
This would result in rows which, if printed using the Tables task ‘tprint’(where only the first value of 1-D columns are printed), would look like:
# row OBSMODE DATACOL PHOTFLAM PHOTFLAM1 PAR1VALUES NELEM1
# flam flam angstrom
1 acs,wfc1,f555w PHOTFLAM 1.9542E-19 0.0 0.0 0
2 acs,wfc1,fr656n PHOTFLAM1 0.0 1.5177E-18 1.8210E-19 11
# row PEDIGREE DESCRIP
#
1 INFLIGHT 04/10/1997 15/09/2000 Combined Component Efficiencies
1 INFLIGHT 04/10/1997 15/09/2000 Combined Component Efficiencies
14.1.5.3 Parameterization of 2 Variables
A table for the PHOTFLAM values for an instrument which requires parameterization of more than one variable represents the next and probably most common style of table. This example, strictly for illustrative purposes, shows how a table for ACS WFC imaging supporting time-dependence and ramp-filter parameterization would look. The column definitions, as reported by the Tables task ‘tlcol’ would be:
OBSMODE CH*40 %-40s ""
DATACOL CH*12 %-12s ""
PHOTFLAM D %10.6g flam
PHOTFLAM1 D[4] %10.6g flam
PHOTFLAM2 D[44] %10.6g flam
PAR1VALUES D[4] %10.6g days
PAR2VALUES D[11] %10.6g angstroms
NELEM1 S %4d ""
NELEM2 S %4d ""
PEDIGREE CH*30 %-30s ""
DESCRIP CH*67 %-67s ""
This would result in rows which, if printed using the Tables task ‘tprint’ (where ‘’’only the first value of 1-D or 2-D columns are printed’’’), would look like:
# row OBSMODE DATACOL PHOTFLAM PHOTFLAM1 PHOTFLAM2 PAR1VALUES PAR2VALUES NELEM1 NELEM2
# flam flam flam days angstrom
1 acs,wfc1,mjd,f555w PHOTFLAM1 0.0 1.9542E-19 0.0 52334.0 0.0 4 0
2 acs,wfc1,mjd,fr656n PHOTFLAM2 0.0 0.0 1.5016E-18 52334.0 6274.0 4 11
# row PEDIGREE DESCRIP
#
1 INFLIGHT 04/10/1997 15/09/2000 Combined Component Efficiencies
1 INFLIGHT 04/10/1997 15/09/2000 Combined Component Efficiencies
The order of the parameterized variables will need to be consistent for all rows in the table; for example, PAR1VALUES will always represent ‘mjd#’. This requirement comes from the definition of the array size for that values in that column. The second parameterized variable would then contain the next most common type of parameterization, and the array definition for that column would be the maximum number of elements required for any of the rows. For ACS, the ramp filters might be the second set of variables, so the PAR2VALUES column would be written out with a size of D[11] if all the ramp filters are specified with only 11 wavelengths. If one ramp filter throughput has been specified using 22 wavelengths, then the column would need to be defined with a size of D[22], instead.
14.1.6 Summary
The table format described here was designed to work with the current capabilities of the STSDAS/Tables library, which supports tables whose cells contains arrays. This results in a file which contains a fair amount of wasted space to accommodate the varying levels of parameterization from one obsmode to the next for a given instrument. The largest expected file size for this reference file would be for WFPC2, if one was generated at all, where they have:
53 filters plus a linear-ramp filter (specified as ‘lrf#’ in the obsmode)
4 separate chips
339 separate time stamps corresponding to each anneal (specified as ‘cont#’ in the obsmode)
996 wavelengths specified for the linear-ramp filter (‘lrf#’ component in the obsmode)
This would result in a reference file on the order of 871 Mb when generated to return values for all 3 photometric keywords. Presumably, the linear-ramp filter throughput tables could be re-delivered to CDBS with fewer wavelengths if linear interpolation would provide for accurate enough results. This would significantly reduce the size of the WFPC2 reference file should one need to be created. The next worst case identified so far would probably be the ACS reference table where there are currently only 4 timestamps specified for the time-dependence and only 11 wavelengths for their linear-ramp filters, resulting in a file only on the order of 32Mb.
This format for the reference file would not be used to support JWST observations. Instead, a more efficient format utilizing variable-length arrays within the cells of a single column would result in a more efficient table that would be smaller than the format proposed here. This more efficient format could not be used for HST as the STSDAS/Tables package does not support this style of table, while PyFITS can already work with tables that use this convention. Therefore, this more efficient form will only be implemented, using PyFITS, to support JWST observations when necessary.