6.7. Working on cubes: the Spectrum and Cube Toolboxes

In this section we describe the tasks of the Spectrum and Cube Toolboxes which you can call up from the Spectrum Explorer. These toolboxes include tasks to perform various spatial and spectral operations on the spectra of a cube, for example to add, average, flag, make flux and velocity maps, crop spectrally or spatially, change units and calculate statistics. The main difference between the two is that the Cube Toolbox works on cubes, while the Spectrum Toolbox will work on any spectral product, including cubes. There is some overlap between the two in what they do: the emphasis of the Cube Toolbox is on working with cubes along the spectral and spatial planes, while the Spectrum Toolbox concentrates more on mathematical tasks.

The toolboxes are opened from the icon menu at the top of the Spectrum Explorer GUI, and from within the toolbox tab that opens in the Spectrum panel you can select their specific tasks. The individual tasks can also be found in the Tasks pane of HIPE; the interaction with a task opened this way is similar to that when opening via the Spectrum Explorer, it is mainly selecting spectra or spectral ranges for the task to work on that differs.

Before continuing with this section you should read Section 6.2 to learn more about working with cubes in HIPE, Section 6.3 to learn more about working with the coordinates of the spaxels/pixel in your cube, and Section 6.4 to learn more about weights, errors, and flags.

See Section 6.6, to learn how to use the Spectrum Explorer. Please also read the next two sections, where we explain the behaviour of the Cube and Spectrum Toolboxes working via the Spectrum Explorer: how they interact, and how you input data and inspect the output. If this tool is not familiar to you, you will benefit greatly from reading Section 6.7.1 and Section 6.7.2.

6.7.1. How to open the Toolboxes; getting extra help

Spectrum Toolbox: can be opened from the Spectrum Explorer by clicking on the crossed hammer and screwdriver icon in the toolbar: , or from DialogueSpectrum Toolbox in the menu you get via a right-click in the Spectrum panel. A new tab will appear to the right of the Spectrum panel, and the tasks can be selected from a drop-down menu.

Cube Toolbox: can be opened from the Spectrum Explorer by clicking on the cube+screwdriver icon: , or from DialogueCube Toolbox in the menu you get via a right-click in the Spectrum panel. A new tab will appear to the right of the Spectrum panel, and the tasks can be selected from a drop-down menu.

For both toolboxes you can also open their individual tasks by name from the Tasks pane of HIPE. The task dialogues will open in the Editor pane.

Getting help: If you open the tasks via the Spectrum Explorer then you can open the User Reference Manual (URM) entry for each task by clicking on the: Cube Toolbox: "Help" button at the bottom of the task panel; Spectrum Toolbox: small question mark icon at the bottom of the task panel. If you opened the task from the Tasks pane, the URM entry for that task can be accessed from a Help button from the task panel, or by right-clicking on the task name in the Tasks pane and selecting Help in URM. The URM entries for the spectral tasks explain the command-line use of the tasks. Here we will explain the GUI usage.

Also, the following task instructions are written assuming you have already opened the task GUI.

[Warning] Warning

It is better to create a variable for the cube you wish to work on, rather than to open it from or the ObservationContext (or other product such as a ListContext as is the case for some PACS products) that the cube is contained within. Many of the tasks change the data, and HIPE will not allow you to change the contents of an ObservationContext in this way. So, if working from an ObservationContext, first extract the cube out of it, and then work on that.

6.7.2. Defining the input, looking at the output

This is a reference section that tells you how to select the spaxels/pixels that you want any task to run on.

The first tabs of the Spectrum Explorer are the ones that open when the Spectrum Explorer does, i.e. one tab in each panel.

  1. More tabs may be added to the Spectrum panel as various toolbox tasks display results; remember that the tab that shows spectra selected from the cube is the first, left-most one called "plot".

  2. More tabs can also be added to the Data Selection panel, either by the toolboxes (in particular the Cube toolbox) or if you drag-and-drop further cubes or spectra to the Spectrum Explorer. Tabs created for a new product loaded into the Spectrum Explorer carry the name of that product. Any tabs that open within each product-tab will be created by the toolbox tasks, and these carry the name of their function; remember that the only sub-tab from which spectra can be selected to display is the first, left-most one called "Select spaxels".

[Note] About tasks that create new data

For the spectrum and cube toolbox tasks that create new cubes or spectra and at the same time add them to the Data Selection panel, the focus may pass to the new product. This should be taken into account for additional runs of the same or other tasks, as the new product will be the new input for the task and some of the parameter entries in the task pane may change. See Section 6.6.13 to learn about setting a preference for this focus (to follow the selected tab or to follow the selected spectra).

Tab arrangement: new tabs will appear in the Data Selection and Spectrum panels as tasks are run. The active tabs are "plot" (Spectrum panel)and "Select Spaxels" (Data Selection panel).

Figure 6.9. Tab arrangement: new tabs will appear in the Data Selection and Spectrum panels as tasks are run. The active tabs are "plot" (Spectrum panel)and "Select Spaxels" (Data Selection panel).


6.7.2.1. Input

The Spectrum Toolbox tasks work on one or two spectral products (e.g. cubes), or on selected spectra from the product(s). For almost all tasks, if the input is a cube, the output is also a cube—even if only some of the spectra of that cube have been changed . The Cube Toolbox tasks work on an entire cube—you can select out spectral or spatial ranges but the input is always the entire cube. For both toolboxes, if working from within the Spectrum Explorer, selection of spectral or spatial regions is most easily done within the Spectrum and Data Selection panels. If the task was opened from the Tasks pane of HIPE, then the selection is done by typing the selection list into the parameter box, or creating the selection list by typing in the Console and dragging it over from the Variables to the parameter box in the task's tab.

When using the Spectrum Explorer and the Spectrum Toolbox. 

  • To run on one or more displayed spectra simply click on the spaxels/pixels from the Data Selection panel to see their spectra in the Spectrum panel, and at the same time this will select them as input for the task. See Section 6.6.2 for more information on plotting spectra. The words "Task is applied on displayed spectrum(a)“ will appear in the task panel in the "ds/ds/ds2" parameter box(es), and only these will be input to the task.

  • To run on only a few spectra of those displayed in the plot, "select" one/some of them by clicking on the selection icon on the button bar of the Spectrum Explorer,; and then clicking on the spectrum to be selected (on a datapoint in it) or drawing a box around (one or) several spectra to select those. The selected spectra are highlighted. As you select spectra, the words "Task is applied on selected spectrum(a)“ will appear in the task panel in the "ds/ds/ds2" parameter box(es), and only these will be input to the task. Click on the same spectrum to deselect, and you can select several one after the other.

  • To select a bunch of datapoints from one or several spectra—only the flagging task asks for this—select the icon (from the icon bar or the Context right-click menu) and then draw a box on the plot that encompasses your datapoint(s); the selected datapoints are highlighted. You can remove one selection by drawing another box around it, and you can extend a selection by drawing a box while depressing the Ctrl key (Cmd on a Mac).

    In the right-click Spectrum Explorer menu, under Selection, you can also select all or deselect all spectra displayed.

  • To select a wavelength/frequency range first make sure that a spectrum is displayed in the Spectrum panel (any spectrum from your cube will do) chose the icon (from the icon bar or the Context right-click menu) and then draw your range on the plot by left-click and dragging the mouse from one end of the desired range to the other; the range is indicated with a grey curtain.

    Ranges can be removed by right-clicking on the drawn range and selecting "remove" or "remove all" from the Range menu. It is good practise to clear ranges that were drawn previously to create input to a toolbox task, before drawing any new ranges. Ranges can be resized by clicking near the edge of the marker (a resize symbol will be seen) and dragging the edge of the marker to the desired position. The right-click menu also gives you the option to change the colour of the marker and of the line.

    [Tip] Tip

    When selecting ranges to input into a task, it is a good idea to first clear out all previous ranges, otherwise they may be carried forward to the current or a subsequent task.

  • To run a task on an entire cube is simply a matter of activating the Data Selection panel tab that holds the cube you want to use. If you have selected a spectrum (from that or any tab) you may need to clear it first. See Section 6.6.13 to learn about setting a preference for this focus. To run on a cube not loaded in the Spectrum Explorer, you can drag the cube from the Variables pane and drop it onto the circle next to the "ds/ds1/ds2" parameter box(es) in the task panel (the circle is grey if nothing has been selected/displayed and green if there are spectra shown in the plot or if you have dragged a cube into it). You will now see the words "Task is applied on variable [name]" appear in the parameter box.

