5.3. How to display spectra

Spectra are viewed in HIPE with the Spectrum Explorer.

To view a spectrum in Spectrum Explorer, right-click on the variable name of your spectrum (in the Variables pane or in the context holding your spectra) and choose Spectrum Explorer from the "Open With" menu option.

By clicking once on a variable in an Observation Context tree you will find that the spectra contained within it may be viewed in a small Spectrum Explorer window that appears next to the Observation Context tree. This can be a convenient way to quickly inspect many spectra. However, not all aspects of the Spectrum Explorer work in this view. You may click on the arrow to the top right of the plot to make Spectrum Explorer 'take over' the entire Editor Pane, which will give you full functionality in Spectrum Explorer, or you may open the variable as described above.

If you have a spectrum stored as a variable in HIPE, say MySpectrum, you can also display it in the Spectrum Explorer from the command line with:

myPlot = openSE(MySpectrum)

Example 5.1. Opening the Spectrum Explorer from a script.

The Spectrum Explorer opens in a new tab inside the Editor view. Note that the tab title is always plot, irrespective of the spectrum variable name.

The Spectrum Explorer is divided into three panels, see Figure 5.1:

You can resize these panels by dragging the divider bar and you can maximise any of the panels by clicking the small black arrows on the divider bars.

The Spectrum Explorer for a single spectrum.

Figure 5.1. The Spectrum Explorer for a single spectrum.

The type of tab that opens depends on the product, but in all tabs you can perform the same actions. (Single-segment Spectrum1d will open in a Data Tree.)

5.3.1. Showing and Hiding spectra

The spectra displayed in the Spectrum Panel are added and removed via the Data Selection Panel:

  • If your dataset contains only one spectrum it will be plotted immediately upon opening the dataset in the Spectrum Explorer. If your dataset contains multiple spectra (multiple rows in the Data Selection Panel) then no spectra will be shown initially when you open Spectrum Explorer using the "Open With" option. You can force Spectrum Explorer to plot all spectra in a dataset upon opening from the command line:

    plot = openSE(MySpectrum, display = 1)

    Example 5.2. Opening the Spectrum Explorer forcing all spectra to be plotted

  • Spectra are displayed by clicking in the squares in the Data Selection Panel. Click on the square again to remove the spectrum from the plot.

  • You can plot all the spectra in your dataset by clicking on the All button at the top left of the Data Selection Panel. Click on it to remove them all again.

  • You can plot all of the spectra in one row by clicking on the index number (first column) of that row and you can plot all the spectra in a column by clicking on the column number. Clicking again will remove these spectra from the display.

  • Data is plotted with a distinct colour for each spectrum, with the colour of the plotted spectrum matching that in its associated square in the Data Selection Panel. The colours cycle through blue, cyan, green, orange, red, magenta and grey.

You can remove all spectra from the plot by choosing the remove from plot option of the With Displayed feature at the far right of the button bar (you may need to resize the Spectrum Explorer panel to see it).

You can also remove one spectrum or a group of spectra from plot after selecting them (see Section 5.4.2). To select a spectrum you should enable the selection mode of the Spectrum Explorer by pressing the arrow icon at the left of the button bar then clicking on the spectrum you wish to remove. Select several spectra by clicking on all the spectra you wish to remove while in selection mode. The With Displayed menu will now read With Selected and you can choose the remove from plot option as above to remove the selected spectra.

5.3.2. Overplotting spectra

Spectra from different SpectrumDatasets can be overplotted in the Spectrum Explorer by dragging a new variable into the Spectrum Panel of an already open Spectrum Explorer.

  • If a specific viewer is available for the type of data you drag into the Spectrum Explorer then this will be opened by default, for example the Data Tree is used for HifiTimelineProducts.

  • From the command line you can add all the spectra in a new variable (MyNewSpectrum) to the plot with:


    Example 5.3. Adding a new spectrum to a plot.

The new spectral product will open in a new tab in the Data Selection panel.

Note that displaying large amounts of data at once can take a long time. It is adviseable to be selective about what you choose to plot.

Adding a new variable to the plot adds a new layer to the plot. The new layer's wave and flux units and descriptions are compared with those already plotted. If the two sets of values are compatible (or one set of values is not defined) then the data are all displayed in the same plot. If the values are not compatible (e.g., different units or same units but a different axis label) the the new data is displayed in a new plot (a subplot) in the Spectrum Panel.

