5. Cube Assembly

This chapter describes in detail the steps required to assemble a cube from a set of mapping ‘BCDs’. A quick checklist of these steps is:

1. See section Quick Start Guide, for more on starting and running CUBISM.
2. Create a new cube project, and enter an appropriate name for the project (this can be changed later, and is not the same as the project's ‘.cpj’ file).
3. Accept the default (latest) calibration set, or load a specific set.
4. Load all data records from the AOR(s) which will be built into a single cube.
5. Load any additional data records to be used for background subtraction. Disable them if they are not intended to appear in the cube (see section Input Files).
6. Select and set the background records (see section Backgrounds).
7. Double-check the cube build settings under the Cube menu, in particular use Set Cube Build Order... to select the order for building the cube (note that high-resolution cubes are typically built using All orders at once).
8. Build the cube using Cube->Build Cube.
9. Save the cube project to file.
10. Manually or automatically generate bad pixels, and re-build the cube. Iterate as necessary.
11. Enjoy your newly assembled cube: extract spectra, build maps, etc.

5.1 Input Files

CUBISM works from a set of input ‘BCD’ or other record level data to produce spectral cubes. It reads positional information from the headers, loads pipeline mask files and uncertainty images, and uses all of this information together to map record-level pixels to the sky plane. Details of the algorithm employed by CUBISM can be found in Smith et al., 2007 (PASP, submitted).

CUBISM works best when applied directly to raw AOR directories downloaded from the Spitzer archives. To import all data (spectra/masks/uncertaines) from all records in a given mapping AOR (or set of related AORs), simply hit the Import AOR button, select a directory which contains one or more AORs, and CUBISM searches all ‘BCD’ files contained in that directory or its subdirectories, assembling them into constituent AOR sets. Select one or more of these AORs to load the associated data sets into the cube project. An example can be seen in fig:bcd_choice.

See section Record Data Types, for more information on non-‘BCD’ data types which CUBISM can use (typically only for debugging problems with the pipeline processing). Note that CUBISM projects can contain data from only one IRS module at a time, and that CUBISM does not check to see that the data sets you have selected are physically grouped, covering a moderate sized region on the sky.

Figure 5.1: Importing AOR data, grouped by AORs found in the selected directory.

Loading sets of non-mapping data, for the purpose of background subtraction (see section Backgrounds), can be accomplished conveniently using the Record->Import Data by Module.... Simply point at a directory containing the data of interest, and select the appropriate data sets, grouped by object and IRS module.

5.2 Build Order

For low-resolution IRS spectral maps, there is a subtle distinction between the build order of a given cube produced by CUBISM, and the target order of the observations from which it was built, which is worth discussing in detail.

Each low-resolution IRS slit consists of two sub-slits, separated by a blocked region. When planning low resolution IRS observations, you must select where your chosen target position will be placed in the full slit. You can choose to have the spacecraft place your chosen target coordinates in the center of the full slit (the blocked location), in which case your record type will be, e.g. ‘LL_Cen’. Alternatively, you might place your target coordinates in the center of one of the sub-slits (e.g. ‘SL1_cen’). Staring mode observations further subdivide each sub-slit, placing the target at roughly 1/3 and 2/3 along the sub-slit; these positions are denoted ‘a’ and ‘b’, e.g. ‘SL1_a’.

None of this, however, has any impact on the order information present in the data themselves. If you have placed your target in ‘SL1_cen’, the other sub-slit will still image the sky onto the detector and record a spectrum. Each record's data will thus contain both orders (as well as the “bonus” order).

It is often useful to build a cube from data in the “other” sub-slit's order, i.e. the one not targeted during the map. When an object is mapped consecutively with both sub-slits, using all the data records to build a cube in a given order results in two potentially disjointed regions. We often call the region of cube built from the sub-slit not being targeted the “outrigger”. Data in the outrigger region can be very useful for improving the statistics for automatic bad pixel selection (see section Automatic Bad Pixels), and for confirming the data levels in low signal regions. Alternatively, for large source, the outrigger field can contain interesting data in its own right.

By default, CUBISM sets the cube build order to the most common target order among the loaded BCD records. Obviously, if the full slit center was targeted, no individual order is preferred, so an arbitrary default is used. In general, you should check the cube build order to ensure you are building the cube you want. In the project window, Info->Project Parameters... provides this information, and you can set the cube build order with Cube->Set Cube Build Order. Recall that each low-resolution cube is built using data from a single IRS order (e.g. ‘SL1’). High resolution order wavelengths are much more continuous, and are combined directly in the cube.

5.3 Calibration Sets

CUBISM needs a large number of different pieces of calibration data to perform its tasks, including flux calibration functions, order positioning and wavelength solutions, extended source flux correction functions, etc. These calibration data are tied directly to those produced by the SSC for point sources, although they are extended and supplemented by additional information. CUBISM uses the concepts of calibration sets, unit bundles of calibration products which snapshot the latest calibration data, appropriate for the most recent pipeline processing.

By default, CUBISM loads the most recent calibration set which is bundled with it. Typically, you will not need to select a calibration set. As long as you are using the most recent IRS pipeline processing version of your data, the latest set is appropriate. The calibration set used with a given cube is saved in its project file, so that future use, even after new calibration sets are created, will continue to use that data. You can see which calibration set you are using, and inspect all of the parameters and input calibration files it consists of, with Info->Calibration Set Details.... New calibration sets (‘.cal’ files) can be loaded with File->Load New Calibration Set.... All input calibration files (in incrementing versions) can be found in the ‘cubism/calib/data/ssc’ directory in your CUBISM distribution.

Note that the general presumption is that more current calibration data is always better when used with data processed with the most up to date SSC IRS pipeline. This is true in general, although there is currently one time dependent calibration (the input bias voltage for the LH detectors was changed). CUBISM automatically uses the appropriate flux calibration values depending on the date of observation.

Though normally not necessary, new calibration sets can be created from the assembled inputs using the included helper routine ‘irs_make_calib_set’; see ‘cubism/calib/irs_make_calib_set.pro’ for more information.

5.4 Backgrounds

All IRS observations are affected at some level by the foreground or background emission of zodiacal dust and Galactic cirrus. For faint sources, subtracting off a local “sky background” in the form of a 2D ‘BCD’ frame constructed from data obtained nearby in position and time is the most effective method for removing the astrophysical background. In addition, ‘BCD’-level background subtraction greatly reduces the number of bad or “rogue” pixels contaminating IRS data, especially in the longer wavelength models, and effectively reduces residual systematic uncertainties which dominate at low flux intensity (often in the form of correlated patterns, bands, etc.). BCD level background subtraction is a recommended step for all cubes, ideally performed with associated background data obtained during the same AOR, using the same integration time, etc.

Here we explore a variety of options for background subtraction, in decreasing order of preference. The degree to which backgrounds must be suppressed also depends on the source flux. Very faint sources at or well below the sky brightness level are more affected by residual background and low-level systematics (which often vary in magnitude and shape among orders and modules).

IMPROVING CUBES WITH BACKGROUND SUBTRACTION: Subtracting a 2D background frame can greatly improve the quality of the assembled cube, especially for faint sources.

5.4.1 In Situ Background

The primary and recommended technique for assembling a background frame is to use dedicated background observations you scheduled along with your mapping AOR, or to use data obtained as part of your mapping observations which went far enough off the source to remove all source flux from the slit.

Finding records in which the full slit is uncontaminated by source emission, either within the spectral map itself, or as part of a dedicated background AOR grouped with the main observations, is the goal. This is often aided in maps using the low-resolution modules by the fact that each low-res slit (LL and SL) is comprised of two sub-slits which define the different spectral orders. For small objects, less than the size of one sub-slit, it is common to map first with one sub-slit, and then with the other (e.g. a SL1 map and, separately, a SL2 map). In this case, the “outrigger” data from those records collected when the source was placed in the other order can be used as a background set. Even if the full slit was used to map a source, the fact that the two orders extend away from the map center to either side often allow useful background frames to be found at the extremities of the map. For a very helpful method for making such selections, See section Background Selection Using Visualization.

For dedicated offset sky observations, simply load the records (for example, with Record->Import Data by Module->BCD), disable them, and Background->Set Background from Recs.... For backgrounds which appear among the mapping data set (e.g. as was done in the Quick Start Guide), simply select these records and choose Background->Set Background from Recs.... Using either the average or min/max trimmed average is fine. These records can be built into the cube directly (though by definition they should not contain much source flux), or disabled to save time and space.

5.4.2 Archive Background

If you didn't obtain dedicated sky observations, and none of the records in your map are free from source emission, you can still recover 2D level BCD maps by “borrowing” suitable data from the Spitzer archives. Useful sky data would have been obtained with the same instrument module, using (ideally) the same exposure time, targeted within roughly 10 degrees in ecliptic latitude from your source, and within 2–3 days of the target observation.

The efficacy of archive sky subtraction can vary widely, and depends on the level of the background at your source, and the historical behavior of the IRS detectors at the time of your observations. The closer in time and ecliptic coordinate the data, the better the subtraction will be (both in terms of removing the astrophysical foreground, and mitigating the effects of rogue pixels). The complete log of all Spitzer observations can be useful for identifying potential data sets which could contain useful background data. Remember that you must decide yourself whether a given BCD record constitutes a valid background frame, i.e. is free from source emission. For low resolution data, often the safest bet is the “outrigger” order from a staring mode observation (which often target unresolved sources) — e.g. SL2 from a SL1 targeted observation. The disadvantage of this technique is that the data must be available in the archive, which for many program requires waiting for the proprietary period to expire.

5.4.3 Background Blend

A related technique to the archive background is the “Background Blend”, useful if a set of observations from the archive which closely match the background properties of your source cannot be identified. In this method, a pair of observations from the archive (or elsewhere) which bracket the target background are linearly blended together to approximate a local 2D background. The same constraints on data of exposure apply: ideally all background observations would have been obtained within 2–3 days of the target observations, to maximize the effectiveness of mitigating rogue pixels (the behavior of which drifts on the time-scale of days).

To use this method, load the two data background sets, ensuring their records are disabled to avoid having them built into the cube. Select the subset of the first which you want to include in the background, and select Background->Background Blend->Set and Scale Background A.... The selected background is displayed, with ‘BackgroundA’ indicated in the image info block (see section Image Info Block). Enter a fiducial background value when prompted. This value serves as the interpolant for determining the weights of the two backgrounds in the blend. For SL data, it is convenient to use the flux measured in the Peak-Up Blue image at 16 microns (the lower of the 2 peak-up fields visible in all SL BCD images), if it is clear of source contamination. The box statistics tool can be useful (e.g. use as a fiducial value the 3-sigma clipped average of a large section of the PU field). Do the same for ‘BackroundB’, and then select Background->Background Blend->Blend A and B Backgrounds..., entering a fiducial of your target data set, formed in the same way (e.g. in from the PU field statistics). Another potentially useful fiducial is the predicted background at the source position and date, as available in Spot.

5.4.4 1D Sky Spectrum

If no 2D BCD-level data are available for subtraction, some of the same benefits can be obtained by specifying a 1D spectrum to subtract from all the cube planes. You can build a cube, extract a spectrum from a carefully chosen area believed to be free from source contamination (use the visualization if possible, see section Background Selection Using Visualization), and use this extracted spectrum as a 1D level background.

FLUX UNITS WARNING: Note that any fluxed 1D spectrum must be extracted from cubes built with the same flux options (e.g. the SLCF correction) as the cube to which it is being applied. Spectra extracted from raw cubes (in ‘e/s’ units) do not have this restriction.

This method does not help mitigate rogue pixels, and is essentially equivalent to extracting spectra and differencing them after the fact, but operates on the entire cube at once.

5.4.5 Combined 1D and 2D Background

Occassionally, a 2D sky spectrum obtained from the archive in a different region of the sky, or from ‘BCD’ data taken with different exposure times, will do a reasonable job mitigating rogue pixels, but leave a residual background (positive or negative), which is obvious in parts of the cube without signal. This background offset can have a large effect on sources at or below the absolute residual background flux level. The “dark” areas in a cube where the residual is obvious should of course be smaller than the slit length, or else an in situ background could have been used (see section In Situ Background).

Assuming you have located a region within the cube which you feel is free of source emission, the residual background can be removed by combining the original 2D-level background, archive or otherwise, together with a further 1D correction (applied as a separate scalar subtraction to all wavelength planes in the cube).

Assemble the 2D background-subtracted cube, extract the region, and save the resulting spectrum to file. At this point, you might like to load in the spectrum at the command line, fit a low order polynomial to it, and write it out again, to avoid adding noise into the cube. Something like:

IDL> p=read_ipac_table('file.tbl',h,UNITS=u)
IDL> fit=poly_fit(p.wavelength,p.flux,2,YFIT=yf)
IDL> p.flux=yf
IDL> write_ipac_table,'file.tbl',DATA=p,HEADER=h,UNITS=u

will accomplish this. Then load this 1D background, using Background->Load Background Spectrum.... You will recieve a warning that both 1D and 2D (record-level) backgrounds are being applied. Re-build the cube, and extract the same region: the spectrum should be near zero (with noise).

EXTENDED SOURCE WARNING: CUBISM does not verify that fluxed 1D background spectra have the same extended source corrections applied as the target cube. Ensure this yourself.

5.4.6 No Background

Using no background is a reasonable last resort option for brighter sources, though the number of bad pixels in the raw unsubtracted data will be much higher, so more work will be required to identify them (see section Bad Pixels). The (astrophysical) foreground flux will also of course remain in the final assembled cube, which may affect analysis of extracted spectra or maps, and the degree to which matched extractions from cubes built in different IRS modules or orders will stitch with each other.

5.4.7 Background Selection Using Visualization

It can be convenient to select suitable records for inclusion in the background frame by using the AOR visualization of an IRAC or MIPS (or other zodiacal and/or cirrus sensitive waveband) image of the target region. See section AOR Visualization Tool, for more information on the visualization tool. Here we describe how to use the “outrigger” method to select suitable records from a set of low-resolution observations in the SL module (LL would be similar).

1. Load all the relevant SL (SL1+SL2) frames, which may span more than one AOR. Using Import AOR will permit selecting more than one AOR at once. Don't mix data taken more than a few days apart, to minimize the effects of day-to-day changes in the pixel response of the detectors.
2. Visualize the AORs using, e.g., an 8 micron IRAC image (see section AOR Visualization Tool). After using the histogram box to scale the image such that low-level diffuse emission is apparent, switch to the visualizer tool. To define background BCDs for, e.g., SL1, set the cube build order to 1 (Cube->Set Cube Build Order), and see which records are free of source flux. Highlight these outriggers with the mouse by click and drag.
3. For reference, save the resulting record set into a ‘.bgl’ file using Background->Save Background Recs....

5.4.8 Saving the Background List

The background list can be saved to a text ‘.bpl’ file using Background->Save Background Rec(s). While not strictly necessary, this is a useful record of the background records for future reference in other cubes. The format is list of unique record IDs (‘DCEID’) which do not change with updated pipeline processing.

5.5 Bad Pixels

Hot, “rogue” or bad pixels occur in IRS data with a broad range of intensities, and they vary in position and frequency on the array on scales of hours to months. Over time, damage to the IRS arrays from solar particles has increased the number of these pixels, in particular on the two long wavelength arrays. Such pixels dominates the noise properties of spectral cubes, maps and extracted spectra, and if left untreated, severely degrade the quality of assembled cubes. Cleaning a cube of bad pixels is typically an iterative task: mark pixels, re-build the cube, inspect the cube for anomalous spectral or spatial features, mark additional pixels, etc.

CUBISM contains a variety of tools for identifying and flagging such pixels, which are then ignored when assembling the cube. Bad pixels can be identified either “manually” or automatically (or a combination of both). As discussed in Backgrounds, subtracting a background record built from data obtained nearby in time, with the same record exposure time, can mitigate many rogue pixels (which can be thought of as pixels which respond normally to light, but have a bright and variable underlying dark current component). However, adjacent-in-time background subtraction is not always available, and even when it is, a number of problematic pixels often remain. CUBISM has multiple facilities for discovering and flagging out these bad pixels.

5.5.1 Global and Record Level Bad Pixels

There are two different types of user-settable bad pixels in CUBISM: Global and Record Level. A global bad pixel is a pixel presumed bad in all ‘BCD’ records. Since global bad pixels remain bad throughout the duration (or a large portion) of the spectral map, they produce “stripes” at individual wavelength planes in the final cube as the pixel is rastered across the map; an example of this effect is seen in fig:cv_stripes. The number of stripes depends on how many steps are executed along the slit. Occasionally, partial stripes will appear, indicating a bad pixel which persisted for only a portion of the map.

The second type of bad pixel is a record level bad pixel, which affects only a single record. These can be useful for treating intermittent bad pixels which affect only a single or small number of records; rather than discarding that pixel's data for the entire map, only the portion affected is removed. This is particularly useful for BCD frames with horizontal band artifacts (a group of rows with garbled data). The number of record level bad pixels set for a given record can be seen in the secondary pane of information in the CUBISM Project window. The total number of bad pixels marked, and their sources, is given in the project parameters (Info->Project Parameters...).

Figure 5.2: An example of a global bad pixel impressing “stripes” in the output cube.

5.5.2 Manual Bad Pixel Selection

Bad pixels can be selected manually at several levels. The most straightforward is at the ‘BCD’ level: simply examine a single or stack of records, and mark errant pixels. See section Bad Pixel Tool, for more on marking user or record level bad pixels, and on the identifying symbols used to mark pixels.

MULTIPLE RECORD BAD PIXELS AT ONCE: Setting record level bad pixels on a stack of more than one record sets that pixel in all the records in the stack.

A typical workflow for manually marking bad pixels at the ‘BCD’ level:

1. View the stack of relevant ‘BCDs’.
2. Show the ‘WAVSAMP’ (see section WAVSAMP Pane).
3. Click ‘BGSub’ (if available) to remove the appearance of many bad pixels using the record level sky background data previously defined.
4. Enlarge the stack viewer window (see section Options Menu).
5. Show the user (cyan/green ‘x’) bad pixel and pipeline fatal (red ‘x’) masks only, by right-clicking two times (see section Bad Pixel Tool).
6. Set the histogram scaling stretch to show only the very brightest pixels.
7. Mark >4 sigma deviations, but ensure you are not marking line data!
8. Reset the scaling to show the next brightest set of pixels.
9. Mark >4 sigma deviations.
10. Iterate this process until you can clearly see emission lines or other real features in the data, to the point where the viewable pixels are no longer >4 sigma deviations.
11. Save the bad pixel mask (see section BadPix Menu).
12. (Re)-build the cube with this mask (uses QuickBuild – See section QuickBuild).

Note that most ‘BCD’ records contain a rim of pixels flagged with ‘[7]’, which appear as red diamonds surrounding each order. These are “flat-field questionable” pixels, but experience shows that many of these pixels are useful. They can be trimmed away by narrowing the WAVSAMP (see section WAVSAMP), but aren't considered fatal by default.

BAD PIXEL TIP: When selecting bad pixels in cubes being built with a background, be sure to enable the BGSub button before selection, since this can mitigate many rogue pixels, which would otherwise appear bad.

5.5.3 Backtracking to Discover Bad Pixels

Backtracking is the term used for listing all the ‘BCD’ records, and pixels within those records, contributing to a given cube pixel. This is a very powerful tool for validating features in a cube. In particular, it is useful for identifying global or persistent record-level bad pixels, which impress stripes in the cube (see fig:cv_stripes). See section Pixel Backtracking Tool, for more on using this tool.

A typical workflow for identifying bad pixels using the backtracking tool is:

1. Inspect each wavelength plane of the cube for out-of-place columns/rows. Using the left/right arrow keys in an extracted spectrum (Full Cube view) is a quick way to step through the cube.
2. Using the backtracking tool, select a cube pixel inside a problematic feature (e.g. a stripe).
3. Note any pixels in the backtracked data set, comparing to other cube pixels along the feature to note record pixels which are consistently outliers.
4. Right-click a given pixel to mark it as a global or record level bad pixel.
5. Re-build the cube after one or more pixels are marked to see whether the cube was improved. If not, undo and try again. With QuickBuild (see section QuickBuild), this process is very fast even for large cubes. The displayed cube and any extracted spectra are automatically updated.

A related useful technique is to extract spectra in different parts of the cube, and look for non-physical spectral features (typically positive or negative spikes, one pixel wide, not corresponding to known lines). Using CubeSpec's Full Cube mode, select the affected cube plane, and look for anomalous stripes or other features. Use the backtracking tool to identify and mark bad pixels, and re-build with QuickBuild.

5.5.4 Automatic Bad Pixels

USING AUTO BAD PIX: Since CUBISM uses the BCD pixel contributions to the cube to discover bad pixels automatically, you must first build the cube before the automatic bad pixel options are enabled.

CUBISM offers a powerful method to automatically discover and mark bad pixels in an assembled cube. Selecting BadPix->Auto-Gen Global Bad Pixels or BadPix->Auto-Gen Record Bad Pixels will show a dialog in which the parameters for the automatic selection are set (see fig:autobadpix). The method by which bad pixels are automatically discovered is similar in concept to the backtracking method described in the previous section, except that all cube pixels are considered simultaneously, and statistics are collected on individual BCD pixels, which can be used to flag them as bad.

AUTO BAD PIX WARNING: The automatic bad pixel tool must be used with caution. It can flag real data such as spectra lines or sharp spatial features (e.g. point sources). Always check the resulting bad pixels it finds, and avoid very low sigma thresholds or fractions.

An example of the auto-badpix parameter dialog is seen in fig:autobadpix. The “Sigma-Trim” option sets the rough number of standard deviations a pixel must lie away from the median record pixel value contributing. The “MinBad-Fac” lists the minimum fraction of occurrence of a given ‘BCD’ pixel in which it must deviate to be considered bad. For example, if ‘sigma-trim’ is 7, and ‘minbad-frac’ is .5, then a given ‘BCD’ pixel is considered bad if at least 50% of the time it appears in the cube, it is 7-sigma from the median pixel value.

Figure 5.3: The dialog for setting auto bad pixel parameters.

The BG button determines whether the test for lying outside the sigma trim threshold is performed on the background subtracted data (comparable to using the ‘Val-Back’ column in the backtracking tool). This is typically a good idea, since many pixels are not outliers when background-subtracted. The UNC option controls how the fiducial spread of data values is determined. If it is set, the pipeline-estimated uncertainties are used. If not, a median absolute deviation is used as an estimate for the fiducial sigma value. Since the pipeline uncertainties severely under-estimate the true spread of data above S/N ~10 or so, for bright sources, it is best not to set the UNC option. It can be useful for faint sources, in particular when the redundancy is small.

Record-level automatic bad pixels are similar to global bad pixels, except instead of demanding that a given ‘BCD’ pixel must deviate at least ‘minbad-frac’ of the time it appears in the cube, only that record's pixel must satisfy this cut. For example, if record 20, pixel ‘(40,79)’ appears 4 times in the cube, ‘minbad-frac=.4’ requires at least 2 of these appearances to be outliers at the ‘sigma-trim’ level to consider it a bad pixel. Many more bad pixels will be generated by record-level auto-badpix, but each of them will have a much smaller impact on the final cube (since they disable that pixel for only a single record). Often, global bad pixels are sufficient. In certain cases, record-level pixels, automatically discovered, are very useful, for example for very short exposures (6s) in which cosmic rays are incompletely identified by the pipeline. This results in small 3–4 pixel stripes along rows, which can often be identified automatically with record-level auto bad pixels.

CLEARING BAD PIXELS: Note that by default the bad pixel list is appended to with subsequent runs of auto-badpix. Clear the bad pixel list first to avoid this, and save intermediate results to ‘.bpl’ files for added flexibility.

Obviously, the amount of redundancy in a spectral map has a major impact on the degree to which outlier pixels can be automatically discovered. A ‘1xn’ map (no steps along the slit) offers a minimum amount of pixel redundancy, whereas a map stepped many times along the slit, placing the same source position at multiple positions along the slit, will offer much better redundancy. With minimum redundancy, the number of record pixel samples mapping into a cube pixel is small, and the natural spread of those samples, which results from the edges of spectral lines or sharp spatial features falling into a single spectral cube, can overwhelm bad pixels. Extreme caution must be exercised in this case to avoid marking legitimate pixels at these edges.

5.5.5 Saving Bad Pixels

The list of global and record level bad pixels can be saved as text in ‘.bpl’ files using BadPix->Save Bad Pixels.... This is useful for sharing bad pixel lists among projects, and providing a backup of the marked pixels outside of the cube project (recommended). Bad pixels can be loaded in from ‘.bpl’ files as well, either replacing the current set, or appending to it. The format of the bad pixel file is a list of 1D pixel indices (‘128*y+x’), prepended (in the case of record level bad pixels) by a line with two entries: the unique record ID (‘DCEID’) and the number of bad pixels associated with that record. The global bad pixel list follows.

See section BadPix Menu.

5.6 Cube Build Settings

The cube build settings are accessed in the Cube menu of the project window. Typically the default values (most options enabled) are fine, but for occasional uses you may prefer to disable some:

FLUXCON

Typically you would build the cube in units of ‘MJy/sr’ using this option. It enables use of the extended source flux calibration files. Once reason you might prefer to build a cube without fluxcon is to make a 1D background in ‘e/s’ units for loading as a background spectrum (see section 1D Sky Spectrum).

SLCF

The slit-loss correction function is used to correct the native IRS pipeline calibration, tuned for point sources, to the case of perfectly extended sources. While most sources are not entirely smooth and slit-filling, this option should be enabled in most cases, except for point sources. Note that the CUBISM calibration of extended sources is made using the SLCF; point source spectrophotometry will be more accurate using SPICE, or another single-pointing extraction tool.

Subtract Background

Only available if a background is set, this is usually a good idea, unless you'd like to create a 1D background spectrum directly, or check the cube without background removal.

Trim Wavelengths

Trimming the unreliable order ends is never a bad idea, unless you are specifically interested in the spectrum there. Note that some additional trimming may be required; this is a conservative trim by default.

Reconstructed Positions

Unless the reconstructed slit positions are thought to be in error, use this option. Disabling it uses the pre-programmed requested slit positions, which can be off by several arc seconds.

Uncertainty Cube

Only an option if all your records have uncertainties, this builds a full uncertainty cube in parallel.

PIPELINE UNCERTAINTIES: Note that pipeline uncertainties are statistical ramp uncertainties only, valid only in the low S/N limit. Above S/N~10–20, systematic uncertainties, not accounted for by CUBISM, dominate.

5.7 WAVSAMP

The ‘WAVSAMP’ is the set of pseudo-rectangles which define the spectral order's location on the array, the (tilted) locus of constant wavelength, and the wavelength calibration (see, e.g., fig:cv_recs). CUBISM uses a custom built version of the ‘WAVSAMP’. which differs slightly from that used by the SSC. The exact position and size of the ‘WAVSAMP’ changes with new SSC calibrations, and it typically includes a small amount (1-2 pixels) of spurious data at the extremities of the slit. For spectral maps without any stepping along the slit (1xn maps), leaving this crust of spurious data will have little impact, since it can be ignored when extracting spectra and making maps. For maps with along the slit redundancy however, it is important to exclude this data directly.

See section WAVSAMP Pane, for more information on editing the ‘WAVSAMP’. Typically, the ‘WAVSAMP’ is edited, and the central handle is used to drag each side in by 2–5% (the reported ‘WAVSAMP’ coordinates are in normalized units, 0.0–1.0), to exclude the bulk of the spurious data at the slit ends. Non-uniform edits (different normalized range at each end of the order) are not recommended. Note that most ‘BCD’ records contain a rim of pixels flagged with ‘[7]’ in their ‘BMASK’, which indicates the flat field is questionable there. These are not fatal bad pixels, and should not be excluded simply because they are flagged.

5.8 Building the Cube

Once the data records are assembled, backgrounds are set, and obvious bad pixels are marked, a first-pass cube can be assembled. Note that disabled records are not included in the cube build. Frames which are completely garbled (a rare occurrence) should be disabled, as should data records which are used only for setting the background (which may be far away on the sky).

Select Cube->Build Cube, or press the Build Cube button, and watch the cube build progress plotted (records lain out and clipped against the sky grid, and then final cube pixels assembled from the record data). Typically several iterations of cube building are performed, refining the background and bad pixel selection, before the cube is considered complete.

Once the cube has been built once, subsequent builds will proceed much more quickly, since the “account” information, which includes all the clipped pixel mapping from ‘BCD’ to the sky grid, is saved. Changing the ‘WAVSAMP’, build order, or manually resetting the accounts with Cube->Reset Accounts will invalidate the accounts, which will need to be reconstructed in a slow cube build. Changing backgrounds, bad pixels, etc. can be done without invalidating the accounts.

5.9 QuickBuild

As a special case of cube rebuild, changes to the bad pixel lists (global or record level) enable a special mode called ‘QuickBuild’. The Build Cube button and Cube menu items in the project window will change to reflect this. In this mode, only cube pixels which are affected by dirty BCD pixels (those recently added or removed from one or more bad pixel lists) are recomputed. The status bar mentions the fraction of cube pixels which are being re-built. This is much faster than a full cube rebuild, typically requiring only a second or two even for large projects.

QuickBuild means that experiments with bad pixels to improve the quality of the cube (see section Bad Pixels) can be performed very rapidly. This is particularly powerful with back-tracking (see section Backtracking to Discover Bad Pixels), since you can try out a bad pixel, quick-build the cube, and the cube view and any extracted spectra are automatically updated. If the problem isn't solved, undo and try again.

5.10 Saving the Project

Saving the project to a ‘.cpj’ project file records all of the information presented in a CUBISM Project window, including data records, background settings, bad pixels, cube build preferences, calibration set details, etc., and allows you to recover a cube project from disk to continue working on it. Saving the cube can be accomplished with menu option File->Save, or File->Save As... to save a version under a different name, or with the convenient Save button below the record pane. File->Revert to Saved... allows you to discard any changes to the project, and restore the version most recently saved to disk.

Not all of the data is saved with the project by default. There are three options related to saving the project file, accessible in the File->Save Setup menu:

1. Save Data with Project: This saves a copy of all the loaded data (including ‘BCD’, associated masks, and uncertainties) into the project file. This adds approximately 192kB per record to the size of the file, and is only necessary when you intend to distribute the file independent of the data directories. This can be useful for sharing ‘.cpj’ files with colleagues without access to the Spitzer archives, but can result in large files when many tens or hundreds of records are involved. It is also redundant when the data files themselves are already available.
2. Relative File Names: By default, the absolute paths of the data files are stored in the project, and, if the data themselves are not stored, they will be recalled from disk when needed. Unfortunately, this makes cube project files non-portable (leading to errors like “Couldn't restore data from file”), unless the absolute path to the ‘BCD’ files is fixed on all systems where the cube is loaded. While you can easily replace the root directory from the file names to fix this issue (see section Troubleshooting), another method is to enable this option to specify that all path names will be saved relative to the path of the ‘.cpj’ file itself. Then, as long as the relative file layout of the project file and data files remains the same, all record data should load without problem. This has the advantage of allowing cubes to be passed back and forth without needlessly re-tranferring all the data, but also not requiring any absolute file layout for the data on disk. For instance, a full directory structure as:

   myproj/myproj.cpj myproj/data/r123456/ch0/bcd/... myproj/inputs/myproj.bpl myproj/inputs/myproj.bgl myproj/myobject_8um_viz.fits

   could be distributed as a unit, with ‘myproj.cpj’ referencing the data in the ‘data’ directory, a visualization image, and even including saved copies of the bad pixel and background list inputs.

3. Save Accounts with Project: The clipping accounts consist of all the information which maps ‘BCD’ pixels to the sky grid. When the accounts are valid, (you don't see needs rebuilding in the Info->Project Parameters... page), the cube can be rebuilt quickly, and pixel backtracking can be used (see section Pixel Backtracking Tool). Saving this account information in the project file gives these benefits to cube projects loaded from disk as well, but comes with a steep cost in terms of disk space: approximately 400–700kB per record.

For distributing CUBISM projects as ‘.cpj’ files, it's easiest to save the project without data or accounts (the default), since this produces the smallest files by far. However, this requires everyone to have access to the data, in the same path (for absolute file names), or with the same relative path layout (for relative file names) as on the build host.

One approach for sharing the data and cube project together is to save the data in the project itself. This creates a larger project file, but is fully self-contained. Another reasonable approach is to use relative file names, and bundle the ‘.cpj’ together with the data directories and visualization image (if any) in a single directory for distribution. The advantage of the latter is it allows the ‘.cpj’ file to be updated independent of the data themselves.

For users who simply wish to examine the cube itself (extract spectra, make maps), access to the record data isn't necessary — any ‘.cpj’ with an assembled cube will do, or even just the FITS Cube (see section Reading a FITS Cube).

5.11 Saving the Cube as FITS

The cube can be saved as a 3D FITS file for further analysis, using File->Write FITS Cube.... If an uncertainty cube exists, it will be saved alongside the main cube, with ‘_unc.fits’ replacing ‘.fits’. Both FITS files include headers from the first assembled ‘BCD’, and an ‘NAXIS=3’ FITS cube in the primary data unit, with WCS header records recording the astrometric positions for the first two (celestial) dimensions, and the third (wavelength) dimension delineated by a lookup table, available in the first cell of the binary table in the single FITS extension. This dimension coordinate description follows the lookup table spectral format of Greisen, E.W. et al., A&A 446, 2006.

5.12 Reading a FITS Cube

A saved FITS cube can later be read from disk for immediate display using CubeView (see section CubeView). No project window will be displayed, instead the cube will be viewed directly in CubeView, with a name ending in ‘[FITS]’. The associated uncertainty cube will also be loaded if available. Note that most of the features associated with a full CUBISM project will be unavailable when viewing a cube loaded from a FITS file, including the CUBISM project interface, record and overlay visualization, bad pixel lists, pixel backtracking (see section Pixel Backtracking Tool), etc. Cubes cannot be (re)-built from versions saved as FITS, since they do not contain all the information on input data records, bad pixels, backgrounds, calibration settings, etc. Spectra can be extracted and maps can be created and saved from a FITS cube; see See section Cube Analysis. Except for low-level analysis of completely validated cubes, it is preferable to work with full cube project files (see section Saving the Project).

LOAD FITS CUBES: By default, when opening a cube from File->Open... or when calling ‘cubism’ directly, only ‘.cpj’ files will be displayed. To load a FITS cube, select the filters list to display ‘.fits’ files, and ensure you select a 3D FITS cube generated by CUBISM.

This document was generated by JD Smith on July, 14 2009 using texi2html 1.78.