[Note] Note

Although it is possible to select spaxels/pixels to plot from two cubes open in the Spectrum Explorer, you must avoid doing this when running toolbox tasks.

When you select spectra via the Spectrum Explorer in this way, you can leave the selection parameter that many tasks have as a parameter empty.

In summary, most tasks will work automatically on the product in the active (top-most) tab, or in the displayed or selected spectra, and the order of preference can be set in the HIPE Preferences (Section 6.6.13).

When using the Spectrum Explorer and the Cube Toolbox. 

  • To select a wavelength/frequency range is the same as working with the Spectrum Toolbox (see above).

  • To set the cube to work on: it is good practise to first bring to the front, in the Data Selection panel, the tab with the cube you want to run the Cube Toolbox on, and then open the toolbox. To run on a new cube that is open in the Spectrum Explorer, close the Cube Toolbox, bring that new cube to the front, and open the Cube Toolbox again.

  • To select spatial regions from that cube is a function that is provided by the tasks themselves and so is explained later: but FYI the approach is to select a shaped region from a cube image that appears in a new tab of the Data Selection panel.

When calling Spectrum Toolbox tasks from the Tasks pane. You are therefore working in the tasks' own GUI, which will open in the Editor pane. The input cube can be dragged and dropped from the Variables pane into the grey circle next to "ds/ds1/ds2" in the task GUI, upon which the grey circle turns green. Replacing the input with another is done with the same action. To select spaxels/pixels from within the cube to run the task on, you need to input a jython list of coordinates:

  • First identify the cube coordinates you want, e.g. by hovering the mouse over the cube selection image in the Spectrum Explorer or in the Standard Cube Viewer [right-click on the cube in the Variables pane to select this viewer]; the coordinates that the viewers show at the bottom left of the cube image are (row, column). For more information, see Section 6.3.

  • Define a selection as a list: let's say you want (row, column) (1,2), (2,2), (4,5) then your selection variable is created by typing, in the Console:

    sel=[(1,2),(2,2),(4,5)]

    Example 6.11. Creating a selection array with spaxel coordinates.


  • Some tasks allow you to type this list directly in the parameter box, for others you need to create the variable on the command line of the Console and then drag and drop it from Variables pane to the parameter box of the task. When running from the command line, you can usually define the parameter "selection" as: selection=sel or selection=[(1,2),(2,2),(4,5)]. If you want to work on the entire cube, you leave this parameter blank.

  • If the task requires spectral index selection coordinates, rather than spaxel coordinates (see Section 6.3 to learn more about coordinates), you can identify the index values for the spaxels using the Data tree of the Spectrum Explorer: Section 6.6.18. In this case the list will look like this:

    sel=[24,25,26]

    Example 6.12. Creating a spectrum selection array.


  • Spectral ranges can be input also as a jython list, and usually the values in the list are in the wavescale of the data.

When calling Cube Toolbox tasks from the Tasks pane. To select spectral and spatial ranges to run on:

  • Spatial ranges are defined as row and column indices given as single numbers typed into the parameter box.

  • Spectral ranges are defined as a listing of spectral indices or wavescale values. You simply type the numbers into the parameter box: 1 2 3 (not 1,2,3, or [1,2,3]).

A comment about some of the selection parameters that many Spectrum Toolbox tasks have. The spectra contained in a SpectrumDataset can contain a number of so-called Spectral Segments (see the Scripting Guide for more information). For example, each subband in HIFI (non-cube) spectra is a Spectral Segment—with each segment identified in the Data Selection panel of the Spectrum Explorer by a different box. For such products you can often choose which Spectral Segments to work on using the "segments" field in the panel of the Spectrum task you are running. You can also select on so-called attributes, which for HIFI could be the things such as the observation start time of that data frame or the position of the chopper. However, you should note that (i) for Level >=2 cubes each spaxel/pixel contains only one segment, and (ii) each spaxel/pixel has the same attributes so you cannot differentiate between them. Hence, when working on these cubes, you can ignore the parameters segments, selection_lookup and attributes.

[Warning] Warning

The Spectrum Explorer will allow you to load more than one SpectrumContainer into it (e.g. two cubes). You could find yourself plotting spectra from different cubes and then trying to run a Spectrum Toolbox task on them. For most tasks this will fail, as they work with selections from a single cube only.

You will realise you are doing this if you see the "ds" parameter in the Toolbox displaying a small red cross. To correct this, clear the plotted spectra from the cube you are not interested in, or instead select only those you are interested in.

6.7.2.2. Output

All tasks send their output to the Variables pane of HIPE. From there you can select any viewer (including another instance of the Spectrum Explorer) to see them.

Many tasks will echo their commands to the Console of HIPE (this offers a quick and dirty way to see how to call a task from the command line).

Tasks that make selections or focus on parts of the input spectra following the user's request—a wavelength to take for the zero velocity, spaxel coordinates, etc—will add Meta data to the output, so you can know what the value of the selection/focus that created that output was.

  • For the Cube Toolbox:

    • Some of the tasks send the products created to new tabs in the Spectrum panel, but these are displays only—you cannot perform any selections from them.

    • When you run a Cube Toolbox task twice, it will "overwrite" the previous output tabs—this is to avoid cluttering up your space with tabs. But the products are still in Variables and so can be loaded into the Editor pane to be viewed from there.

  • For the Spectrum Toolbox:

    • Some tasks send created cubes to the Data Selection panel as new tabs and these are active displays—you can perform spatial selections from them.

    • Some tasks send newly created spectra to the Spectrum panel "Plot" tab.

    • Some tasks will send tabular output to the Data Selection panel as active displays.

You can delete any tab—the variable they "belong" to will not also be deleted. To remove them you simply click on the "x" on the tab. Removing the product from the Variables pane will also not remove the tab.

6.7.3. Spectrum extraction and cube cropping

There are four tasks to extract spectra from cubes or to crop a cube spatially or spectrally. Two—select and extract—are in the Spectrum Toolbox and the others—extractRegionSpectrum and cropCube—are found in the Cube Toolbox. Briefly, the differences between these are:

  • select can be used to extract any spaxels from a cube, and these are then placed in a Spectrum2d, which is a row-stacked spectral product rather than a 3d cube.

  • extract can do the same as select and it can also be used to crop a cube spectrally, in which case the output product is a cube.

  • extractRegionSpectrum can be used to extract out a single spaxel from a cube and place it in a SimpleSpectrum (i.e. a single spectrum product); it will also produce an averaged or summed spectrum from a spatial region.

  • cropCube can be used to crop a cube spectrally and/or spatially, and the output is a cube.

There is additionally one PACS-specific task that is offered in the Spectrum Explorer running in a PACS-version of HIPE, to extract out a single spectrum from a cube and turn it into a SimpleSpectrum: ConvertPacsProduct2SimpleSpectrum. This will only work on a cube of class PacsRebinnedCube. The spaxel coordinates must be specified in the task pane, and the slice number can always be left on 0 when used in the Spectrum Explorer. See the PACS URM entry for this task to learn more about using it on the command line.

6.7.3.1. select and extract: spatially and spectrally extract from a cube

From the Spectrum Toolbox you can find the "select" and "extract" tasks (see Section 6.7.1 for instructions on opening the Spectrum Toolbox). You can also select these tasks directly from the Tasks panel.

