Copyright © 2004,2005 California Institute of Technology
| Revision History | ||
|---|---|---|
| Revision 1.2.1 | 9 June 2005 | tdh |
| Updated for new functionality of SPICE Version 1.2. | ||
| Revision 1.1.2 | 19 April 2005 | tdh |
| Added instructions for Client and Server functions of SPICE Version 1.1. | ||
| Revision 1.1.1 | 18 April 2005 | tdh |
| Updates for Version 1.1 release of SPICE. | ||
| Revision 1.2 | 1 September 2004 | tdh |
| Updates for Version 1.0-beta1 release of SPICE. | ||
| Revision 1.1 | 28 April 2004 | tdh |
| Updates for added functionality in SPICE GUI. | ||
| Revision 1.0 | 1 Mar 2004 | tdh |
| Update to version supporting external configuration. Rename to CAPRI. | ||
| Revision 1.0 | 4 Dec 2002 | tdh |
| First Version. | ||
Table of Contents
These help files will allow you to use CAPRI to reprocess Spitzer Space Telescope science data.
This program allows the user to interactively reprocess Spitzer science data.
This software consists of two components, the CAPRI java engine for implementing the user interface, and the SPICE reprocessing kit, which defines the interface and provides binaries which do the actual data reduction.
CAPRI is an acronym for Configurable Application for Pipeline Reprocessing Interfaces.
CAPRI provides a java engine for invoking the user interface for Spitzer data reduction pipelines. One such example of a user interface is the SPICE kit, which allows a user to run IRS modules from the BQD pipeline in order to extract spectra.
CAPRI contains a built-in FITS viewer, which is useful for many pipelines.
SPICE is an acronym for Spitzer IRS Custom Extractor.
SPICE is a tool for running Spitzer IRS data reduction modules. The main purpose of SPICE is to provide a user interface to downlink software which is normally invoked by the automated processing system. With SPICE, a user can select the data to be processed, specify processing parameters, and invoke the pipelines.
The main design criterion for SPICE has been to make it easier to run pipelines offline. For this reason, the major controls for setting up pipelines have been included. While providing a convenient interface for running pipelines, SPICE does not automate the process of setting them up. Therefore a good knowledge of how pipelines work is a prerequisite for using SPICE.
Table of Contents
The java application CAPRI shows tabs that contain components of the user interface. The SPICE tab contains the components for the custom spectral extraction interface. The following sections explain the use of each tab.
Drag and Drop is the primary method of selecting files. For example, to enter a file name into a text field, drag the file's name from the filesystem view into the text area. Dragging the name of an image into the FITS display pane causes the image to be displayed. File names can also be entered into text fields by typing or by pressing the button to the right of the text field, which starts a file chooser dialog.
Settings can be loaded or saved using the main menu's File/Open Settings and File/Save Settings selections. Font size and font bold/plain selection can be made from the main menu's Options/Font choices, and from context menus in file system and text views. This help file can be displayed upon selecting the main menu's Help/User Interface item.
The two panels can be resized relative to each other by grabbing the borders between them with the mouse and dragging. The whole application can be resized either horizontally or vertically by grabbing a border or corner with the mouse and dragging.
The various functions of the package are accessed by clicking on the corresponding tab at the lower left of the application. The Image and View tabs allow further control of image and overlay displays. For mulitplane images, the FITS panel includes a control which allow scrolling through the planes.
Usage of each tab's functions is described in the following.
In this tab one chooses the input files from which a spectrum is to be extracted.
For extraction from a single BCD product, the "Input Image" should be supplied with the name of the BCD dispersed image, which has an archive name of the form SIRTF_S1_1234567890_1234_1234_01_bcd.fits. The name for the corresponding "Image Unc" is SIRTF_S1_1234567890_1234_1234_01_func.fits. The "Mask" file is named SIRTF_S1_1234567890_1234_1234_01_bmask.fits.
The Input Directory field will contain the directory of the latest file specified in the Input tab using the drag and drop method. The locations of files entered in the other fields are assumed to be relative to that directory. This feature can be overridden for a file by entering its full path for its name, which can be done by typing or by clicking on the file chooser button to the right of each input text field.
An "Up" button is provided which allows changing the root of the tree view to a higher directory. To see the next highest level of the filesystem, press the "Up" button. This will reset the tree view root to one directory above the current root directory. To set the root of the filesystem to a lower directory, select the directory with the mouse and press the right mouse button. A menu appears. Select the "Set as Root" item and the selected directory will become the top level of the filesystem view. Should the directory contents change by an external program, SPICE may not show an updated directory listing. The directory listing may be updated by right-clicking in the filesystem view and selecting the "Refresh" item.
The "Filter" button and text field can be used to reduce the size of the directory listing when there are many files at one level. The pattern which should be matched is entered into the text field. A file name from the filesystem view may be dragged into the text field to provide an entry which can then be modified to form a pattern. Unix-type wildcard patterns using "*" and regular expressions which do not use reserved characters are supported.
The "Channel" dropdown menu indicates the channel of the data to be processed. The channel is automatically selected when the Input Image is specified if the image header contains a CHNLNUM value. The channel can be manually selected by using the mouse on the dropdown menu. Default calibration and control data file names are set whenever the channel number or calibration version changes. See the Calibration section for details on automatic cal file selection.
To set the inputs for this tab, supply file names to text fields "Input Image", "Input Unc" (optional), and "Mask File" at the top of the tab. If any of these names are not full paths in the filesystem, the names are prepended with whatever appears in the field "Input Directory" before use. There are three methods for supplying the file names to the fields.
Here are the steps involved in using File System view to select input files:
Browse through the tree view of the file system until the desired file is visible.
Drag the file name into the appropriate text field by holding the left mouse button down when the cursor is over the file name, moving the cursor to a position over the text field, and releasing the mouse button. The file name (not including its path) will appear in the text field. The path will appear in the "Input Directory" text field.
Any "Input" file will be looked for under the "Input Directory", except if it is specified by a full path in its text field. Therefore, if an input file is not in the "Input Directory", use one of the alternative entry methods described below to enter the full path of the file in the text field.
The "Input Directory" text field can be modified without changing any file names by dragging a directory name from the filesystem view into the "Input Directory" text field.
When "Input Image" is specified, two additional things happen: 1) the image is displayed in the "FITS" tab and 2) the image header is read, and if the channel can be determined, the "Channel" dropdown menu is automatically set. If the channel number cannot be obtained from the header, the channel is set according to the first field (using any punctuation as separators) in the input image name of the form "Sn" or "n", where n is a single digit. If no channel can be determined the setting is unaltered. The channel number can also be set manually from the "Channel" dropdown menu.
Within the program, file names from text fields will be prepended with the specified "Input Directory" path, unless the file name is in the form of a full path. There are two ways to enter a file name as a full path. One is by using the File Chooser Dialog. To use the File Chooser:
Press the button labeled with an ellipses symbol at the right end of the text field for the file to be specified.
This File Chooser Dialog appears.
Browse the file system by clicking on directory icons or the "Up" icon until the name of the desired file is seen.
Click on the file name and then click on the "Open" button.
This File Chooser Dialog closes and the full path name of the selected file is placed in the text field.
The text fields may be filled in or edited by typing, including the use of Cut-and-Paste. To create or modify an entry:
Place the cursor over the point in the text at which editing is to occur.
Press the left mouse button.
The editing cursor will appear.
Use the "Paste" key combination, backspace, or other keyboard input to modify the text.
When the name of a FITS file is dragged into the "Input Image" text field, the image is displayed in the Image tab under the FITS tab in the right-hand pane of the application. To show more details in the image, the stretch minimum and maximum values are by default set to exclude the highest one percent and lowest one percent of the image pixels, displaying them with value maximum or minimum brightness, respectively. See the View section for information on controlling the stretch. Missing values (NaNs) in the input image are displayed with minimum brightness.
An image can also be displayed by dragging it's name directly into the image viewing area. The two panes of the application can be resized relative to one another by clicking the mouse on the center divider and dragging it horizontally.
Selection by Drag and Drop
Browse through the tree view of the file system until the desired file is visible.
Drag the file name over the image or blank space in the FITS panel.
The image will be displayed. The display can be controlled by settings in the "View" tab. See the View section for a description of the controls.
The header is displayed in the Header tab. The header text can be filtered by entering a wild-card string, such as *CHN*, in the text field and pressing the Filter button.
If the input image has more than one plane, the controls of the Multi-Plane tab will be active. The displayed plane can be changed by dragging the slider control or pressing the arrow buttons at the ends of the slider.
By default, this tab is hidden and calibration files are set automatically according to channel number and calibration version. The automatic selection of cal files is governed by the channel number, which is taken from the "CHANNEL" keyword of the header of the Input Image file, and by the calibration version, which is taken from the "CREATOR" keyword. The calibration version refers the configuration of the online pipeline which produces the input bcd image, uncertainty, and mask. The cal and cdf files used in SPICE must be prepared based the specific calibration version of the input data. SPICE comes bundled with several sets of cal and cdf files.
The default operation of SPICE is to read the CHANNEL and CREATOR keywords from the Input Image file and set the values in the Cal and CDF tabs to the correct files. To change or override the default behavior, it is first necesary to show the Cal tab,
In the main menu, choose "View".
Under "View", move the cursor over "SPICE".
Under "SPICE", move the cursor over "Cal".
A "Show" checkbox becomes visible.
Click on the "Show" checkbox so that a check mark appears.
Hiding of tabs is done via these menu items also.
When setting calibration files manually, the same input methods as for specifying input image files can be used. See the section Input for details.
Unchecking the box "Auto-Select Version" will prevent the values in the textfields of the Cal and CDF tabs from being automatically changed when a new Input Image is selected. The values can be modified manually as described above, or by selecting the calibration version from the "Cal Version" dropdown menu. To do the latter,
Uncheck the "Auto-Select Version" box.
Click on the "Cal Version" menu.
A list of available calibration version file sets is shown.
Click on the radio button next to the correct calibration version for your data.
The textfields of the Cal tab are changed to those of the chosen calibration version.
The calibration versions listed in the men correspond to the names of the directories in the irs/cal directory of the spice installation. The directory name must match exactly the CREATOR value. The "Cal Directory" text field shows the full path of the one chosen. The names of the calibration files are by default taken from the file irs/cal/calfiles_channel_X.xml, where "X" is the channel number. If the subdirectory of irs/cal for a specific calibration version contains the calfiles_channel_X.xml file, it is read instead. Therefore the calibration filenames for a specific calibration version can be changed by placing modified versions of the calfiles_channel_X.xml files into the subdirectory.
Another customization is supported for automatic calfile selection in which a subdirectory of irs/cal is automatically selected which does not match the CREATOR keyword. With this option, one can cause a specified calibration version to be used whenever the CREATOR keyword takes on a certain value. To define this mapping,
Check the "Use Version Mapping" box.
The Cal Version Mapping dialog appears.
Enter the expected CREATOR value of your data into a textbox.
From the "Cal Version" dropdown menu, select the cal version to be used for this CREATOR value.
Press the "OK" button of the dialog.
New cal file sets can be installed into SPICE from the SSC website using the Update tab. See section Update.
You can also install your own sets of calibration files. Simply create a subdirectory containing the cal files under irs/cal with the directory name exactly matching the CREATOR value. SPICE must be restarted for this to take effect.
This tab is normally hidden; files are set automatically according to channel number and calibration version. To make the tab visible, in the main menu check the box for View/Spice/CDF/Show. All defaults input methods are exactly analogous as for specifying calibration files. See the section CDF for details.
Output file names are automatically entered when the Input Image field of the Input tab is altered. This feature can be turned off by unchecking the Auto-Select control in the Ouput tab. File names are chosen based on the input file name, after truncation of "bcd.fits" (or ".fits" if the input file does not end with "bcd.fits").
The input methods are the same here as for specifying input image files. If the files do not exist at time of specfication, the desired names may be entered by typing the the text boxes. See the section Input for details.
When a file name is entered in an Output text field and the file exists, the data in it will be displayed in the appropriate tab or overlaid on the image. The display will be updated when the module is run which produces a new version of the output file. To remove the display of output data from a plot or image, right-click in the plot or image and select the "Clear" item.
This tab provides the interface for running both the Profile and Ridge modules. It contains
Profile Tab Components
A Plot Panel
Plots the profile after the Profile module is run.
The "Profile" Button
Invokes the Profile module, which runs as a system call from the CAPRI java application.
The "Orders" Menu
Allows the selection of which orders the Profile module shall use.
The "Ridge" Button
Invokes the Ridge module, which runs as a system call from the CAPRI java application.
The "Center" Radio Buttons and Text Box
Allows the optional use of a manual setting for the center of the profile to be input to the ridge module.
The selection of this component defaults to Auto.
The operation of module also depends on settings in the Input and Output tabs. See sections Input and Output for details.
The orders which the Profile module is to use may be selected from the Orders menu. For low resolution modes, the selecting a combination of orders in the Profile tab causes the order selection in the Extract to be automatically updated. Select orders in Profile by the following steps:
Selecting the Orders
Click on the Orders menu.
Submenus "Low Res" and "High Res" appear. Click on the enabled submenu.
Menu items for selection of orders appear.
For low resolution modes, click on one of the combinations of orders presented.
The Orders menu in the Extract tab is automatically updated with the order selection. See Extract.
For high resolution modes, if changing from some orders to all orders, click on the "All" checkbox.
If changing from all orders to some orders, or changing the selection of orders, with the "All" checkbox unselected, select the "Choose" menu item and click on the order or orders to be used by the Profile module.
To run the Profile module:
Running the Profile Module
Click on the "Profile" button.
The module will be invoked as a system call by the CAPRI application using the settings specified in the SPICE user interface.
The profile table specified by the "Profile" text box of the "Output" tab will be produced by the module.
CAPRI will read the profile table and plot it in the Plot panel of the "Profile" tab.
During the running and plotting of the module, an icon will appear in the "Profile" button and remain until processing is finished.
To kill a running module, select the "Kill Jobs" item under "Process" in the main menu.
If not all required settings have been made, or if a needed file does not exist, a red error message box will appear listing what was not found. If the module runs but an output file has the same time stamp as before the run, the module may not have run correctly, so an orange warning message box is displayed with the names of these output files.
The profile center to be used by the Ridge module may be specified as follows:
Selecting the Ridge Center
Click on the "Ridge Center" Auto or Manual radio button.
If Auto is selected, the Ridge module will use the center computed by the Profile module.
If Manual is selected, the center as a percentage of the profile width may be entered in the text box.
Alternatively, the center may be chosen by clicking on the plotted profile line.
A green marker will appear on the plot and the center value will be placed in the text box.
The ridge width is an input to the Extract module and does not affect the running of the Ridge module.
Selecting the Ridge Width
See the Extract section for information on adjustment of the ridge width.
To run the Ridge module, first make the required selections in the Input and Output tabs. Then,
Running the Ridge Module
Click on the "Ridge" button.
The module will be invoked as a system call by the CAPRI application using the settings specified in the SPICE user interface.
The ridge table specified by the "Ridge" text box of the "Output" tab will be produced by the module.
CAPRI will read the ridge table and overlay the ridge center and width boundaries in the image display of the "FITS" tab. See the Input section for instructions on displaying an image.
During the running and plotting of the module, an icon will appear in the "Ridge" button and remain until processing is finished.
To kill a running module, select the "Kill Jobs" item under "Process" in the main menu.
This tab provides the interface for running the Extract module. It contains
Extract Tab Components
A Plot Panel
Plots the spectrum after the Extract module is run.
The "Extract" Button
Invokes the Extract module, which runs as a system call from the CAPRI java application.
The Width Menu
Menu which selects whether the ridge width used by the Extract module shall be automatic (that calculated by the Ridge module), one input by the user, or the full width.
The selection of this component defaults to automatic.
Width text boxes.
For entry of width and corresponding wavelength.
The "Mask" Menu
Menu for selection of bits which shall be considered fatal for a pixel if set in mask file.
The "Orders" Checkbox
Allows the selection of the orders to be included in the spectrum.
Allows the selection of whether the Extract module shall use the orders indicated by the FOV (default), all orders, order 1, or orders 2 and 3.
This component is enabled for "Low Res" channels only.
It is automatically updated when low resolution orders are chosen from the Orders menu in the Profile tab.
Orders in the Profile tab are not automatically updated when orders are selected in the Extract tab.
The operation of module also depends on settings in the Input and Output tabs. See sections Input and Output for details.
In computing the spectrum, the Extract module computes the ridge width based on a given width for a specific wavelength (the relation of width to wavelength is linear). The width calculation algorithms from the Extract module have been coded into SPICE, allowing the width to be previewed before running Extract. To adjust the ridge width,
Selecting the Ridge Width
Select one of "Auto", "Manual", or "Full" from the "Width" menu.
If Auto is selected, the width and wavelength parameters are the FOV calibration file are filled into the two text boxes and the corresponding width is displayed on the image.
Exceptions are Channel 1 (Long-Lo) and the "Center" apertures of channels 0 and 2, which by default use the full width:
To correspond to the operation of the automated pipelines, for Channel 1, if Auto is selected, the width is displayed from the boundaries of the full dispersion and the center is not displayed (since it is not used in the extraction). This also occurrs for the "Center" apertures of the low resolution channels (0 and 2).
If Manual is selected, in the two text boxes enter the width as a percentage of the profile width and the corresponding wavelength for that width. The new width is displayed on the image. To do a constant-width extraction, enter a width and delete any characters that are in the wavelength text box.
If Full is selected, the width is displayed from the boundaries of the full dispersion and the center is not displayed
The ridge display with is updated whenever the ridge or width changes which is
A new ridge table is specified.
A new ridge table is created by running the Ridge module.
A new FOV table is specified.
A new width or wavelength parameter is entered.
The selection of Auto, Manual, or Full is made.
When the "Extract" button is pressed, the appropriate parameters for the width, based on the above selections, are passed to extract module.
The bits which, if set for a pixel, are to be considered fatal by the Extract module, are set by the Bit Mask menu:
Setting Fatal Bit Mask Bits
Click on the Bit Mask menu.
Click on the bit or bits which shall define fatal conditions for a pixel.
The default for this menu is for bits 12, 13, and 14 to be set as fatal.
The orders which the Extract module is to use may be selected as follows:
Selecting the Orders
If the menu is not enabled, the setting does apply to the channel being processed.
If the menu is enabled and Default is selected, the Extract module will do extraction based on the FOV value.
If the Extract module is to use all orders, click on the "All" menu item.
To use order 1 only, click on the menu item labeled "1".
To use orders 2 and 3 only, click on the menu item labeled "2 and 3".
To run the Extract module, first make the required selections in the Input and Output tabs. Then,
Running the Extract Module
Click on the "Extract" button.
The module will be invoked as a system call by the CAPRI application using the settings specified in the SPICE user interface.
The extract table specified by the "Extract" text box of the "Output" tab will be produced by the module.
CAPRI will read the extract table and plot it in the Plot panel of the "Extract" tab.
During the running and plotting of the module, an icon will appear in the "Extract" button and remain until processing is finished.
To kill a running module, select the "Kill Jobs" item under "Process" in the main menu.
This tab provides the interface for running the Tune module. It contains
Tune Tab Components
A Plot Panel
Plots the spectrum after the Tune module is run.
The "Tune" Button
Invokes the Tune module, which runs as a system call from the CAPRI java application.
The operation of module also depends on settings in the Input and Output tabs. See sections Input and Output for details.
To run the Tune module, first make the required selections in the Input and Output tabs. Then,
Running the Tune Module
Click on the "Tune" button.
The module will be invoked as a system call by the CAPRI application using the settings specified in the SPICE user interface.
The extract table specified by the "Tune" text box of the "Output" tab will be produced by the module.
CAPRI will read the tune table and plot it in the Plot panel of the "Tune" tab.
During the running and plotting of the module, an icon will appear in the "Tune" button and remain until processing is finished.
To kill a running module, select the "Kill Jobs" item under "Process" in the main menu.
This tab provides controls for the display of the input image and overlays. It contains four subtabs.
The Display Tab
Input Image
Refers to the image selected for Input Image (see Input), or to an image displayed by dragging a file name from the filesystem view into the FITS display, whichever is most recent. The name of the image currently being displayed is shown in the Image text field of the FITS tab.
The Input Image row, and every other row controlling a displayed item, contains the following controls
Color dropdown menu
Allows selection of the color mapping of the image or overlay.
Show checkbox
Toggles whether the image or overlay is displayed.
Transparency slider
Controls the brightness of the image or overlay with respect to other displayed items.
Ridge Overlay
Refers to the ridge center in the table selected for Ridge in the Output tab.
Width Overlay
Refers to the left and right boundaries of the extraction area.
Alternate Image
Refers to the image selected for Alternate Image in the Alternates tab.
Alternate Ridge
Refers to the ridge center in the table selected for Alternate Ridge in the Alternates tab.
Alternate Width
Refers to the left and right boundaries of an extraction area based on the table selected for Alternate Ridge, computed with the width parameters set for Ridge Width.
Image Zoom
Scales the images and overlays by a factor.
Fractional scaling may be specified by typing in the text field.
The Stretch Tab
Histogram Display
Shows a histogram of the current image plane.
Stretch Min Slider
Sets the minimum pixel value for the display. Values less than or equal to this are displayed as zero.
The setting is always relative to the histogram bins and the position of the slider corresponds to the histogram bin of the value.
Stretch Max Slider
Sets the maximum pixel value for the display. Values greater than or equal to this are displayed as zero.
The setting is always relative to the histogram bins and the position of the slider corresponds to the histogram bin of the value.
Stretch Min Textbox
Shows the value from Stretch Min slider.
The Stretch Minimum setting can be altered by typing in this text box.
Stretch Max Textbox
Shows the value from Stretch Max slider.
The Stretch Maximum setting can be altered by typing in this text box.
Function
The function used in the stretching of the display values.
Linear: All values scale equally.
LogE: Logarithm base e is applied.
Histogram Eq: Histogram equalization is applied.
SquareRoot: Square root of the values is applied.
The default stretch function is Linear.
Histogram Min Textbox
Shows the value used as the minimum for the histogram.
Out-of-range low-valued counts are plotted in the left-most bar of the histogram.
When a new image or plane is displayed, the value is set so that one percent of the pixels lie at or below it.
The Stretch Min slider is then ignored until it is moved.
The value can only be altered by typing in this text box.
Histogram Max Textbox
Shows the value used as the maximum for the histogram.
Out-of-range high-valued counts are plotted in the right-most bar of the histogram.
When a new image or plane is displayed, the value is set so that one percent of the pixels lie at or above it.
The Stretch Max slider is then ignored until it is moved.
The value can only be altered by typing in this text box.
Bar Spacing
The histogram fills the Histogram panel, therefore the number of bins depends on the size of the panel. When the panel is resized, the histogram is recalculated with a changed number of bins. The number of bins also depends on the bin spacing, which is in pixels. Setting the bin spacing to a low value results in more bins and lower counts per bin, and vice versa.
The Cuts Tab
XY Cuts
By default the cuts are continuously updated in the plot panels as the mouse moves over the image.
Clicking on the image with the left mouse button stops the continuous updating.
Checking the "Continuous Update" checkbox or clicking on the image again restores continuous updating.
Z Cut
If the image is multi-plane, a cut through the planes is shown according to mouse position.
Continuous updating is controlled as with XY Cuts.
The Alternates Tab
To provide for comparison of images or ridges, one additional image and one additional ridge may be specified. To assist the comparison, any displayed item may be toggled on and off using its "Show" checkbox in the Display tab. The brightness of the item may also be smoothly varied with respect to the other items by adjusting its slider in the Display tab. Finally, various color choices are allowed to help distinguish the items.
Tip: one way to do a complete toggle between Input Image and Alternate Image is to set the transparency slider for Input Image near the right end of the scale, and the transparency slider for Alternate Image near the left end of the scale. Then clicking the "Show" checkbox of Input Image will effectively toggle the images. When the show button is checked, the high value for the Input Image slider causes it to dominate the view. When the show button is unchecked, Alternate Image is fully displayed even with a low slider value, since there is no contribution from Input Image.
Image Directory
The directory containing the alternate images and overlays. Will be set automatically to the directory containing the most recently selected file. Setting will be prepended to the file name at time of use unless the file name specifies a full path.
Alternate Image
The additional image to be displayed.
Alternate Ridge
The additional ridge to be displayed. The width is computed using the same parameters as the currently-displayed primary Ridge overlay. See the Extract section for details on changing the width calculation.
To adjust an aspect of the display, click on the corresponding button, dropdown menu, checkbox, or slider next to the display component to be altered.
For the Alternates tab, the input methods are the same as for specifying input image files. See the section Input for details.
FITS images can be viewed in the panel of the FITS tab. Display of the image can be adjusted using the controls of the View tab of SPICE.
Tabs of the FITS Display
The Image Tab
Display Panel
Dragging an image file name from a file system view into the image panel causes the image to be displayed.
Right-clicking in the display panel brings up "Clear" button. Selecting the button will cause any overlays to be cleared from the display.
Image
When an image file name has been dragged into the image panel and the image displayed, its name is shown in the Image text field.
Dragging an image file name from the file system panel into the Image text field causes the image to be displayed.
File Chooser Button
Clicking on the button to the right of the text field causes a file chooser dialog to be displayed, which allows selection of the image file.
The Header Tab
The header of the image file is displayed in the Header tab.
The Filter Button
Pressing the button causes the header to be filtered according to the pattern in the filter text field.
The Filter Text Field
The header text can be filtered by entering a wild-card string, such as *AOR*, in the text field and pressing the Filter button.
The Multi-Plane Tab
If the input image has more than one plane, the controls of the Multi-Plane tab will be active.
The Plane Text Field
The displayed plane can be changed by entering the plane number in the text field. The number of the first plane is "1".
The Plane Slider
The displayed plane can be changed by dragging the slider control or pressing the arrow buttons at the ends of the slider.
This Batch tab is normally hidden and processing is done for one DCE at a time. In SPICE it is possible to run many DCEs as a batch. In batch processing, all DCEs in the batch queue are processed with the same settings, which are the settings at the time batch processing begins.
Each DCE in the batch is run with the same settings, except for the three input data files
Input Image
Input Uncertainty
Mask File
In single-DCE processing, these three files are specified in the Input tab. In batch processing, the Input tab is not used. Instead the three input data files are specified for each DCE in a list, which is called the batch queue.
There are several ways of setting up the batch queue. The methods are similar to those used for setting individual DCEs. If the Batch tab is not showing, do the following:
In the main menu, choose "View".
Under "View", move the cursor over "SPICE".
Under "SPICE", move the cursor over "Batch".
A "Show" checkbox becomes visible.
Click on the "Show" checkbox so that a check mark appears.
Drag and Drop from the Browse Dialog
Procedure
Press the "Set Files" button of the Batch tab.
A dialog entitled "Browse" appears.
Click on the "New Entry" button of the dialog.
Lines are added to the table with a label "new entry ..." and an arbitrary tag number.
In the file browser, find the directory containing the input data files for the next DCE.
Drag the file name for the input image into the cell of the File column in the row labeled Input Image.
Do the same for the input uncertainty image in the row labeled Input Unc.
Do the same for the mask file in the row labeled Mask File.
The file names are saved in the table cells, and the directory cell is set to the directory containing the files. If the files are not all in the same directory, use the File Chooser method to set any files not in the selected directory.
Repeat the process starting with the "New Entry" button press for other DCEs in the batch.
File Chooser from the Browse Dialog
The procedure is the same as for Drag and Drop, but instead of dragging file names into cells, press the "..." button to the right of the File cell for any input data file. A file chooser dialog opens. Find the desired file and press "Open". The full path of the file is entered into the cell, and the Input Directory's cell is not altered.
Cell contents can also be modified by typing.
Checking Batch Queue Files
SPICE can check that all necessary files for each DCE have been set and exist. This can be done in the dialog. It is also done automatically when the batch is run.
Procedure
Press the "Check All" button of the dialog.
SPICE will check that all needed files are set and exist.
The Status cell of the table will be set to gray for each DCE that checks OK, and magenta if the check did not pass.
To check an individual DCE, click on one of its cells and press the "Check Selected" button.
Cell contents can also be modified by typing.
The output files will be written into in the "Output Directory" specified in the Output tab. The output names are taken from the initial part of each DCE's Input Image name, with suffixes according to their type: profile, ridge, etc. See the section "File Selection from the Search Dialog" for an example.
Queueing Entries
When the files have been selected in the dialog, the new entries can be added to the batch queue.
Procedure
To add all the selected DCEs to the batch queue, press the "Add All" button of the dialog.
The entries will be added to the table of the Batch tab.
Each entry is given a label "entry ..." followed by an arbitary tag number (which will not be the same tag number as in the dialog).
To add an individual DCE to the batch queue, click on one of its cells and press the "Add Selected" button.
Removing DCEs
To remove an individual DCE from the Browse dialog's table, click on one of its cells and press the "Remove Selected" button.
The dialog table can be cleared completely by pressing the "Remove All" button.
The "Remove ..." buttons of the Batch tab work in the same way.
After adding the entries to the batch queue, press the Browse dialog's "Done" button to close the dialog. Contents of the Browse table will be preserved.
File Selection from the Search Dialog
A large number of DCEs may be selected for batch processing by using a pattern matching technique on their file names. This is useful when the three input files have the same name except for a suffix indicating the data type. For example, suppose there is a directory /scr/data with output files from the BCD pipeline named
/scr/data/SPITZER_S1_9876540_96_0_1_bcd.fits
/scr/data/SPITZER_S1_9876540_96_0_1_func.fits
/scr/data/SPITZER_S1_9876540_96_0_1_bmask.fits
/scr/data/SPITZER_S1_9876540_97_0_1_bcd.fits
/scr/data/SPITZER_S1_9876540_97_0_1_func.fits
/scr/data/SPITZER_S1_9876540_97_0_1_bmask.fits
The DCE with Exposure ID 96 could be selected by pattern matching on the string /scr/data/SPITZER_S1_9876540_96_0_1_*. Both DCEs could be selected by matching on the string /scr/data/SPITZER_S1_9876540_*. Wildcards can also be used in directory names for the case where the files are not all in the same directory.
The output files will be written into the directory specified in the "Output Directory" text field of the Output tab. They will be given suffixes according to their type, prepended with the initial part of the filename for the DCE's Input Image. For example, if the Output Directory is specified as /scr/output, then running the batch job for the example above would create the following files
/scr/output/SPITZER_S1_9876540_96_0_1_profile.tbl
/scr/output/SPITZER_S1_9876540_96_0_1_ridge.tbl
/scr/output/SPITZER_S1_9876540_96_0_1_extract.tbl
/scr/output/SPITZER_S1_9876540_96_0_1_spect.tbl
/scr/output/SPITZER_S1_9876540_97_0_1_profile.tbl
/scr/output/SPITZER_S1_9876540_97_0_1_ridge.tbl
/scr/output/SPITZER_S1_9876540_97_0_1_extract.tbl
/scr/output/SPITZER_S1_9876540_97_0_1_spect.tbl
Procedure
Press the "Set by Search" button of the Batch tab.
A dialog entitled "Search" appears.
Enter into the "Pattern Match" text field a path with unix-type wildcards, such as
/scr/data/SPITZER_S1_9876540_96_0_1_*
/scr/data/SPITZER_S1_9876540_*
A file chooser button is provided so that a file name can be placed in the text field through browsing the file system. The file name may then be modified with wildcards by editing it in the text field, making it unnecessary to type in the full path name.
Examine the text fields for Input Image Suffix, Input Uncertainty Suffix, and Mask File Suffix. Only files ending in these suffixes are returned by the search. Modify any of the fields that do not match the suffix convention of your BCD files. Suffixes should start after a boundary character of either "_" or ".".
Press the dialog's "Search" button.
Files with full paths matching the search string and suffixes matching the specified BCD file suffixes with be found.
The files will be sorted into DCEs according to initial part of their names.
A new entry will be added to the table for each DCE, tagged with "new entry ...", followed by an arbitrary number.
Buttons for checking the entries, adding them to the batch queue, or removing them from the Search dialog's table have the same function as they do in the Browse dialog.
Press the dialog's "Done" button when finished.
Loading a Batch Queue from a File
The batch queue may be set by opening a file containing a list of full-path file names with one name per line. Lines starting with "#" or containing only whitespace are ignored. For example,
# An example batch queue file
/scr/data/SPITZER_S1_9876540_96_0_1_bcd.fits
/scr/data/SPITZER_S1_9876540_96_0_1_func.fits
/scr/data/SPITZER_S1_9876540_96_0_1_bmask.fits
/scr/data/SPITZER_S1_9876540_97_0_1_bcd.fits
/scr/data/SPITZER_S1_9876540_97_0_1_func.fits
/scr/data/SPITZER_S1_9876540_97_0_1_bmask.fits
Procedure
Press the "Load" button of the Batch tab.
A "Load" dialog appears.
Input Image, Input Uncertainty, and Mask File will be selected from the loaded list according to the suffixes specified by Input Image Suffix, etc.
If the input files to be set end with different strings than those shown, edit the text fields for the suffixes.
Press the "Load" button of the Batch tab.
Select the desired batch queue file.
Press the "Open" button of the dialog.
The files from the list will be sorted into DCEs according to initial part of their names.
An entry will be shown in the dialog for each DCE in the list.
Use the "Add All", "Add Selected", "Remove All", "Remove Selected", and "Check All" buttons as with the "Set By Search" dialog.
Location and naming of the ouput files is as for the other methods of batch setup.
Saving a Batch Queue to a File
The batch queue may be saved into the format described above, from which it can be loaded again.
Procedure
Press the "Save" button of the Batch tab.
Enter or choose a file name from the file chooser dialog which appears.
Press the "Save" button of the dialog.
The file names from the entries in the current batch queue will be saved in a text file with one name per line.
Starting Batch Processing
Batch processing is started from the Batch tab.
Procedure
To run all entries of the batch queue, press the "Run All" button of the Batch tab.
To run an individual DCE, click on one of its cells and press the "Run Selected" button.
Entries will be run using the SPICE settings in effect at the time the button is pressed.
Each DCEs status is updated according to the following:
White = Input files not checked.
Light Gray = Input files checked OK.
Magenta = Input files checked, file not specified or not found.
Gray = DCE submitted for processing.
Yellow = DCE is in the processing queue.
Orange = DCE is running.
Pink = DCE's processing was interrupted.
Red = DCE processing finished with error.
Green = DCE processing finished OK. SPICE does not check the return values of the modules, so this will be green even if a module finished and reported an error to the unix shell. To see the standard output of a module, select the Display checkbox of the Run item of the main View menu and run the module interactively.
Processing of single DCEs may be done during batch processing using the other SPICE tabs. Changing the settings will not affect the batch being run, but the next time a batch is started, it will be run with the latest settings.
Interrupting Batch Processing
With nominal processing speed, each DCE takes several seconds to run. If the queue appears "stuck", running jobs may be killed and pending jobs removed from the procesing queue.
Procedure
To kill running jobs and unqueue the others, press the Batch tab's "Kill Jobs" button.
Alternatively, select the "Kill Jobs" menu item under "Process" on the main menu.
The same command is used to kill a single module, so killing a module also kills any running batch job, and vice versa.
Rerunning a Batch
Pressing the "Run All" or "Run Selected" button again will cause batch processing to start, using the current settings. However, jobs that have green "finished-ok" status will not be rerun. To rerun them, first reset their status.
Procedure
To reset the status for all entries, press the Batch tab's "Reset All" button.
Every entry's status is set to white "unchecked".
To reset the status for an individual entry, click on one of the entry's cells and press the "Reset Selected" button.
CAPRI allows files needed by an application to be updated over the internet from within the application.
The Update panel must first be visible. If it is not,
In the main menu, choose "View".
Under "View", move the cursor over "Update".
A "Show" checkbox becomes visible.
Click on the "Show" checkbox so that a check mark appears.
Make sure that the "Show" checkbox for the desired user interface is also checked.
Update Procedure
Under the Update tab, click on the tab for the user interface to be updated.
Enter the URL for the update website in the text field labeled "Update URL".
Click on the "Refresh List" button.
A list of updates appears.
Check the box next to each update to be installed.
Press the "Update Now" button.
The updates will be downloaded and unpacked into the correct locations.
You can have your spice jobs run on a remote machine while the display runs locally. You can also have your input files on a remote machine and have them served to your display. They can then be used in exactly the same way within SPICE as files from the local filesystem. For these functions, all you need is to have SPICE installed on both the local (client) and remote (server) machines.
The following shows how to use SPICE as a server. It is important to note that if you have used SPICE as a client and then wish to use it as a server, you must restart SPICE. One instance of SPICE cannot be used as both client and server. To use SPICE as a server,
In the main menu, choose "Process".
Under "Process", move the cursor over "Server Settings".
A "Server Settings" dialog appears.
To serve files, check the "Serve requests for files" box.
Enter the path of the highest-level directory to be browsable by a client.
To act as a server for running spice jobs, check the "Serve requests for processing" box.
Select "Modify Server Settings" only if there is a port number conflict on your machine. If needed, check the box and enter an unused port number.
Click on the "OK" button.
Alternatively, SPICE can be run as a server from the command line.
In a shell, cd to the spice installation directory.
cd to "plugins".
cd to "server".
If the version of java in your path is not version 1.4.0 or higher, (find out by typing "java -version" in the shell), edit the shell script, start_server.csh, changing the definition of JAVA_BIN to the full path to the java binary of a java installation of version 1.4.0 or higher. This is the same procedure as in editing the shell script spice.csh, which starts SPICE. Edit the JAVA_BIN definition in stop_server.csh also.
On the command line, type ./start_server.csh /path/to/mydata.
This will start a server which will both act as a job server (to run SPICE jobs as requested by SPICE clients), and a file server (to serve files over http as requested by SPICE clients or any web browser). The highest-level directory browsable by a client is specified as the argument of start_server.csh. If you do not wish to serve files, run start_server.csh without an argument.
To stop serving jobs and files, run ./stop_server.csh or use Control-C to exit the SPICE server process.
The procedure is also written in the README file in the plugins/server subdirectory of the SPICE installation.
To use SPICE as a client,
In the main menu, choose "Process".
Under "Process", move the cursor over "Client Settings".
A "Client Settings" dialog appears.
To use files from a remote server, check the "Use a server for selecting files" box.
Enter the address of the server in the "File Server URL" text box. For example, if the files are being served from machine pepper.ipac.caltech.edu, enter http://pepper.ipac.caltech.edu:8880
To use a remote server for processing your jobs check the "Use a server for processing" box.
Enter the address of the job running service in the "Job Server URL" text box. For example, if the jobs are to be run on machine pepper.ipac.caltech.edu, enter http://pepper.ipac.caltech.edu:8880/runstage/runner.
Click on the "OK" button.
The file tree view under the Input and other tabs will show the file listing from the server. It can be navigated and files selected just as with files on the local filesystem.
The file chooser method of selecting files (clicking the "..." button next to a text field) will still use the local filesystem. In this way a mixture of local and remote files can be used.
Jobs run from the Batch tab will also be directed to the remote server.