1.102. mkFluxHotCold

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

HIFI/Pipeline/Level 1 Pipeline

Description

Computes the bandpass and receiver temperature from the hot cold spectra.

In a first part, the measurements of the hot and cold load included in the input {@link HifiTimelineProduct htp} are identified and suitable groups are build from which receiver temperature and bandpass are calculated at suitable grid points (grid points along the observation time axis). Note that as a minimum requirement for the task to be successful data from both, hot and cold load should be included in the input timeline product.

For an identification of hot and cold measurements, we adopt the following scheme:

  • Datasets with sds_type 'hot': all measurements are treated as hot measurements.

  • Datasets with sds_type 'cold': all measurements are treated as cold measurements.

  • Datasets with sds_type 'hc': typically includes both hot and cold measurements. Here, by default, we distinguish hot and cold measurements from the chopper position. Chopper values larger than 6.3 indicate a 'hot' - values below a 'cold' measurement. Alternatively, the buffer value (values 1,2) can be used. Set the signature keyword 'indicator' to 'buffer'. A value '1' is treated as 'hot' and, consequently, the value '2' as 'cold'. A further alternative is just to assume a suitable pattern of the form hot-cold-cold-hot in case 'isABBA' is not set or set to true or hot-cold-hot-cold-...ins case 'isABBA' is set to False.

Basically, the average flux for the hot and the cold measurements are computed from these groups and combined with the coupling coefficients eta_h and eta_c according to the formulas:

  • For the receiver temperature:

    ((eta_h + y*eta_c - yfactor)*j_h - (eta_h + y*eta_c - 1)*j_c)/(yfactor - 1) where the factor y denotes the ratio of the average hot and the average cold flux data and j_h and j_c the temperature of the thermal radiation field.

  • For the bandpass:

    (avg_h - avg_c) / (eta_h + eta_c - 1) * (j_h - j_c)

In addition to creating the spectra with the system temperature, a scalar system temperature is constructed which is defined as the median of a tsys spectrum where all the subbands are concatenated. This scalar system temperature is included in the tsys and the bandpass datasets as an additional column ("tsys_median").

Special attention is given to when different LO frequencies are observed (in the frequency switch mode but also in the spectral surveys). Each LO frequency up to within a given tolerance) leads to a different entry in the resulting calibration product (of type CalFluxHotCold).

A calibration product of type GenericPipelineCalProduct which contains the coupling coefficients eta_h and eta_c is needed. Either you can pass such a calibration product to the task by setting the value of the task parameter coupling accordingly. Alternatively, you can pass the calibration context included in the observation context (obs.calibration). Once you set the task parameter calibration with a calibration context you don't need to set the coupling parameter.

A validation mechanism checks the spectra to be subtracted from each other and, if needed, sets in the result data a row flag. The default mechanism inspects the mixer currents (columns 'MJC_hor' or 'MJC_Ver', respectively) and tests their relative deviation (of the hot and cold scans to be combined) to be less than a given tolerance. Once the tolerance is exceeded, for the result spectrum a row flag (bit 16) is set. The tolerance can be set by specifying the 'validatorTolerance'-parameter. By default it is set to 0.025. Alternatively, you can pass a calibration product (typically obtained from the calibration tree) with band-specific tolerances to be applied ('mixerCurrentTolerances'). Yet another possibility is to pass the whole calibration context - the task retrieves the appropriate product with the tolerances. Furthermore, you can use the parameter 'calibration' for that purpose. Once a product of type GenericPipelineCalProduct is obtained, the appropriate tolerance is looked up from a table (associated with the given date) from a column named 'mkFluxHotCold'. This checking mechanism can be overruled by passing as 'validator'-parameter an instance of the {@link DataValidator} interface. When setting this parameter to None, no checking is done.

Examples

Example 1: In HIPE:
calib=mkFluxHotCold(htp=htp)
Example 2: In HIPE:
# coupling a product of type GenericPipelineCalProduct with the coupling efficiencies included
calib=mkFluxHotCold(htp=htp, coupling=coupling)
Example 3: In HIPE:
calib=mkFluxHotCold(htp=htp, validatorTolerance=0.1)
Example 4: In HIPE:
# tolerance of a product of type GenericPipelineCalProduct with the mixer current tolerances
calib=mkFluxHotCold(htp=htp, coupling=coupling, validatorTolerance=tolerance)
Example 5: In HIPE:
# obs an observation context: both, the coupling efficiencies and the mixer curerent tolerance are obtained from it.
calib=mkFluxHotCold(htp=htp, coupling=obs.calibration, validatorTolerance=obs.calibration)
# or, equivalent to the above, but much simpler
calib=mkFluxHotCold(htp=htp, calibration=obs.calibration)
Example 6: In HIPE:
calib=mkFluxHotCold(htp=htp, indicator='buffer')

API details

Properties

HifiTimelineProduct htp [INPUT, MANDATORY, default=no default value]

HifiTimelineProduct

CalFluxHotCold cal [OUTPUT, OPTIONAL, default=no default value]

Calibration output product created by this task with the spectra the bandpass and receiver temperature spectra.

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

Product containing coupling efficiencies. Alternatively pass a calibration context.

MapContext calibration [INPUT, OPTIONAL, default=no default value]

Reference to the calibration tree from which coupling efficiencies and mixer current tolerance is obtained.

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

Parameter to specify whether the calibration tree should be used as primary source of information. It plays a role for task parameters that can explicitly be set as task parameter value (here, for the validatorTolerance-parameter) or, alternatively, retrieved from the calibration tree (see parameter calibration). If useCalTree=True but no reference to the calibration tree is provided the validatorTolerance parameter is used.

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

Pipeline configuration parameters that can be passed to the task.

String indicator [INPUT, OPTIONAL, default=no default value]

Scheme for identifying hot and cold spectra ('Chopper', 'buffer', 'pattern').

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

In case you have chosen 'pattern' as the way to identify the Hot/Cold measurements, you here can specify whether it is a pattern of the form hot-cold-cold-hot (isABBA=True) or hot-cold-hot-cold (isABBA=False).

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

If set to true the input product is assumed to contain FSwitch data so that the data is tested for the correct number of different LOFrequencies.

Object validatorTolerance [INPUT, OPTIONAL, default=0.025]

The tolerance to be used for the default validator that checks the difference in the mixer currents and sets a row flag once the mixer currents found in the science data and the bandpass deviate by more than the tolerance from each other. A relative distance measure is used to quantify the deviation (2abs(x1-x2)/(abs(x1)+abs(x2))). Alternatively, a calibration object of type GenericPipelineCalProductcan be passed from which the band-specific tolerances will be extracted. The tolerances will be looked up from the table in the column named 'mkFluxHotCold'.

DataValidator validator [INPUT, OPTIONAL, default=no default value]

Custom validator that can be passed to the task to check source and ref that is subtracted from each other and flag data once the tolerance exceeds a given tolerance. Note that the validatorTolerance cannot be used to specify this threshold. Furthermore, the default validator is overwritten once a validator or None is passed here.

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 MkFluxHotColdTask.
  • 2012-01-16 - Melchior: : Mixer current deviation row flag bit set to RowMask.MCD_HOT.getIndex() --> URM adjusted