1.155. flagPixels

Full Name: herschel.ia.toolbox.spectrum.FlagPixelsTask
Alias: flagPixels
Type: Java Task - Java Task
Import: from herschel.ia.toolbox.spectrum import FlagPixelsTask
Category

Spectra/Analysis

Description

Task for flagging pixels in spectra.

By setting the 'mask' parameter (and possibly restricting the selection of point spectra and segments to consider for flagging) you specify the wavescale bins to be flagged. Optionally, you can specify a flag (by default 2 power 30 is used). Then, the task sets the flags by modifying the input data. Please be aware that when the task is applied to cubes, flags values above 32767 will not be honoured. Also note that a pre-condition for the task to work is that the data structure already contains flag values (also referred to as mask for SPIRE and PACS). To learn more about the meaning and usage of flags/masks for each instrument, please see the HIFI User Manual, the PACS Data Reduction Guide: Spectroscopy or the SPIRE Data Reduction Guide as appropriate.

You have different alternatives to specify a 'mask' with the pixel indices to be flagged. For the following, it is helpful, to understand the data structure defined with SpectrumContainer, PointSpectrum and SpectralSegment. Please see the associated URM entries.

  1. General mask: For each segment within a specific point spectrum specify an entry in a dictionary, with keys given by tuples (i,j) (where i stands for the point spectrum index and j for the segment index) and values specifying the list of pixel to be flagged.

  2. Uniform masks: For all the point spectra (possibly restricted by a suitable selection model - see the 'selection' parameter below) the same mask apply. This is given again by a dictionary where the keys specify the segment index (an integer) and the values specify the list of pixel indices to be flagged. Alternatively, you can directly specify a java.util.Map with Integer keys and herschel.ia.dataset.Selection as values. The values specified as Selection's contain the indices of the pixels to be flagged. Alternatively, instead of a Selection you can also specify an Int1d cointaining the indices or a Bool1d with 'true' at the positions the flag should be set.

  3. Uniform masks, uniform for several segments: Specify a list of pixel indices to be flagged. This mask applies to all the segments and point spectra - possibly restricted by a suitable 'selection' and 'segments' indices.

As input spectra you can specify not only a single spectrum container but also a list of spectrum containers. Alternatively, you can specify a list of tuples with the first argument in the tuple specifying the spectrum container and the second argument the mask with the pixels to be flagged.

Example

Example 1: various ways to flag pixels in spectra
global spectra,  spectra1,  spectra2 # defined elsewhere
# For the following, assume 'spectra' to be a SpectrumContainer with several point spectra containing 
# several segments.
# Set flag 2 in point spectrum 0 / segments 1 at the pixel indices 1,2,667 and 
# in point spectrum 0 / segment 3 at the pixel indices 30,690 - see the 'General mask' (1.) above.
flagPixels(ds=spectra, mask={(0,1):[1,20,667], (0,3):[30,690]}, flag=2) 
# Set flag 2 in segments 1 and 3 at the indices 1,2,667 and 30,690 respectively. 
# The same scheme is applied to all point spectra - see the 'Uniform mask' (2.) above.
flagPixels(ds=spectra, mask={1:[1,20,667], 3:[30,690]}, flag=2) 
# Set flag 2 power 30 in segments 1 and 3 at the indices 1,2,667 and 30,690 respectively. 
# The same scheme is applied to all point spectra - see the 'Uniform mask' (2.) above.
flagPixels(ds=spectra, mask={1:[1,20,667], 3:[30,690]})
# Set flag 2 in segments 1 and 3 at the indices 1,2,667 and 30,690 respectively.
# In contrast to the example above, here restricting to the point spectra with indices [0]
# (again a 'Uniform mask' (2.) combined with the selection parameter). 
# For further ways of how to specify selections see e.g. the AverageSpectrum-task
flagPixels(ds=spectra, mask={1:[1,20,667], 3:[30,690]}, flag=2, selection=[0])
# For spectra1 and spectra2 two SpectrumContainers:
# Set flag 2 at the pixels 1,20,667 in the segments 1,2,3 for spectra1 and 
# for spectra2 in point spectrum 0 and segments 1 at the pixel indices 1,2,667 and 
# in point spectrum 0 and segment 3 at the pixel indices 30,690.
flagPixels(ds=[(spectra1,[1,20,667]),(spectra2,{(0,1):[1,20,667], (0,3):[30,690]})], segments=[1,2,3], flag=2) 
# With a single container you can just specify one tuple - which is equivalent to the very first example above:
flagPixels(ds=(spectra,{(0,1):[1,20,667], (0,3):[30,690]}), flag=2)

API details

Properties

Object ds [INOUT, MANDATORY, default=no default value.]

The input container(s) in which pixels should be flagged. See examples below. Examples of SpectrumContainer are Spectrum1d, Spectrum2d, SpectralSimpleCube.

Object mask [INPUT, OPTIONAL, default=None.]

Specification of the pixels to flag. See the description above and the examples below.

Object selection [INPUT, OPTIONAL, default=None.]

Specification of what point spectra the flagging mask should be applied to. Different ways to specify these selections are possible:

  • Specify a list of indices (in jython) of the point spectra for which the mask should be applied.

  • Use a dictionary (in jython) to specify a selection model (lookup for attributes, filter attributes to be included in ranges or intervals).

  • Pass a string representation of a jython list or a jython dictionary. The string will be parsed and the processing delegated to the two cases above.

  • Pass any java instance that implements the SelectionModel interface (for the advanced user).

See the examples below and the SelectSpectrumTask for how to specify selections.

Object segments [INPUT, OPTIONAL, default=no default value.]

Specify what segments to restrict on. There are two options available:

  • Specify a PyList of segment indices or

  • pass an instance of a SegmentSelection which gives the information on what segments for each point spectrum included in the container.

int flag [INPUT, OPTIONAL, default=2 up to the power of 30 = 1073741824.]

The flag value to set for the specified pixel.

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

Boolean to indicate that the flux value of the pixels to flag should be set to NaN. This will typically remove the pixel from plots.

PyDictionary filter_meta [INPUT, OPTIONAL, default=No default value.]

Restrict the operation on spectrum containers with meta data that match given values. This only applies in case more than one container is passed as input data to the task.

See also

History

  • 2011-08-08 - melchior: renamed from FlagPixels