5.3.3. Viewing multiple plots

It is possible to view several plots (subplots) in the Spectrum Panel. You can add plots either below or to the right of existing ones.

  • To add a new plot below an existing one, right click beneath the plot and select Add subplot from the menu. An empty subplot will appear below the existing plot.

  • Drag a spectrum from the Variables pane into the new subplot. The spectrum will be displayed and a new tab will be added to the Data Selection panel.

  • Right-click to the right of any plot to add a new subplot to the right hand side.

Right clicking inside a subplot and on subplot axes gives you access to a subplot menu (over the usual menu items found by right clicking on a plot) with the following options:

  • Remove: removes the subplot from the Spectrum Panel. If you remove all of the subplots you can add a new one by right clicking anywhere in the Spectrum Panel and selecting Add subplot.

  • Create plot variable: creates a variable (an instance of SpectrumPlot) representing the plot that can be used in scripting. The first such variable created will be named splot_0. The following example shows how you can add spectra to a variable of this type:

    obs = getObservation(1342249478, useHsa=True)
    slwc3 = obs.level2.getProduct("HR_spectrum_point").getDefault()["SLWC3"]
    sswd4 = obs.level2.getProduct("HR_spectrum_point").getDefault()["SSWD4"]
    # splot_0 can be created from the Spectrum Explorer using the context menu
    splot_0 = SpectrumPlot(slwc3)

    Example 5.4. Usage of SpectrumPlot variables (overplotting spectra).

  • Create plot copy: creates a new PlotXY undocked window displaying just the selected subplot. Note that the new window lacks the Spectrum Explorer toolbar and options.

  • Active: making a subplot active means that any (de-)selections you make in the Data Selection Panel will be reflected in this subplot, even if the data in the tab you are modifying 'belongs' to a different subplot. Clicking on a plot will make it active too.

  • Lock axes: locks the axes of the subplots so that a pan, zoom in or rescale on one will be reflected on the other(s).

  • Unlock axes: unlocks axes.

  • Align axes: used on an axis or subplot, aligns the axes of the other subplots so that all show the same range for that axis. To undo this action, you must use the Auto range option (you can find it in the same right-click menu as the others) in each of the aligned subplots.

The option to (un)lock and align is also available from the Axis menu option upon right-clicking on an axis.

When the Spectrum Panel contains more than two subplots, the axis options Align and Lock allow the user to select one or more subplots where to apply the operation by pressing Ctrl + left-click for multiple selections. While doing multiple plot axes selections, the cursor will appear as a cross shape and the axes selection in the subplots will result in a blue highlight. To complete the operation, left-click on an blank area of the Spectrum Panel.

5.3.4. Zooming and Panning

  • You can zoom in and out using the scroll wheel on your mouse (or with a two-finger gesture on any compatible trackpad or touchpad).

  • This icon in the Spectrum Explorer button bar enables zoom mode, which is the default mode when the Spectrum Explorer is started. When this mode is enabled you can change zoom by drawing a rectangular box using the left mouse button and you can zoom back out to the original scale using Ctrl + left click (Cmd + left click on a Mac) in the plot.

  • You can also zoom back out to the original scale using the Autorange option under the right mouse button. Autorange gives you the option to auto-scale the plot axes ignoring any flagged data (without flags); this can be helpful if there is a very strong artifact in your data.

  • This icon in the Spectrum Explorer button bar enables panning mode. When this mode is enabled you can pan through the spectrum in the plot window by clicking the left mouse button and moving the mouse, you can pan along both axes.

5.3.5. Changing Display Axes

