Synthetic Spectrum Package for IDL Design, supervision, contact: Dr. Joseph Harrington 326 Space Sciences Building Cornell University Ithaca, NY 14853-6801 jh@oobleck.astro.cornell.edu Programmers: John Dermody (Cornell) Version 0.10 03 Jul 03 OVERVIEW: This set of functions will create a synthetic spectrum and corresponding synthetic sky frame for your use testing spectrum extraction programs. It has many available options for you to modify, so you can test different aspects of your program. Its modules simulate sky lines, spatial resolution, spectral resolution, optical distortions, cosmic rays, read noise, photon noise, and bad pixels to an object spectrum created from a black body curve and random emission and absorption lines. The default values simulate moderate levels of all effects. INSTALLATION: To install, copy the synthspec directory into your idl function directory, where it can been seen by the IDL program. To test if your installation is correct, change to a directory where you can write files, and run testsynthspec. If the following six lines appear on your screen, things are working normally: Creating simple test files Creating default test files PASS - Simple Object Frame PASS - Simple Sky Frame PASS - Default Object Frame PASS - Default Sky Frame BASIC USE: IDL> objframe = synthspec() Synthspec returns a 2D data array containing a computed spectrum that has been processed to simulate a number of sky and instrumental effects. The object spectrum is the Planck function with random emission and absorption line superposed. Sky lines from an OH database appear on a flat background. Spectral and spatial spreading are simulated through convolution with a Gaussian function. Imperfect object trace and bent sky lines are simulated with sine functions. These data are slightly rotated to simulate imperfect chip alignment, and random cosmic rays, bad pixels, Poisson signal noise, and read noise are added. Each of these steps is a module that can be controlled or turned off by keywords to synthspec, as described below. In addition, the user can specifiy certain inputs (levels, spectrum, bad pixels, etc.) and has access to several internal variables of the package. SKY FRAME AND HEADERS: If the package is being used for infrared astronomy, the first argument of synthspec will contain a corresponding sky frame: IDL> objframe = synthspec(skyframe) This 2D array is the same size as objframe, and contains the same simulations as objframe. It does not contain the object spectrum, and its random cosmic rays and noise values are generated seperatly. Information from the creation of the array is saved in the FITS header info for the sky frame and the object frame. To access the header, set a variable to SKYHEADER or OBJHEADER. IDL> objframe = synthspec(skyframe, skyheader=skyheader) IDL> print, skyheader SIZE: NX and NY control the size of the resulting array. NX defaults to 512 and NY defaults to whatever NX is. For example, to make a rectangular array of size 256x512 type, IDL> objframe = synthspec(skyframe, nx = 256, ny = 512) LEVELS: The intensity of every element can be modified in the synthspec package. To change the background level, IDL> objframe = synthspec(skyframe, bklevel = 400) Background, object spectrum, maximum values for bad pixels, rays, and spectral lines are all measure in ADUs. The only commands measured in electrons are the gain (e-/ADU) and readnoise (e-). The following is a brief summary of the most used level commands. Each is discussed in more depth later. BKLEVEL: The sky background level SPECLEVEL: The object's spectrum level SKYLVLV: The maximum intensity of the sky lines EMILVLV: The maximum intensity of the object emission lines EPADU: The gain of the chip. It impacts signal noise RDNOISE: The readnoise of the chip. MAXBADVAL: The maximum bad pixel intensity. MAXRAYVAL: The maximum cosmic ray intensity. MODULE OVERVIEW: Sky Lines: Sky lines can be from the OH Database or randomly generated. Set RANDSKYL to randomly generate, or NOSKYL to turn off sky lines. Object Spectrum: A blackbody curve is used as the base of the object spectrum. Set NOBBCURVE to use a single value instead. Object spectrum lines are always randomly generated; set NOSPECL to not add lines to the object spectrum. Distort: Frames can be distorted by bending the spatial and spectral directions and rotating the frame. Setting the keywords NOSMILE, NOTRACE, and NOTILT will turn off each effect respectively. Bad Pixels: The same set of bad pixels are in the sky frame and object frame. Setting NOBAD will give a frame free of bad pixels. Cosmic rays are generated for each frame, and NORAYS turns off this module. Noise: Signal noise and read noise are added to both frames. To turn off all noise, set NONOISE. For example, to produce a frame with no bad pixels and no noise: IDL> objframe = synthspec(skyframe, /nonoise, /nobad, /norays) INPUT: Four keywords are available for user input. If a spectrum is set to INOBJSPEC, it will be used instead of randomly creating the spectrum. However, by default a blackbody curve will be used for the base of the object's spectrum unless otherwise noted. Similarly, INSKYSPEC will take a 1D array of the sky spectrum, and will add the bklevel to the input spectrum. For instance, to make a sine function be the only source for the object's spectrum: IDL> ny = 512 IDL> inspec = sin(findgen(ny)/ny * !pi*20) ^ 2 IDL> objframe = synthspec(ny = ny, inobjspec = inspec, $ /nobad, /norays) IDL> tvscl, objframe To simulate an real CCD array, FLATFRAME and BIASFRAME accept 2D arrays of size nx by ny. At the last step, the frame being processed is multiplied by flat frame and added to the bias frame. OUTPUT: To assist with debugging, 2 masks, 7 frames, the object's spectrum can be outputted from synthspec. The object's spectrum (before any loss of data from rotation, curvature, noise, or bad values) is saved in the SPECTRUM keyword. To use, IDL> objframe = synthspec(spectrum = spec) Perhaps most useful, a bad pixel mask for each frame is derived by setting bad pixels and cosmic rays to 0, and all other values to 1. The masks can be found in OBJCRMASK and SKYCRMASK. For instance, you may want to see the object frame without any light from bad values. IDL> objframe = synthspec(objcrmask = objcrmask) IDL> tvscl, (objframe*objcrmask) If you wish to test your extraction's package background interpolation routine, get the original background from BGFRAME. The object's profile on the CDD array is saved in PROFRAME. If you need to see the object spectrum alone on a frame, use the SPECFRAME keyword. It contains the object frame before sky, noise, and bad pixels were added, but after distortions. SKY LINES: Sky lines can be derived in three ways. Either the user inputs the sky lines through INSKYSPEC, tells the function to look up sky lines in the OH database, or randomly generates them. The OH database contains information for sky lines from 10103 to 20063 Angstroms. The ohlines function uses the SWAVEL and EWAVEL keywords to set the starting and ending wavelength of the CCD chip. The units of both keywords are meters, and they default to [1.5e-6, 1.6e-6] If the RANDSKYL keyword is set, sky lines are derived randomly. The number of large sky lines is set by the NUMSKYL keyword. In all cases, the resulting spectrum is scaled up to SKYLLVL and added to BKLEVEL. The OHLOC keyword controls the location on the oh lines database. To use a different database than the one located at ohsky/database.txt set the OHLOC keyword to the full path of the new database. OBJECT SPECTRUM: Unless the NOBBCURVE keyword is set, the base of the object spectrum is a Planck function of temperature TEMP, and wavelengths SWAVEL through EWAVEL. The result is then scaled up to SPECLEVEL. The object's spectrum lines are either user defined in INOBJSPEC, or randomly ggenerated. The synthspec package can generate emission and absorption lines. The number of lines is set by the NUMEMIL and NUMABSL keywords respectfully. The emission line level can also be manually set using the EMILLVL keyword. The randlines function actually generates 100 times the number of lines set, but uses an inverted distribution so that only 1% of the lines generated are above .1, and 10% are above .01, with the ceiling set at 1. Whether by user input or randomly the spectrum is scaled so that its max value is EMILLVL. If the spectrum was randomly generated, absorption lines can be added. DISTORTIONS: To simulate imperfections in the geometries, curvature and tilt can be introduced into the frames. The SMILE keyword controls the amplitude of the curve in the spacial dimension. The TRACEAMP and TRACEOSC keywords control the amplitude and oscillations of the curve in spectral dimension. TRACEOSC gives the number of full sine oscillations of the trace. TRACEAMP and SMILE are both measured in pixels and give the amplitude of the sine function. Tilting the array can be used to simulate inconsistencies between the chip dimensions and actual spacial and spectral dimensions. TILT is the angle of this rotation, and it is measured in degrees. TILT can also be used to swap the spacial and spectral dimensions, or invert the maximum wavelength side and minimum wavelength side of chip. To do this, simply add 90, 180, or 270 to the tilt angle. IDL> objframe = synthspec(tilt = 95) IDL> tvscl, synthspec NX and NY still refer to the vertical and horizontal directions in the output. All output frames and masks are also rotated, so they are correct with the output. The package also tries to adjust the outputted spectrum to the tilt. It is able to tell the difference between spectrum running vertical and those running horizontal, but if the frame is largely skewed, what is possible to get and what SPECTRUM shows may not be the same thing. In these cases the SPECFRAME keyword might give you a more useful frame. NOISE AND BAD VALES: Bad pixels are set to be pixels with the same intensity (before noise) in both frames. 20% of bad pixels are set to 0 before readnoise, and the other 80% are uniformly distributed with a max set by MAXBADVAL. Cosmic rays are events unique to one frame. All cosmic rays are additive, with a uniform distribution less than MAXRAYVAL. The number of cosmic ray and bad pixel events are set by NUMRAYS and NUMBAD respectfully. Each event may impact up to 4 pixels, in one of 16 different shapes. The mask is first derived, then bad values calculated. The bad pixels and cosmic rays are added after distortions and before noise. By default, signal noise and readnoise are added to the object and sky frames. Signal noise is simulated to be Gaussian, with a variance set to pixel intensity. Readnoise is calculated as a Gaussian with mean 0 and standard deviation of the keyword RDNOISE. RDNOISE defaults to 10. Signal noise is best controlled by the EPADU keyword. To double the signal noise, quadruple the gain. THE 'FAKE' PIXELS To make sure this synthetic data is not confused with real data, the words'FAKE' are added to both the sky frame and object frame at the end of the program. IDL FUNCTIONS: synthspec.pro - driver routine for package speclines.pro - returns a base and spectrum lines distort.pro - spreads, rotates, and bends the array adderrors.pro - returns a frame of bad pixels and noise badpixloc.pro - returns a mask with bad pixel locations badpixval.pro - returns a frame with bad pixel values at locations cnvlgauss.pro - convols the input with a Gaussian cosrays.pro - returns a frame with cosmic ray values at locations curveframe.pro - curves the frame initheader.pro - initializes a string array for header information ohlines.pro - returns a 1D array with OH sky lines planckfunc.pro - calculates the planck function for given temp and wavl randlines.pro - returns a 1D array with random spectrum lines EXAMPLE/TEST DATA: In the synthspec directory there are four example.fits files. These files provide respresentatives of the following four example runs. 1) Default run: IDL> objframe = synthspec(skyframe, objheader=objheader, $ skyheader=skyheader) 2) No noise or bad pixels or distortions: IDL> objframe = synthspec(objheader=objheader, /nonoise, /nobad, $ /norays, /notilt, /nosmile, /notrace) 3) Swap the spectral and spacial dimensions, make the chip read from 1200 to 1250 nanometers, and set the object temperature to 3000K: IDL> objframe = synthspec(objheader=objheader, tiltangle=90, $ swavel=1.2e-6, ewavel=1.25e-6, temp=3000) 4) Add 500 bad pixels and 400 cosmic rays to a frame with 20 e- readnoise, background level at 400 ADUs, and object spectrum level at 4000 ADUs IDL> objframe = synthspec(objheader=objheader, numbad=500, $ numrays=400, rdnoise=20, bklevel=400, $ speclevel=4000) OH DATABASE: Compiled by Kim Ennico at kennico@ast.cam.ac.uk. Last modified: 4 December 1997. Further information can be found at ohsky/database.txt inside synthspec directory