2 Displaying spectrograms

Spectrograms read from file or memory buffer (see Sec. 1) are automatically displayed by Specview.  See Sec. 1.3.2 for an alternate way of displaying spectrograms in tiled mode.

 

2.1 Main display panel

At startup, the main display panel contains one plot window. A panoramic sub-window can be brought up by clicking on the Pan button at the lower left corner. The panoramic window always displays the full extent of the data range in both X and Y, regardless of zoom / pan settings. The display panel is fully resizable. Beware however that if trying to set it to a too small size, some of the control buttons and widgets may disappear from screen.

Bug: The hard copy feature will only work with a white background  (is this a bug or feature of the Java 2D Graphics API ?).

Bug: Under some circumstances, the display panel may fail to properly refresh itself, resulting in a partially or totally blank plot, or in leftovers from the previous plot still showing up. This happens more often the slower the computer running Specview is. To fix it, click the Redraw button (see below), or do anything that causes a system screen refresh of the window, such as resizing it, covering and uncovering it, iconizing and un-iconizing it, etc.
 

2.2 Controls

The topmost controls in the display window enable the selection among internal data arrays stored in the spectrogram currently being displayed. There are selectors for both the independent and dependent variables.

controls.gif

These selectors are populated with information taken from the spectrogram, thus the specific list of available data arrays is spectrogram dependent.

Bug: when displaying arrays other that the default, and then going back to the default selection, the display units associated with Y axis in the original plot are lost. Use the Units selector (Sec. 2.11) to get back the display to its former state.

The cursor text windows report the cross-hair cursor position in World Coordinate System (WCS) coordinates. There is some formatting capability associated with these windows, accessible from the Cursor menu at the top menu row. These formatting capabilities were put in place during the development phase and are not especially useful. It is recommended that the default mode be used throughout.

The Print button activates the hardcopy engine, described in Sec. 2.15.

The Redraw button causes the plot surface to be redrawn without changing any settings. This should be used to clean the display of leftovers from previous plots, which sometimes show up, especially if running Specview on a slow computer.

The second row contains two sets of controls.

The set of widgets at left is mostly dedicated to WCS view port handling. These are, from left to right:

controls2.gif

  • Grid off/on:  this selector toggles the drawing/erasing of a coordinate grid on the main display window.
  • Auto/fixed WCS:  when the data being displayed changes in any way, the plot is automatically refreshed and the default action is to auto scale the WCS view port to fully encompass the (modified) data. By selecting the "Fixed" choice, all subsequent plot refreshes that result from a data change will take place on a fixed WCS view port.
  • Plot type: sets the linear/log axis mapping.
  • Reset: sets WCS view port to a full view of the data.
  • Reset to central data: sets WCS view port to central view of data. The central 1/3 of the wavelength span of the data is used to normalize the view port. This is useful when the edges of the spectrogram are contaminated by bad data that throw the view port off scale.
  • Back: returns to the previously used WCS view port. Successive application of this function causes a walk back throughout the WCS view port history.
  • Out: zooms out by 20%
  • In: zooms in by 20%.
  • Move left: moves the WCS view port to the left.
  • Move right: moves the WCS view port to the right.
  • Expand in X: expands the WCS view port in the X axis only.

The main zoom and pan functionality is provided by the cross-hair cursor, described in Sec. 2.4. One can also set explicit values for the corners of the WCS view port (Sec. 2.5).

The set of buttons at right is context-dependent. These buttons will appear only if the associated functionality is available for the data currently displayed and for the specific display window. Typically these buttons give access to:

controls3.gif

  • Quality:  Data Quality selector - brings up a data quality selector (Sec. 2.10).
  • Fit:  Fit - initiates a model fitting session (Sec. 6).
  • Units: Display Units selector - brings up a units selector (Sec. 2.11) to select the display units (read more in Sec. 7).
  • Measure: Quick Measure spectrogram features (Sec. 3).
  • Line IDs: Line identification tool (Sec. 10).

Hover the mouse cursor over each button to see a longer description of it.

 

2.3 Multiple display panels

The default operation when reading a spectrogram from external file, standards library, or internal buffer, is to plot it on the main display panel. Spectrograms, once read, are also stored in the memory buffer, and can be displayed from there as well, as explained in Sec. 1.3.

