\documentclass[letterpaper,11pt]{book} \usepackage{makeidx} \usepackage{amsmath} \usepackage{amsfonts} \usepackage{amssymb} \usepackage{graphicx} \usepackage{tabularx} \usepackage{ucs} \usepackage[utf8x]{inputenc} \usepackage{rotating} \usepackage{sectsty,fancyhdr,hyperref,minitoc} % Don't indent paragraphs \setlength{\parindent}{0pt} \setlength{\parskip}{8pt} % Define some uppercase Greek characters that MediaWiki uses \def\Alpha{{A{}}} \def\Beta{{B{}}} \def\Epsilon{{E{}}} \def\Zeta{{Z{}}} \def\Eta{{H{}}} \def\Iota{{I{}}} \def\Kappa{{K{}}} \def\Mu{{M{}}} \def\Nu{{N{}}} \def\Rho{{P{}}} \def\Tau{{T{}}} \def\Chi{{C{}}} % Set the title of the document \title{Image Photometry Table (IMPHTTAB) Reference File Format } % Change the section styles to be sans-serif \allsectionsfont{\sffamily} % Change the chapter headers to have thick black bars \chapternumberfont{\rule{\textwidth}{0.5in}\\\Large\sffamily\raggedleft} \chaptertitlefont{\Huge\sffamily\raggedleft} \sectionfont{\rule{\textwidth}{2pt}\\\nohang\sffamily} % Generate the files necessary for the index \makeindex % New table column types \newcolumntype{C}{>{\centering\arraybackslash}X} \newcolumntype{L}{>{\raggedright\arraybackslash}X} \newcolumntype{R}{>{\raggedleft\arraybackslash}X} % Customize the minitocs (Table of Contents at the start of each chapter) \mtcsetdepth{minitoc}{1} \mtcsettitle{minitoc}{} \mtcsetfont{minitoc}{*}{\sffamily} % Adjust page margins to have a little larger text area \addtolength{\textwidth}{0.5in} \addtolength{\oddsidemargin}{0.5in} \addtolength{\evensidemargin}{-0.5in} \addtolength{\topmargin}{-0.75in} \addtolength{\textheight}{1.5in} % Format headers and footers \pagestyle{fancy} \fancyhf{} \fancyhead[LE]{\sffamily \thepage \hspace{1.5pt} $\blacksquare$ \leftmark} \fancyhead[RO]{\sffamily \rightmark \hspace{1.5pt} $\blacksquare$ \thepage} \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt} \fancypagestyle{plain}{ \fancyhf{} % clear all header and footer fields \fancyfoot[C]{\sffamily \thepage} % except the center \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt}} % Change bullet styles \renewcommand{\labelitemi}{$\blacksquare$} \renewcommand{\labelitemii}{$\square$} \renewcommand{\labelitemiii}{--} \begin{document} \dominitoc \frontmatter \thispagestyle{empty} \rule{\linewidth}{0.5in} \vspace{0.66in} \begin{raggedleft} \Huge \textsf{\textbf{Image Photometry Table (IMPHTTAB) Reference File Format }} \end{raggedleft} \vspace{1in} \begin{raggedleft} \LARGE \textsf{\textbf{}} \end{raggedleft} \vfill \normalsize \begin{raggedright} \includegraphics[width=160pt]{STScI_logo_trim.pdf} \\ Hubble Division \\ 3700 San Martin Drive \\ Baltimore, Maryland 21218 \\ help@stsci.edu \\ \end{raggedright} \rule{\linewidth}{2pt} \begin{raggedright} \footnotesize Produced automatically from \\ \href{http://mediawiki.stsci.edu/mediawiki/index.php/Telescopedia:ImPhtTabDescription}{http://mediawiki.stsci.edu/mediawiki/index.php/Telescopedia:ImPhtTabDescription} \\ on Monday, May 02, 2011. \end{raggedright} \break \normalsize \tableofcontents \listoftables \listoffigures \mainmatter Science Software Report 2009-01 [SSR2009-01] \section{Introduction } \label{xref:introduction} Current pipeline calibration software for WFPC2, ACS and STIS relies on direct calls to synphot functions to compute the photometric keyword values for the image header. The keywords computed by these calls include: PHOTFLAM, PHOTBW, and PHOTPLAM. This imposes a fairly serious dependency on synphot for the pipeline environment making any updates to the core synphot code a critical path change for pipeline operations and prevents these instrument’s pipeline software from taking advantage of the new synthetic photometry package \textbf{pysynphot}. Replacing the direct calls to synphot functions with the use of pre-computed values from a new reference file would eliminate this dependency in the pipeline environment. This document describes the format for this new reference file, the Image Photometry Table. A companion document, ImPhtTab code description. (Section \ref{xref:imphttabsoftware}), describes the software required by the pipeline code to use this new photometry table, along with the task for automatically generating this reference file for a given instrument. \section{Current usage of PHOTTAB } \label{xref:current_usage_of_phottab} Two instruments currently rely on PHOTTAB reference tables during calibration processing in the pipeline; namely, STIS and NICMOS. These instruments, however, use the table in slightly different ways. The values from the STIS PHOTTAB get scaled by the values from APERTAB while NICMOS stores the values from the PHOTTAB directly in the science image global header. These differences need to be accomodated by the new format in order to minimize the coding changes required to support the new tables. \section{New Format } \label{xref:new_format} The new Image Photometry Table (IMPHTTAB) reference file will need to support at least 1 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: \footnotesize \begin{verbatim} Keyword: PHOTFLAM Name: inverse sensitivity (erg cm-2 s-1 Ang-1) As computed by: synphot.bandpar.uresp \end{verbatim} \normalsize \footnotesize \begin{verbatim} Keyword: PHOTPLAM Name: Pivot wavelength (Ang) As computed by: synphot.bandpar.pivwv \end{verbatim} \normalsize \footnotesize \begin{verbatim} Keyword: PHOTBW Name: rms bandwidth (Ang) As computed by: synphot.bandpar.bandw \end{verbatim} \normalsize \subsection{An Extension for each value } \label{xref:an_extension_for_each_value} Because of the parameterization, the values for each keyword will be stored in separate extensions where each value can be parameterized separately. The values returned by each extension would correspond to the EXTNAME header keyword value for that extension. For example, ‘jref\$t9999999q\_imp.fits[photflam,1]’ would contain the PHOTFLAM values, while extension ‘jref\$t9999999q\_imp.fits[photbw,1]’ would contain the PHOTBW values. \section{Primary Header } \label{xref:primary_header} The primary header would contain the keyword PHOTZPZT and any other photometry related keyword values that do not change with obsmode. Additional extensions could also be added to provide the values for additional photometric keyword values, should any be required or desired at a later point. \subsubsection{Sample Header } \label{xref:sample_header} A sample PRIMARY header would be: \footnotesize \begin{verbatim} 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 ' 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 \end{verbatim} \normalsize The required keywords in the primary header SYNSWVER,GRAPHTAB, and COMPTAB document the (py)synphot software version, graph table, and component table 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. \section{Table column definitions } \label{xref:table_column_definitions} The column names would conform to the following conventions for the minimum required columns for the table: \footnotesize \begin{verbatim} - OBSMODE - DATACOL - - NELEM - PARVALUES - \end{verbatim} \normalsize The selection of the appropriate row will be performed using the value of OBSMODE as generated by the calibration software and compared to the values in the \textbf{OBSMODE} column of this table. The name and units will be specified for each column, as usual, through the use of the TTYPE* and TUNIT* keyword in the extension headers. The name of the \textbf{$<$result$>$} columns will correspond to the same name as EXTNAME; for example, in the PHOTFLAM extension, the table would have \textbf{PHOTFLAM} and \textbf{PHOTFLAM$<$n$>$} columns. This will allow the table to be self-documenting regarding what values are stored in each table. The default value, corresponding to the value for an OBSMODE with no parameterization at all, would be found in the \textbf{$<$result$>$} column, whereas the \textbf{$<$result$>$$<$n$>$} columns would contain the values necessary to perform interpolation to compute the result given \emph{$<$n$>$} number of parameterized components. The \textbf{DATACOL} column would provide the name of the column to be used for determining the return value for any given \textbf{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 \textbf{PHOTFLAM1} column, while an ACS FR686N (ramp-filter) observation would get PHOTFLAM from the \textbf{PHOTFLAM2} column, given that both cases would also include time-dependence. \subsection{Parameterization of Results } \label{xref:parameterization_of_results} For most observations, there will be 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. The columns supporting parameterized components would follow this naming convention: \footnotesize \begin{verbatim} - - PARVALUES - NELEM \end{verbatim} \normalsize where the maximum value of \emph{$<$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 \textbf{$<$result$>$}, \textbf{$<$result$>$1}, \textbf{NELEM1}, \textbf{PAR1VALUES}, and \textbf{DATACOL}. However, for an instrument which supports time-dependence and ramp-filters, it would contain \textbf{$<$result$>$2}, \textbf{NELEM2}, and \textbf{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 \textbf{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 \textbf{PAR1VALUES} will be defined as with 1-D arrays in each cell with as many entries as that parameter defines, yet \textbf{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 \textbf{$<$result$>$$<$n$>$} columns will be defined as fixed-width columns which will contain arrays in each cell, with \textbf{$<$result$>$1} columns (like \textbf{PHOTFLAM1}) containing 1-D arrays in each cell, \textbf{$<$result$>$2} columns (like \textbf{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 \textbf{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 \textbf{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 \textbf{NELEM} and \textbf{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 \textbf{OPT\_ELEM} and \textbf{CENWAVE} columns would be combined into a single \textbf{OBSMODE} column, and the \textbf{THROUGHPUT} column would be renamed \textbf{PHOTFLAM} in the PHOTFLAM extension. \subsubsection{Aperture Dependence } \label{xref: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 \emph{infinite} aperture corresponding to the total flux for each object and not provide any support for parameterization based on aperture size. \subsection{Default Parameter Values } \label{xref: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 \textbf{$<$result$>$} column, or \textbf{PHOTFLAM} column in the PHOTFLAM extension, would hold this scalar default value. \section{Sample Table Data } \label{xref: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. \subsubsection{No Parameterization Case } \label{xref: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: \footnotesize \begin{verbatim} OBSMODE CH*20 %-20s "" DATACOL CH*12 %-12s "" PHOTFLAM D %10.6g flam PEDIGREE CH*30 %-30s "" DESCRIP CH*67 %-67s "" \end{verbatim} \normalsize This would result in rows which, if printed using the Tables task ‘tprint’, would look like: \footnotesize \begin{verbatim} # 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 \end{verbatim} \normalsize \subsubsection{Parameterization of One Variable } \label{xref: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: \footnotesize \begin{verbatim} 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 "" \end{verbatim} \normalsize 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: \footnotesize \begin{verbatim} # 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 \end{verbatim} \normalsize \footnotesize \begin{verbatim} # 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 \end{verbatim} \normalsize \subsubsection{Parameterization of 2 Variables } \label{xref: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: \footnotesize \begin{verbatim} 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 "" \end{verbatim} \normalsize This would result in rows which, if printed using the Tables task ‘tprint’ (where \textbf{only the first value of 1-D or 2-D columns are printed}), would look like: \footnotesize \begin{verbatim} # 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 \end{verbatim} \normalsize \footnotesize \begin{verbatim} # 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 \end{verbatim} \normalsize 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. \subsection{Summary} \label{xref: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: \begin{itemize} \item 53 filters plus a linear-ramp filter (specified as ‘lrf\#’ in the obsmode) \item 4 separate chips \item 339 separate time stamps corresponding to each anneal (specified as ‘cont\#’ in the obsmode) \item 996 wavelengths specified for the linear-ramp filter (‘lrf\#’ component in the obsmode) \end{itemize} 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. \backmatter \printindex \end{document}