1.120. selectHifi

Full Name:	herschel.hifi.pipeline.util.tools.SelectSpectrumTask
Alias:	selectHifi
Type:	Java Task -
Import:	from herschel.hifi.pipeline.util.tools import SelectSpectrumTask
Category	HIFI/Analysis

Description

Task for selecting datasets and/or rows of a timeline product ({@link HifiProduct}

or a dataset ({@link Spectrum2d}).

A timeline product or a dataset can be specififed as input but not both - otherwise a runtime exception is thrown. It is an extension of the SelectSpectrumTask in herschel.ia.toolbox.spectrum from which it inherits the selection functionality from within the datasets. An additional selection scheme is available to select datasets from within the HifiTimelineProduct by looking at meta data.

In summary, the following selection models are available:

Selection of the datasets from the timeline product by referring to meta data: use 'selection_meta'.
Selection of the rows from the (possibly in the previous steps pre-selected) datasets by looking up suitable values in specific (1d-)columns: use 'selection_lookup'.
Select rows by specifying a list of row numbers: use 'selection_index'. Note that this seems not to be suited when processing timeline products.
Selection of the rows from a general selection model (such as IntervalSelectionModel): use 'selection'.

Remarks:Note that only either a timeline product or a dataset should be passed as input data. In case a timeline product and a dataset are passed a runtime exception is thrown.

Example

Example 1: in HIPE

from herschel.hifi.pipeline.util.tools import SelectSpectrumTask
selectHifi = SelectSpectrumTask()
selectSpectra = selectHifi(htp=product, selection_meta={"sds_type":["science,hc"]})
dsAllScience = selectHifi(htp=product, selection_meta={"sds_type":["science"], return_single_ds=True})
selectSpectra = selectHifi(htp=product, selection_lookup={"bbtype":[6031]})
dsAllScienceOn = selectHifi(htp=product, selection_lookup={"bbtype":[6031]}, return_single_ds=True})
2011-08-08 melchior : renamed from SelectSpectrum

API Summary

Properties
`HifiTimelineProduct htp [INPUT, OPTIONAL, default=No default value.]`
`Object ds [INPUT, OPTIONAL, default=no default value.]`
`Object segments [INPUT, OPTIONAL, default=no default value.]`
`Object selection [INPUT, OPTIONAL, default=None.]`
`PyDictionary\|Map&lt;String,Set&lt;Object&gt;&gt; selection_lookup [INPUT, OPTIONAL, default=no default value.]`
`PyList selection_index [INPUT, OPTIONAL, default=No default value.]`
`Boolean return_single_ds [INPUT, OPTIONAL, default=False.]`
`PyDictionary selection_meta [INPUT, OPTIONAL, default=No default value.]`
`PyList add_from_metadata [INPUT, OPTIONAL, default=no default value.]`
`SpectrumContainer result [OUTPUT, OPTIONAL, default=no default value]`

API details

Properties

`HifiTimelineProduct htp [INPUT, OPTIONAL, default=No default value.]`
	The input timeline product.

`Object ds [INPUT, OPTIONAL, default=no default value.]`
	Input data to be processed by the task. Several types are possible: SpectrumContainer Array of SpectrumContainer, i.e. SpectrumContainer[] (e.g. `[ds1,ds2,ds3]`) List of SpectrumContainer, i.e. List (Any product with implementations of `SpectrumContainer` inside.) Examples of `SpectrumContainer` are `Spectrum1d, Spectrum2d, SpectralSimpleCube`.

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

Input data to be processed by the task. Several types are possible:

SpectrumContainer
Array of SpectrumContainer, i.e. SpectrumContainer[] (e.g. [ds1,ds2,ds3])
List of SpectrumContainer, i.e. List
(Any product with implementations of SpectrumContainer inside.)

Examples of SpectrumContainer are Spectrum1d, Spectrum2d, SpectralSimpleCube.

`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.

`Object selection [INPUT, OPTIONAL, default=None.]`
	Specification of what point spectra select. Different ways to specify these selections are possible: Specify a list of indices (in jython) of the point spectra to select. 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 for how to specify selections according to the first two bullets.

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

Specification of what point spectra select. Different ways to specify these selections are possible:

Specify a list of indices (in jython) of the point spectra to select.
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 for how to specify selections according to the first two bullets.

`PyDictionary\|Map&lt;String,Set&lt;Object&gt;&gt; selection_lookup [INPUT, OPTIONAL, default=no default value.]`
	Specify a PyDictionary with keys given by the attribute name to look up and a list of admissible values. Behind the scenes, a DiscreteValueSelectionModel is instantiated.

`PyList selection_index [INPUT, OPTIONAL, default=No default value.]`
	Specify a PyList with the indices of the point spectra to be considered.

`Boolean return_single_ds [INPUT, OPTIONAL, default=False.]`
	If set to true all the selected point spectra are written to a single dataset. In case a single dataset should be returned the situation may occur taht not all datasets that should be selected have exactly the same subband lengths. In this situation, the subbands are cropped (from above) to the minimum subband length of the spectra to be selected.

`PyDictionary selection_meta [INPUT, OPTIONAL, default=No default value.]`
	Selects point spectra (scans) if the hosting dataset have meta data with given values.

`PyList add_from_metadata [INPUT, OPTIONAL, default=no default value.]`
	If you set `return_single_ds` to True you have the possibility to fill meta data from the different datasets into columns of the resulting dataset. Just specify the list of meta data keys to be added. Currently, only meta data values of type `int, long, double, float, string` and `boolean` are supported. In case the specified meta data key is not in all datasets present you can a default value is entered. These defaults are set to `long` : maximum long number `int` : maximum int number `double` : NaN `float` : NaN `boolean` : false `string` : empty string Note that in particular for boolean parameters caution is needed.

PyList add_from_metadata [INPUT, OPTIONAL, default=no default value.]

If you set return_single_ds to True you have the possibility to fill meta data from the different datasets into columns of the resulting dataset. Just specify the list of meta data keys to be added. Currently, only meta data values of type int, long, double, float, string and boolean are supported. In case the specified meta data key is not in all datasets present you can a default value is entered. These defaults are set to

long : maximum long number
int : maximum int number
double : NaN
float : NaN
boolean : false
string : empty string

Note that in particular for boolean parameters caution is needed.

`SpectrumContainer result [OUTPUT, OPTIONAL, default=no default value]`
	Result object containing the results returned if `return_single_ds=true` or a dataset is specified as input.