Specification for VDAS and PAS files, headers, and structure on disk - MEC - 3/7/12 NOTE: This specification has been superseded by https://luna.mpe.mpg.de/wikihetdex/index.php/VDAS_and_PAS_specification. For VIRUS data, the baseline plan has 75 IFUs, with a goal of 82 IFUs laid out in an approximately hexagonal pattern, with six IFUs missing in the middle to leave space for LRS2, HRS, and MRS. See https://luna.mpe.mpg.de/wikihetdex/index.php/Image:Example.jpg. Each IFU feeds two CCDs. Each CCD is read out by a pair of amplifiers in opposing corners. For most/all CCDs, these will be the amplifiers labeled LR and UL on page 2 of HXTR0043. The data read out by each amplifier is stored in a separate FITS file on disk. File layout on disk $VIRUS_DATA_ROOT/20120604/ <--- organized in nightly working directories as is done at HET now? [yes?] virus1234567/ <--- organized by an incrementing unique serial number (as for lrs and hrs exposures now) exp001/ <--- by exposure (which may or may not be at different dither positions) exp002/ [could even be different CR splits at the same dither position, for example] exp003/ ... expnnn/ virus/ gp/ <--- the filenames in 'gp' and 'wfs' may just be soft links to files in a metrology directory elsewhere wfs/ e.g. $VIRUS_DATA_ROOT/20120604/metrology/ log <--- note anything useful for a human to understand this observation ql-driver ql-results ql-recipe ------------------------------------------------------------------------------- File names We name files by UTC start time, source, and image type. For the UTC, we use ISO 8601 compliant date and time strings, leaving out dashes and columns because they can cause problems, depending on the operating system. The "source" field for VIRUS science data files encodes the IFU slot in the focal plane, the CCD, and the amplifier used to read out each half of the detector. IFU slot numbers refer to a particular location on the focal plane, and will map to a particular place on the sky, e.g.: 91 92 93 ... 100 ... 31 32 33 ... 40 21 22 23 ... 30 (on sky) 11 12 13 ... 20 1 2 3 ... 10 We will need to document exactly which IFU slots numbers are currently populated with which IFUs in a configuration file whose format is TBD. <--- Please note. Another config The IFU slot position is also encoded in the FITS keyword IFUSLOT. file that VDAS needs to parse. Simple table: IFU slot vs. IFUID. CCDs come in pairs, and are labeled "L" for left and "R" for right. See page 2 of HXTR0043. This role is also documented in the FITS keyword CCDPOS. Amplifiers are labeled "U" for upper and "L" for lower, which refer to the upper and lower halves of the physical CCD. This label is also documented in the FITS keyword CCDHALF. The vendor's mark "A" is by definition on the upper edge of the CCD. This U/L scheme has the advantage that the vendor also labels the four possible amplifiers LR, LL, UR, and UL (but ignore the vendor's left/right labeling of the amplifiers, which is as seen from the front of the detector, where we illuminate the CCD from the back). See page 2 of HXTR0043. For the image type, we standardize on fixed length strings, say 3 characters: sci, drk, zro, flt, cmp For VIRUS science data files we have, for example: 20120604T053713.3_042RU_drk.fits 20120604T053713.3_100RL_flt.fits 20120604T053713.3_002LL_sci.fits 20120604T053713.3_047LU_cmp.fits For the rest of the cameras, there is interest in 3-character abbreviations for the "source" field, e.g.: gc1 - guide camera 1 gc2 - guide camera 2 wf1 - WFS 1 wf2 - WFS 2 acm - acquisition camera pvw - pupil viewer cwf - calibration WFS ttc - tip/tilt camera bib - boresight imaging bundle ccm - commissioning camera For guider data files we have, for example: 20120604T053713.3_gc1_drk.fits For acqusition camera data files we have, for example: 20120604T053713.3_acm_sci.fits Q: Should we encode the filter in guider or acquisition camera data file names? [yes?] That would drive us away from fixed length filenames. e.g. 20120604T053713.3_gc1_sci_g.fits or something. Note that the most interesting guide camera files will be the accumulated images, formed by summing the guide images over a science exposure. These are the images that will be used to compute the FWHM, relative transparency, and so on that CURE needs to reduce the science data. These images will be named... =============================================================================== Headers VIRUS: Standard stuff: SIMPLE = T / file does conform to FITS standard BITPIX = 16 / number of bits per data pixel NAXIS = 2 / number of data axes NAXIS1 = 1064 / length of data axis 1 NAXIS2 = 2064 / length of data axis 2 EXTEND = T / FITS dataset may contain extensions COMMENT FITS (Flexible Image Transport System) format defined in Astronomy and COMMENT Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365. COMMENT Contact the NASA Science Office of Standards and Technology for the COMMENT FITS Definition document #100 and other FITS information. BZERO = 32768 / offset data range to that of unsigned short BSCALE = 1 / default scaling factor ------------------------------------------------------------------------------- First we document the observation: HETDEX observations are labeled with a target->observation->dither hierarchy. These are encoded into FITS header keywords as follows: OBJECT = 'DEX_016' / Target name OBSID = 3 / Observation number for this target DITHER = 1 / Position of dither mechanism The position of the dither mechanism is read from the hardware to populate the header (and was presumably specified as a setup parameter at some point). OBJECT and OBSID are passed in with other target information, There is an operational issue of whether the HETDEX observation planner passes OBSID in as a separate parameter (OBJECT='DEX_016' and OBSID=3), or if the planner passes OBSID in as a compound parameter (OBJECT='DEX_016 obs 3'). In the second case, VDAS would parse that string to separate the two values). To decide which is best, we need to resolve what the planning software keeps for its list of targets. Either it keeps a list of separate visits, conceptually equivalent to 'DEX_016 obs 1', 'DEX_016 obs 2', and 'DEX_016 obs 3', or it knows about field DEX_016, and then knows we want 3 separate visits. Next we need to add a keyword to describe the mode of the observation, e.g. standard HETDEX, or some non-standard, non-dithered, parallel, or whatever, observation. Perhaps just the recipe name, a version number, and the date would suffice, e.g.: RECIPE = 'hetdex-1.01 2012-02-05T16:54:47Z' / Recipe used for this observation Next we provide details of the exposure: OBSERVAT= 'MCDONALD' / Observatory OBSERVER= 'Resident Astronomer' / Observers EXPTIME = 360.00 / Actual integration time (sec) DARKTIME= 360.17 / Total elapsed time (sec) IMAGETYP= 'object' / object, zero, dark, flat, comp, etc. DATE-OBS= '2012-06-04' / Date (yyyy-mm-dd) of observation UT = '05:37:13.30' / Universal time ST = '15:33:25.69' / Local mean sidereal time MJD = 56082.2341817 / Modified Julian Date TELESCOP= 'het' / Telescope name to make it easy to plot a footprint in ds9, for example: RA = '13:01:14.11' / Right Ascension of IFU center DEC = '+53:22:11.1' / Declination of IFU center EQUINOX = 2000.00 / Equinox for IFU coordinates then either: CMDRA = '13:01:14.11' / Commanded Right Ascension for telescope CMDDEC = '+53:22:11.1' / Commanded Declination for telescope CMDEQNOX= 2000.00 / Equinox of commanded coordinates or: TELRA = '13:01:14.11' / Right Ascension from tracker TELDEC = '+53:22:11.1' / Declination from tracker TELEQNOX= 2000.00 / Equinox of tracker coordinates depending on whether we can read back encoder-based coordinates from the tracker, and then invert to get a position on the sky. These: HA = '+02:31:35.50' / Hour Angle ZD = 35.40 / Zenith Distance (deg) AIRMASS = 1.227 / Airmass AZIMUTH = 320.70 / Azimuth (deg) PARANGLE= 64.67 / Parallactic angle (deg) STRUCTAZ= 321.1000 / Azimuth of telescope structure (deg) X_STRT = -45.0139 / X pos of tracker at start of exposure (mm) Y_STRT = -97.9065 / Y pos of tracker at start of exposure (mm) Z_STRT = 0.4634 / Z pos of tracker at start of exposure (mm) RHO_STRT= -0.4478 / Rho pos of tracker at start of exposure (deg) THE_STRT= -0.2059 / Theta pos of tracker at start of exposure (deg) PHI_STRT= -0.6612 / Phi pos of tracker at start of exposure (deg) RHO_OFFS= 0.0000 / Rho offset (deg) are probably derived from the commanded coordinates and initial trajectory regardless. They are meant to correspond as accurately as possible to the start of the exposure. Note that if we can also query the structure subsystem for the telescope's elevation angle, we should include that in a keyword following STRUCTAZ: STRUCTEL= 55.0120 / Elevation of telescope structure (deg) Both STRUCTAZ and STRUCTEL are astronomical coordinates, corrected for any internal structure subsystem coordinate system. ------------------------------------------------------------------------------- Next we specify a WCS that maps rows to fiber number and columns to wavelength. Niv tells me that in CURE this transform is a 7th order polynomial with cross terms, but for the VDAS header 3rd order will probably be sufficient. This can be encoded using the Simple Imaging Polynomial (SIP) transform (http://fits.gsfc.nasa.gov/registry/sip.html). SIP for a "linear" transformation is supported in ds9 as of Version 7.0 Beta 17. (This form of SIP is probably *not* supported in wcstools, but *is* supported in the latest version of the AST library, on which ds9 is based.) For a wavelength/fiber number mapping, the "linear" keywords might look like: CTYPE1 = 'LINEAR---SIP' / linear map with distortion in pixel space CTYPE2 = 'LINEAR---SIP' / linear map with distortion in pixel space CRVAL1 = 3500. / [Angstroms] Wavelength at CRPIX1,CRPIX2 CRVAL2 = 1. / [] Fiber number at CRPIX1,CRPIX2 CRPIX1 = 6. / Reference pixel along axis 1 CRPIX2 = 1. / Reference pixel along axis 2 CD1_1 = 1.93986421 / Corrected CD matrix element CD1_2 = 0. / Corrected CD matrix element CD2_1 = 0. / Corrected CD matrix element CD2_2 = 0.21295855 / Corrected CD matrix element A_ORDER = 3 / polynomial order, axis 1, detector to sky A_0_2 = 2.9656E-06 / distortion coefficient A_0_3 = 3.7746E-09 / distortion coefficient A_1_1 = 2.1886E-05 / distortion coefficient A_1_2 = -1.6847E-07 / distortion coefficient A_2_0 = -2.3863E-05 / distortion coefficient A_2_1 = -8.561E-09 / distortion coefficient A_3_0 = -1.4172E-07 / distortion coefficient A_DMAX = 1.394 / [pixel] maximum correction B_ORDER = 3 / polynomial order, axis 2, detector to sky B_0_2 = 2.31E-05 / distortion coefficient B_0_3 = -1.6168E-07 / distortion coefficient B_1_1 = -2.4386E-05 / distortion coefficient B_1_2 = -5.7813E-09 / distortion coefficient B_2_0 = 2.1197E-06 / distortion coefficient B_2_1 = -1.6583E-07 / distortion coefficient B_3_0 = -2.0249E-08 / distortion coefficient B_DMAX = 1.501 / [pixel] maximum correction AP_ORDER= 3 / polynomial order, axis 1, sky to detector AP_0_1 = -6.4275E-07 / distortion coefficient AP_0_2 = -2.9425E-06 / distortion coefficient AP_0_3 = -3.582E-09 / distortion coefficient AP_1_0 = -1.4897E-05 / distortion coefficient AP_1_1 = -2.225E-05 / distortion coefficient AP_1_2 = 1.7195E-07 / distortion coefficient AP_2_0 = 2.4146E-05 / distortion coefficient AP_2_1 = 6.709E-09 / distortion coefficient AP_3_0 = 1.4492E-07 / distortion coefficient BP_ORDER= 3 / polynomial order, axis 2, sky to detector BP_0_1 = -1.6588E-05 / distortion coefficient BP_0_2 = -2.3424E-05 / distortion coefficient BP_0_3 = 1.651E-07 / distortion coefficient BP_1_0 = -2.6783E-06 / distortion coefficient BP_1_1 = 2.4753E-05 / distortion coefficient BP_1_2 = 3.8917E-09 / distortion coefficient BP_2_0 = -2.151E-06 / distortion coefficient BP_2_1 = 1.7E-07 / distortion coefficient BP_3_0 = 2.0482E-08 / distortion coefficient Note that the AP, BP keywords describe the reverse transformation (wavelength and fiber to pixel coordinates). 11/7/11: It is not clear that we will actually need those in our headers, but we agreed to include the possibility of including them. We may choose to leave them out of the configuration file, and hence they would not appear in the header. Niv points out (Wed Jan 25 16:02:56 2012) that SIP only permits regular polynomials while CURE uses Chebyshev polynomials for their stability at the edges of their validity and for their rapid convergence and ease of fitting due to their orthogonality. This means that we can't just copy CURE coefficients into the FITS header. Instead we'll need to write a small program that converts CURE distortion coefficients into SIP compatible ones and stores these in the headers (or vice versa). Note that eventually we will probably have a different transformation for each CCD. ------------------------------------------------------------------------------- Next we document the weather conditions: WEATDATE= '2012-06-04T05:36:47' / Date and time of last update (UTC) AMBTEMP = 7.50 / Ambient temperature (Celcius) HUMIDITY= 26.1 / Ambient relative humidity (percent) DEWPOINT= -9.54 / Dew point (Celcius) BAROMPRE= 784.1 / Barometric pressure (mbar) WINDDIR = 313.1 / Wind direction (deg) WINDSPD = 4.42 / Wind speed (mph) DUST1_0 = 10562 / Dust count 1.0 um (ppcf) DUST0_3 = 164237 / Dust count 0.3 um (ppcf) Q: Should we also include DIMM measurements? ------------------------------------------------------------------------------- Next we document anything in the light path: FILTEREN= 'Red' / Filter in wheel one (entrance window) FILTEREX= 'ADC' / Filter in wheel two (exit window) Q: Should we also document other potentially interfering mechanisms? e.g. cal system, acquisition camera, pupil viewer/CWFS. Should we at least document in/out for each of these? Now document the configuration of the Facility Calibration Unit (FCU) (see Niv's email Mon Dec 5 10:29:44 2011): HGLAMPID= 'xxxxxx' / He lamp ID CDLAMPID= 'xxxxxx' / Cd lamp ID NELAMPID= 'xxxxxx' / Ne lamp ID KRLAMPID= 'xxxxxx' / Kr lamp ID CTLAMPID= 'xxxxxx' / Continuuum lamp ID We would include keywords for any part of the calibration system with a limited lifetime and a signature in the data that vary from part to part. The above LAMPID keywords would have corresponding entries in the VDAS config file. That config file would be edited by the mountain staff whenever such a component was replaced. Q: These LAMPID keywords are only relevant when the frame is a line lamp, that is when IMAGETYP = 'comp'. Would it be best to only include the LAMPID keywords when IMAGETYP = 'comp'? Should we only include the particular keyword (HG, CD, NE, KR, etc.) that is relevant to the frame at hand? Or should we think about this as documenting the state of the FCU, and just include all of these keywords in all VIRUS frames? ------------------------------------------------------------------------------- Describe the hardware and software that created this header: HOSTCOMP= 'vdas' / Host computer name HOSTOPS = 'Red Hat Enterprise Linux Server release 5.5 (Tikanga)' / Host OS PROGRAM = 'vdas-1.01 2012-02-05T16:54:47Z' / Data acquisition program INSTRUME= 'virus' / Instrument name Now we document the instrumental setup, including version and serial number information stored in the serial ID chips that are scattered throughout the VIRUS CCD controllers. Two assumptions: 1) A given IFU fiber bundle can be plugged into one of several IFU slot positions on the focal surface, and might be moved around to different slots fairly easily, especially during commissioning. This means that there is no convenient serial ID chip in which to store this mapping of slot position vs. the IFU fiber bundle serial number. We therefore store the information as a simple lookup table in a VDAS configuration file. 2) Once a given IFU fiber bundle is installed on the telescope and the cables dressed, it can really only attach to whichever spectrograph is plugged into the rack a single location in the VIRUS enclosure. If that is the case, then we could program the IFU fiber bundle's serial number into the spectrograph slot address serial ID chip at that location. This makes sense only if we do not expect the bundle to ever be plugged into spectrographs in different locations in the stack. If that is possible, then we are better off keeping track of the IFU serial number mapping to spectrograph slot ID in another VDAS configuration file. IFUID = 'VIFU6-XXX-NNN' / IFU head ID IFUSLOT = 96 / IFU slot position Based on the comments above, the IFUID is stored in one of the user programmable fields in the spectrograph slot address serial ID chip (keep in mind that each field is 8 characters -- we'll either have to trim the string from 'VIFU6-XXX-NNN' or let it span two fields). IFUSLOT is populated by reading the VDAS configuration file that maps IFU slot position vs. the IFU head ID stored in IFUID. Each spectrograph will have a unique serial number. This serial number could be stored in the flex cable's serial ID chip, as long as a given cryostat (where the flex cable is located physically) is always attached to the same spectrograph. If not, then the spectrograph serial numbers could be stored in the spectrograph slot address serial ID chip (if we don't think spectrographs move). If we think spectrographs move around, then we could map spectrograph serial number to slot position in a VDAS configuration file. SPECID = 'sp001' / Spectrograph ID SPECSLOT= 42 / Spectrograph slot address I don't actually know what the spectrograph serial numbers look like, yet. The spectrograph slot address can be read from say the 5th field in the spectrograph slot address serial ID chip that this CCD controller can access. This serial ID chip is located physically in the VIRUS enclosure wiring harness. The addresses are programmed into the chips as they are installed in the VIRUS racks. See next paragraph for a discussion of the serial ID chips. Now we document which boards are in this particular CCD controller. See Bob Leach's email dated Sat Dec 31 16:40:12 2011 and his document '1-Wire.pdf'. We concatentate the board ID information provided by ARC in the first 4 to 6 8-byte fields in the non-volatile read/write memory in the serial ID chips on each board: CONTID = 'S/N 0xxx' / Controller ID TIMING = 'ARC1215 REV 2A DD/MM/YY S/N 0xxx U1R2A.0 U48R2A.0' / Timing board CD = 'ARC13 REV 1C DD/MM/YY S/N 0xxx U49R1C.0' / Clock driver board VIDEO = 'ARC14 REV 1V DD/MM/YY S/N 0xxx U9R1V.0' / Video processor PC = 'ARC17 REV 1V DD/MM/YY S/N 0xxx U1R1V.0' / Power controller board FLEX = 'ARCVFlex REV 3 DD/MM/YY S/N 0xxx' / Flex cable SSA = 'SSA REV 1 DD/MM/YY S/N 0xxx' / Spectrograph slot address Note that I insert a blank character between fields for readability. I trimmed the comments so that each card will fit into a single 80-character FITS record. Note that these keywords just store the board identification information read from the serial ID chips. There is additional data stored in fields 5-8 of the flex cable chip, say: field data 5 Ôo 7 'SN12347 ' 8 'LL/UR 2 ' I made up the values for now, but they are intended to contain 1) the CCD serial number, 2) information about the alternate jumpers for selecting the LL/LR/UR/UL readout amplifiers on each of the two CCDs attached to this flex cable, and 3) the selection of one readout instead of two for the device in the left and right positions respectively. The default is LL/UR and dual readout for both CCDs. The CCD serial number is encoded into the DETECTOR keyword (see below). The only way to tell which CCD you are reading (Left or Right) is from the order of the pixels in the data stream. Once you've worked that out, that information is stored in the CCDPOS keyword (see below). The amplifier ID for the lower and upper halves of each detector are written into the AMPLIFIE keyword (see below). The pixel order in the data stream tells you which half of the detector you are reading. The ARC13T temperature sensor on the clock driver board doesn't have an EEPROM, so it has no ID information written into it (see Bob's email Fri Feb 17 17:55:11 2012). I therefore leave it out of the keywords above. We will still read the sensor, however, to record the controller temperature in the header. See below. Note also that for the initial installation, the controller's serial number (which we store in CONTID) is defined to be the same as that of the ARC1215 timing/temperature controller board. If we ever swap the timing board out of a controller, we need to change the serial number written on the controller housing (or recognize that the controller ID's being written into the header are different from the ones written on the housing). Finally, note that CONTID above is the serial number of the controller, and *not* the CONTROLLER_ID address that the ARC software uses internally to talk to the controller. MICROCOD= 'tim.lod' / CCD controller microcode filename Hopefully the name of the tim file is more explicit than that, encoding a date or version number. We would append keywords after MICROCOD to describe and voltages or settings that were not standard, or different from those in that tim file. Q: Weren't we supposed to be able to read back a status word from the CCD controller with bits about health, voltages in range, etc.? When that exists, document it here with some keyword. It is specific to a given controller? Or detector? Now we describe the detector: DETECTOR= 'SN12407' / Detector ID DETSIZE = '[1:2064,1:2064]' / Detector size NCCDS = 1 / Number of CCDs in detector NAMPS = 2 / Number of amplifiers used I assume the detector ID is stored in and then read from the serial ID chip in the flex cable, and is entered when we first install the detectors. Now we describe the thermal setup of the detector: SETTEMP = -100.00 / Detector setpoint temperature (Celsius) DETTEMP = -100.00 / Detector temperature (Celsius) CRYOTEMP= -196.05 / Cold sink temperature (Celsius) CONTTEMP= 5.84 / Controller temperature (Celsius) INSTRTEM= 0.72 / Instrument temperature (Celsius) SERVOPWR= 0.79 / Servo heater power (watts) PRESSURE= 5.44E-08 / Cryostat vacuum pressure (mbar) SETTEMP is specified in a VDAS configuration file. It may be different for each CCD, or for each of several defined groups of CCDs. See the spec 'vdas-parameters', dated 11/16/11. DETTEMP and CRYOTEMP are read from two temperature sensors inside the cryostat, via the CCD controller. There is one sensor for each CCD (whose values go into their respective DETTEMP keywords), and a single shared sensor that measures the cold sink temperature in the cryostat. CONTTEMP is the temperature read from the ARC13T temperature sensor on the clock driver board in the CCD controller housing. (See Bob's email Fri Feb 17 17:55:11 2012.) INSTRTEM would be a temperature characteristic of the temperature inside the VIRUS cabinets, near where this spectrograph is installed. This temperature would have to be read from some VSS metrology system. SERVOPWR is read from the CCD controller. PRESSURE is read from some VSS metrology system, or perhaps from sensors more directly connected to the VDAS computer. These pressure sensors may or may not exist in the final plan. Next we have the keywords that describe where in the array the data come from. Note that when we deinterlace the CCD data stream and create the FITS files, by default we flip the data from the Left/Lower and Right/Upper amplifiers left and right so that bluer wavelengths are always on the left when the raw data are displayed in a simple way. We must also flip the data from the Left/Upper and Right/Upper amplifiers top and bottom so that fiber number always increases with row number. (The flips are documented in AMPSEC.) CCDPOS and CCDHALF come from the pixel order in the data stream. I assume the amplifier ID (AMPLIFIE) is stored in and then read from the serial ID chip in the flex cable, and is entered when we first install the detectors. Left CCD, Lower Amplifier: CCDPOS = 'L' / CCD position in cryostat CCDHALF = 'L' / Amplifier position AMPLIFIE= 'LR' / Amplifier(s) in use RDNOISE = 4.20 / Readout noise (electrons) GAIN = 1.0000 / Gain (electrons per ADU) CCDSIZE = '[1:2064,1:2064]' / CCD size CCDSUM = '2 1' / CCD on chip binning (col row) CCDSEC = '[1:2064,1:1032]' / Region of CCD read (unbinned CCD pixels) AMPSEC = '[2064:1,1:1032]' / Amplifier section (unbinned CCD pixels) DETSEC = '[1:2064,1:1032]' / Detector section (unbinned CCD pixels) DATASEC = '[33:1064,1:1032]' / Image region of data frame BIASSEC = '[1:32,1:1032]' / Overscan region of data frame TRIMSEC = '[33:1064,1:1032]' / Image region to be extracted Left CCD, Upper Amplifier: CCDPOS = 'L' / CCD position in cryostat CCDHALF = 'U' / Amplifier position AMPLIFIE= 'UL' / Amplifier(s) in use RDNOISE = 4.20 / Readout noise (electrons) GAIN = 1.0000 / Gain (electrons per ADU) CCDSIZE = '[1:2064,1:2064]' / CCD size CCDSUM = '2 1' / CCD on chip binning (col row) CCDSEC = '[1:2064,1033:2064]' / Region of CCD read (unbinned CCD pixels) AMPSEC = '[1:2064,1032:1]' / Amplifier section (unbinned CCD pixels) DETSEC = '[1:2064,1033:2064]' / Detector section (unbinned CCD pixels) DATASEC = '[1:1032,1:1032]' / Image region of data frame BIASSEC = '[1033:1064,1:1032]' / Overscan region of data frame TRIMSEC = '[1:1032,1:1032]' / Image region to be extracted Right CCD, Lower Amplifier: CCDPOS = 'R' / CCD position in cryostat CCDHALF = 'L' / Amplifier position AMPLIFIE= 'LR' / Amplifier(s) in use RDNOISE = 4.20 / Readout noise (electrons) GAIN = 1.0000 / Gain (electrons per ADU) CCDSIZE = '[1:2064,1:2064]' / CCD size CCDSUM = '2 1' / CCD on chip binning (col row) CCDSEC = '[1:2064,1:1032]' / Region of CCD read (unbinned CCD pixels) AMPSEC = '[1:2064,1:1032]' / Amplifier section (unbinned CCD pixels) DETSEC = '[1:2064,1:1032]' / Detector section (unbinned CCD pixels) DATASEC = '[1:1032,1:1032]' / Image region of data frame BIASSEC = '[1033:1064,1:1032]' / Overscan region of data frame TRIMSEC = '[1:1032,1:1032]' / Image region to be extracted Right CCD, Upper Amplifier: CCDPOS = 'R' / CCD position in cryostat CCDHALF = 'U' / Amplifier position AMPLIFIE= 'UL' / Amplifier(s) in use RDNOISE = 4.20 / Readout noise (electrons) GAIN = 1.0000 / Gain (electrons per ADU) CCDSIZE = '[1:2064,1:2064]' / CCD size CCDSUM = '2 1' / CCD on chip binning (col row) CCDSEC = '[1:2064,1033:2064]' / Region of CCD read (unbinned CCD pixels) AMPSEC = '[2064:1,1032:1]' / Amplifier section (unbinned CCD pixels) DETSEC = '[1:2064,1033:2064]' / Detector section (unbinned CCD pixels) DATASEC = '[33:1064,1:1032]' / Image region of data frame BIASSEC = '[1:32,1:1032]' / Overscan region of data frame TRIMSEC = '[33:1064,1:1032]' / Image region to be extracted Note that in the above image sections I have assumed that all rows and columns are good. Typically we would trim at least one column and row from each edge in BIASSEC and TRIMSEC. We'll have to revisit this when we get real data. In the discussion above, I assume that we read out all CCDs using the default pair of amplifiers. These are the lower left and upper right amplifiers as seen from the illuminated (back) side of the CCD. They are actually called LR and UL respectively, since the names are defined by the vendor as seen from the front side of the CCD. If we ever switch to the alternate pair of amplifiers to read out a given CCD, then the deinterlacing code will have to flip the data from the Left/Upper and Right/Lower amplifiers left and right instead, and the above keywords (AMPSEC, DATASEC, BIASSEC, TRIMSEC) will change. Summary of the flip logic to be implemented in VDAS: Amplifier Flips Left CCD UL* Flip Y UR Flip X, Flip Y LR* Flip X LL No flips Right CCD UL* Flip X, Flip Y UR Flip Y LR* No flips LL Flip X * default amplifier pair, used for majority (maybe all) CCDs. The amplifier pair will be documented (by us) in the serial ID chip on the flex cable when we install the CCDs. The flips that were applied by VDAS are also documented in the header as: FLIPX = T / Whether the pixel array was flipped in X FLIPY = T / Whether the pixel array was flipped in Y ------------------------------------------------------------------------------- It might be interesting to document which of the four power supplies this CCD controller was plugged into. We could determine that from a mapping from spectrograph slot address to physical location in the racks, and hence to a specific power supply. ------------------------------------------------------------------------------- END Q: Should we document the positions of the guide/WFS probes in the *science* data headers, to make it easy to tell later if an IFU is vignetted? e.g. PROBE1X, PROBE1Y, PROBE2X, PROBE2Y, PROBE3X, PROBE3Y, PROBE4X, PROBE4Y? (The "role", guide vs. WFS, is not relevant here.) [yes? If you had these coordinates it would be easy to generate a ds9 regions file that you could overlay showing the approximate vignetting by the probes. But wouldn't a list of the blocked IFUs be easier to use?] =============================================================================== guider: Here we assume that we store images as 4-byte unsigned integers, because we may be doing software binning. If we are only doing hardware binning, we can stick to 2-byte unsigned integers (see these keywords for the VIRUS CCDs). SIMPLE = T / file does conform to FITS standard BITPIX = 32 / number of bits per data pixel NAXIS = 2 / number of data axes NAXIS1 = 179 / length of data axis 1 NAXIS2 = 131 / length of data axis 2 EXTEND = T / FITS dataset may contain extensions COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy COMMENT and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H BZERO = 2147483648 / offset data range to that of unsigned long BSCALE = 1 / default scaling factor ------------------------------------------------------------------------------- We put the catalog name of the target in the OBJECT keyword. The comment depends on whether the object comes from SDSS: OBJECT = '1237661418744709237' / ObjID from SDSS or from USNO-B1.0: OBJECT = '1481.0261635' / USNO-B ID number (zone.record) We'll need catalog coordinates for the guide star: CATRA = '12:59:43.86' / Catalog Right Ascension for guide star CATDEC = '+58:06:37.5' / Catalog Declination for guide star CATEQNOX= 2000.00 / Equinox of guide star coordinates Then photometry information. Either: CALSYS = 'SDSS DR8' / Source of guide star data SDSSU = 19.745 / u-magnitude of guide star SDSSUERR= 0.037 / error in u-magnitude of guide star SDSSG = 19.685 / g-magnitude of guide star SDSSGERR= 0.014 / error in g-magnitude of guide star SDSSR = 19.611 / r-magnitude of guide star SDSSRERR= 0.017 / error in r-magnitude of guide star SDSSI = 19.446 / i-magnitude of guide star SDSSIERR= 0.020 / error in i-magnitude of guide star SDSSZ = 19.539 / z-magnitude of guide star SDSSZERR= 0.071 / error in z-magnitude of guide star STARGAL = 6 / star-galaxy classification (3=galaxy, 6=star) for SDSS, or CALSYS = 'USNO-B1.0' / Source of guide star data USBOB1 = 19.72 / Magnitude from first blue survey USNOR1 = 19.70 / Magnitude from first red survey USNOB2 = 20.13 / Magnitude from second blue survey USNOR2 = 19.41 / Magnitude from second red survey USNON = 99.99 / Magnitude from near-IR survey STARGAL = 6 / similarity to stellar PSF (0-3=nonstellar, 8-11=stellar) for USNO-B1.0. ------------------------------------------------------------------------------- EXPTIME = 1.00 / Actual integration time (sec) IMAGETYP= 'object' / object, zero, dark, flat, comp, etc. DATE-OBS= '2012-06-04' / Date (yyyy-mm-dd) of observation UT = '05:37:13.30' / Universal time ST = '15:33:25.69' / Local mean sidereal time MJD = 56082.2341817 / Modified Julian Date TELESCOP= 'het' / Telescope name RA = '13:01:14.11' / Right Ascension of guide probe center DEC = '+53:22:11.1' / Declination of guide probe center EQUINOX = 2000.00 / Equinox for guide probe coordinates then either: CMDRA = '13:01:14.11' / Commanded Right Ascension for telescope CMDDEC = '+53:22:11.1' / Commanded Declination for telescope CMDEQNOX= 2000.00 / Equinox of commanded coordinates or: TELRA = '13:01:14.11' / Right Ascension from tracker TELDEC = '+53:22:11.1' / Declination from tracker TELEQNOX= 2000.00 / Equinox of tracker coordinates depending on whether we can read back real coordinates from the tracker, and then invert to get a position on the sky. ------------------------------------------------------------------------------- Next we specify a WCS to map pixel position to RA, Dec. The map written into the FITS header only has to be accurate over the small size of the detector. (It does not have to apply over the entire focal surface, for instance. A separate transformation will handle that.) A simple tangent plane projection would look like this, from astrometry.net: CTYPE1 = 'RA---TAN' / TAN (gnomic) projection CTYPE2 = 'DEC--TAN' / TAN (gnomic) projection WCSAXES = 2 / no comment LONPOLE = 180.0 / no comment LATPOLE = 0.0 / no comment CRVAL1 = 188.258151983 / RA of reference point CRVAL2 = 10.7693414897 / DEC of reference point CRPIX1 = 704.268802652 / X reference pixel CRPIX2 = 484.386157987 / Y reference pixel CUNIT1 = 'deg ' / X pixel scale units CUNIT2 = 'deg ' / Y pixel scale units CD1_1 = -0.00037647481938 / Transformation matrix CD1_2 = 1.15984092959E-06 / no comment CD2_1 = 1.15984092959E-06 / no comment CD2_2 = 0.00037647481938 / no comment A more sophisticated map would be a tangent plane projection, with a distortion map superimposed. This can be encoded using the Simple Imaging Polynomial (SIP) transform (http://fits.gsfc.nasa.gov/registry/sip.html). SIP is supported in wcstools and ds9 (for RA/Dec). For a 3rd order RA/Dec mapping, the keywords look like: CTYPE1 = 'RA---TAN-SIP' / RA---TAN with distortion in pixel space CTYPE2 = 'DEC--TAN-SIP' / DEC--TAN with distortion in pixel space CRVAL1 = 202.482322805429 / [deg] RA at CRPIX1,CRPIX2 CRVAL2 = 47.1751189300101 / [deg] DEC at CRPIX1,CRPIX2 CRPIX1 = 128. / Reference pixel along axis 1 CRPIX2 = 128. / Reference pixel along axis 2 CD1_1 = 0.000249756880272355 / Corrected CD matrix element CD1_2 = 0.000230177809743655 / Corrected CD matrix element CD2_1 = 0.000230428519265417 / Corrected CD matrix element CD2_2 = -0.000249965770576587 / Corrected CD matrix element A_ORDER = 3 / polynomial order, axis 1, detector to sky A_0_2 = 2.9656E-06 / distortion coefficient A_0_3 = 3.7746E-09 / distortion coefficient A_1_1 = 2.1886E-05 / distortion coefficient A_1_2 = -1.6847E-07 / distortion coefficient A_2_0 = -2.3863E-05 / distortion coefficient A_2_1 = -8.561E-09 / distortion coefficient A_3_0 = -1.4172E-07 / distortion coefficient A_DMAX = 1.394 / [pixel] maximum correction B_ORDER = 3 / polynomial order, axis 2, detector to sky B_0_2 = 2.31E-05 / distortion coefficient B_0_3 = -1.6168E-07 / distortion coefficient B_1_1 = -2.4386E-05 / distortion coefficient B_1_2 = -5.7813E-09 / distortion coefficient B_2_0 = 2.1197E-06 / distortion coefficient B_2_1 = -1.6583E-07 / distortion coefficient B_3_0 = -2.0249E-08 / distortion coefficient B_DMAX = 1.501 / [pixel] maximum correction AP_ORDER= 3 / polynomial order, axis 1, sky to detector AP_0_1 = -6.4275E-07 / distortion coefficient AP_0_2 = -2.9425E-06 / distortion coefficient AP_0_3 = -3.582E-09 / distortion coefficient AP_1_0 = -1.4897E-05 / distortion coefficient AP_1_1 = -2.225E-05 / distortion coefficient AP_1_2 = 1.7195E-07 / distortion coefficient AP_2_0 = 2.4146E-05 / distortion coefficient AP_2_1 = 6.709E-09 / distortion coefficient AP_3_0 = 1.4492E-07 / distortion coefficient BP_ORDER= 3 / polynomial order, axis 2, sky to detector BP_0_1 = -1.6588E-05 / distortion coefficient BP_0_2 = -2.3424E-05 / distortion coefficient BP_0_3 = 1.651E-07 / distortion coefficient BP_1_0 = -2.6783E-06 / distortion coefficient BP_1_1 = 2.4753E-05 / distortion coefficient BP_1_2 = 3.8917E-09 / distortion coefficient BP_2_0 = -2.151E-06 / distortion coefficient BP_2_1 = 1.7E-07 / distortion coefficient BP_3_0 = 2.0482E-08 / distortion coefficient Note that the AP, BP keywords describe the reverse transformation (RA/Dec to pixel coordinates). 11/7/11: It is not clear that we will actually need those in our headers, but we agreed to include the possibility of including them. We may choose to leave them out of the configuration file, and hence they would not appear in the header. ------------------------------------------------------------------------------- Now document the telescope's position: HA = '+02:31:35.50' / Hour Angle ZD = 35.40 / Zenith Distance (deg) AIRMASS = 1.227 / Airmass AZIMUTH = 320.70 / Azimuth (deg) PARANGLE= 64.67 / Parallactic angle (deg) STRUCTAZ= 321.1000 / Azimuth of telescope structure (deg) X_STRT = -45.0139 / X pos of tracker at start of exposure (mm) Y_STRT = -97.9065 / Y pos of tracker at start of exposure (mm) Z_STRT = 0.4634 / Z pos of tracker at start of exposure (mm) RHO_STRT= -0.4478 / Rho pos of tracker at start of exposure (deg) THE_STRT= -0.2059 / Theta pos of tracker at start of exposure (deg) PHI_STRT= -0.6612 / Phi pos of tracker at start of exposure (deg) RHO_OFFS= 0.0000 / Rho offset (deg) ------------------------------------------------------------------------------- Now document the light path: FILTER = 'g' / Filter in guider filter wheel FILTEREN= 'Red' / Filter in wheel one (entrance window) FILTEREX= 'ADC' / Filter in wheel two (exit window) ------------------------------------------------------------------------------- Now document the guide probe's position to 0.01 arcsec, in each of the relevant coordinate systems. See Walter's spreadsheet 'focal.xls', dated Wed Jan 25 14:35:05 2012. (That will need updating with an optical scale factor from Hanshin.) PROBEX = 9.07947 / X pos of guide probe (arcmin) PROBEY = 4.20854 / Y pos of guide probe (arcmin) PROBER = 10.00000 / R coord of guide probe (arcmin) PROBEANG= 25.000000 / Pos angle of guide probe (deg) PROBETHE= 25.000000 / Theta coord of guide probe (deg) PROBEPHI= 76.236991 / Phi coord of guide probe (deg) Note that PROBEX, PROBEY, and PROBEY are expresed in terms of field angle in arcminutes, measured from the center of the focal surface. ------------------------------------------------------------------------------- Now document the weather conditions: WEATDATE= '2012-06-04T05:36:47' / Date and time of last update (UTC) AMBTEMP = 7.50 / Ambient temperature (Celcius) HUMIDITY= 26.1 / Ambient relative humidity (percent) DEWPOINT= -9.54 / Dew point (Celcius) BAROMPRE= 784.1 / Barometric pressure (mbar) WINDDIR = 313.1 / Wind direction (deg) WINDSPD = 4.42 / Wind speed (mph) DUST1_0 = 10562 / Dust count 1.0 um (ppcf) DUST0_3 = 164237 / Dust count 0.3 um (ppcf) ------------------------------------------------------------------------------- Now document the measurements derived from this frame: For a circularly symmetric Moffat (1969, AA 3, 455) profile, I(r) = I0 * (1 + (r/alpha)**2)**(-beta) where r = SQRT((x-x0)**2 + (y-y0)**2) and so we might document the fitted parameters as: FWHM = 1.532 / Full width half maximum (arcsec) SKY = 102.334 / Sky background (ADU) SKYERR = 2.125 / Error in sky background (ADU) CENTX = 101.22 / X centroid (pixels) CENTY = 98.79 / Y centroid (pixels) CENTHRSH= 6.375 / Threshold for centroid (ADU) FIDUCX = 100.66 / X fiducial (pixels) FIDUCY = 99.12 / Y fiducial (pixels) INSTMAG = 17.854 / Instrumental magnitude (mag) GMAG = 16.773 / g-band magnitude (mag) TRANSPAR= 75.43 / Transparency (percent) FITX = 100.33 / X center from fit (pixels) FITY = 99.32 / Y center from fit (pixels) FITAMP = 223.456 / Fit amplitude (ADU) FITALPHA= 52.930 / Fit scale factor (pixels) FITBETA = 2.235 / Fit exponent (ADU) Then: FWHM is the full 1-D width (converted to arcsec) of the stellar profile at half of the peak intensity (after subtracting the background). It would be helpful to derive this value directly from the stellar profile non-parametrically, rather than from a model fit. An alternative is to calculate it from the fit parameters (see below). SKY and SKYERR come from say a 1-D gaussian fit to the histogram of pixel values in the image (or perhaps directly from the stellar profile fit). CENTX and CENTY are the 1-D marginal centroids of the image, calculated including only pixels above the threshold CENTHRSH. These are used for guiding and have the advantage of being model independent. (See the modified moment algorithm in Stone 1989, AJ 97, 1227. I think Hanshin's WFS centroiding code uses this algorithm as well.) We specify the threshold CENTHRSH in two ways. For dark time, a threshold of 3 sigma (3 * SKYERR) above the background level (SKY) often works well. For bright time, a threshold above sky level of some fraction of the peak pixel value (after subtracting the sky level) works well, say 50%. FIDUCX and FIDUCY are the coordinates of the reference position for guiding. We do a non-linear least squares fit to the 2-D stellar profile to obtain: FWHM = 2 * alpha * SQRT(2**(1/beta)-1)) FITX = x0 FITY = y0 FITAMP = I0 FITALPHA = alpha FITBETA = beta In the presence of guide errors, it would be better not to assume circular symmetry. Instead we'll fit an elliptical Moffat profile: I(x,y) = I0 * (1 + axx*(x-x0)**2 + axy*(x-x0)*(y-y0) + ayy*(y-y0)**2)**(-beta) and then document axx, axy, ayy, plus a major axis FWHM (FITFWHMA), a minor axis FWHM (FITFWHMB), (or ellipticity) and a position angle (FITPHI), instead of the FWHM and FITALPHA parameters above. (See the appendix in http://www.ast.cam.ac.uk/ioa/research/vdfs/docs/reports/psf.) INSTMAG is calculated from the (possibly analytic and possibly numeric) integral of the model. INSTMAG = -2.5 * log(total counts above sky) + 25, where the zeropoint of 25 is arbitrary, and the specific value of 25 is adopted for convenience. Q: Presumably INSTMAG = -2.5 * log(counts) + const, and then GMAG is an observed magnitude formed by transforming INSTMAG to "g". The log is base 10. e.g. GMAG = INSTMAG + ZPTG + CG*(SDSSU-SDSSG) + KG*X, where ZPTG is the zeropoint of the photometric transformation in g CG is the color term of the photometric transformation for u-g KG is the airmass term of the photometric transformation in g X is the airmass (AIRMASS keyword) In what bandpass(es) should we report the observed magnitudes? Presumably these differ from the catalog magnitudes only by the transparency: TRANSPAR = 10**(-0.4*(INSTMAG-GMAG)) as a fraction. Multiply by 100 for a percentage. Does only one bandpass makes sense: whatever transforms best for the filter used for this frame? Do we want to calculate GMAG in terms of the u-g color? Is that the best choice for the optical system, with its limited u-band transmission? Q: Should we include the parameters we assumed for the photometric transformation? e.g. the airmass and color terms, and the zeropoint (ZPTG, CG, and KG)? (Note that I assume the transformation will be a function of the catalog colors.) Probably, so we add to the header: ZPTG = 25.234 / g-band photometric zeropoint (mag) CG = 2.123 / g-band color term in u-g KG = 1.123 / g-band extinction coefficient These will be defined in a configuration file. Note again that the most interesting guide camera files will be the accumulated images, formed by summing the guide images over a science exposure. These should have the same parameters computed and documented as above. There would be an accumulated image for each filter, so a typical science exposure might have say four associated accumulated images: the "guide" image, and then one each in say the g, r, and i filters. Since each accumulated image has a different filter, the keyword names that apply to a specific filter (e.g. GMAG, ZPTG, ZG, and KG above) would change, depending on the filter in use. Finally, all of the keyword values in this section with native units of ADU (i.e pixel values) should be scaled to a one-second exposure using EXPTIME. All of the keyword values in this section with native units of "pixels" should be scaled to 1x1 binning. [TBR]. ------------------------------------------------------------------------------- Now document how the data were taken: HOSTCOMP= 'pas' / Host computer name HOSTOPS = 'Red Hat Enterprise Linux Server release 5.5 (Tikanga)' / Host computer operating system PROGRAM = 'cameraclient1 Thu Sep 9 12:04:39 CDT 2010' / Data acquisition program APISWV = 'FLI Software Development Library for Linux 1.71' / API version WDGTHWV = 'TS-7800' / Widget model number WDGTMAC = '00:25:00:a5:1c:c4' / Widget MAC address WDGTOPS = 'Linux 2.6.24' / Widget operating system WDGTSWV = '1.02' / Widget firmware version DETHWV = 'MicroLine MLx285' / Camera model number DETECTOR= 'ML0110210' / Camera serial number DETMODE = '6 MHz' / Camera readout speed PIXSIZE1= 6.45 / Unbinned pixel size (microns) PIXSIZE2= 6.45 / Unbinned pixel size (microns) CONTTEMP= 32.06 / Heatsink temperature (Celsius) SETTEMP = -35.00 / Cooler setpoint temperature (Celsius) DETTEMP = -35.15 / Detector temperature (Celsius) SERVOPWR= 10.79 / Servo heater power (percent) BACKFLSH= T / Whether background flushing is on NFLUSH = 0 / Number of CCD flushes before exposure start See my old spec 'metrology-system-header-requirements', dated 9/24/10, for a discussion of the calls to FLI's API necessary to populate these keywords. ------------------------------------------------------------------------------- Now provide information for data analysis: RDNOISE = 4.3 / Readout noise (electrons) GAIN = 0.320 / Gain (electrons per ADU) CCDSIZE = '[1:1434,1:1050]' / CCD size (unbinned pixels) HWSUM = '2 2' / CCD on-chip binning (col row) SWSUM = '4 4' / CCD software binning (col row) CCDSUM = '8 8' / CCD total binning (col row) HWSEC = '[1:1434,1:1050]' / Region of CCD read (unbinned pixels) CCDSEC = '[1:1434,1:1050]' / Region of CCD output (unbinned pixels) DATASEC = '[1:179,1:131]' / Image region of data frame (binned pixels) BIASSEC = '[178:179,2:131]' / Bias region of data frame (binned pixels) TRIMSEC = '[4:176,2:131]' / Image region to be extracted (binned pixels) END The Sony ICX285AL interline CCD used in the guide cameras has tiny (6.45 micron) pixels and will require considerable binning to obtain a reasonable pixel scale on the sky. Typical binning with the guide cameras will be 8x8, with 16x16 possible in bad seeing. Normally we would do the binning on-chip to reduce read noise. However, there are two problems with that approach: 1) the summing wells are small and high binning will lose dynamic range, and 2) the detector suffers from considerable amplifier glow that gets increasingly worse with more binning. As a compromise, we have decided to bin 2x2 on-chip, and the rest in software. [N.B. 3/2/12: Hardware modifications to the guide cameras may have fixed the amplifier glow, and so we may revisit the need for software binning.] The combintion of on-chip and software binning complicates the FITS header a bit, as we must document the initial subimage read out from the detector, the on-chip binning used to do that readout, then how much additional binning is done in software, and how much of the binned array is finally returned to the user. There are three possible sections of the detector. The full extent of the CCD is documented in unbinned pixels in the standard keyword CCDSIZE. The subimage of the CCD that was actually read out by the hardware is documented in a new keyword we invent, HWSEC. These pixel coordinates are also given in *unbinned* pixels, and refer to a subset of the entire pixel array. The subimage that we read out has been binned on-chip by the amount documented in our invented HWSUM keyword. A possibly smaller subset of this subimage is then binned more in software, but another factor documented in the invented keyword SWSUM. The relationship of the final output hardware and software binned subarray to the original array of CCD pixels is documented in the standard keyword CCDSEC, again in *unbinned* pixels. It is crucial to express these pixel coordinates in terms of the original pixel array, so that standard software can calibrate any subimages from calibration frames taken with no subimaging. 1050 +-----------------------------------------------+ | full CCD: CCDSIZE | | | | +-----------------------------------+ | | | HW bin: HWSEC | | | | | | | | +-------------------+ | | | | | SW bin: CCDSEC | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +-------------------+ | | | | | | | +-----------------------------------+ | | | 1 +-----------------------------------------------+ 1 1434 In practice, our 1.5x re-imaged fiber bundle takes up most of the vertical extent of the CCD (6 mm / 6.45 microns = 931 pixels), and reading an FLI subimage only saves time if you can significantly reduce the number of rows read out. That means that reading just the subimage we need does not save much time over reading the full CCD. (We might also like a few rows that are not illuminated by the fiber bundle, in case they are useful for determining the bias level.) We therefore probably won't read just a subimage from the CCD, and HWSEC will probably be the same as CCDSIZE. We may also decide to just bin that whole array in software, in which case CCDSEC is the same as HWSEC. We could, however, save some calculation time and decide to bin just the upper right corner illuminated by the image bundle, in which case CCDSEC might be more like [484:1414,120:1050]. In terms of our existing software, HWSEC is just the argument we give to Trey's cameraclient software, specifying the subimage to read from the CCD. We need a new parameter to specify the portion of that subimage that we bin in software and pass to the user. For the simplest case, CCDSIZE = '[1:1434,1:1050]' / CCD size (unbinned pixels) HWSUM = '2 2' / CCD on-chip binning (col row) SWSUM = '4 4' / CCD software binning (col row) CCDSUM = '8 8' / CCD total binning (col row) HWSEC = '[1:1434,1:1050]' / Region of CCD read (unbinned pixels) CCDSEC = '[1:1434,1:1050]' / Region of CCD output (unbinned pixels) DATASEC = '[1:179,1:131]' / Image region of data frame (binned pixels) Here the CCD is 1434x1050. We read the entire CCD, so HWSEC is the same as CCDSIZE. We bin on-chip 2x2, so the array we read from the CCD is 717x525. We bin that whole 717x525 array 4x4, ending up with an array that is 179x131. See DATASEC, which is always described in binned pixels. Note that since there are no formal prescan pixels on the detector, DATASEC starts at pixel (1,1). A slightly more complicated case: CCDSIZE = '[1:1434,1:1050]' / CCD size (unbinned pixels) HWSUM = '2 2' / CCD on-chip binning (col row) SWSUM = '4 4' / CCD software binning (col row) CCDSUM = '8 8' / CCD total binning (col row) HWSEC = '[1:1434,1:1050]' / Region of CCD read (unbinned pixels) CCDSEC = '[499:1434,115:1050]' / Region of CCD output (unbinned pixels) DATASEC = '[1:117,1:117]' / Image region of data frame (binned pixels) The CCD is again 1434x1050. We read the entire CCD, so HWSEC is again the same as CCDSIZE. We bin on-chip 2x2 (HWSUM), so the array we read from the CCD has 717x525 elements. We want to software bin only the upper right corner of that array. We want a subimage that is about 6 mm / 6.45 microns = 930.2 unbinned pixels in size, to cover the whole imaging bundle. Call it 936 pixels, so it is evenly divisible by 8. That will result in 117 binned pixels in the end. 117 pixels when binning by 8 corresponds to 468 pixels when binning by 2, as in the hardware subimage. So we want to software bin the upper right 468x468 portion of the 717x525 hardware subimage. We skip 717-468=249 pixels in x and 525-468=57 pixels in y and begin software binning by a factor of 4 (SWSUM). The resulting array is 117x117 pixels (see DATASEC). Its relation to the original CCD pixel array is given in CCDSEC as [249*2+1:249*2+8*117,57*2+1:57*2+8*117], or [499:1434,115:1050]. Note the 249 and 57 come from the pixels we skipped in the software binning step. A more realistic case: CCDSIZE = '[1:1434,1:1050]' / CCD size (unbinned pixels) HWSUM = '2 2' / CCD on-chip binning (col row) SWSUM = '4 4' / CCD software binning (col row) CCDSUM = '8 8' / CCD total binning (col row) HWSEC = '[1:1434,1:1050]' / Region of CCD read (unbinned pixels) CCDSEC = '[479:1414,115:1050]' / Region of CCD output (unbinned pixels) DATASEC = '[1:117,1:117]' / Image region of data frame (binned pixels) The CCD is again 1434x1050. We read the entire CCD, so HWSEC is again the same as CCDSIZE. We bin on-chip 2x2 (HWSUM), so the array we read from the CCD has 717x525 elements. We again want to software bin a subimage that is 936 unbinned pixels in size, to cover the whole imaging bundle. This time we want place the imaging bundle on the detector so we avoid the non-active pixels on the right hand side. The active region of the CCD is [23:1434-20,12:1050] or [23:1414,12:1050]. So we want CCDSEC to end up [1414-936+1:1414,1050-936+1:1050] or [479:1414,115:1050]. So we skip the first (479-1)/2 = 239 pixels in x and (115-1)/2 = 57 pixels in y of the hardware subimage, and begin software binning by a factor of 4 (SWSUM). The resulting array is 117x117 pixels (see DATASEC). Same region with 4x4 total binning: CCDSIZE = '[1:1434,1:1050]' / CCD size (unbinned pixels) HWSUM = '2 2' / CCD on-chip binning (col row) SWSUM = '2 2' / CCD software binning (col row) CCDSUM = '4 4' / CCD total binning (col row) HWSEC = '[1:1434,1:1050]' / Region of CCD read (unbinned pixels) CCDSEC = '[479:1414,115:1050]' / Region of CCD output (unbinned pixels) DATASEC = '[1:234,1:234]' / Image region of data frame (binned pixels) Same region with 16x16 total binning: CCDSIZE = '[1:1434,1:1050]' / CCD size (unbinned pixels) HWSUM = '2 2' / CCD on-chip binning (col row) SWSUM = '8 8' / CCD software binning (col row) CCDSUM = '16 16' / CCD total binning (col row) HWSEC = '[1:1434,1:1050]' / Region of CCD read (unbinned pixels) CCDSEC = '[479:1406,115:1042]' / Region of CCD output (unbinned pixels) DATASEC = '[1:58,1:58]' / Image region of data frame (binned pixels) Note that here CCDSEC is not quite the same as in the previous cases, because our 936 pixel subimage is not evenly divisible by 16. We could either read a slightly bigger subimage that is evenly divisible by 16, or we can truncate. We assume that the physical location of the fiber bundle is fixed and optimized for 8x8 binning, so reading a bigger subimage won't help. If we truncate, we end up with a subimage that is only 16*INT(936/16) = 928 pixels across. Therefore CCDSEC is [479:479-1+928,115:115-1+928] = [479:1406,115:1042]. I'm sure one could derive more general cordinate transformations by studying http://iraf.noao.edu/projects/ccdmosaic/imagedef/imagedef.html, but I think this can just be handled by a lookup table of a few common setups (e.g. 4x4, 8x8, and 16x16 binning) and the keywords that go with them as above. =============================================================================== acquisition camera: Same header requirements as for the guide/WFS cameras. Some keyword values are of course different: DETHWV = 'MicroLine ML09000' / Camera model number DETECTOR= 'ML0662510' / Camera serial number DETMODE = '1 MHz' / Camera readout speed PIXSIZE1= 12.0 / Unbinned pixel size (microns) PIXSIZE2= 12.0 / Unbinned pixel size (microns) CCDSIZE = '[1:3103,1:3086]' / CCD size (unbinned pixels) The acquisition camera is not generally used for guiding, so some guide-specific keywords (e.g. FIDUCX, FIDUCY) would not appear.