You can modify the displayed axes and add auxiliary axes within Spectrum Explorer by right-clicking on a plot axis and selecting the Axis option from the menu:

  • On the left (or main) y-axis you have the option to hide the main axis (after hiding an axis this option becomes show the main axis), to invert the axis and also to show a grid, which displays grid lines at the values of the main tick points on the y-axis.

  • On the lower (main) and x-axes, you have the same options as on the y-axis and also the possibility to add an auxilliary axis (add aux axis). Under the auxiliary axis option you can choose from wave number, wavelength (in m) and radial velocity (in km/s, RELATIVISTIC convention). The wavelength and radial velocity options offer other units from sub-menus.

    [Note] Note

    Some level products from the HIFI processing are computed on an IF (Intermediate Frequency) scale, which is an intermediate scale proper to the instrument but is not yet representative of the absolute sky frequency scale applying to the data. While the x-axes for these spectra can be displayed with other units, it is scientifically meaningless. Please consult the explanation on HIFI data below for more information.

    Once an auxilliary axis has been added you will also find the options to remove and change the units of an axis. Note that these actions only change the way the axes are displayed and do not change the data at all. To change the data you should use the appropriate unit conversion tools, such as convertWavescale.

    You may also find an instrument specific menu option. This is only enabled for HIFI data at the moment and allows the possibilty to display data in velocity (km/s, RADIO convention), LSB/USB (GHz), or intermediate frequency (MHz). Each of these options has other units available from sub-menus. The LSB/USB option is automatically the opposite to the frequency scale of the plotted data, i.e., LSB scale is offered for USB data.

    Chapter 22 of the HIFI Data Reduction Guide includes a table of velocity conventions.

  • On the right y-axis and the upper x-axis you do not have the option the show or hide the main axis but otherwise have the same options as for the main axis.

You can change the properties of the axes by right-clicking on an axis and selecting Properties... from the menu.

5.3.6. Changing Plot Properties

As of version 13.0 onwards, many of the buttons that affect the layout of the spectrum plot have been moved to a dedicated panel: the layout properties panel. Only the shortcuts on the main toolbar of the Spectrum Explorer have been removed, the functionality is still present and it is easier to use when displayed in its own properties panel.

  • To open the layout properties panel click on the icon of the toolbar .

    The new layout properties panel.

    Figure 5.2. The new layout properties panel.

    You can change the following properties in this panel:

    • Display/hide the plot title using the checkbox Show plot title. This text can be changed at any moment the textbox to the right. The updated text is applied to the plot in real time.

    • Display/hide the plot legend with the checkbox Show plot legend.

    • Access finer configuration options for the plot clicking on the Plot properties... button.

    • The line colour, line style, chart type (determined in the HIPE preferences), and line fill are automatically assigned by default. You can modify these using the lower part of the layout options panel ( Line options ), after deselecting the Use automatic line properties checkbox.

      • Line (layer) colour: Choose between automatic or manual line colour selection. To choose line (or layer) colours, first you have to deselect the checkbox Use automatic line colour. A coloured square button appears to the right. If you click on it, a grid of swatches will appear in a pop-up from which you can select the colour you want. Automatic mode can be enabled again selecting the checkbox as it is by default.

      • Select if the areas above and below the slope (the line between the start and the end values of the spectrum) are to be filled with a light gray colour. To do so, check the box Fill area below the line . More advanced options are available if you use PlotXY to plot your data.

      • Line style: after enabling manual configuration of the line options, you can select SOLID, MARKED (solid line with '+' symbols), DASHED, MARK_DASHED (dashed line with '+' symbols) or NONE in the combo-box to the right. Finer configuration is available (symbol shape, size and colour) using the properties panel, described below.

      • Chart type: select the chart syle from the drop-down menu. Choose between LINECHART (smooth line through the data points), HISTOGRAM, HISTOGRAM_EDGE (histogram with end points drawn to zero).

      You can apply these properties to all the subplots in the Spectrum Panel by selecting assign layer properties from the drop-down menu under With Displayed at the far right of the button bar. Note that you may have to resize the Spectrum Explorer to see this.

      Alternatively, you can apply these properties to a selection of spectra by selecting (see Section 5.4.2) those spectra, whereupon the menu changes to With Selected and then assigning the layer properties.

  • To open the plot properties in the top-right panel of the Spectrum Explorer click on this icon . This dialog allows you to modify almost all the properties of the plot.

    Properties can be applied to three different plot elements: layer (line), axes, and plot. Once the property panel is open you can access the properties for a different element by clicking on it while holding down the Shift key. Each layer (line) has its own properties so you need to do this for each line you wish to modify the properties of.

    You can also open the properties panel using the 'Properties...' option seen in the pop-up menu when right clicking on a plot element. If a particular element in the context contains no changeable properties, the plot properties are displayed.

  • The icon of the button displays/hides a grid in the active sub plot.

To change the default Spectrum Explorer settings, choose Preferences from the Edit HIPE menu and go to the Spectrum Explorer sections. There you can choose the default chart type and also make displaying grids and/or legends a default by checking those boxes.

