1. Unpack the file DarkSettle1.3.tgz somewhere in your IDL path to run the standard version or in the directory of your choice if you wish to use the VM version:

   unix% tar -xvzf DarkSettle1.3.tgz -C [directory]

2. If you wish to use the standard version, your directory should be invoked in the IDL_PATH with a plus sign, e.g.

   "+/home/mydir/idl" 

Running DARKSETTLE

1. Gather *bcd.fits files for a single AOR and IRS module (LH is the only module for which the program has been tested). Download from the archive on the Level 2 (PBCD) tab.
   
2. Gather appropriate calibration files (flatfield.fits, flatfield_cmask.fits, and pmask.fits) in a parallel ../cal directory to the directory where the bcd.fits data reside. This is automatically done for you when you download "calibration files" from the archive. If calibration files are not found in this default location or other expected locations, the program will query you for the appropriate directory. This location can also be set using the "CAL_DIR" keyword (see below). If you are using pre-flatfielded data (eg., rsc.fits), you should set the keyword /RSC.
   
3. Run dark_settle on the files, producing *_dks_bcd.fits files.
   
4. [Optional] Perform background subtraction on *_dks_bcd.fits files.
   
5. [Optional] Clean rogue pixels in the dark-settled, background-subtracted data using IRSCLEAN.
   
6. Extract using SPICE. Dark-settled, bg-subtracted, cleaned BCDs can be used with cleaned bmask and uncertainty files.

The sofware has one optional input (a list of data files), as well as several optional keywords to choose from. The IDL calling sequence is:

 IDL> dark_settle [,dataFiles] [,DIRECTORY=Directory] [,FILTER=filter] [,/NOCORRECT] [,/NOSUGGEST] [,SPLIT=split] $

[,OUTPUT_DIR=output_dir] [,CAL_DIR=cal_dir] [,PMASK=pmask] [,FLATFIELD=flatfield] [,/RSC ] [,/CUBE ][,/HELP]

Each of the optional inputs and keywords in the above calling sequence is described in Optional Inputs to dark_settle.

Each file will have each row corrected so that its median equals that of the "target column". The file names will have the string "dks" (dark-settle) appended to the front of the file type. If the file is a *_bcd.fits file, the corrected version will be *_dks_bcd.fits.

When the program exits, the equivalent command line input that you could have typed (incorporating any file dialogs) will be printed to the screen.

1. SIMPLE MODE: program will query for any needed inputs.

IDL> dark_settle

NOTE: Under the IDL Virtual Machine (VM), this is the only mode that operates. It is invoked from the Unix command line by typing:

unix% idl -vm=[path to dark_settle]/dark_settle.sav

This mode is useful for embedding dark_settle in a program and/or re-running on newly processed BCDs. The following example uses the sample data that comes with the dark_settle distribution:

IDL> cd,'[path to DarkSettle]'

IDL> dark_settle,'sampledata/r12076032/ch3/bcd/*[!dks]_bcd.fits'

The input file list can include wild cards accepted by IDL's FILE_SEARCH procedure, as well as names of text files. See the Optional Inputs to dark_settle documentation for more details.

NOTE: This mode is not available under the IDL Virtual Machine.

This routine changes the dark current in IRS BCDs.

SPLIT=0 is the same as SPLIT=1 (don't split the array, or "split" into a single "subarray"), but /SPLIT is the same as SPLIT=2 (default split into two subarrays).

As of version 0.4, this program requires that the data files be flatfield-corrected IRS data. This will be checked by examining the fits header for reference to FLATAP.

This program also requires access to the flatfield and pmask calibration data that were used on the BCDs. The flatfield will be "taken out" before the correction and then restored after correction.

LH is the only IRS module for which this program has been tested. Other modules will "work" when run, but we can't yet guarantee the quality of results.

dataFiles

List of files to be processed (string array). This list can include any of the following:

1. Fits file names, including wildcard expressions (see documentation on IDL FILE_SEARCH for supported wildcards and expansions).
   
2. Text file names (*.txt). Text files list (one per line) fits files, wildcard expressions, as well as other .txt files! Comments in list files are denoted by # as the first character in the line.

Null string input () will produce a file picker dialog. Default is .

Files are assumed to be in the current working directory, unless either a path is given or DIRECTORY= is set.

An example input is:

['SPITZER_S3_12076032_0012_0000_6_bcd.fits','/home/data/*_bcd.fits','filestosettle.txt']

Directory to get dataFiles from, or directory to start file search from. Default is the current working directory. File dialogs start from this location.

Directory(ies) to save corrected data files in. Default is directory where each input data file resides. Scalar (all corrected files go to same output directory) or vector (one per input file).

Filter for file dialog. Default is *.fits (can be edited in the dialog).

Set this keyword to not save the corrected data to fits files.

Set this keyword to avoid printing a command line hint.

Integer >=0 specifying how many (approximately) equally-spaced vertical subdivisions to split the array into. Each subdivision will be used to separately compute the row-dependent dark current and correct that portion of the array. The separately-corrected pieces will be patched together to form the corrected whole array. Default is 1 (whole array). Keyword SPLIT cuts the array in vertical strips, as equally sized as possible, with the constraint that the strip boundaries do not cross an order.

Directory path(s) to calibration .fits file(s) that were applied to the observations. This is either a scalar specifying a single directory that contains the calibration files for all input files, or a vector with the same number of elements as the input file list. If this keyword is not present, module and time-appropriate calibration files will be sought in the following places:

1. a parallel directory "../cal" wrt the data directory - this is the default when data were downloaded from the archive;
2. the directory where the data reside.
3. If the appropriate calibration file set is not found in either of these locations, then the program will query the user for a calibration file directory corresponding to each input file.

This specifies the full path of the pmask file(s) applied to your data files. If scalar (one element), the same pmask file applies to all input data files. If a vector, there should be one element per input data file. A scalar entry with wildcards will expand to a vector (assuming the wildcard string expresses correctly). This keyword overrides the CAL_DIR keyword when locating the pmask.

This specifies the full path of the flatfield file(s) applied to your data files. If scalar (one element), the same flatfield file applies to all input data files. If a vector, there should be one element per input data file. A scalar entry with wildcards will expand to a vector (assuming the wildcard string expresses correctly). This keyword overrides the CAL_DIR keyword when locating the flatfield. An appropriate flatfield_cmask file will be sought to match the input filename(s).

Print documentation header.

The following two keywords are for expert users. This program allows you to work on non-flatfielded pipeline data, of both the 2D (/RSC) and 3D (/CUBE) variety. A flatfield will not be needed.

Set this keyword if the input data files are not flatfielded (i.e., you are using the *rsc.fits or other pre-flatfield files from the pipeline such as *droop.fits). Dark_Settle will set the flatfield image equal to unity and the flatfield cmask equal to zero. As usual, results will be in [...]_dks_[type].fits files, where [type] is the file type (eg, rsc).

Set this keyword to process data cubes from the IRS pipeline (usually cubesub.fits). Each frame of data will be operated on separately.