1.155. flagPixels

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.

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.

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.

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)