The Display menu also gives the possibility of displaying on a "secondary" display panel, as show below:

memory_buffer_2

The secondary display is exactly the same plotting tool panel used in the main display, but it is placed on a separate, floating frame window that can be repositioned, resized, and operated upon, independently of the existing display windows on screen. Most of the functionality provided by the controls in the main display is also available at the secondary displays.

This feature enables the simultaneous and multiple views of different parts of the same spectrogram, for instance displaying side by side the flux and error array, or displaying the data, model and residuals arrays when fitting models to data, or even displaying the same data with different units in each display panel. The maximum number of secondary display panels is limited only by the memory available to the Java Virtual Machine.

 

2.4 Cross-hair cursor

The cross-hair cursor is the main interactive device in Specview. Its main characteristic is its global  nature. The cursor operates on data (WCS) space and draws itself simultaneously on all display windows that share a common, overlapping, region in WCS space. The cursor includes internal on the fly units conversion, so it is capable of displaying itself on WCS space regardless of which physical units are selected on each window. If two display windows share a common piece of WCS space but are displaying data with different physical units, the cross hair will nevertheless appear on both windows at the correct point.

 

Three sizes are available for the cross hair: big, small, and system. They can be selected with the Preferences->Cursor menu. Also, different line styles are available as well.

 

By default, the big cross hair cursor sports rulings that coincide with the tick marks at the margins of the plot window. These rulings can be switched off by a command line switch (Sec. 8), by a setting in a preferences file (Sec. 9), or by selecting “Plain” under the Preferences->Cursor->Size>-Big menu entry.

 

Bug: Under Mac OS X, the cross hair cursor does not display properly due to bugs in the Java2D XOR graphics mode. It is turned off by default when Specview is run under that OS. The cross hair can be turned on at any time using the Preferences->Cursor menu Size options.

 

 

The plot surface is “alive”:  the plot area in Specview can respond to the cursor presence and/or mouse actions throughout its entire surface. The exact behavior depends on where exactly the cursor is hanging:

 

  • Little hand: whenever the cursor crosses an active region, the cross center becomes a little hand symbol. By clicking or double-clicking the mouse there, a window will pop, giving access to functionality associated with the active region. This happens at the corners of the WCS view port (Sec. 2.5), and over text annotations (Sec. 2.6), including the axis labels and object identification string, if present.
  • Spectral plot: whenever the cursor hangs over a spectral plot and the left mouse button is clicked, an identification associated with that spectrogram is displayed in a balloon. If the right mouse button is clicked instead, a window containing a tabbed pane with properties associated with the spectrogram is displayed. Some of these properties are editable (see Sec. 4).
  • Empty surface: Double-clicking the mouse over an empty plot region will cause a text annotation (Sec. 2.6) to be created at that point
  • Anywhere:
    1. Hiting any alphanumeric key (except the 'v' key) brings up a help window for cursor commands.
    2. The mouse wheel causes the display to zoom around the point pointed by the cursor. Holding the Shift key pressed while turning the wheel causes the zoom to take place only in the X axis.
    3. The keyboard arrow keys move the cursor step by step in each direction.

 

Bug: The arrow keys only work when the focus control is enabled. It is disabled by default under certain combinations of OS and Java version. See Sec. 9 on how to change the default behavior.

 

Zooming / panning:  Often times the most convenient way to zoom is by just spinning the mouse wheel around the point of interest. Hold the Shift key while spinning the wheel in order to zoom in X only.

Simultaneous zoom-in and pan action is achieved by dragging the cursor over the plotting area, drawing a rubber band box and in the process delimiting the region in WCS space one wants to fill the device view port with. This can be done on either the main display window or the panoramic window. In the panoramic window, one can select an entirely different, disjoint region, and thus perform a pan operation.

An example can be seen below:

cursor1
 

Scaling directly to the data:  an alternate way to perform a zoom-in action is to drag the cursor in such a way as to define a very skinny rubber band box. If the box height is less than 20 screen pixels, and its X/Y aspect ratio is larger than 20, an alternate mode is used to define the new zoomed WCS view port. This zoomed view port will have its X extremes defined in the same way as in the standard mode. However, its Y extremes will be defined by the actual data contained in the X range, and not by the rubber band box corners.

