1.66. doStitch

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

HIFI/Pipeline/Interactive Pipeline Steps

Description

Stitch the scans included in a HifiTimelineProduct.

The stitching is performed on a per point spectrum (scan) basis. The result is again a point spectrum that still may consist of several segments - in case gaps are found between consecutive segments. The way how the stitching is done is defined by the parameter 'variant' (see below). The task iterates through the datasets found in the timeline product and delegates the processing to the {@link StitchSpectrum}-task in the spectrum toolbox. The stiched spectra originating from the same dataset are included in a new dataset. Since the shape of these spectra may be different after stitching the spectra need to be resampled. Here, the sampling width can be specified using the stepsize parameter. In case no or a zero stepsize is specified, resampling is avoided if all the stitched point spectra have the same shape.

Example

Example 1: In HIPE:
from herschel.hifi.pipeline.generic import DoStitchTask
stitch = DoStitchTask()
stitched11 = stitch(htp=htp)
# cut at crossover points and concatenate
stitched12 = stitch(htp=htp, variant="crossoverPoints")
# cut at crossover points and concatenate, consider crossover points only by 10 percent off the border 
# to of the overlapping region
stitched13 = stitch(htp=htp, variant="crossoverPoints", edgeTolerance=0.1)
# cut at crossover points and concatenate, resample the resulting spectra to 1MHz channel width
stitched14 = stitch(htp=htp, variant="crossoverPoints", edgeTolerance=0.1, stepsize=1.0, unit="MHz")
# cut at mid points of the overlapping regions and concatenate
stitched21 = stitch(htp=htp, variant="midPoints")
# cut at mid points of the overlapping regions and concatenate,
# resample to 1.0 channel width (in units of the underlying frequency scale)
stitched22 = stitch(htp=htp, variant="midPoints", stepsize=1.0)
# cut at predefined split points and concatenate
stitched31 = stitch(htp=htp, variant="splitPoints", splitPoints = [5000.0, 6000.0, 7000.0])
# cut at predefined split points and concatenate, resample to 1.0 channel width 
# (in units of the underlying frequency scale)
stitched32 = stitch(htp=htp, variant="splitPoints", splitPoints = [5000.0, 6000.0, 7000.0], stepsize=1.0)
# cut at predefined split points and concatenate, resample to 0.001 GHz channel width
stitched33 = stitch(htp=htp, variant="splitPoints", splitPoints = [5.0, 6.0, 7.0], stepsize=0.001, unit="GHz")
# average the parts of the spectra that are overlapping,
# resample to a 1.0 channel width (in units of the underlying frequency scale)
stitched4 = stitch(htp=htp, variant="average", stepsize=1.0)
# average the parts of the spectra that are overlapping,
# resample to a 1.0 MHz channel width, do not consider flags and weights
# when computing teh average (but propagate them)
stitched41 = stitch(htp=htp, variant="average", stepsize=1.0, unit="MHz", avg_variant="flux")
# average the parts of the spectra that are overlapping, avoid resampling as far as possible
stitched42 = stitch(htp=htp, variant="average", avg_variant="flux")
# average the parts of the spectra that are overlapping, avoid resampling as far as possible
stitched5 = stitch(htp=htp, selection_meta = ["science", "hc"])

API details

Properties

HifiTimelineProduct htp [INOUT, MANDATORY, default=no default value.]

The input timeline product with the spectra to be stitched.

String variant [INPUT, OPTIONAL, default="crossoverPoints".]

Specify how to do the stitching. Possible values:

  • "crossoverPoints": In overlapping ranges of the spectra a crossover point is taken to split the spectra. In case no crossover point is found a point is taken where the spectra come closest. In case many crossover points are found the one closest to the midpoint of the overlapping range is taken. The range where the crossover points are searched for is reduced by setting a non-zero edge tolerance (see parameter edgeTolerance below). This option only works if at most two segments 'participate' in the same overlapping range.

  • "midPoint": In the overlapping ranges of the spectra the mid point is taken to split the spectra. Similar to the above, this option only works if at most two segments 'participate' in the same overlapping range.

  • "splitPoints": In the overlapping ranges of the spectra previously specified points are taken to split the spectra (parameter splitPoints). the mid point is taken. Similar to the above, this option only works if at most two segments 'participate' in the same overlapping range.

  • "average": In the overlapping ranges the average of the involved spectra is taken. This option allows to stitch spectra in which more than two spectra contribute to the same overlapping part.

