1.80. HiClassTask

Full Name:	herschel.hifi.dp.tools.HiClassTask
Type:	Jython Task -
Import:	from herschel.hifi.dp.tools import HiClassTask
Category:	HIFI/Conversion

Description

Export HIFI spectra to a FITS file that CLASS can read.

This task is designed to export Data (at least level 0.5: having gone through the instrument pipeline) to a FITS file that CLASS can understand. Datasets, HTP and ObservationContexts can be passed to the task. Passing the ObservationContext will result in all the level 2 data being converted to a CLASS readable FITS file. See the HIFI Data Reduction Guide for more information. For a complete documentation of the hiclass_tools and the HiClass object, please type >>> print herschel.hifi.dp.tools.hiclass_tools.__doc__

Examples

Example 1: Simply export one dataset to a FITS file:

HiClassTask()(dataset = myspectra, fileName = 'myspectra.fits')

Example 2: Simply export one HIFI timeline product to a FITS file:

HiClassTask()(product = myhtp, fileName = 'myhtp.fits')

Example 3: Export an entire HifiTimelineProduct dataset by dataset:

hiclasstask = HiClassTask()
hiclassobj = None
dataset_iterator = htp.iterator() # To loop over the datasets.
while dataset_iterator.hasNext():
    dataset = dataset_iterator.next()
    # Here, you can do some processing on the dataset,
    # like stitching the subbands, or setting to Double.NaN
    # the channels flagged as spurs.  And then you continue:
    hiclasstask.hiClassObj = hiclassobj # Re-inject the previous HiClass object.
    hiclasstask.dataset = dataset # We want to add this dataset.
    hiclassobj = hiclasstask() # Add it.
# Export to fits file.
hiclasstask.dataset = None # We're not adding datasets anymore.
hiclasstask.hiClassObj = hiclassobj # We're exporting this result.
hiclasstask.fileName = 'myhtp.fits' # We're exporting to this file.
hiclasstask() # Export the HiClass product into the FITS file.

Example 4: Export a system temperature spectrum

# You must first provide the Tsys spectrum you want. 
tsys = obs.calibration.getProduct('pipeline-out')\
          .getProduct('Tsys').getProduct('WBS-H')
# Export it like you would do for any product.
h = HiClassTask()(product = tsys, fileName = 'tsys_WBS-H.fits')

Example 5: Export all the system temperature spectra

hiclasstask = HiClassTask()
hiclassobj = None
for backend in ('WBS-H', 'WBS-V', 'HRS-H', 'HRS-V'):
    tsys = obs.calibration.getProduct('pipeline-out')\
              .getProduct('Tsys').getProduct(backend)
    if tsys is None:
        print "No way. %s is not present." % backend
    else:
        hiclasstask.hiClassObj = hiclassobj
        hiclasstask.product = tsys
        hiclassobj = hiclasstask()
# Export to fits file.
hiclasstask.hiClassObj = hiclassobj
hiclasstask.fileName = 'mytsys.fits'
hiclasstask()

Example 6: See what does the HiClass Product look like.

# after the previous example, enter:
hiclassobj = hiclasstask()
hiclassprod = hiclassobj.Prod
# now, look at it with the Dataset Explorer.
# It is the product exported by FitsArchive.

Example 7: the HiClassTask is a wrapper around the HiClass object defined in herschel/hifi/dp/tools/hiclass_tools.py. If you wish to directly use hiclass_tools.py and not use this task, then enter:

from herschel.hifi.dp.tools.hiclass_tools import HiClass
h = HiClass()
h.add(my_product_or_dataset)
h.saveToFits('blah.fits')

API Summary

Jython Syntax
`HiClassTask()(dataset = ds, fileName = 'myfits.fits')`

Properties
`Product product [INPUT, OPTIONAL, default=None]`
`HifiSpectrumDataset dataset [INPUT, OPTIONAL, default=None]`
`String fileName [INPUT, OPTIONAL, default='']`
`HiClass hiClassObj [INPUT, OPTIONAL, default=None]`
`HiClass hiClassObj [OUTPUT, '', default='']`
`Boolean engineeringMode [INPUT, OPTIONAL, default=false]`

API details

Properties