This mode is useful when the data spans a very large range in Y, perhaps due to the presence of bad data points, and one wants to quickly zoom in into a region where structure is largely “invisible”, that is, where the data basically displays as a straight horizontal line.

This alternate mode does not work on the panoramic window.

An example can be seen below:

cursor2
 

Cursor commands

Besides simple mouse wheel and dragging actions, the cross-hair cursor supports other functions:

  • Spectrogram identification: By left-clicking the cursor near a particular region of a spectral plot, an identification of that region is displayed in a balloon box. If the spectrogram being displayed is of echelle or multi-segment type, the spectral order number or segment ID is displayed in the balloon box. If the spectrogram being displayed is the result of a combination of spectrograms, the file name of the original spectrogram is displayed in the balloon box.
  • Visualize spectrum internals (header, data) and manipulate it: By right-clicking the cursor near a particular region of a spectral plot, a window containing a tabbed pane with multiple functions is displayed. Functionality provided by each pane is described in Sec. 4.
  • Dragging with the Shift key: By dragging the mouse with the Shift key held down and the cursor positioned near a particular spectral plot segment, an “afterimage” depiction of that segment can be dragged along to any point on screen.  Unfortunately, the cursor text windows cannot be updated while in this drag mode without a significant penalty in speed. The processor engine user interface (Sec. 5.7.1.1) and the template comparison mechanism (Sec. 10.4) make use of this feature.

Cursor quick help

Pressing any keyboard key (except the 'v' key – Sec. 2.13 - and ‘Ctrl’ key) brings up a temporary window with the complete list of keystrokes that are understood by the cursor, including the modifier key sequences. The window goes away as soon as the cursor is moved over the display area.

 

The same help window is available under the Help->Cursor/mouse menu.

 

Bug: The auto popup cursor window only works when the focus control is enabled. It is disabled by default under certain combinations of OS and Java version. See Sec. 9 on how to change the default behavior.

 

2.5 Custom WCS view ports

Moving the mouse pointer near any one of the four corners of the main plot window view port changes the cursor to a little hand.  Clicking the mouse there brings up a dialog box where the X and Y values associated with that corner can be edited. Once the values are typed in, press the OK button to redraw the plot. This feature is most useful when used in conjunction with the Auto/Fix selector (Sec. 2.2).
 

WCS_controls.gif
 

Bug: Under certain combinations of OS and Java version, the dialog may instatly disappear under the Specview window, when the focus control is enabled. See Sec. 9 on how to change focus control.

 

 

2.6 Plot annotation

Double-clicking the cross-hair cursor over an empty region of the view port will cause a widget to pop up. Typing into the text field in the widget and either hitting the Enter/Return key, or clicking on the OK button, will inscribe the text onto the plot surface at the point where the cross-hair cursor was double-clicked. The text string is centered over that point.


annotation


Bug: Sometimes residual crosshair afterimages can be left on screen. They result either from incomplete handling of XOR painting mode by the Java graphics thread, or from loss of synch on the crosshair paint routine due to a partially covered plot surface. The fix usually involves forcing the plot to redraw itself, by say resizing the window or dragging the annotation (see below).

 

The Flip button causes the text to be redrawn in a vertical orientation. Successive uses of the Flip button cause the text to be flipped between horizontal and vertical orientations.

Bug: Vertical annotations are drawn by rotating the “graphics context”. A bug in the Java graphics rotation mechanism randomly prevents the plot axes do be drawn correctly after a vertical annotation is drawn. One or more of the axes (usually the top) may not show up except for the tick marks. The fix usually involves forcing the plot to redraw itself, by say resizing the window or dragging the annotation (see below).

Annotations are by default "pinned down" on the World Coordinate System (WCS) surface. That is, they follow the data when the display is zoomed, panned, resized, or when display physical units are changed. This behavior can be modified by selecting the Screen radio button. This will change the corresponding annotation to be "pinned down" on the screen surface instead. It will not follow any zoom/pan/resize operations, remaining fixed at the same physical distance from the top left corner of the display frame. Annotations can be reverted back to WCS-aware mode by selecting the WCS radio button.

Editing: When moving the cross-hair cursor over an existing annotation, the mouse pointer changes from a cross to a little hand. Clicking the mouse at this point brings back the control widget associated with the particular annotation. This provides a way to modify existing annotations.