Note that for these tasks the "selection" is on spectral index number (0,1,2,3...: more specifically, it is the PointSpectrum number) rather than cube coordinates ([0,0], [0,1],...) so you will need to read Section 6.3 to know how to translate between the two if you run them on the command line or via the GUI.

  • select is to choose random spaxels/pixels to take out of the cube and put into a new, Spectrum2d product. Do not confuse this with "selecting" spectra to use immediately as input to another task.

    To identify the spectra that the task should select out, you need to plot them: see Section 6.7.2. Press Accept and the task is executed and a new product, by default called "result", will be created and added to the Variables pane, and a new tab containing this product will appear in the Data Selection panel if you are working via the Spectrum Explorer. In Section 6.7.2 you will also find information about the parameters "selection", "segments" and "selection_lookup".

  • extract will select out spectra and input them into a new product. You can specify a spectral and or and spatial range to extract. If you set a list of spectra to extract the output is a Spectrum2d, if you define only a spectral range the output is a SpectralSimpleCube, and if you define both the output is a Spectrum2d.

    To identify the spectra that the task should run on, see Section 6.7.2. Identify the wavelength/frequency range to extract over using the "select ranges" icon in the button bar (also explained in Section 6.7.2), or you can write the range value into the boxes in the GUI, pressing the Return key to add extra ranges. After selecting the input cube/spectra, press Accept and the task is executed and a new product, by default called result, will be created and added to the Variables pane.

    You can select more than one range to extract, and they do not have to be continuous. (You can open the output product in the Spectrum Explorer and inspect it by selecting from its row-listing in the Data Selection panel).

[Tip] Tip

For both tasks, if you are running this task from the Spectrum Explorer then you have no choice over the order the spectra are selected from the cube and placed into the output product: it is in index numerical order. If you want any other order you should run the task via its own GUI or on the command line: create a selection PyList (see Section 6.7.2). Once the selection array has been created, drag and drop it from the Variables pane into the "selection" grey circle of the task panel.

6.7.3.2. Extracting out a single spectrum with the Cube Toolbox and changing the units

To extract out a single spectrum using the Cube Toolbox use the extractRegionSpectrum task. This task also allows you to extract out an average or sum of a region but that will be explained in Section 6.7.5.2.

See Section 6.7.1 for instructions on opening the Cube Toolbox, and from there select "extractRegionSpectrum". Then do the following, in this order

  1. First, select the "SINGLE_PIXEL" from the "regionType" parameter box.

  2. Then, go to the Data Selection panel to the sub-tab "extractRegionSpectrum" there. Select the icon, and then click on the single spaxel/pixel that you want to extract out. Note that the spectrum will not appear in the Spectrum panel when you do this. The coordinates are sent to the appropriate parameter box.

  3. From the "arithmetics" menu you then chose to average or sum (these are clearly the same for a single spaxel/pixel), the units of the output will be [flux]/pixel (i.e. flux in an area of a single spaxel of that cube).

  4. If choosing the average option, you then also have the choice of selecting the doAreaConversion option. The flux is converted by the area of the region selected (in this case, one spaxel), and will be in units of [flux]/Sr, converted by:

    1. getting the area of the spaxel in square arcsec from the WCS

    2. dividing the flux by this area

    3. converting from e.g. Jy/sq_arcsec to e.g. Jy/Sr by multiplying with (3600*180/π)2 (conversion factor arcsec2/steradian).. This conversion assumes that the input units are [flux]/pixel (type "print cube.getFluxUnit()" on the command line to check)—this is the case for most Herschel cubes. Your fluxes will be weirdly converted if they are already in units of flux per area instead, e.g. Jy/beam: the "/beam" part is not converted, so your final unit ought to be e.g. Jy/beam/Sr, and will be correctly calculated for such a unit, but the unit as reported in HIPE will just be Jy/Sr.

Upon pressing Accept a SimpleSpectrum product is created and added to Variables. A display plot of that spectrum will appear in the Plot tab of the Spectrum panel.

6.7.3.3. Cropping a cube spectrally and spatially with the Cube Toolbox

To crop a rectangular region and/or to crop a spectral region of a cube, you can use the Cube Toolbox. See Section 6.7.1 for instructions on opening the Cube Toolbox. The task you want is cropCube.

  1. When you select this task a new sub-tab will appear in the cube’s tab in the Data Selection panel, from where you can select the spatial range you want to crop over: select the rectangular region icon , click on the cube image, and then click on the rectangle that will have appeared there to move and resize it. The parameter boxes col|row|Min|Max will be filled with the limits you have chosen (given in spaxel coordinates rather than image coordinates: see Section 6.3).

  2. If this is all that you want to do, now press Accept.

  3. If you wish to also, or instead only, define a wavelength/frequency range, the ranges must be entered as the parameters startWave|endWave—you can enter the values in the parameter boxes manually or define the range using the "select range" Spectrum Explorer icon from the button bar: (see Section 6.7.2). You can only select one wavelength range (the first you define), and it is good practise to clear out any existing ranges first (right-click to access RangeRemove). When running this task from the command line, you can define the spectral region to extract either in wavelength/frequency space or as array index (see the URM to learn more).

  4. Press Accept, and a new cube will be created and added to the Variables.

Upon execution, an image of the new cube is added to the Spectrum panel of the Spectrum Explorer and an image of the cube appears in the Spectrum panel (this is just an image; to explore the new cube you need to open it with the Spectrum Explorer).

You can run the task twice in a row and define a new spatial region by moving and resizing the region box in the cube image of the Data Selection panel. To run a second time with a new spectral region, remove the existing region first.

You can also run this task via the Tasks menu. The GUI looks the same, the only difference here is that the spectral ranges have to be entered manually.

[Warning] Warning

For PACS users of PacsRebinnedCubes: the cropCube task will not work. Instead:

  • to crop spectrally you can use the PACS task pacsExtractSpectralRange (see the PACS URM to learn how to run this task), or the extract task explained above—which will create a SpectrumSimpleCube as output but thereby losing some of the datasets of the cube; these are not important unless you wish to continue working with this cube in the PACS pipeline.

  • to crop spatially is more difficult; you can use the "extract" or "select" tasks to push spaxels into a Spectrum2d.

6.7.4. Spectrum arithmetics

Add, subtract, multiply, divide a scalar value to/from a cube or spectra to/from a cube, or perform pair-wise operations on spectra in two cubes.

The tasks are in the Spectrum Toolbox (see Section 6.7.1 for instructions on opening the Spectrum Toolbox). You can also run them directly from the Tasks panel. To know how to select the spectra that the tasks should run on, see Section 6.7.2, and there is also information about the parameters "segments", "selection" and "selection_lookup".

The scalar value to add, subtract etc. is entered in the param field if the "mode" is Scalar. If the "mode" is Pair-wise then you will input the two spectrum products (e.g. two cubes) as "ds1" and "ds2", using the standard drag-ang-drop motion (from the Variables to the circle next to the parameter box in the task panel).

The following operations are possible:

  • Scalar, one entire cube: To work on an entire cube, chose the Scalar mode and enter the scalar into the param field, and press Accept. (See below for information on "overwrite".)

  • Scalar, one cube, some spaxels only: To work on only certain spectra in the cube, see Section 6.7.2 to learn how to select the desired spectra from the cube, either via the Spectrum Explorer or via typed commands. Then enter the scalar value in param field, and press Accept.

  • Pair-wise, two entire cubes: the two cubes should be of the same length along all three dimensions. The spaxels/pixels are combined in a pair-wise order. (See below for information on "overwrite".)

  • Pair-wise, parts of two cubes: this cannot be done directly from the task, i.e. you cannot specify a selection to be taken from two cubes. To do this you first need to use extract or select from the cubes (as described above) to create new Spectrum2d products containing the (same number of) spectra to be added in a pair-wise manner.

[Warning] Warning

For all operations you have to select the "overwrite" button: the tasks will not work on cubes otherwise. Because "overwrite" will overwrite the input cube, you can make a deep copy of it before running the task:

cube_cp=cube.copy()

Example 6.13. Creating a deep copy of a cube.


After pressing Accept the task is executed and a new cube that is effectively a copy of the input cube, ds1, but with the selected spaxel-spectra adjusted. By default it is called result (you can change the name in the panel), and is added to the Variables pane.

6.7.5. Spectrum averaging/summing and statistics

These tasks are in the Spectrum and/or Cube Toolbox (see Section 6.7.1 for instructions on opening the Toolboxes). You can also run them directly from the Tasks panel. To know how to select the spectra that the tasks should run on, see Section 6.7.2, where there is also information about the parameters "segments", "selection" and "selection_lookup".

