1.87. hebCorrection

Full Name: herschel.hifi.pipeline.generic.HebCorrectionTask
Alias: hebCorrection
Type: Java Task - Java Task
Import: from herschel.hifi.pipeline.generic import HebCorrectionTask
Category

HIFI/Pipeline/Interactive Pipeline Steps

Description

Task to correct (remove) Electric Standing Waves in Bands 6 & 7.

The correction is performed on Level 1 spectra (type 'science': on-target spectra by default, and also off-target spectra if input parameter offsource=True).

The user will then have to (re)process the observation from Level 1 onward to create a final product.

The HRS bands are corrected using the fit parameters found for the WBS.

Regions with lines are automatically excluded from the fit, or can be specified using the "exclude_if/exclude_sky" parameters. Automatic disregard of lines is done by (iterative) robust fitting. All channels with a flag not equal to 0 are disregarded in the fitting.

Expert options:

By default the model set for fitting is taken from the Calibration tree. The model set can also be supplied on the command line with the "catalog" parameter. See the HIFI Data Reduction Guide section on Electrical Standing Wave removal for example usage and how to obtain the model file.

It is advised to use the plot parameter to check the performance of the task.

Experts may also set the number of knots in the background spline, the order of that spline, the length of the boxcar filter, the Tukey scale and/or the order of the multiplicative polynomial. See JavaDoc for info.

Example

Example 1: HebCorrectionTask
# Assume that obs is an observation context
# use the automatic exclusion of lines.
hct = hebCorrection
tds = hct( obs=obs, plot=2 )                     # correct for ESW
plotlist = hct.plotList
# double click on plotlist variable and double click on an item to display the plot
# Use exclude keyword
tds = hebCorrection( obs=obs, exclude_if= Double1d([lo1,hi1,lo2,hi2,...]) )
# It's probably more convenient to exclude lines using sky freqs.
# The lines will be excluded when they come into the IF range.
# robust fitting is on by default, even when exclude_if or exclude_sky is used. 
# If you find run-time too long or memory is exhausted, you can turn off robust fitting.
# We recommend using robust fitting, though.
tds = hebCorrection( obs=obs, exclude_sky= Double1d([lo1,hi1,lo2,hi2,...]), robust=False )
# And always rerun the pipeline from level 1
obs = hifiPipeline( obs=obs, fromLevel=1.0 )   # reprocess from level 1
#####################################################################################
# Other options. They can be combined.
# Reprocess the same (fresh) observation again.
# Assume tdsPrev is a TableDataset resulting from a previous hebCorrection processing of the same obs.
tds = hct( obs=obs, redo=tdsPrev )
# Undo the HEB correction. variable tdsPrev is a solution table from a previous run of hebCorrection.
# Output table tds will be a copy of the solutionsin tdsPrev
tds = hct( obs=obs, undo=tdsPrev )
# Reuse exclude, robust and offsource settings from a previous run 
tds = hct( obs=obs, reuse=tdsPrev )
# Correct the off-source positions too
tds = hct( obs=obs, offsource=True )
# Make plots for the HRS corrections too. Use negative plot values.
tds = hct( obs=obs, plot=-1 )
# Use a catalog instead of using the caltree.
# Assume catalog is a Product containing model splines.
# E.g. taken from the HIFI calibration pages.
tds = hct( obs=obs, catalog=catalog )
# The task can be run on individual HTP or HDS too. It <b>always</b> needs a catalog
# as there is no access to the caltree.
tds = hct( htp=htp, catalog=catalog )      # htp is HifiTimelineProduct
tds = hct( wbs=wbs, catalog=catalog )      # wbs is HifiSpectrumsDataset of WBS
# And always rerun the pipeline from level 1
obs = hifiPipeline( obs=obs, fromLevel=1.0)

API details

Properties

ObservationContext obs [INPUT, OPTIONAL, default=null]

To be cleaned if necessary (one of obs, htp or wbs is obligatory)

HifiTimelineProduct htp [INPUT, OPTIONAL, default=null]

to be cleaned if necessary. It needs to be a WBS-HTP and a catalog.

HifiSpectrumDataset wbs [INPUT, OPTIONAL, default=null]

It needs to be WBS and it needs a catalog.

TableDataset fitpars [OUTPUT, OPTIONAL, default=(none)]

The TableDataset contains all fit parameters.

Double1d exclude [INPUT, OPTIONAL, default=(none)]

Deprecated. Use exclude_if in stead (or exclude_sky)

One or more pairs of [low,high] IF frequencies which should be exclude from fitting. E.g. because a line is present in that region.

When exclude is set, robust fitting is turned off.

Double1d exclude_if [INPUT, OPTIONAL, default=(none)]

One or more pairs of [low,high] IF frequencies which should be exclude from fitting. E.g. because a line is present in that region.

When exclude_if is set, robust fitting is turned off.

Double1d exclude_sky [INPUT, OPTIONAL, default=(none)]

One or more pairs of [low,high] sky frequencies which should be exclude from fitting.

Note: Robust fitting is not turned off. Use parameter robust when needed.

Boolean robust [INPUT, OPTIONAL, default=(true)]

Robust fitting is turned on/off. It overrides consequences of the exclude keywords

String band [INPUT, OPTIONAL, default=(from obs)]

Deprecated. Don't use it. It has no effect anymore.

Product catalog [INPUT, OPTIONAL, default=(from calibration context)]

the calfile to be used. It contains a catalog of spline-forms that suffice to model all existing ESW shapes.

Object redo [INPUT, OPTIONAL, default=null]

Use fit parameters derived in a previous run to reprocess the same observation again. The parameters are either taken from a TableDataset (if redo is a TDS) or from the caltree.

Only one of the parameters [redo, reuse, undo] can be given.

Object reuse [INPUT, OPTIONAL, default=null]

Use info (exclude, robust, offsource) from a previous run to process the data. The info is either taken from a TableDataset (if reuse is a TDS) or from the caltree.

The can be replaced by parameter settings.

Only one of the parameters [redo, reuse, undo] can be given.

Object undo [INPUT, OPTIONAL, default=null]

Use fit parameters in the TableDatset to undo the corrections. The parameters are either taken from a TableDataset (if undo is a TDS) or from the caltree.

Undo leaves a mark in MetaData: HebCorrection is set to false.

Only one of the parameters [redo, reuse, undo] can be given.

Boolean offsource [INPUT, OPTIONAL, default=false (only on-source is done)]

When set to true, also the off-source science spectra are corrected.

Integer plot [INPUT, OPTIONAL, default=(no Plotting)]

0 : no plot

1 : plot all PointSources, overplot in one frame

2 : plot all PointSources collected in a Arraylist

3 : plot all PointSources in separate frames

negative values will plot HRS too.

See also

History

  • 2012-03-10 - DK: Initial version