Dragging: Whenever the mouse pointer is depicted as a little hand over an existing annotation, dragging the cursor will drag along the annotation. Thus, annotations can be repositioned at will after being created.

The Erase button erases the annotation. The Reset button reverts the typed text to whatever state it was at the time the annotation was first created. Normally this is an empty string, so this provides an alternate way to erase an annotation from the plot surface.
 
 

2.7 Axis labeling

Default axis labels are built by Specview based on the current display units associated with each axis. Changing the display units may cause the axis labels to change accordingly.

Axes labels can be customized however, since they (as well as the target ID at the top left corner of the view port), are also regular annotations (Sec. 2.6). They behave in a slightly different way than user-created annotations though. Axis labels are initialized with non-empty strings, and they cannot be flipped or moved.

Customized axis labels will retain their text strings only for the duration of the current plot. If a plot is replaced by another one, when it is recalled back (either from the memory buffer, Sec. 1.3, or from a display save file, Sec.2.16), the axis labels revert to their default values. This is a side effect of  Specview enforcing consistency of the display with the internal data that generated it. Axis labels and physical units are regarded as an integral part of the display data itself, and the units mechanism has its internal rules for deciding what is the best way to label a particular axis that displays a particular physical quantity. The axis label customization is useful in the case one wants to produce a plot hardcopy with non-standard labels.

 

2.8 Logarithmic scaling

Both linear and log scaling can be selected independently in both axes. The selector is accessible via the same dialog box (Sec.2.5) used to select custom WCS view port values. Bear in mind that, when the Auto/Fix (Sec. 2.2) selector is in Fix mode, changing the mapping type may require an additional click on the Reset (Sec. 2.2) button in order to bring the data into view again.

Log plotting is performed internally by the specific display panel at which it was selected. The internal spectrogram data, as well as other windows displaying the same data, are not affected.

Logarithmic mapping of WCS values to device (relative screen) coordinates can be performed by two types of functions. The default is the standard log10 function. An alternate "extended" log function can be used as well..

The "extended" log function was borrowed from the IRAF Graphics IO library. This extended log function supports both positive and negative arguments, and is defined as:

      10.0 <  x              y = log (x)
     -10.0 <= x <= 10.0      y = x / 10.0
              x < -10.0      y = -log (-x)

This function provides a more or less continuous log representation, defined for all x, reasonable for plotting purposes. However, since it does effectively implement linear scaling for small (in absolute value) values, effective log scaling of values in this range may be achieved only throughout the combined use of the log scaling and physical units selection mechanisms (Sec. 1.7 and 7). The goal is to transform the small values into large ones (in absolute value) using appropriate physical units, enabling them to be expressed in the range where the extended log function exhibits "true" log behavior.

Bug: Currently, a bug prevents the panoramic window to update properly when the scaling mode is selected on the main display window. As a temporary workaround, one can force a proper display by clicking twice on the Hide button or selecting/unselecting the Grid on/off  control.

2.9 Auto Log

When displaying data with a wavelength / frequency / energy scale that encompasses more than one order of magnitude between extremes, Specview will automatically set the X plot axis to logarithmic scaling.

This behavior can be modified by setting Auto log to off mode in the Preferences menu. Both axis are affected simultaneously by this selection.

Alternatively, auto-log mode can also be modified by a command line switch (Sec. 8), or a setting in the preferences file (Sec. 9). The preferences file enables separate, independent settings for X and Y.

 

2.10 Data quality selector

If data quality information is present in the currently displayed spectrogram, the DQ button gives access to a data quality window selector that may look like this:

DQ_selector

The selector lists instrument dependent names of all data quality anomalies present in the currently displayed spectrogram. The user can select, with the help of the Shift and Control keys, subsets of these anomalies. Or by clicking the All button, select all anomalies present. When clicking either the Apply or All buttons, the spectrogram is re-displayed with the data values associated with the selected anomalies removed from the data arrays. The spectrogram itself, not its plot, is affected by this operation, so the setting, once performed, is remembered until the spectrogram is deleted from the memory buffer, or until the end of the application.

If the data set being displayed resulted from a combination of spectrograms taken with different instruments, the data quality selector will show a separate list of the existing anomalies for each of the instruments that contributed to the data set. Thus, one can perform instrument-dependent data quality filtering.
 