In addition, there are subcategories for the data types that can be displayed in the Spectrum Explorer, such as SpectralLineList. For each data type, you can specify a custom plot title, subtitle and legend to be applied every time this data stype is displayed in Spectrum Explorer. Metadata fields and attribute fields can be filled in automatically by specifying the fields name between angular brackets, optionally with a printf-style format suffix. For example, <longitude>%.2f in the legend element field displays the value of the longitude attribute for each spectrum in the legend.

5.3.7. Viewing large datasets

The Spectrum Explorer will load all the data before starting to plot it and this can be a slow process for very large datsets - for example, a HIFI Spectral Scan or PACS, SPIRE EGS. It is adviseable to be selective about what you plot in the Spectrum Panel and there are several options available from the Spectrum Explorer button bar to help you to do that.

  • : (de-) activates preview mode. This mode is automatically turned on and causes a preview of any row selected in the Data Selection panel to be shown in the Preview panel in the bottom right of Spectrum Explorer.

    You can use the preview to scan through your data by clicking on one row in the Data Selection panel and using the arrow keys to navigate row-by-row through the remainder. Checking the box in the bottom left of the preview panel will show the data in the main plot.

  • : shows/hides the filter panel. The filter panel allows you to eliminate datasets from the Data Selection table, based on values of attributes (see the section below) in this way you can define a limited sample of data to plot.

  • You can use the selection task to create a subset of your data to view and work with, see Section 5.4.2.

  • : shows/hides the Data Tree panel. The Data Tree allows 'lazy loading', which means that a product is not loaded into HIPE until you click on it to display it. This allows you to start looking at large datasets without having to wait for the entire product to load, as was previously the case. It also means that you do not have to load all of a product even if you are only interested in looking at a few spectra contained in it, which saves memory in HIPE. One consequence of lazy loading is that you will not see any attributes for a spectrum until it is loaded.

    The Data Tree shows the hierarchical structure of all of the data in the Spectrum Explorer GUI in one tab. Data are shown in a collapsable tree structure that allows you plot or hide an entire branch of data in one go. The Data Tree allows you to inspect all of the data in the Spectrum Explorer and to add or remove data from the Spectrum Explorer from one location, rather than having to work with multiple tabs. However, you can open a tab for any product listed in the Data Tree by double clicking on its variable name in the second column.

    A right click anywhere in the Data Tree brings up a pop-up menu with the options to display/hide, select/deselect or expand/collapse one more selected rows (or all rows of none are selected). Right clicking on any cell and selecting the copy cell contents option copies the cell content to the clipboard, which can then be pasted elsewhere in HIPE or in other software.

    Rows are selected by clicking and are coloured yellow, a plot will be previewed in the Preview panel. Spectra selected in the plot (using the selection mode) are coloured pink.

    The columns (from left to right) show:

    • First column: a '+' for collapsed data containing multiple spectra, or a '-' for expanded datasets. Clicking on the symbol will expand or collapse that data tree.

    • Second column: displays the variable name of the data. You can rename the variable by double clicking on the variable name, the renamed variable will be added to HIPE Variables pane. Double clicking on a variable name also causes a red cross to appear next to the variable name, clicking on the red cross allows you to remove the data (and all 'sub-data' beloinging to it) from the Spectrum Explorer.

    • Third column: displays the colour of the line (layer), if displayed. If collapsed data are displayed in the plot the box will be grey coloured. Clicking on this box will display or hide all the spectra in this data set. On mouse-over a displayed spectrum in the plot will be temporarily highlighted.

    • Remaining columns: meta data in the data. As for the Data Selection panel, the columns can be reordered horizontally or sorted according to the meta data value (see Section 5.3.8).

  • : opens a mosaic panel. This does not allow you to select spectra for plotting but rather shows large sets of data in a more efficient way in a new tab in the Spectrum Panel. The raster panel has three modes, which can be selected from the drop-down menu at the top right of the panel:

    • Grid: all of the spectra in the dataset are displayed in order from top to bottom-right as a series of postage stamps. On mouse-over a spectrum is displayed in the preview panel. You can adjust the x and y ranges of the data are viewed over using the slide bars at the top of the panel. This is the default mode the raster panel opens in.

    • Raster: the spectra are displayed according to their position, RA and dec values are given on the left and top axes, respectively. The x and y ranges of the data viewd can be adjusted as for the grid view. Spectra that are from close-by sky positions may be plotted so close together that they overlap but each plot moves to the top on mouse-over and is displayed in the preview pane. You can also zoom in and out on the raster display using the mouse wheel or track pad equivalent.

    • Location: crosses mark the positions of spectra in the dataset, with RA and dec given on the left and top axes. On mouse-over the spectrum of each point is shown in the preview panel and you can zoom in and out on the display using the mouse wheel or track pad equivalent.

    You can reset the display with the reset button at the top right on the panel and return to the original scale after zooming with a right-click.