double edgeTolerance [INPUT, OPTIONAL, default=0.01.]

Defines a reduction in the overlap region of segments in which cross over points are searched. With length denoting the length of the original overlapping range [n,m] (in number of pixels) the reduced range is defined by [n+p*length, m-p*length] where p is the edge tolerance.

Object splitPoints [INPUT, OPTIONAL, default=no default value]

Specify the list of split points for where to cut and concatenate the segments. This parameter is used only in combination with the option variant="splitPoints". The split points are specified as a Python list. Note that the number of split points shoudl correspond to the number of overlapping ranges (per point spectrum).

double stepsize [INPUT, OPTIONAL, default=no default value.]

Specify the stepsize used to define a linear frequency grid the spectra are resampled to. The resampling is important in the following situations:

  • When including the stitched point spectra in a common container. In case a stepsize>0 is specified, a frequency grid is constructed with the given step size. The upper and lower bounds are determined from the minimum and maximum frequencies found in all the stitched point spectra (for a give segment index). In case a stepsize=0 is specified, the frequency grid found in the first (stitched) point spectrum is taken as the output grid.

  • When using variant="average" the spectra contributing to common ovrlapping frequency ranges are resampled to a common frequency grid.

When searching for crossover points, one of the spectra also needs to be resampled to a common frequency scale - here, the frequency scale of the other spectrum is used, though so that the stepsize parameter is not needed here.

String unit [INPUT, OPTIONAL, default=no default value.]

The unit the stepsize and/or split points are expressed in. In case no unit is specified the stepsize and/or the split points are assumed to be in the same units as the underlying frequency grid.

String avg_variant [INPUT, OPTIONAL, default=no default value.]

The variant of the average to be used (how to incorporate flags and weights).

Object selection_meta [INPUT, OPTIONAL, default=no default value]

Specify a selection of datasets included in the timeline product by by matching specific meta data values. Basically, there are two possibilities:

  • As a py dictionary with keys specifying the meta data key and values the admissible values. These values are specified as lists.

  • As a list of admissible 'sds_type's (the type appearing in the summary table). Hence this is internally translated into a py dictionary with 'sds_type' set as key. In order to distinguish ON and OFF science datasets, wee (artificially) allow for the values "scienceOn" and "scienceOff".

PipelineConfiguration params [INPUT, OPTIONAL, default=no default value]

Pipeline configuration parameters that can be passed to the task.

Boolean fillGaps [INPUT, OPTIONAL, default=False.]

If set to True the non-overlapping segments remaining after applying the stitch segment operation are combined into a single segment by filling gaps with NaN values (on a per PointSpectrum basis). In the gaps, the wave scale is defined by filling in wave scale steps of size determined by the average of all the steps found in the PointSpectrum. Finally, NaN values are added to the edges of the spectra so that all the PointSpectra (now consisting of a single segment) have the same number of bins. The processing is delegated to {@link StitchSpectrumTask}.

int gapTolerance [INPUT, OPTIONAL, default=2.]

It is an integer specifying the maximum number of missing channels that will be filled in a gap even with fillGaps=False. In the gaps whose length <= gapTolerance, the flux will be linearly interpolated if the number of missing channels is 2 at most, and filled with NaNs otherwise (for gapTolerance > 2).

Boolean ignore [INPUT, OPTIONAL, default=no default value]

If set to True task is not executed.

See also

History

  • 2011-07-11 - melchior: : history added.
  • 2011-08-14 - melchior: : renamed to DoStitchTask.