2.11 Units selector

If the currently displayed spectrogram supports units conversion, the Units button gives access to a units selector window that may look like this:

units_selector

The selection is independent on each axis. In some cases, only the wavelength selector may be populated, for instance when displaying a net count array expressed in counts/s. If the displayed spectrum is not guaranteed to have the wavelength / frequency / energy / wavenumber scale sorted in either ascending or descending order, some flux density units types may not be available.

The selected units act only on the specific display window they where selected at. The internal spectrogram data are not affected and are always expressed in fixed, "standard" physical units.

 

Read more about physical units in Sec. 7.
  

2.12 Default units

When spectrogram data originally expressed in different units is brought together by either a coplot or a combination operation, the result will be expressed by default in Default Units.  These are by default set to Angstrom and flam (erg/s/cm2/Angstrom) but can be set by the user either interactively, by a command line parameter (Sec. 8), or by preferences file setting (Sec. 9).

 

In interactive mode, just use the Preferences menu to access the units selector to set the default units.

 

Read more about physical units in Sec. 7.

 

2.13 Velocity plots

Plots in velocity space are handled by special velocity units instances. They act as regular units for the X axis and can be transformed back and forth in between themselves and in between all the other supported units types for the X axis. As with the other units types, they affect only the display of spectral data, not the spectral data temselves.

 

Specview comes loaded with a few pre-defined velocity units instances.

 

Placing the cross hair cursor over any given wavelength / frequency / energy / wavenumber on the plot, and hitting the 'v' key on the keyboard, creates a specific velocity units instance for that reference wavelength and redisplays the spectrogram with that new instance. The ‘v’ key can be used as many times as desired, and the spectrogram can be converted back to wavelength / frequency / energy / wavenumber at any time using the units selector described in Sec. 2.11.
 

Bug: The ‘v’ key only works when the focus control is enabled. It is disabled by default under certain combinations of OS and Java version. See Sec. 9 on how to change the default behavior.

 

 

2.14 Smoothing

A Fourier-based low-pass filter is discussed in Sec. 5.
 

2.15 Graphics hardcopy

The Print button (Sec. 2.2) gives access to the standard Java screen print mechanism.  The Print main display entry in the File menu (Sec. 1.1) also gives access to the same mechanism.

Unix/Linux only: due to a bug in the printer support software, the user cannot enter information about page layout in the system; default page layout is currently output by Specview. The main display window is printed in landscape format, using about half the page. By resizing the window on screen, it is possible to exert some control on the final output. The output can be sent to a printer or to a PostScript file.

The printing mechanism is rather slow and runs as a background thread. During the print process the Hardcopy button changes function and can be used to stop the print job by just clicking on it. While printing is in progress, it is wise to avoid resizing the window or redisplaying the data.

Note that hard copy output will only work with a white background color.

Hardcopies of the main plot surface can also be made directly to JPEG format files, using the Print to JPEG file menu item.
 

2.16 Saving plots to file

If a plot is showing up on the main display window, the File Menu will enable saving that plot to a so called display save file. The operation will preserve all customizations made by the user, such as colors, line and symbol types, annotations, axis mappings and view port values, frame size, etc.
 

savedisplay_menu.gif

 

Selecting the Save main display as... option gives access to a system-dependent file chooser window so the file name for this plot can be selected. Display save file names should end with a .dis suffix. If no suffix is provided, or a different suffix is provided, Specview will add / replace the suffix. The file chooser will only list file names in the current working directory that have this suffix.

Once a plot is saved to file, subsequent invocations of the File Menu will have the Save main display option also enabled. Selecting this option will cause the current plot to overwrite the last display save file where a plot was saved.

Only plots in Specview's main window can be saved to file. Plots from model fitting sessions cannot be saved.

 Bug: Co added echelle and ISO spectrograms won’t save correctly to a display file (Sec. 2.16). Reading such files may cause an exception to be thrown.

 

2.17 Reading plots from file

Display save files previously created by Specview can be read using the standard Read from file entry in the File menu (Sec. 1.1) The file selector invoked by that entry also lists files with the .dis name suffix.