5.3.8. Filtering and sorting what is viewed

You can refine what data is shown in the Data Selection panel using the filter panel to hide data based on values in the data. The icon in the button bar opens and closes the filter panel. Alternatively, you can right-click on the plot and choose DialogueFilter to open the filter panel.

To apply a filter, click the cell in the attribute column to display a list of available attribute. Click on the = sign to choose a comparison operator. Finally, enter a value in the value column and press Enter. The entries in the Data Selection Panel are filtered according to your criterion, and a new line appears in case you want to define another filter.

Although the numbers reported in the Data Selection Panel are displayed to a few significant figures the actual values, found by hovering your mouse over a cell, are given to many more significant figures: the filter is sensitive to these values rather than the displayed ones. This means that you may find better results by limiting your filtering to between two ranges for a variable than giving a precise value.

Click on the green circle next to a filter to temporarily disable it; the Data Selection Panel will be immediately updated to show the results of the modified filtering. Click the red cross to remove a filter permanently.

Filters on attributes.

Figure 5.3. Filters on attributes.

You can sort data in the Data Selection Panel according to the values of attributes by clicking on the column header, click again to reverse the order. You can also modify which attributes are displayed: a right click on a column header will bring up an alphabetically ordered list of attributes in the data, each one preceded by a check box. Attributes that are checked will be displayed, by default all attributes are displayed. Clicking once in a check box will uncheck it and hide that column, clicking again will bring it back. Clicking in one check box and shift-clicking in another will toggle the states of all the columns in between.

Finally, you can change the order of attribute columns from left to right by directly dragging the columns around in the data selection panel, or you can drag column names up and down in the attribute list described above.

5.3.9. Viewing Flags/masks and plot information

You can visualise more detailed information about the data in your spectrum in Spectrum Explorer using two buttons in the button bar.

  • : shows/hides flagged channels. If your data contains any flags (sometimes equivalently called masks) pressing this button once will cause a coloured block to appear over the spectrum in the region that is flagged. A different colour is used for each flag/mask in the spectrum but the colours are selected at random. Pressing the button again removes the flags from the plot.

  • You can also find information about the plotted data in the lower left corner of the Spectrum Panel. On mouse-over of a plot element (a subplot, an axis or a plot layer/spectrum, the name of the context and location of the mouse cursor is displayed). When the mouse is near a spectrum a bullet the same colour as the spectrum is shown by the variable name, the channel number and any flag information is also displayed.

5.3.10. Viewing SpectralLineLists

SpectralLineLists contain information about spectral lines and can be overlaid on spectra to show the position of spectral lines. At the moment they are only produced in HIPE by the Spectrum Fitter, see Section 7.18.

  • To view a SpectralLineList, open it in HIPE using the appropriate method (they can be saved as pools, FITS files or text files) and drag the SpectralLineList product into an already existing plot. The entries in the SpectralLineList will be displayed as a vertical line on the plot.

  • You can also view the dataset in the SpectralLineList by opening the SpectralLineList with the Product Viewer and then opening the dataset contain in the with the Dataset Viewer product with the Dataset Viewer.

5.3.11. Printing and saving

Printing and saving of the plot (or all the subplots in the Spectrum Explorer) can be done via buttons on the button bar or from the menu that pops up on a right click in the plot.

  • : saves the plot as a PNG, PDF, EPS or JPEG file. A pop-up appears in which you can specify the plot type, file name and file location. The same is reached by selecting Save from the File option upon right-clicking on the plot. Note that if several subplots are displayed they will all be saved together in the same file.

  • : prints the plot (subplots). A pop-up allows you to set up the print job. The same is reached by selecting the Print from the File option upon right-clicking on the plot. Note that all subplots displayed in the Spectrum Panel will be printed.

5.3.12. Plotting from the command line

When making plots for publication or as interim results when running scripts it is more convenient to create plots via the command line. This is done using PlotXY or the command line version of the Spectrum Explorer, splot (a contraction of spectrum plot). The usage of these packages are described in the Chapter 3 in this manual.