The averaging tasks will average together spectra, rather than average all the data in a single spectrum.

  • The Spectrum Toolbox averaging is nice to use if you want to average a set of contiguous or randomly-selected spaxels. If you know their coordinates, you can average either via the Tasks pane or the Spectrum Explorer, but if you do not know the coordinates and want to select the spectra from a cube image, you should use the Spectrum Explorer.

    If you want to average together two entire cubes, you need to use the Spectrum Toolbox.

  • The Cube Toolbox is easier to use if you want to average over a shaped area.

6.7.5.1. Averaging and statistics via the Spectrum Toolbox tasks

  • avg: Averages together a selection of spectra to create a Spectrum1d.

    Quick explanation: select the spectra to average (see Section 6.7.2) and press Accept, whereupon the "result" will be created.

    Longer additional explanation: In Section 6.7.2 you will also find the information for parameters "Selection lookup" and "Segments". If you want to average all the spaxels/pixels in an entire cube, don't "select" but simply drag-and-drop the cube name from the Variables pane to the "ds" parameter.

    See the URM entry for the task to learn more about the different ways to do averaging: considering flags, and/or weights, and/or to average also the wavelength grids. The choice is set with the "variant" parameter. If you set the flag variant then flagged data can be ignored—you define the flag value to be ignored is the parameter "flagToIgnore". Datapoint weights can be considered in the averaging. If your cube has errors instead of weights, these are used instead. See Section 6.4 for information about flags, weights and errors.

    If you have NaN values in your cube then you should select the filterNaNSpectra checkbox, otherwise the NaNs will dominate the results (one NaN in a list of datapoints being averaged results in a NaN).

    The parameters "grouping" and "per group" are not useful for cubes, as there is nothing in Herschel cubes on which one can group; this is more useful for non-cube spectral data.

  • pairAvg: Pair-average two input spectrum containers, e.g. two cubes or a cube and a single spectrum. Pair-wise averaging means that the first spectrum in the first and second container are averaged, and so on. In case the size of the two containers is different, the result will contain a number of point spectra equal to the lowest size.

    [Note] Note

    The choosing of the "first" and "second" spectra to combine is based on their spectrum index, not their cube coordinates: so 0,1,2,3... rather than (0,0), (0,1) etc., although this is only important to know about if your input cubes are of different spatial sizes. To learn how to convert between the two coordinate systems, see Section 6.3.

    For cubes this task will only pair-average two entire cubes. Input the two cubes as "ds1" and "ds2" via a drag-and-drop from the Variables pane to the circle next to these parameters in the task's GUI, and press Accept. The output called "result" is created. To pair-wise average parts of cubes, you will first need to use the extract or select tasks (described above) to select the (same number of) spectra out into two new Spectrum2d, and then pair-wise average those.

    See the URM entry for the task to learn more about the different ways to do averaging, which consider flags, and/or weights (or errors), and/or to average also the wavelength grids. The choice is set with the "variant". See Section 6.4 for information about flags, weights and errors in general.

    Note that the input data should have the same frequency/wavelength grid, but this is not checked for. You can resample them to be the same using the resample task (see Section 6.7.6).

  • accumulate: Accumulates (averages) spectra to a common wave-scale grid and returns a Spectrum1d with a single segment (i.e. it is a single spectrum). In contrast to the average task it checks whether the spectra align at the wave-scale (within a given tolerance specified by the wavescaleTolerance parameter) and automatically does a resampling if not. Furthermore, the length of the spectra need not be the same.

    For this task to work on cubes you need to set the "pointing tolerance" to a high number (so the sky offsets of the spaxels/pixels from each other is effectively ignored). To set the wavelength range(s) to include, use the range selection icon of the Spectrum Explorer ( Section 6.7.2) and the wavelength ranges you chose will be entered in the "range" parameter box. Or you can type the numbers in directly yourself, particularly if running the task via its own GUI or on the command line. You can select spectra to work on using the methods explained in see Section 6.7.2. See the task's URM entry to learn more about the other parameters.

    The advantage of this task over the avg task is that the individual spectra in the input product need not have the same wavescale or length of spectra; however, as the wavescale and length of the spectra is the same for all spectra in a cube, this plays no role here.

  • statistics: Performs statistical operations on the datasets, calculating the mean, rms, median and percentiles (quantiles).

    Quick explanation: To select the spectra that the tasks should run on, see Section 6.7.2. After chosing the cube, and perhaps also a spaxel/pixel selection, your next choice is the mode: perChannel to work across the wavelength/frequency grid, e.g. you want to work out what the rms is for each wavelength point across an entire cube; acrossChannels to work along the spectral grid for each individual spectrum; or both. For the acrossChannels mode you can also select wavelength ranges to include or exclude: using the range selection ( Section 6.7.2), upon which your chosen ranges will appear in the table in the task's GUI, or by typing the numbers directly into the table, and then choosing between "exclude" and "include" from the drop-down menu to the left of the table; this sets the task parameters "exclude" and "range", respectively (you can also set this for the perChannel mode, but it will ignore the request). Press Accept and the result, called stats, will be a set of Spectrum1d for the perChannel mode (these can then be inspected in the Spectrum Explorer) or a TableDataset for the acrossChannels mode.

    Longer additional explanation: In Section 6.7.2 you will also find the information for parameters "selection lookup" and "segments". With the "variant" checkboxes you can ask to include flag, weights (or error), and wavelengths in a special way in the statistical calculations: see the URM entry for the task to learn more. If you set the flag variant then flagged data can be ignored—you define the flag value to be ignored as the parameter "flagToIgnore".

    The two modes of operation available from the drop-down menu:

    • perChannel: this mode operates per channel, i.e. per wavelength/frequency point. Taking the mean as an example, if you had, say, ten spectra in your dataset, this mode would calculate the mean in the first data bin (or channel) from all ten spectra, and then for the second bin, then the third, and so on. In other words, you are looking at all the spectra together, frequency/wavelength point by frequency/wavelength point.

    • acrossChannels: this mode operates across the wavelength/frequency range of each spectrum in the data. In other words, it works on each input spectrum separately, working on all the frequency/wavelength points in each. Taking the same example as above the result would be ten mean values. This mode produces a TableDataset that can be inspected in HIPE with the Dataset Viewer, allowing one to read off the values and from where you can export to a text file (see Chapter 2). When using this mode you can also use sigma clipping, by supplying the clip value and a flag value to be assigned to the clipped data. Data will be clipped when it is above clipvalue*sigma (standard deviation). The parameters to set are "clipvalue" and "clipflag", where the latter is a flag value you want these clipped datapoints to be given.

      With this mode you can also select ranges (e.g. a spectral line) to include or exclude (chose the icon from the Spectrum Explorer button bar and draw the range(s) on the plot: see Section 6.7.3), and choose whether the range is to be included or excluded from the drop-down menu to the left of the parameter table, by clicking on exclude|include ranges. (You can set the ranges if you ask for "perChannel" mode also, but it will be ignored.)

    Finally, the "integrated flux" box allows you to ask for the integrated flux over the spectra and region you have selected to be computed. The wavelength scale must be strictly monotonic.

6.7.5.2. Averaging and summing via the Cube Toolbox and changing the units

You can create a SimpleSpectrum (a single spectrum product) that is the sum or average of a spaxel region using the Cube Toolbox, using the task extractRegionSpectrum. See Section 6.7.1 for instructions on opening this toolbox.

Quick explanation: chose whether you want to sum or average from the "arithmetics" menu; then chose whether you want to work on an entire cube, a single spaxel, or a shaped region ("regionType"), and if you chose for a shaped region or single spaxel, then go to the cube image in the extractRegionSpectrum tab of the Data Selection panel and create (and then edit) the shape/single pixel by first selecting the icon (e.g. ) and then making your choice on the cube image; chose whether you want the units in [flux]/Sr (doAreaConversion clicked) or just [flux] (not clicked). Press Accept.

Longer additional explanation: You must first selection what type of region you want from the task tab, then select the region on the cube. The coordinates will be send to the task tab if you do it in this order.

For elliptical regions the edge spaxels have their flux scaled by the relative area of the part covered by the ellipses' contour to the total area of the spaxel.