A display save file contains a list of the file names that store the spectrograms used to build the plot before it was saved, but does not store the spectrograms themselves. Thus a display save file can be corrupted if the files used to build the plot are moved around or renamed. Specview has no way to know that that happened, and will sometimes generate obscure error messages when presented with a corrupted display save file.

Once a display save file is selected for reading, Specview will proceed to read all spectrograms listed in that file, together with the plot parameters present there. The spectrograms are stored in the internal memory buffer (Sec. 1.3), then combined (co plot mode) into a single composite spectrogram, and displayed using the plot parameters retrieved from the display save file.

If spectrograms specified in a display save file are already present in the memory buffer, they will be re-read and the corresponding slot in the buffer will be overwritten. Note that this can lead to potentially confusing situations if the buffer is keeping composite spectrograms made from spectrograms that are overwritten by the display save file entries.
 
 

2.18 Display colors

Default mode:  The default plot colors used throughout Specview are black lines on top of a white background. Other pre-fixed colors are used to plot spectral models (red), grid (green), WCS boxes (blue), data range symbols (blue), etc.

The user can change the default behavior in a number of ways, by selecting either an inverse video mode from the Preferences menu, or custom-designed colors via a preferences file (Sec. 9). Both modes can be selected via menu controls, or from the command line (Sec. 8).

Once a new color scheme is selected, any existing on-screen windows become corrupted (invalid) and the data must be re-plotted again.

Multi-instrument mode: The default behavior changes when co plotting together data generated by different instruments (data coming from different files but from the same instrument are still handled in the default mode. It remains to be seen if this is an acceptable behavior.). In that case, each segment of the spectrogram that corresponds to a separate input file is displayed with a different color.

The colors are drawn from a circular palette and are associated with each file in the order they are stored in the memory buffer (Sec. 1.3).

After the initial plot takes place, the user can change the color associated with any given segment by double-clicking the cursor near that segment's on-screen depiction. A color chooser will be presented to the user in a tabbed pane (Sec. 4.4). Selecting any color will immediately cause a redrawn of the spectrogram with the new selected color.

The user can change this behavior by selecting the appropriate entries in the Preferences menu. The Monochrome plots entry, when selected, disables the entire coloring mechanism associated with multi-instrument spectrograms. The mechanism can be put back in line by selecting the Multicolor plots entry. Once a new color scheme is selected, any existing on-screen windows become invalid and the data must be re-plotted again.

All color customizations set up by the user are erased from memory when, and if, the combined spectrogram is deleted from the internal memory buffer (Sec. 1.3), even when its individual spectrogram constituents are still in the buffer. This behavior expresses the fact that display colors are not an intrinsic part of a spectrogram, but just an artifact associated with its visual depiction.
 
Multi-segment mode: If a single file stores an echelle spectrogram, such as a STIS, IUE echelle, or Tubingen Orfeus (TUES) echelle, the plot will be rendered in a single color. ISO multi-segment spectrograms such as LWS are rendered in multi-color mode as described above. These behaviors were mandated by user requirements.

 

2.19 Line and symbol style

Default mode:  Currently Specview uses the following criteria to decide which display style to use by default:

  • If a spectrogram comes from any file but the ASCII table format, it is displayed using a continuous line.
  • If a spectrogram comes from an ASCII table file, it is still displayed using a continuous line if the number of data points is larger than 50.
  • If the spectrogram comes from an ASCII table file and there are less than 50 data points, it is displayed using unconnected square symbols.

These criteria are used as a crude mechanism to support SED (Spectral Energy Distribution) data plotting.

When plotting SED data, error bars (if provided) are automatically included in the plot.

With SED data Specview allows customization of the symbol types and sizes. After the initial plot takes place, the user can change the symbol types, sizes, and the line style of the line that connects the symbols, by right-clicking the cursor near that segment's on-screen depiction. A selector will be presented to the user in a tabbed panel. Selecting any value will immediately cause a redrawn of the SED data with the new selected style

Multi-instrument and multi-segment modes: The default behavior is still the same as above when co plotting together data generated by different instruments. However, in this case, the user can change the line style, and, if applicable, symbol shape and size, of each segment in the plot that corresponds to a separate input file or segment. The selector is present in a tabbed pane invoked by double-clicking the cursor near that segment's on-screen depiction.

See more about styles in Sec. 4.5.