`Product product [INPUT, OPTIONAL, default=None]`
	A product containing other products or HifiSpectrumDatasets. HiClassTask recognizes these types of products: - ObservationContext - MapContext - HifiTimelineProduct - Product HiClassTask will navigate as deep as it can into these products, going through references, until it finds HifiSpectrumDataset objects on which HiClassTask ultimately work. See the input task parameter 'dataset' below. If at any point HiClassTask finds a product it cannot handle, then a ValueError exception is raised. NaNs in the flux columns will be replaced by -1000. That is the only way to blank channels in CLASS as CLASS does not handle flags or NaNs.

Product product [INPUT, OPTIONAL, default=None]

A product containing other products or HifiSpectrumDatasets. HiClassTask recognizes these types of products: - ObservationContext - MapContext - HifiTimelineProduct - Product HiClassTask will navigate as deep as it can into these products, going through references, until it finds HifiSpectrumDataset objects on which HiClassTask ultimately work. See the input task parameter 'dataset' below. If at any point HiClassTask finds a product it cannot handle, then a ValueError exception is raised. NaNs in the flux columns will be replaced by -1000. That is the only way to blank channels in CLASS as CLASS does not handle flags or NaNs.

`HifiSpectrumDataset dataset [INPUT, OPTIONAL, default=None]`
	This input task parameter is an alternative for the previous parameter 'product'. Use this parameter when you wish to export a HifiSpectrumDataset (such as a WbsSpectrumDataset or HrsSpectrumDataset) without having to wrap it into a product before. The task parameters datasets and product must NOT be set at the same time, otherwise a SignatureException is raised when the task is executed (this is checked in the preamble). You may choose to let the parameters product and dataset to None. It can make sense in some cases. See example below.

HifiSpectrumDataset dataset [INPUT, OPTIONAL, default=None]

This input task parameter is an alternative for the previous parameter 'product'. Use this parameter when you wish to export a HifiSpectrumDataset (such as a WbsSpectrumDataset or HrsSpectrumDataset) without having to wrap it into a product before. The task parameters datasets and product must NOT be set at the same time, otherwise a SignatureException is raised when the task is executed (this is checked in the preamble). You may choose to let the parameters product and dataset to None. It can make sense in some cases. See example below.

`String fileName [INPUT, OPTIONAL, default='']`
	The name of the FITS file (path included) that you wish to generate. If left empty ('') then no file is created, which can be useful if you with to add several products/datasets into the same object. See examples.

`HiClass hiClassObj [INPUT, OPTIONAL, default=None]`
	A HiClass object. It contains a Product which, when exported to FITS, can be understood by CLASS. It also contains methods to insert datasets into that Product (quite a lot of processing and reshaping is required). You don't have to know much about that object to be able to use it. One HiClass object corresponds to one FITS file. You can add as many datasets as you want to this HiClass object before exporting it as a FITS file. If you leave the task parameter hiClassObj to its default value None, then a HiClass object will be created for you. And you usually don't have to touch it after that.

HiClass hiClassObj [INPUT, OPTIONAL, default=None]

A HiClass object. It contains a Product which, when exported to FITS, can be understood by CLASS. It also contains methods to insert datasets into that Product (quite a lot of processing and reshaping is required). You don't have to know much about that object to be able to use it. One HiClass object corresponds to one FITS file. You can add as many datasets as you want to this HiClass object before exporting it as a FITS file. If you leave the task parameter hiClassObj to its default value None, then a HiClass object will be created for you. And you usually don't have to touch it after that.

`HiClass hiClassObj [OUTPUT, '', default='']`
	The HiClass object resulting from an export. It is created when the hiClassObj input parameter is left to its default value. Please look at the examples for a practical use of this object.

`Boolean engineeringMode [INPUT, OPTIONAL, default=false]`
	Force the access to the calibration tree root. This parameter should be set to true (box checked) if the user has an up-to-date calibration tree and wants to get the following engineering parameters: - the chopper position (ELEVATIO) - the beam efficiency (BEAMEFF) - the forward efficiency (FORWEFF) Note that accesssing the calibration tree can take some time. Complete documentation of the HiClass object : >>> print herschel.hifi.dp.tools.hiclass_tools.__doc__