You can also extract a single spaxel with this task: see Section 6.7.3.

From the "arithmetics" menu you can chose average or sum. From the doAreaConversion button you can chose to have the area included in the calculation—the flux is converted by the area of the region selected, and will be [unit]/Sr (per steradian) in the output spectrum. This is done as follows:

If choosing the average option, you then also have the choice of selecting the doAreaConversion option. The flux is converted by the area of the region selected (in this case, one spaxel), and will be in units of [flux]/Sr, converted by:

  1. get the area of the spaxel in square arcsec from the WCS

  2. divide the flux by this area

  3. convert from e.g. Jy/sq_arcsec to e.g. Jy/Sr by multiplying with (3600*180/π)2 (conversion factor arcsec2/steradian).. This conversion assumes that the input units are [flux]/pixel (type "print cube.getFluxUnit()" on the command line to check)—this is the case for most Herschel cubes. Your fluxes will be weirdly converted if they are already in units of flux per area instead, e.g. Jy/beam: the "/beam" part is not converted, so your final unit ought to be e.g. Jy/beam/Sr, and will be correctly calculated for such a unit, but the unit as reported in HIPE will just be Jy/Sr.

Upon pressing Accept a SimpleSpectrum product (called "spectrum") is created and added to Variables. A display plot of that spectrum will also appear in a new tab in the Spectrum panel.

6.7.6. Spectrum manipulation: resampling, smoothing, replacing, gridding, stitching, and folding

