****************************WARNING THIS FILE IS MORE THAN 80 CHARACTERS WIDE!******************************* Reference Guide of FOS Calibration Reference Files and Tables Cynthia J. Taylor and Charles D. Keyes Space Telescope Science Institute August 1994 Abstract Complete tabulations of recommended FOS reference files (except flat field, inverse sensitivity, and dead diodes) and reference tables AS OF 12 AUGUST 1994 are specified in convenient matrix format. Lists of recommended flat fields are covered in CAL/FOS-090 (C. D. Keyes and C. J. Taylor, April, 1993), inverse sensitivity is in CAL/FOS-093 (C. J. Taylor and C. D. Keyes, June, 1993), and dead diodes is in CAL/FOS-112 (C. J. Taylor, August, 1994) and current lists of all three are found on STEIS in the /instrument_news/fos directory. ASCII and Postscript versions of the lists of recommended FOS reference files and tables covered in this report are posted on STEIS in the /instrument_news/fos directory. I. Introduction There are currently six reference file types and eleven reference table types used in calibration (see Table 1). Two reference file types, Point Spread Function and Line Spread Function, are not used in CALFOS. Determining the correct file to use can be daunting, as there are thousands of reference files. This report will list the recommended files as well as the history of all the files delivered to CDBS. While the IRAF/STSDAS task getreffile and the Calibration Reference screens in StarView will list the recommended reference files and tables for a particular observation, it is a good idea to double check this report and the latest versions of the flat field, inverse sensitivity (IVS), and dead diodes recommendation lists on STEIS. In the future there will be one new reference file type and four new reference table types. The reference file will be an Average Inverse Sensitivity (not to be confused with the current Inverse Sensitivity reference file). The four new reference tables will be: HST Focus History, Relative aperture throughput, Relative aperture throughput versus focus, and Time changes in inverse sensitivity. An upcoming Instrument Science Report will explain the new file and tables. Future updates to the recommendation list and history list will contain these new files. Table 1: FOS Reference Files and Tables Types CALFOS CDBS Header Filename relation Keyword Extension Contents ---------------------------------------------------------------------------------------------- cybacr BACHFILE .r0h & .r0d Default background file (count rate) cyfltr FLnHFILE .r1h & .r1d Flat field file cyivsr IVnHFILE .r2h & .r2d Inverse Sensitivity file (ergs cm-2 A-1) cyretr RETHFILE .r3h & .r3d Retardation file for polarimetry data cyddtr DDTHFILE .r4h & .r4d Dead (Disabled) Diode file cyqinr DQnHFILE .r5h & .r5d Data Quality Initialization file cypsf N/A .r6h & .r6d Point Spread Function files cylsf N/A .r7h & .r7d Line Spread Function files cyccs0r CCS0 .cy0 Aperture areas cyccs1r CCS1 .cy1 Aperture positions cyccs2r CCS2 .cy2 Sky emission line position cyccs3r CCS3 .cy3 Sky/background filter widths cyccs4r CCS4 .cy4 Wollaston/waveplate parameters (Polarimetry) cyccs5r CCS5 .cy5 Sky shift parameters cyccs6r CCS6 .cy6 Wavelength parameters cyccs7r CCS7 .cy7 GIMP scale factors cyccs8r CCS8 .cy8 Mean background count rate cyccs9r CCS9 .cy9 Scattered light correction coccg2r CCG2 .cmg Paired-pulse parameters (with GHRS) The three reference file types that are covered in CAL/FOS-090, 093, and 112 (flat fields, inverse sensitivity, and dead diodes, respectively) are time variable and have more complex recommendations. The reference files and tables in this report have more straightforward recommendations. Tables 2-8 are recommended reference files and tables. Two types of reference files, the Data Quality Initialization and Line Spread Functions, have too many files to be easily presented in a table. However, ASCII tables of the recommended files are posted on STEIS as fos_qin_recommend.txt (for Data Quality Initialization) and fos_lsf_recommend.txt (for Line Spread Function) in the /instrument_news/fos directory. II. Lists of Recommended Files and Tables The common and/or supported configurations of the recommended files and tables are presented in Tables 2-8. The columns vary according to type of reference file and table and depend on the CDBS selection criteria. However, each entry does have the same format: the USEAFTER date as yyyymmdd and the filename with both the header and data file extensions. This section contains a brief description and the selection criteria used by CDBS (except USEAFTER) to determine the correct file. The selection criteria are from the Calibration Data Base Design, Version 6.0 (April, 1994). Background Reference File (Table 2): ------------------------------------ This reference file is the default background in count rate. The CDBS selection criteria are detector and overscan. However Table 2 shows the files for the default, overscan=5. Flat Field Reference File (not listed here): -------------------------------------------- The recommended flat field files are listed in CAL/FOS-090 and in updated files (in both ASCII and Postscript formats) on STEIS in the /instrument_news/fos directory. The updated files are: "flat_field_tables_mmmyy.ps", "flat_field_tables_mmmyy.txt", "post_costar_flat_field_mmmyy.ps", and "post_costar_flat_field_mmmyy.txt", where "mmmyy" is month the posting date in month and year, ".ps" indicates the Postscript version, and ".txt" is the ASCII text version. The CDBS selection criteria are: detector, overscan, aperture id, aperture position, filter grating wheel id, polarizer id, and pass direction. The tables in CAL/FOS-090 and the updated tables on STEIS are for overscan=5. Inverse Sensitivity Reference File (not listed here): ---------------------------------------------------- The recommended IVS files are listed in CAL/FOS-093 and in updated files (in both ASCII and Postscript formats) on STEIS in the /instrument_news/fos directory. The updated files are: "ivs_tables_mmmyy.ps", "ivs_tables_mmmyy.txt", "post_costar_ivs_mmmyy.ps", and "post_costar_ivs_mmmyy.txt", where "mmmyy" is the posting date in month and year, ".ps" indicates the Postscript version, and ".txt" is the ASCII text version. The CDBS selection criteria are: detector, overscan, aperture id, aperture position, filter grating wheel id, polarizer id, and pass direction. The tables in CAL/FOS-093 and the updated tables on STEIS are for overscan=5. Retardation Reference Files (Tables 3-6): ----------------------------------------- The retardation files are used during polarimetry calibration to create the observation matrix f(w). Tables 3 and 4 show the reference files for the supported configurations. The recommended files are ground based numbers based on recent inflight wavelength dispersion and were created by Richard Allen. Tables 5 and 6 show the reference files for the non-supported configurations. The CDBS selection criteria are: detector, overscan, polarizer id, and filter grating wheel id. Dead (Disabled) Diode Reference Files (not listed here): -------------------------------------------------------- The recommended dead diode files are listed in CAL/FOS-112 and in updated files (in both ASCII and Postscript formats) on STEIS in the /instrument_news/fos directory. The updated files are: "dead_diode_tables_mmmyy.ps" and "dead_diode_tables_mmmyy.txt", where "mmmyy" is month the posting date in month and year, ".ps" indicates the Postscript version, and ".txt" is the ASCII text version. The CDBS selection criterion is detector. Quality Initialization Reference Files (not listed here): --------------------------------------------------------- Because there are almost 1800 different recommended quality initialization files, tables of recommended files are not listed here. Posted on STEIS in the /instrument_news/fos is an ASCII table of the recommended files, "fos_qin_recommend.txt". The table columns are: useafter, detector, overscan, aper_id, aper_pos, fgwa_id, polar_id, pass_dir, and header_file. WARNING, THE FILE IS MORE THAN 80 CHARACTERS WIDE. The quality initialization files are used to flag intermittent or noisy diodes but have not been kept up to date. Current lists of intermittent and noisy diodes are included in the recommended list of dead diode reference files posted on STEIS and are available from the Research Support Branch Analysis Hot Line (telephone: (410) 338-1082 or e-mail: analysis@stsci.edu). The CDBS selection criteria are: detector, overscan, aperture id, aperture position, filter grating wheel id, polarizer id, and pass direction. Point Spread Function Reference Files (Table 7): ------------------------------------------------ FOS point spread function (PSF) reference files are not used in CALFOS calibration steps. They have been delivered to CDBS for reference. The PSF's are Pre-COSTAR only. Refer to CAL/ FOS-104 (I. N. Evans, September, 1993) for more details. The CDBS selection criteria are: detector and wavelength. Line Spread Function Reference Files (not listed here): ------------------------------------------------------- Because there are 513 Line spread function (LSF) reference files, tables of the recommended files are not listed here. Posted on STEIS in the /instrument_news/fos directory is an ASCII table of the recommended files, "fos_lsf_recommend.txt". The table columns are: useafter, detector, aper_id, wavelength, and header_file. The LSF are Pre-COSTAR only. For more details, please refer to CAL/FOS-104. The CDBS criteria are: detector, wavelength, and aperture id. Aperture Areas Reference Table (Table 8): ---------------------------------------- This reference table contains the areas of the FOS entrance apertures and is used to scale the sky spectrum to the object spectrum. The appropriate table entry is determined by: detector, aperture id, and aperture position. Aperture Positions Reference Table (Table 8): --------------------------------------------- This reference table is used to determine which aperture (UPPER or LOWER) of a paired aperture was used. The appropriate table entry is determined by: detector and filter grating wheel id. Sky Emission Line Position Reference Table (Table 8): ----------------------------------------------------- This reference table specifies spectral regions in a sky spectrum known to have emission lines. The regions are not smoothed before the sky is subtracted from the object spectrum. The appropriate table entry is determined by: detector, filter grating wheel id, first channel (diode), and NXSTEPS. Note that these are the pre-launch values. The Science Verification data has never been confirmed due to poor table design. Sky/Background Filter Widths Reference Table (Table 8): ------------------------------------------------------- This reference table specifies the mean and median filter widths for smoothing the background and sky spectra. The appropriate table entry is determined by detector. Wollaston/Waveplate Parameters Reference Table (Table 8): --------------------------------------------------------- This reference table is used in the polarimetry calibration. It contains the angles of each of the two pass directions with respect to the Q=1 coordinate axis of the polarization reference frame. The appropriate table entry is determined by: detector and polarizer id. The difference between the b9d1019my.cy4 table and the e5v13262y.cy4 tables is that the latter table has the first inflight calibrated Red side (Amber) values and updated Blue side values. Only the supported configurations were updated. Sky Shift Parameters Reference Table (Table 8): ----------------------------------------------- This reference table gives the shift (in data points) used to align the sky spectrum with the object spectrum before subtracting. The appropriate table entry is determined by: detector, aperture id, aperture position, filter grating wheel id, and NXSTEPS. Wavelength Parameters Reference Table (Table 8): ------------------------------------------------ This reference table gives the dispersion relation used to compute the wavelength of each data point from the diode position. The appropriate table entry is determined by: detector, filter grating wheel id, aperture id, aperture position, polarizer id, and pass direction. The difference between the two tables, bck10546y.cy6 and e5v11576y.cy6, is that the latter contains the first calibrated Red side (Amber) polarimetry wavelengths and updated Blue side polarimetry wavelengths. Only supported polarimetry configurations were updated. GIMP Scale Factors Reference Table (Table 8): --------------------------------------------- This reference table contains the scale factors used for scaling the model geomagnetic field strength calculations in CALFOS. These calculations are used to correct the geomagnetically induced image motion problem (GIMP). The appropriate table entry is determined by detector. Starting in April, 1993 the GIMP has been corrected onboard by default. If the science header keyword YFGIMPEN is equal to FALSE, then the onboard correction was not performed and this calibration table is used in CALFOS. Mean Background Count Rates Reference Table (Table 8): ------------------------------------------------------ This reference table contains the predicted mean background count rates as a function of geomagnetic latitude and longitude. The mean background count rate at the position and time of the observation is interpolated from the table and scales the reference background file in CALFOS. The appropriate table entry is determined by: detector, geomagnetic latitude, and geomagnetic longitude. Scattered Light Correction Reference Table (Table 8): ----------------------------------------------------- This reference table contains the beginning and ending diode ranges which define the region of the spectral data from which the amplitude of scattered light will be measured. These regions correspond to spectral regions that have no sensitivity to dispersed light. Some gratings lack regions of no sensitivity and therefore contain zeros for the range specification. The appropriate table entry is determined by: detector and filter grating wheel id. Paired-Pulse Parameters Reference Table (Table 8): -------------------------------------------------- This reference table contains the paired-pulse parameters used to correct for non-linearity at high count rates. This table is shared with GHRS. The appropriate table entry is determined by: instrument and detector. III. Location of Reference Files and Tables Unless otherwise noted, all the reference files and tables listed in this report are in CDBS, PODPS, and the Archive. The files and tables are first delivered to CDBS and then get released to PODPS and delivered to Archive. In addition, copies of the files are made available in /cdbs/yref (for reference files) and /cdbs/ytab (for reference tables) directories on: Tib, Nemesis, Icarus, Sol, VAX Science Cluster, and are posted on STEIS. New files and tables are copied nightly via daemon from the Tib cluster to STEIS and Nemesis (the UNIX science clusters then point to Nemesis). However, the files and tables must be manually put on Tib and the VAX Science Cluster by Calvin Tullos in the Science Observatory Branch. Outside users can get them from STEIS in the /cdbs/yref or /cdbs/ytab directories, or retrieve them from Archive using the Files or Dataset screen. Remember that the files and tables will be in UNIX format on STEIS and VAX format from the Archive. Use the STSDAS tasks, vax2sun and sun2vax, to convert to the appropriate format. The easiest methods to determine if you have the correct reference file or table for your observation are to run STSDAS getreffile (in stlocal.cdbsutil) or use the Calibration Reference screen in StarView (see HST Data Handbook, "Identifying the Best Files Using StarView", page 71). Both programs use the date of the observation and the USEAFTER dates of the reference files and tables to determine the correct file. The most recent version of the file will be chosen if there are multiple files with the same USEAFTER date. We urge you to check the results with the tables of recommended files posted on STEIS. Note that getreffile is available only at STScI. If you want to find the files for a particular configuration, then the best way is to use the STSDAS task, query, in the stlocal.cdbsutil package (again only at STScI). You'll have to use the CDBS Relation name in Table 1 to as the parameter id in query. The CDBS selection criteria are listed in Section II for each reference file and table. Refer to the Calibration Data Base Design (Version 6.0, April, 1994) for the list of columns available for each reference file and table. In order to find out the "filename" for the reference tables, you'll have to use the STSDAS task, inquiry (in stlocal.cdbsutil). The parameter id "relinfo_sdas" contains the names of the reference tables. These tasks will give you the reference file or table that fulfills the specified search parameters, but it will not tell you if it is an appropriate file. Please refer to tables of recommended files and the history tables to verify if it is an appropriate file or table. All information in this report from the CDBS was obtained using query and inquiry. IV. Availability of Information and Updates Periodically updated ASCII text and Postscript versions of Tables 2-8 will be maintained in the /instrument_news/fos directory on STEIS and will be available for anonymous ftp from stsci.edu. The files will be named "ref_files_tables_mmmyy.ps" and "ref_files_tables_mmmyy.txt", where mmmyy is the posting date in month and year, the extension ".ps" denotes the Postscript version, and ".txt" denotes the ASCII version. For example, the first files delivered are "ref_files_tables_aug94.ps" and "ref_files_tables_aug94.ps". Remember this is for all reference files and tables except for flat fields, IVS, and dead diodes which have their own recommended lists (flat_field_tables_mmmyy.*, post_costar_flat_fields_mmmyy.*, ivs_tables_mmmyy.*, post_costar_ivs_mmmyy.*, and dead_diodes_mmmyy.* - where * is ".txt" or ".ps"). Copies and updates can be obtained from the Research Support Branch Analysis Hot Line (telephone: (410) 338-1082 or e-mail: analysis@stsci.edu). References Baum, S. (ed.), 1994, HST Data Handbook. Calibration Data Base Design, Version 6, 1994. Evans, I.N., 1993, Instrument Science Report CAL/FOS-104. Keyes, C.D. and Taylor, C.J., 1993, Instrument Science Report CAL/FOS-090. Taylor, C.J., 1994, Instrument Science Report CAL/FOS-112. Taylor, C.J. and Keyes, C.D., 1993, Instrument Science Report CAL/FOS-093. Notes for Table Interpretation: "*": wildcard yyyymmdd: USEAFTER date (4 digit year A.D., 2-digit month, 2-digit day) {in Tables 2-8} abcdefghi.r*h,(.r*d): rootname of reference file and extensions for header (and data) files abcdefghi.cy* or .cm*: rootname and extension of reference table The letter "l" in rootnames in the tables is capitalized ("L") to make it more legible. RECOMMENDED FOS REFERENCE FILES ------------------------------- RECOMMENDED FOS BACKGROUND REFERENCE FILES (.r0h) Table 2: FOS BACKGROUND REFERENCE FILES Detector USEAFTER and File ------------------------------------------- AMBER 19900101 b3m1128fy.r0h,.r0d BLUE 19900101 b3m1128my.r0h,.r0d RECOMMENDED FOS RETARDATION REFERENCE FILES (.r3h) Table 3: AMBER RETARDATION REFERENCE FILES for SUPPORTED CONFIGURATIONS Grating Pol A Pol B --------------------------------------------------------------------------- H19 Not supported 19900101 a4n1540sy.r3h,.r3d 19930608 e5v1122ry.r3h,.r3d H27 Not supported 19900101 a4n15413y.r3h,.r3d 19930608 e5v1122sy.r3h,.r3d H40 19900101 b6o10478y.r3h,.r3d Not supported 19930608 e5v1122ty.r3h,.r3d Table 4: BLUE RETARDATION REFERENCE FILES for SUPPORTED CONFIGURATIONS Grating Pol A Pol B --------------------------------------------------------------------------- H13 Not supported 19900101 b6o10471y.r3h,.r3d 19930608 e5v11230y.r3h,.r3d H19 Not supported 19900101 b7p12535y.r3h,.r3d 19930608 e5v11231y.r3h,.r3d H27 Not supported 19900101 b6o10478y.r3h,.r3d 19930608 e5v11232y.r3h,.r3d Table 5: AMBER RETARDATION REFERENCE FILES for NON -SUPPORTED CONFIGURATIONS Grating Pol A Pol B ---------------------------------------------------------------------------- H19 19900101 a4n1540py.r3h,.r3d Supported H27 19900101 a4n15410y.r3h,.r3d Supported H40 Supported 19900101 a4n15418y.r3h,.r3d H57 19900101 a4n1541by.r3h,.r3d 19900101 a4n1541ey.r3h,.r3d H78 19900101 a4n1541jy.r3h,.r3d 19900101 a4n1541Ly.r3h,.r3d L15 19900101 a4n1541oy.r3h,.r3d 19900101 a4n1541qy.r3h,.r3d L65 19900101 a4n1541sy.r3h,.r3d 19900101 a4n15421y.r3h,.r3d PRISM 19900101 a4n15423y.r3h,.r3d 19900101 a4n15426y.r3h,.r3d Table 6: BLUE RETARDATION REFERENCE FILES for NON -SUPPORTED CONFIGURATIONS Grating Pol A Pol B ---------------------------------------------------------------------------- H13 19900101 a4n15429y.r3h,.r3d Supported H19 19900101 a4n1542fy.r3h,.r3d Supported H27 19900101 a4n1542ny.r3h,.r3d Supported H40 19900101 b6o1047ay.r3h,.r3d 19900101 a4n1543ky.r3h,.r3d H57 19900101 a4n1543oy.r3h,.r3d 19900101 a4n1543qy.r3h,.r3d L15 19900101 a4n1543ty.r3h,.r3d 19900101 a4n15442y.r3h,.r3d L65 19900101 a4n15445y.r3h,.r3d 19900101 a4n15449y.r3h,.r3d PRISM 19900101 a4n1544cy.r3h,.r3d 19900101 a4n1544fy.r3h,.r3d RECOMMENDED FOS DATA QUALITY INITIALIZATION REFERENCE FILES (.r5h) See ASCII table fos_qin_recommend.txt RECOMMENDED FOS POINT SPREAD FUNCTION FILES (.r6h) Table 7: FOS POINT SPREAD FUNCTION FILES AMBER BLUE Wavelength USEAFTER and Filename Wavelength USEAFTER and Filename ------------------------------------------------------------------------------------------- 1600 19900101 dbb1015ry.r6h,.r6d 1200 19900101 dbb10189y.r6h,.r6d 1800 19900101 dbb10160y.r6h,.r6d 1400 19900101 dbb1018ey.r6h,.r6d 2000 19900101 dbb10163y.r6h,.r6d 1600 19900101 dbb1018hy.r6h,.r6d 2200 19900101 dbb10166y.r6h,.r6d 1800 19900101 dbb1018jy.r6h,.r6d 2400 19900101 dbb10168y.r6h,.r6d 2000 19900101 dbb1018Ly.r6h,.r6d 2600 19900101 dbb1016ay.r6h,.r6d 2200 19900101 dbb1018py.r6h,.r6d 2800 19900101 dbb1016cy.r6h,.r6d 2400 19900101 dbb1018ry.r6h,.r6d 3000 19900101 dbb1016ey.r6h,.r6d 2600 19900101 dbb10190y.r6h,.r6d 3200 19900101 dbb1016gy.r6h,.r6d 2800 19900101 dbb10192y.r6h,.r6d 3400 19900101 dbb1016iy.r6h,.r6d 3000 19900101 dbb10194y.r6h,.r6d 3600 19900101 dbb1016Ly.r6h,.r6d 3200 19900101 dbb10196y.r6h,.r6d 3800 19900101 dbb1016my.r6h,.r6d 3400 19900101 dbb10199y.r6h,.r6d 4000 19900101 dbb1016py.r6h,.r6d 3600 19900101 dbb1019by.r6h,.r6d 4200 19900101 dbb1016ry.r6h,.r6d 3800 19900101 dbb1019ey.r6h,.r6d 4400 19900101 dbb1016ty.r6h,.r6d 4000 19900101 dbb1019hy.r6h,.r6d 4600 19900101 dbb10171y.r6h,.r6d 4200 19900101 dbb1019ky.r6h,.r6d 4800 19900101 dbb10172y.r6h,.r6d 4400 19900101 dbb1019Ly.r6h,.r6d 5000 19900101 dbb10174y.r6h,.r6d 4600 19900101 dbb1019ny.r6h,.r6d 5200 19900101 dbb10176y.r6h,.r6d 4800 19900101 dbb1019py.r6h,.r6d 5400 19900101 dbb10178y.r6h,.r6d 5000 19900101 dbb1019ry.r6h,.r6d 5600 19900101 dbb1017ay.r6h,.r6d 5200 19900101 dbb1019ty.r6h,.r6d 5800 19900101 dbb1017dy.r6h,.r6d 5400 19900101 dbb10201y.r6h,.r6d 6000 19900101 dbb1017fy.r6h,.r6d 6200 19900101 dbb1017iy.r6h,.r6d 6400 19900101 dbb1017ky.r6h,.r6d 6600 19900101 dbb1017Ly.r6h,.r6d 6800 19900101 dbb1017ny.r6h,.r6d 7000 19900101 dbb1017py.r6h,.r6d 7200 19900101 dbb1017ry.r6h,.r6d 7400 19900101 dbb1017ty.r6h,.r6d 7600 19900101 dbb10180y.r6h,.r6d 7800 19900101 dbb10182y.r6h,.r6d 8000 19900101 dbb10183y.r6h,.r6d 8200 19900101 dbb10184y.r6h,.r6d 8400 19900101 dbb10186y.r6h,.r6d RECOMMENDED FOS LINE SPREAD FUNCTION FILES (.r7h) See ASCII table fos_lsf_recommend.txt. RECOMMENDED FOS REFERENCE TABLES -------------------------------- Table 8: RECOMMENDED FOS REFERENCE TABLES Table Description Keyword USEAFTER and Filename -------------------------------------------------------------------------------------- Aperture areas CCS0 19900101 a3d1145dy.cy0 Aperture positions CCS1 19900101 aaj0732ay.cy1 Sky emission line position CCS2 19900101 a3d1145fy.cy2 Sky/background filter widths CCS3 19900101 a3d1145gy.cy3 Wollaston/waveplate parameters (polarimetry) CCS4 19900101 b9d1019my.cy4 19930608 e5v13262y.cy4 Sky shift parameters CCS5 19900101 a3d1145jy.cy5 Wavelength parameters CCS6 19900101 bck10546y.cy6 19930608 e5v11576y.cy6 GIMP scale factors CCS7 19900101 ba910502y.cy7 Mean background count rates CCS8 19900101 ba31407Ly.cy8 Scattered light correction CCS9 19900101 e3i09491y.cy9 Paired-pulse parameters CCG2 19900101 a3d1145Ly.cmg