1.82. flagTool

Full Name:	herschel.hifi.dp.tools.FlagToolTask
Alias:	flagTool
Type:	Jython Task -
Import:	from herschel.hifi.dp.tools import FlagToolTask
Category	HIFI/Spectra/Analysis

Description

FlagTool is a tool for flagging rows and specific channels of HifiSpectrumDatasets.

It currently works for single point observations and spectral surveys. It provides an interactive mode to help the user visualize his/her data in a plot, look through them and flag the regions of interest.

It saves the information about the flags in a mask table in order to reuse them later.

The available flags are:

HifiMask.SPUR_CANDIDATE
HifiMask.LINE
HifiMask.BRIGHT_LINE
HifiMask.IGNORE_DATA
RowMask.SUSPECT_LO
RowMask.IGNORE_DATA

How to use it?

FlagTool provides a graphical interface for flagging the data in the HifiTimelineProduct. This interface is made up of 4 components that allow different actions:

Radio buttons:

Select the wanted channel flag to be used in the plot window

Plot window:

Create masks by dragging with Shift-click.
Disable existing masks by clicking on them.
Use mouse wheel to zoom in and out.

Table:

Plot all the subbands of a given dataset by clicking on the corresponding row of the table
Plot a single subband by right-clicking on the corresponding cell of the table
Toggle the user rowflags by clicking on the corresponding checkbox of the table

Buttons:

Apply FitHifiFringe or FitBaseline
Undo the modifications done on the current dataset
Exit FlagTool

How does it work?

A. With channel flags

Each time a mask is created on the channels:

a flag is set on the selected channels of the SpectrumDataset
the HifiTimelineProduct is updated
a colored marker is created on the selected channels to reflect the flag set (see the section 'Flags and colours')
the mask table ('Linemasks') in the HifiTimelineProduct is updated with the information about the mask

B. With rowflags

Each time a user rowflag is modified:

the rowflag column of the current SpectrumDataset is updated (setting or unsetting the rowflag)
the HifiTimelineProduct is updated

Flags and colours

The available channel flags in flagTool are defined by the HifiMask class. The colors of the masks in flagTool follow the colors of the masks in Spectrum Explorer.

Flag	Value	Color
SPUR_CANDIDATE	2**7	Orange
LINE	2**28	Pink
BRIGHT_LINE	2**29	Blue
IGNORE_DATA	2**30	Green

For more information, see the wiki about channel flags: http://www.sron.rug.nl/docserver/wiki/doku.php?id=docbook:hifi-um:cflags /

Notes

In the current version of FlagTool, a FITS file (backup_[obsid]_[backend].fits) containing the mask table is created in the directory where HIPE was launched.

It is used as a backup because long flagging sessions may crash for some reasons. Losing all the flags you defined for 3 hours is not pleasant so this backup can help recover the masks previously created.

If the mask table contained in the file is reinjected in your original HifiTimelineProduct, FlagTool will read this table and reapply the corresponding flags to the data.

Examples

Example 1: Process WBS-H in level 1

FlagToolTask()(obs, "WBS-H", level="level1")

Example 2: Process WBS-H-USB in level 2

# By default the level is level2 so it's not necessary to precise it in the
# call
FlagToolTask()(obs, "WBS-H-USB")

Example 3: Process WBS-H-USB and use a polynomial of order=3 to fit the baseline

FlagToolTask()(obs, "WBS-H-USB", order=3)

Example 4: Process WBS-H-USB and use 2 sine waves for fitHifiFringe

FlagToolTask()(obs, "WBS-H-USB", nfringes=2)

Example 5: Process WBS-H-USB and and don't display the plot for FitHifiFringe

FlagToolTask()(obs, "WBS-H-USB", fhfPlot=0)

Example 6: Process the rowflags in WBS-H-USB

FlagToolTask()(obs, "WBS-H-USB", category="rowflag")

Example 7: Process both channel flags and rowflags in WBS-H-USB

FlagToolTask()(obs, "WBS-H-USB", category="both")

Example 8: Process WBS-H-USB in off-spectra

# The off-spectra are in obs.getProduct("calibration").getProduct("pipeline-out").getProduct("ReferenceSpectra")
FlagToolTask()(obs, "WBS-H-USB", level="off-spectra")

Example 9: Process directly the htp

FlagToolTask()(htp)

API Summary

Jython Syntax
`FlagToolTask()(obs, backend=backend, level=level, order=order, nfringes=nfringes, fhfPlot=fhfPlot)`
`FlagToolTask()(htp, order=order, nfringes=nfringes, fhfPlot=fhfPlot)`

Properties
`ObservationContext obs [INPUT, OPTIONAL, default=None]`
`HifiTimelineProduct htp [INPUT, OPTIONAL, default=None]`
`String backend [INPUT, OPTIONAL, default='WBS-H-USB']`
`String level [INPUT, OPTIONAL, default=2]`
`Integer order [INPUT, OPTIONAL, default=2]`
`Integer nfringes [INPUT, OPTIONAL, default=1]`
`Integer fhfPlot [INPUT, OPTIONAL, default=2]`

API details

Properties

`ObservationContext obs [INPUT, OPTIONAL, default=None]`
	FlagToolTask takes an ObserationContext as prime input parameter (recommended).

`HifiTimelineProduct htp [INPUT, OPTIONAL, default=None]`
	FlagToolTask can take an HifiTimelineProduct as input parameter.

`String backend [INPUT, OPTIONAL, default='WBS-H-USB']`
	Specify the backend to extract the HifiTimelineProduct to work with.

`String level [INPUT, OPTIONAL, default=2]`
	Specify the level of the data.

`Integer order [INPUT, OPTIONAL, default=2]`
	Specify the polynomial order for the fitting of the baseline in FitBaseline.

`Integer nfringes [INPUT, OPTIONAL, default=1]`
	Specify the number of sine waves for the fitting of the fringes in FitHifiFringe.

`Integer fhfPlot [INPUT, OPTIONAL, default=2]`
	Specify the plot options for FitHifiFringe: fhfPlot=0: no plotting at all fhfPlot=1: one chi^2 plot and one before/after plot for each of N scans (the user ends up with 2*N plot windows on the screen) fhfPlot=2: one chi^2 plot and one before/after plot for a scan a popup box with 2 buttons (Next, Non-stop)

History

DR-16/09/2013: FlagTool accepts htps. (HIFI-5410)
DR-23/01/2013: Handle rowflags and channel flags. (HIFI-5196)
DR-27/01/2012: Documentation updated. Deep refactoring.
DR-27/10/2011: Documentation updated. Command line mode implemented.
DR-16/10/2011: Initial version