These tasks are offered by the Spectrum Toolbox: see Section 6.7.1 for instructions on opening this toolbox. To select the spectra that the tasks should run on, see Section 6.7.2. The "overwrite" checkbox that some of these tasks have will replace the input cube with the output cube, the default is to create a new, separate output cube. For all tasks, read their URM entries to learn about the details of what (and how) they do.

  • resample: Resamples flux values of the input cube with respect to a modified wavelength/frequency grid. This task will always change all the spectra in a cube, even if you try to specify spectral selections.

    Various interpolation schemes are offered (set via the "scheme" drop-down menu). The schemes are typically a filter method in combination with an interpolation scheme and an integration scheme to assure flux conservation. The default scheme uses a box filter in combination with trapezoidal integration and linear interpolation. A second scheme consists of using a box filter in combination with Euler integration and nearest neighbour interpolation. A third scheme is based on a Gaussian filter.

    You can supply a wavelength/frequency grid that the data should be resampled to as an array of Double1ds, e.g.:

    grid=Double1d([56.1, 56.2, 56.3, 56.4,...])

    Example 6.14. Creating a wavelength/frequency grid for resampling data.


    which you can either type directly into the "grid" parameter box, or you can create as a variable (on the Console command line) and drag and drop it from Variables to the circle next to the parameter box in the task panel. Alternatively, you can simply supply a fixed width via the "resolution" parameter, where resolution value you supply is actually twice the width that the data is resampled to: if you want to resample data to, say 0.5 km/s (so a 'width' of 0.5 km/s per bin) then you supply a resolution parameter of 1 km/s. The unit of the resolution is either set by the "unit" selection button or takes that of the input cube. Flags and weights/errors, if present, are also resampled.

    If you use a Gaussian filter, you are required to set the "kernel" (this box will appear when you set scheme to "Gaussian"). This is a smoothing filter width (the Gaussian's sigma rather than its FWHM).

    By default the density option is set to True (the box is checked) and this means that the flux data is treated as a flux density (per wavescale unit); if set to false the flux is treated as a per wavescale bin quantity (i.e. the integrated flux per bin).

  • smooth: Smooths the data in the spectral domain via a Box or Gaussian (of user-selected width) filter. This task will always change all the spectra in a cube, even if you try to specify spectral selections.

    The "width" parameterises the kernel functions: if the "unit" is set to "pixels", the width is rounded to the nearest integer and taken as the width of the box (for the Box smoothing) or as the standard deviation (not the FWHM) of the Gaussian kernel function (for Gaussian smoothing). Consult this task's URM entry to learn about the "edge" parameter, which is used to determine how the smoothing works at the edges of the spectra.

    The "variant" parameter sets whether you include weights and flags in the task. If you set the flag variant then flagged data can be ignored—you define the flag value to be ignored as the parameter flagToIgnore. Datapoint weights can be considered, giving you weighted averages for the smoothed values. If your cube has errors instead of weights, these are used instead: see Section 6.4. (See Section 6.4 for information about flags, weights (and errors) in general.)

    If you have NaN values in your cube then you should select the ignoreNaNs checkbox, otherwise the NaNs will dominate the results (one NaN in a list of datapoints gives a result of NaN).

    The smoothing units you can set in the GUI are rather limited; but it is possible to smooth data on any wavescale using the command line and specifying. e.g. unit="km/s" .

  • replace: Replaces the data of the desired wavelength/frequency ranges in one cube with the data of the same wavelegth/frequency ranges in another cube. For example, if the first cube has a range with bad data, that for the second cube is filled with good data, you can replace the good with the bad. The input cubes must be of the same length along the two spatial dimensions, but do not have to be the same length in the spectral dimension. However, the entirety of the second cube is placed into the first cube, so the second cube should extend over the spectral range you want to replace, and no more. (You can use the extract task to extract out a spectral range: Section 6.7.3). See the URM entry to learn about the mathematics of the replacing, which is set via the mode parameter.

  • stitch: Stitches together spectra or spectral segments that overlap. This is mostly used for HIFI data to stitch subbands. It is currently not useful for Herschel cubes since it will not stitch together two cubes, rather it will stick together different segments of the same cube—but Herschel cubes do not have segments. It is therefore useful only for non-cube multi-spectral products.

    The task parameters control the stitching: "variant" is to control how the stitching works (how the overlap regions are handled); "edgeTolerance" controls the task's search for overlapping points; "unit" is used to set the spectral unit that the stepSize and splitPoints are expressed in; "stepSize" is used to define a linear wavescale/frequency step the spectra are resampled to. "splitPoints" is a additional parameter that comes up if you select "splitPoints" for the "variant". Choosing this variant means you are telling the task where, in the overlapping ranges of the spectra, the points are taken to split and then join the spectra. The split points are specified as a Python list (e.g. splitPoints=[1,2,3,4]). Consult the URM entry to learn more.

  • fold: A HIFI-specific tool that folds frequency-switched spectra (it will not work on SPIRE or PACS cubes). The frequency throw is found in the meta data and is picked up automatically by the task. If the parameter "shift" is set to True, the spectrum is shifted in frequency scale by half the throw distance so that the resulting spectrum is centred between the original and the "switched" spectrum.

See below for some command-line example of how to use these tasks with real data.

spireObs = getObservation(obsid = 1342227519, useHsa = True)
spireCube = spireObs.refs["browseProduct"].product.refs["HR_SSW_cube"].product
spireCube2 = spireObs.refs["browseProduct"].product.refs["HR_SLW_cube"].product
# resample
resampledCube = resample(ds = spireCube, density = True, resolution = 1.0)
# smooth
smoothedCube = smooth(ds = spireCube, filter = "box", width = 10)
# replace (requires, as per the documentation, that the two input cubes are of the same size)
# extract from the second cube only the part of the spectra that overlaps
# SSW: from 945 GHz to 1570 GHz
# SLW: from 450 GHz to 1015 GHz
pixnum = spireCube2.wcs.naxis3
extractedCube = extract (ds = spireCube2, minFreq = Double1d(pixnum, 950.0), maxFreq = Double1d(pixnum, 1000.0))
replacedSlices1 = replace(ds = spireCube, by = extractedCube, mode = "replace")

Example 6.15. Using resampling tasks with cubes.


6.7.7. Spectrum flagging

flagPixels: Flags pixels in a spectrum according to a wavelength mask that the user can set. This will flag the pixels in the cube you are working on, no separate output cube is created.

Note: this task does not work on any PACS cubes and may not on SPIRE cubes either. For PACS and SPIRE, flagging during the data reduction is anyway part of their pipelines.

6.7.7.1. Pre-requisites

A pre-requisite for this task to work is that the cube should contain a flag dataset.To check for the presence of a flag dataset you can use the Product viewer on your cube (chosen via a right-click on the cube in the Variables pane), which will show, in its listing, all the datasets in the cube. If you run the task on a cube without the necessary flag dataset, then a standard java error message will be returned. Another prerequisite is that the task should be able to modify the data, and so you cannot open the task on a dataset that is still embedded in an ObservationContext.

[Tip] Tip

If you want to add a flag dataset, you can try the following:

# set up the array (by default filled with 0)
flag = Short3d(len(cube.wave),cube.wcs.naxis2,cube.wcs.naxis1)

# Now set the values in the flag array,  
# and then add the flag dataset to the cube
cube.setFlag(flag)

Example 6.16. Declaring a Short3d array as flags for a cube.


"Set the values in the flag array" can be done: by copying a pre-existing flag dataset, if you have one that has the flag values you exactly want; via your own scripting; or by attaching the default flag dataset and then manually editing the values via the task explained in Section 6.7.7. Note that creating and working with flags while doing your data reduction is something that is only recommended to be done within the PACS and SPIRE Herschel data-reduction pipelines, while for HIFI this task can be used but it will be better explained in the HIFI DRG. And as mentioned above, this task not work on PACS cubes.

6.7.7.2. Running the task

The task lies in the Spectrum Toolbox (see Section 6.7.1 for instructions on opening the Spectrum Toolbox). You can also run it directly from the Tasks panel.

Quick explanation: Display the spectrum/spectra you want to flag data from, and then select the datapoints to flag using the select point(s) item of the Spectrum Explorer: (see Section 6.7.2). The datapoints to flag and the spectra they belong to are selected with the same movement, so it is best to display only the spectra you want to flag datapoints of. You set the flag value/type using a parameter box/listing if using the task's own GUI: which you get depends on which instrument build of HIPE you are using (see below). If running from the Spectrum Explorer you can also select with a right-click on a selected point to select from a "Point Spectrum" menu.

Longer additional explanation: There are some differences in the way you run this task via the Spectrum Explorer or via the task's own GUI:

  • Via the Spectrum Toolbox of the Spectrum Explorer: To define the frequency/wavelength range to flag and at the same time the spectra for the flagging to work on, you can use the select point(s) item of the Spectrum Explorer which can be found in its button bar (: see Section 6.7.2 to learn how to use this selection). That allows you to select either a single point (single click) or a range of points (draw a box), and at the same time all the spectra included in your selection will be included in the running of the task. Hence, it is recommend to run this task with only the spectra you wish to work on displayed in the plot. Several selections can be made.

    Click and/or drag with the left mouse button to select one or more spectral points. This selection then becomes the "mask" parameter. You can use the setFluxToNaN checkbox if you want the flagged datapoints also set to NaN, but this can also be set using the right-click described just next. The "flag" parameter box is provided for you to entre/chose the flag to set for these datapoints.

    You can also chose flag values to set by right-clicking on the selected points to bring up a PointSelection menu which allows various flagging options:

    • flag: you will then be asked what flag value you want these data to have.

    • flag & remove: add a flag to those wavelength points and the data values are set to NaN.

    • deselect.

    • create variable(s): this creates a Selection class product that will be placed in the Variables pane.

    As soon as you select any of the above options, the task is executed. You do not need to press the Accept button. If you do press the Accept button, the task will simply be executed again.

  • Via the task GUI: To define the input cube ("ds") you drag and drop the cube from the Variables pane into the grey circle next to "ds", upon which the grey circle turns green. Replacing the input with another is done with the same action. If you want to not only set a flag for some datapoints but set the flux values to NaN, then check the setFluxToNaN box. In the "flag" parameter box you enter the value you want the flag to have or chose from the offered drop-down menu.

    To set what datapoint you want to be flagged, you need to set the parameter "mask" to the index values of those wavelengths/frequencies. This parameter is also used to define which spectra from the cube you want to have the flag set for. Defining these two is actually rather awkward: see the examples in the URM entry for the task. For example, one way to define "mask" is:

    mask={1:[1,20,667], 2:[30,690]}

    Example 6.17. Creating a mask using list slicing.


    for spectrum array index 1, wavelength/frequency array indices 1,20,667, and spectrum array index 2, wavelength/frequency array indices 30, 690. Working out what these indices are is not easy, and for this reason we recommend you run the task via the Spectrum Explorer.

For either method, if you do not specify a range but you do specify spectra to flag, then the flags will apply to all datapoints of the selected spaxels/pixels.

The values for the flags that you can set is instrument-dependent. In the "flag" box you can type in any number you like. Set your own or use a number that corresponds to flags your instrument has: consult the data reduction or instrument guides for more information.

[Note] Note

For your information (and maybe only for HIFI): flag values are calculated as 2 to the power of (n+1), where n is a bit number. The default value used is 2 to the power of 30. Flag values that are recognised by instrument pipelines or instrument-specific data reduction tools are documented in the instrument Data Reduction Guides. There is no general 'ignore' or 'bad data' flag, although a value of 1 for bad and 0 for good is a common choice, for PACS and SPIRE at least.

6.7.8. Spectrum wave unit conversion

convertWavescale: This Spectrum Toolbox task ransforms the wavescale between frequency, velocity, wavelength and wavenumber. When converting to velocity you must supply a reference frequency and the units of the reference frequency. Note that all spectra in a cube are changed, not only any previously-selected spectra.

Running this task via the Spectrum Explorer or its own GUI is the same: since no spectral selections can be done, there is no difference in how they work. Working from the task panel directly you should drag and drop the cube from the Variables pane into the grey circle next to "ds", upon which the grey circle turns green. Replacing the input with another is done with the same action. Then choose the units you want to convert to and press Accept.

6.7.9. Weight/error and flag propagation

Weights and errors in datasets are set by the instrument pipelines and are propagated by the spectral arithmetics tasks described above. All Herschel cubes contain a weights and flags array, SPIRE cubes may also have errors. General information on these arrays can be found in Section 6.4.

In practice, the spectral arithmetics tasks only propagate weights (w) and use the standard weight-sigma relation to propagate errors, w = σ-2 to work on errors.

Until HIPE 9.0, weight propagation was carried out using a simplistic scheme. In HIPE 9.0 the propagation was done such that errors are also correctly propagated for scalar and pair-wise addition, subtraction, multiplication, division and pair-average. A weight propagation scheme that also correctly propagates errors for the remaining tasks was set in place in HIPE 10.0. The table below shows the weight propagation scheme used in HIPE 9.0 and 10.0 now, and throughout the subscript 1 refers to the first dataset passed to the task and the subscript 2 to the second. The errors are propagated with the same equations, where w=1/e2.

Task Weight propagation scheme Comment Flag/mask propagation scheme
Pair-wise add/subtract w = 1/w1 + 1/w2 If the denominator is zero then a zero weight is returned bitwise OR
Scalar add/subtract unchanged   unchanged
Pair-wise multiply/divide w = (1/u1 + 1/u2) * f -2 where uk = wk * fk 2 and f is flux. If the resulting flux is zero then a zero weight is returned bitwise OR
Scalar multiply/divide w = w / k 2 where k is the scalar unchanged
Pair-average warithmetic mean = 4 * (1/w1 + 1/w2), wweighted = (w1 + w2) If the denominator is zero then a zero weight is returned. The arithmetic mean is calculated with variant="flux", the weighted mean with variant = "flux-weight". bitwise OR
Smooth Same smoothing as chosen for the fluxes   bitwise-OR logic
Resample same scheme as used for the fluxes   bitwise-OR logic

6.7.10. Making 2d flux maps from cubes

Flux mapping is provided by the Cube Toolbox via two tasks. In all cases the mapping is non-, or semi-interactive. Interactive fitting with the SpectrumFitterGUI is an alternative way to make such maps: for instructions see Chapter 7.

  • To make direct integrated flux maps you can use integrateSpectralMap which you select from the drop-down menu of the Cube Toolbox. This task adds up all the flux between 0 and the flux points of your line. Hence, if you wish to integrate the flux of a spectral line only, you should subtract the continuum first. Removal of the continuum can be done with another Cube Toolbox task (see Section 6.7.13).

  • To make flux maps using the velocity mapping task, select computeVelocityMap. This velocity task also produces 2d maps of the line peak flux and the integrated line flux (everything between the line—be it absorption or emission—and 0) either by fitting the line with a Gaussian or by computing the moments. For this task to work properly, you must remove the continuum and should also crop your cube around the spectral line of interest. Removal of the continuum can be done with another Cube Toolbox task (see Section 6.7.13).

The integration approach of the Cube Toolbox is especially useful for spectral profiles that are too complex to fit with analytical functions. To find the Cube Toolbox in the Spectrum Explorer, go to the "Cube Toolbox" icon: . The toolbox will open to the right of the Spectrum panel.

6.7.10.1. Integrated flux maps

integrateSpectralMap will sum up all of the flux values that are associated with each wavelength/frequency point contained within the spectral range you define. No interpolation between data-points is done. If you want a 2d map of emission/absorption line flux only, you should first remove its continuum/baseline (see Section 6.7.13), and then continue with this task on the baseline-subtracted cube.

To run the task from the Cube Toolbox you need to enter the start and end array points of your spectrum that you want to integrate over. Do this by selecting ranges (Section 6.7.2: the icon), for which you first need to have a spectrum plotted in the Spectrum panel (in the "plot" tab); or you can type the numbers into the box (e.g. 88.211 88.549 for startArray and 88.278 88.597 for endArray). It is good practise to remove any pre-existing ranges before defining new ones (right-click to access RangeRemove). You can also set the ranges on the command line:

start=Double1d([88.158,88.428])
end=Double1d([88.269,88.578])

Example 6.18. Creating start and end point array for integration.


and drag and drop "start" and "end" to the small circles (grey when not filled, green when filled) in the integrateSpectralMap panel and next to the "end|startOfRanges" boxes. The values will be in the units of your data (e.g. micrometres for PACS). Several spectral ranges can be input to the task at the same time.

Upon clicking Accept, an image will appear in a new tab in the Spectrum panel. Each layer of this image is a 2d map from a range you selected. Scroll through the images (if you selected more than one range) with a slide-bar at the bottom of the "images (integrateSpectralMap)" tab.

The resulting map or maps are placed into a SimpleCube. To extract the individual SimpleImages you can do one of the following:

  1. Right click from inside the image in the "images (integrateSpectralMap)" tab and select the item "Extract current layer". This "extractedLayer" will then appear in the Variables.

  2. On the command line, working on the output ("IntegratedMap" by default):

    myimage=images.getSimpleImage(layer) # layer is a number

    Example 6.19. Getting a layer from the images dataset of a cube.


    The layer numbers begin from 0, and the images are placed in the SimpleCube in the order they were specified in (note that if you select the ranges via the Spectrum panel, then the order is always organised by wavelength value). This order can also be found by looking at the "LayerInfo" dataset of the "IntegratedMap" output (use the Product viewer on "IntegratedMap" to see this). This gives you a table of index number with the start and end of ranges information following. Or you can type:

    print images["LayerInfo"] # see what columns are there
    print images["LayerInfo"]["LayerIndex"],images["LayerInfo"]["StartOfRange"]

    Example 6.20. Inspecting the contents of the images dataset of a cube.


The units of the data are their flux unit times spectral_unit (e.g. Jy∙μm). See Section 6.7.16 to learn how to convert this to other units.

6.7.10.2. Gaussian line fit, and moments flux maps

You can also make flux maps—line peak and integrated line flux—using the Cube Toolbox task computeVelocityMap. The velocity task uses two algorithms: fitting a Gaussian to the line, and computing the moments. Flux maps come out automatically from this task, along with the velocity maps. The way these work, and how to use the task, is explained in Section 6.7.11.

The units of the data is of the integrated flux map for this task is its flux unit times velocity (e.g. Jy∙km/s). See Section 6.7.16 to learn how to convert this to other units.

6.7.11. Velocity maps

To make velocity maps—radial velocity and dispersion—from spectral cubes you can use a task from the Cube Toolbox. To find the Cube Toolbox in the Spectrum Explorer, go to the "Cube Toolbox" icon: . The toolbox will open to the right of the Spectrum panel. The task you want is called computeVelocityMap. The task will also compute two flux maps: integrated line flux (everything between the line and 0 flux) and peak line flux.

[Note] Note

You can also make velocity and flux maps using the SpectrumFitterGUI, or the command-line SpectrumFitter: this is documented in worked examples of Chapter 7.

The velocity mapping task recommends:

  1. that you have subtracted or divided the continuum, i.e. that it is at 0 (for emission lines) or 1 (for absorption lines),

  2. there is only one spectral line of interest in your cube.

Not doing either of these will give you wrong results. To tune your cube to one spectral region of interest, you can crop it spectrally using the extract task (Section 6.7.3) of the Spectrum Toolbox or the cropCube task of the Cube Toolbox: Section 6.7.3. To learn how to remove the continuum (baseline), see Section 6.7.13, and then continue with this task on the baseline-subtracted cube.

There are two ways to compute these maps: non-interactive Gaussian fitting, or a moments method. You choose one of the two in the "velAlgorithm" parameter of the tab. You must also enter the reference wavelength (the value for zero velocity), and whether the line is emission or absorption (isEmission radio button). Press Accept to execute the task.

  • The Gaussian algorithm will fit a single Gaussian to the brightest peak in your spectrum, using the HIPE fitter functions, for each pixel/spaxel. The names of the output products can be set in the task GUI (in "Outputs").

    Before computing the velocities the spectral grid is converted to velocity using the input reference (wavelength or frequency). The equations used in this task are given in the URM entry. The task will produce the following:

    1. A velocity map: a SimpleImage called velocityMap by default, containing the datasets image (the velocities), chiSquared (the χ2 of the fit), and error (the error returned by the fitter task used to fit the Gaussian).

    2. A dispersion map: a SimpleImage called dispersionMap by default, this being the sigma (not the FWHM) of the Gaussian. This map also has an error dataset (the error returned by the fitter task used to fit the Gaussian).

    3. A SimpleImage of the maximum flux (maxFluxMap) and of the integrated flux (lineIntensityMap), where the integrated flux is calculated from the equation for a Gaussian. These maps also have an error dataset (the error returned by the fitter task used to fit the Gaussian).

    4. A vel[ocity]Cube, which is your input cube but with axes of km/s rather than the input spectral unit.

    5. And a fittedLineCube, which contains the model fit to each spaxel from which the velocities and fluxes were computed. The X-axis here is also km/s, so you can compare the model to the data by opening the Spectrum Explorer on the velCube and the fittedLineCube together (see Section 6.6.5).

  • The moments method. This method calculates the three moments (see the URM entry for the equations): M0 is the integrated flux, M1 is the velocity, M2 is the velocity dispersion (similar to the sigma of the Gaussian fit). This method also returns the maximum flux in the array. The moments are calculated on a spectral region that is hunted for by the task, i.e. for each spaxel/pixel, the task itself identifies where your spectral line lies. This is explained in the URM entry of the task. Before computing the velocities the spectral grid is converted to velocity using the input reference (wavelength or frequency).

    The task will produce the following:

    1. A velocity map: a SimpleImage called velocityMap by default, containing the datasets image (the velocities), error (the propagated error computed with the standard deviation values that are calculated by the moments method: see the URM entry to know what these stddev values are), and windows (the velocity windows that the task computes [see its URM entry to learn about this] and inside of which the spectral line should be located).

    2. A dispersion map: a SimpleImage called dispersionMap by default, this being the sigma (not the FWHM) of the Gaussian. This map also has an error dataset (the propagated error computed with the standard deviation values that are calculated by the moments method: see the URM entry to know what these stddev values are).

    3. A SimpleImage of the maximum flux (maxFluxMap) and of the integrated flux (lineIntensityMap), where the integrated flux is the sum of the flux-data-points in the spectral line. These maps also have an error dataset (the propagated error computed with the standard deviation values that are calculated by the moments method: see the URM entry to know what these stddev values are).

    4. A vel[ocity]Cube, which is your input cube but with axes of km/s rather than the input spectral unit.

    5. No fittedLineCube is produced, instead an emptyCube is produced (and this should be ignored).

Before computing the velocities the spectral grid is converted to velocity using the input reference (wavelength or frequency). Note that the radio astronomy convention is used: moving from frequency to velocity: v = c·(f0 -f)/f0, moving from wavelength to velocity: v = c·(w-w0)/w.

The unit of the integrated flux map is the flux unit [e.g. Jy] times km/s, the velocity maps are in km/s, and the peak flux map is in the flux unit of your data.

The images created by this task will appear in the Spectrum panel as inactive displays (no selections can be done from them), each in its own tab, and the image products will appear in the Variables pane of HIPE, from were they can be double-clicked and displayed with an image viewer. The cubes also appear in the Spectrum panel as inactive displays, and in the Variables pane from where you can open them with the Spectrum Explorer. Remember that you can change the spectral layer the cube image is made from in the Data Selection panel using its slide bar at the bottom. A second running of the same task will overwrite previously-created displays, but the products created will always be found in the Variables pane: each subsequent product created with the same name will have an iterator added (1, 2, 3....) to the name.

6.7.12. Position-velocity maps

The PV map task will create a 2d image: along the horizontal axis is position (offset along a line drawn on a cube) and the vertical axis is velocity, and the flux units are those of your data. You can input the width of the line (in spaxel/pixel size, e.g. 1 is +/-0.5 spaxel width). To run this task select computePVMap from the drop-down menu of the Cube Toolbox. Then draw your slit (your line) on the cube using the line selection icon (see: Section 6.6.2): where you click in the cube image becomes the bottom-left end of the line, and you can resize and move the line from there (to any direction and angle). The starting and ending rows and columns appear in the corresponding parameter boxes of the panel as you move this line about. Then enter the reference wavelength/frequency (where 0 km/s is to be found) and click Accept.

Before computing the velocities the spectral grid is converted to velocity using the input reference (wavelength or frequency). Note that the radio astronomy convention is used: moving from frequency to velocity: v = c·(f0-f)/f0, moving from wavelength to velocity: v = c·(w-w0)/w. For more information on the computation, see the URM entry of the task.

There are two parameters to help deal with the maps created from data with extreme aspect ratios (e.g. when you spectral range is very much longer than your spatial range). If you set to True the "correct aspect ratio" (check the radio button), then the task checks the aspect ratio of the PV map against the minimum value you give as the minAspectRatio parameter (value cannot be greater than 1). This minAspectRatio parameter is the minimum dimension ratio of the map, and is row/column (height/width: position is along the width and velocity along the height). If the aspect ratio exceeds your minimum, it calls the scale task to rescale the map. It sets the values for the parameters "x" and "y" of the scale task (which are column, row) in the following way:

  • x = (row/column)*minAspectRatio when row/column >1.0; and y = 1

  • y = minAspectRatio / (row/column) when row/column <= 1.0; and x = 1

The task produces an image in the Variables pane and in the Spectrum panel. The value and units of the map appear on the bottom-right of the image in the Spectrum panel as you scroll over it.

6.7.13. Removing the continuum from cubes

In the Cube Toolbox there is a task to remove the "baseline", or continuum. This is a necessary prerequisite for creating accurate velocity and flux maps using the Cube Toolbox (as detailed in the previous section).

The output of this task is the subtracted or divided cube, and remember that if you want to continue working on it, you will need to open a new instance of the Spectrum Explorer on the new cube.

This task does an automatic fit to the continuum. To indicate the spectral regions to use in the fitting use the range selection (Section 6.7.2: the icon) on a spectrum from any spaxel/pixel of your cube. These ranges are added to the "end|startOfRanges" boxes as space-separated lists. You can also create the ranges yourself:

start=Double1d([88.158,88.428])
end=Double1d([88.269,88.578])

Example 6.21. Defining some Double1d arrays for range selection.


and drag and drop these variables from the Variables pane to in the Cube Toolbox task panel, next to the "end|startOfRanges" boxes (look for the the small circles, which are grey when not filled, and green when filled). You then input the degree of the polynomial (polyDegree). The parameter divide is to allow you to choose whether to subtract the fitted continuum or to divide by it. Then Accept the fitting and the whole cube is fit with the ranges and order you defined. The fit is then subtracted from or divided into the cube spectra.

"fitInfo" is a product that contains a TableDataset with the information of the fitting to each spaxel. If you click on "fitInfo" in Variables to open it with a Product viewer, and from the viewer click on the "FitInfo" in the "Data" section, you will see this information: for each spaxel row and column coordinate, the parameters of the polynomial are given, as well as the standard deviation and χ2.

Upon pressing Accept two cubes are created: baseCube which contains the polynomial fits, and subCube which contains the continuum-subtracted|divided spectra. To compare one to the other, open either with the Spectrum Explorer and drag and drop the second into the Data Selection panel; you can then select the same spaxels from both to see the overplotted spectra in the Spectrum panel: Section 6.6.5.

Do remember that if using this task before running the velocity mapping tasks, you will need to open the cube in the current or a new Spectrum Explorer instance. The cube you ran removeBaselineFromCube from is not overwritten.

6.7.14. Dealing with baseline issues

To learn how to use the baseline smoothing and fitting tasks, written for HIFI but usable for other instruments, read the section in the previous chapter: Section 5.5. These tasks remove regular signals, sine-waves, from the baselines. However, they do not work on a full cube, rather they work on one spectrum at a time. Hence, the instructions in the previous chapter will work for cubes also.

6.7.15. Exporting to ASCII or FITS

The task exportSpectrumToAscii allows you to write out your cube/spectra to a text file. It is a task that can be found in the Spectrum Toolbox, and it is described in the ASCII chapter of the Data Analysis Guide: Section 2.12.

The task simpleFitsWriter is also offered via the Spectrum Toolbox, and this will save spectral products to FITS files. See Section 1.16 for more detail.

6.7.16. Converting units for Cube Toolbox flux maps

With the Cube Toolbox you can make flux maps via the velocity task and via the integrate flux task. The flux units you get from these are different: the velocity task returns flux unit [eg. Jy] times km/s and the integrated task returns flux unit [eg. Jy] times spectral_unit [e.g. μm]. This is because the tasks sum up under (or over) an emission (absorption) line over the velocity/spectral dimension.

To help you compare the results from the two tasks that return flux maps, and also to convert the units to the more physical W/m2, you can use these equations:

# To convert from Jy∙km/s to Jy∙μm
# (or from K∙km/s to K∙GHz, or any other similar combination)
#
# Let f_jykm be the flux in e.g. Jy∙km/s
# Let f_jymum be the flux in e.g. Jy∙μm
# Let w_mum be the line wavelength in e.g. μm 
# Let c be the speed of light in km/s
c = herschel.share.unit.Constant.SPEED_OF_LIGHT.value
c=c/1000.0
# then:
f_jymum = f_jykm * (w_mum/c)    

# To convert from Jy∙km/s to W/m2
#
# Let f_wm be the flux in W/m2 
f_wm = f_jykm * (w_mum/c) * (2.99e-12/w_mum**2)   

# To convert from Jy∙μm to W/m2
#
# Let f_wm be the flux in W/m2 
f_wm = f_jymum * (2.99e-12/w_mum**2)   

Example 6.22. Converting the units of the flux maps generated by the Cube Toolbox


[Note] Note

Obviously, "Jy" is a unit of flux density rather than flux, but the word "flux" here is shorthand for whatever the signal of your spectrum is recorded in. Similarly, when we say "integrated flux" we mean that the "flux" in the area under the emission line (or over the absorption line) has been summed up.

To apply this to a map (a SimpleImage) edit the following to your specifications:

# To convert the units of a map, a SimpleImage, 
# e.g. from f_jykm to f_wm
c = herschel.share.unit.Constant.SPEED_OF_LIGHT.value
c=c/1000.0
mapdata=map.getImage()
w_mum = 88.3 # the central wavelength of the line 
mapdata = mapdata * (w_mum/c) * (2.99e-12/w_mum**2)   
map.setImage(mapdata)
map.setUnit(herschel.share.unit.Unit.parse("W/m2"))

Example 6.23. Converting the units of a map represented as a SimpleImage.