Boolean engineeringMode [INPUT, OPTIONAL, default=false]

Force the access to the calibration tree root. This parameter should be set to true (box checked) if the user has an up-to-date calibration tree and wants to get the following engineering parameters: - the chopper position (ELEVATIO) - the beam efficiency (BEAMEFF) - the forward efficiency (FORWEFF) Note that accesssing the calibration tree can take some time. Complete documentation of the HiClass object : >>> print herschel.hifi.dp.tools.hiclass_tools.__doc__

History

$Log: HiClassTask.py,v $
Revision 1.21 2011/06/17 20:16:40 drabois
HIFI-4235: Improvements to HiClass URM entry
Revision 1.20 2011/05/05 16:05:38 drabois
D_HIFI_DP_TOOLS_0_94: HIFI-4148: Moved the global import statements outside of the functions (jython 2.5)
Revision 1.19 2011/05/02 08:59:32 drabois
HIFI-4111: jcategory set to HIFI/Conversion
Revision 1.18 2011/04/14 13:06:15 drabois
Updated hiclass_tools and HiClassTask documentation
Revision 1.17 2011/04/06 15:43:41 drabois
D_HIFI_DP_TOOLS_0_89: HIFI-4033: taskin hifi_dp_tools not registered
Revision 1.16 2011/04/06 13:31:11 drabois
D_HIFI_DP_TOOLS_0_88: HIFI-3847: Export system temperature spectrum to CLASS
Revision 1.15 2011/03/30 16:43:13 drabois
D_HIFI_DP_TOOLS_0_86: Put descriptions to HiClassTask task parameters
Revision 1.14 2011/03/17 12:54:16 drabois
D_HIFI_DP_TOOLS_0_80: Reexported the HOBSID keyword
Revision 1.13 2011/03/16 14:13:56 drabois
D_HIFI_DP_TOOLS_0_79 Cleaned up hiclass_tools.py
Revision 1.12 2010/09/09 12:16:23 delforge
Implements SCR-3567: HiClass GUI is now linked to products (instead of
datasets) and appears applicable to them.
Revision 1.11 2010/06/18 12:16:03 delforge
Minor changes.
Revision 1.10 2010/02/11 13:49:17 delforge
Checks the validity of specsys in the preamble.
Revision 1.9 2010/02/10 16:51:21 delforge
HiClass now produces the signal and image frequencies in the reference
frame of the source (rest frequencies) which is the only one CLASS is
supposed to deal with.
Two new input parameters were introduced: 'veloSource' and
'specsys'. They are used to override the velocity of the source and
the reference frame in which the frequencies are expressed in the
input dataset. Useful when the proposal or the pipeline is lacking
something.
Revision 1.8 2010/02/03 16:43:31 delforge
* blanking value set to -1000 instead of 1000
* better exception handling around the code loading the chopper table
* exports a tsys value for each spectrum
* specify LSR as a referential for velocity
Revision 1.7 2010/02/02 10:43:51 hsclib
LGPL
Revision 1.6 2010/01/26 14:27:03 delforge
Reformatted the documentation paragraphs.
Revision 1.5 2009/12/07 10:18:13 delforge
Implements SPR HIFI-3173: Typo in documentation corrected.
Revision 1.4 2009/10/27 09:46:45 delforge
Implements SPR HIFI-3029: When exporting an HTP or an
ObservationContext (new feature btw), HiClass will try to find a
common reference position for all the datasets. This comes as a
workaround a pipeline problem: the pipeline doesn't fill the raNominal
and decNominal of the datasets yet, so the information has to be found
somewhere else. The user can also set raNominal and decNominal
himself now by setting the right task parameters (HiClassTask) or
configuration items (HiClass).
Revision 1.3 2009/10/09 11:34:06 delforge
Implements SCR HIFI-2983: HiClassTask is now visible from Hipe. In
order for this to really happen, there is a new version of all.py in
herschel.hifi.dp to be committed as well.
Revision 1.2 2009/10/05 13:51:21 delforge
Implements SCR HIFI-2975: The task can export products as well as
datasets and allow the configuration of the HiClass object.
Revision 1.1 2009/09/11 14:58:33 delforge
First version in hifi.dp.tools.
10-10-2008 BD: Creation.