UniHIPE release 4.0

UniHIPE is a tool that produces fits file in the format required by Unimap.

Using UniHIPE you can also launch directly Unimap and generate the final maps.

The tool requires HIPE (v.12 or greater) installed in your computer. In order to install HIPE follow the link: http://www.cosmos.esa.int/web/herschel/hipe-download

To generate final maps you have to install Unimap:to install Unimap follow the link http://infocom.uniroma1.it/unimap/

INSTALLING UniHIPE

To install UniHIPE:

Launch HIPE
Go to Tools menu > Plugins and click Install new... button in the plugins window
A new window will be open: you can copy directly the link at the jar file on the SSDC website: https://herschel.ssdc.asi.it/files/UniHipePlugin_4.0.jar in the text field or select the jar file from a local directory if you have already downloaded the plugin. A popup window will inform you if the installation process worked as expected.
Restart HIPE

Now UniHIPE is added to the HIPE task list (look for uniHipe under SPIRE or PACS task list).

UniHIPE plugin description

Double click on uniHipe in the task list opens the plugin GUI. A brief description of the parameters available to the users is provided here. The description follow the GUI division: the GUI is divided in three sections: Main, UniHIPE and Unimap.

Main Tab

In the main tab you have to define main inputs for the UniHIPE/Unimap process

obsidList: the list of the obsid that you want process using UniHIPE and Unimap:
```
obsidList=[1342198592, 1342198593]
```
tag: the name to identify the UniHIPE run (if not set the default is a combination of obsids name, e.g. obsid1_obsid2)
```
tag="myUniHIPE Run"
```
inOutDir (MANDATORY): in this directory will be stored the fits file in the format required by Unimap generated UniHIPE and the final maps produced by Unimap.
```
inOutDir="/home/myhome/myworkingdir/"
```
instrument (MANDATORY): select between SPIRE and PACS
```
instrument="SPIRE"
```
batchExec (default value: False): select it to exec the task in batch mode. If is set and store is set to Local Directory you have to provide a list of directory where the level1 fits files are stored using location parameter (see below)
```
batchExec = False
```
execUniHipe (default value: True): if selected UniHIPE is used to produce the level1 data in the format expected by Unimap. If set, you have to provide also values for the specific UniHipe parameters (see description of these parameters below in the section UniHipe Tab. You can deselect it f you have already generated the level1 data and you want execute only Unimap.
```
execUniHipe=True 
```
execUnimap (default value: False): select it to execute the Unimap process and generate the maps. If set, you have to provide also values for the specific Unimap parameters (see description of these parameters below in the section Unimap Tab.
```
execUnimap=True 
```

UniHipe Tab

In the UniHipe tab you have to define specific inputs for the UniHIPE process, i.e. the process that convert standard SPIRE/PACS level1 into Unimap input format.

type: select the type of process: i.e. from where starts the SPIRE process or which PACS band process. Possible values are:
- spire: converts directly the standard level1 (not recommended if data are taken directly from HSA)
- spire_lev0: generates new SPIRE level1 starting from level0 (engineering conversion included) and then covert them to Unimap format
- spire_lev05: generates new SPIRE level1 starting from level0_5 and then covert them to Unimap format
- pacs_red: converts level1 PACS red band
- pacs_blue: converts level1 PACS blue band
```
type="spire_lev0"
```
store: where the products to convert are stored. Possible values are:
- Local Store: the products are stored in the HIPE Local Store
- HSA: the data should be downloaded from the Herschel Science Archive (HSA)
- Local Directory: the products are stored in a local directory outside the HIPE local store. If the parameter is set to Local Directory you have to provide a list of directory (one for each obsid in obsList). If the task is executed in interactive way (i.e. batchExec is set to false) a popup window will be open and you will select the directories using the GUI interface. Otherwise you have to provide a list of directories using the "location" parameter (see below).
```
store="HSA"
```
location: if store is set to Local Store you can use this parameter to provide the name of the local store. Only if the store parameter (see above) is set to Local Directory, you have to provide a list of directory (separated by a comma) where the level1 data are stored as for the following example:
```
location="~/1342198246/level1/herschel.spire.ia.dataset.PointedPhotTimeline, ~/1342198247/level1/herschel.spire.ia.dataset.PointedPhotTimeline"
```
updateCal (only for SPIRE data): if set to True, the calibration tree attached to the observations is updated using the last calibration tree available locally (i.e. the last tree stored on your machine) and it will be used when the data are reprocessed from level0 or level0_5.
```
updateCal = True
```

Unimap Tab

In the Unimap tab you have to define specific inputs for the Unimap process, i.e. the process that convert level1 generated by UniHIPE process in the final maps.

mcrDir: location of the MATLAB runtime.
```
mcrDir= "/Applications/MATLAB/v716"
```
unimapDir: where Unimap is installed
```
unimapDir="/Users/Gabri/hcss/unimap"
```
spireArray and pacsArray: the SPIRE/PACS band to process with Unimap. For SPIRE, if you select ALL, all the three bands are processed.
```
spireArray="ALL"
```
filterSize: pgls high pass filter size in arcsec
```
filterSize=10.0
```
noiseFilterType: Noise Filter Type. Possible values:
- 0 raw unit power
- 1 fit unit power
- 2 raw estimated power
- 3 fit estimated power
- 4 raw avefilt
- 5 fit avefilt
```
noiseFilterType=2
```
startImage: Starting image for the gls (default value: 1). Possible values:
- 0 zero image
- 1 rebin
- 2 highpass
```
startImage= 0
```
wglsDThreshold: Threshold to detect an artifact (lower values = more artifacts)
```
wglsDThreshold=3.0
```
wglsGThreshold: Threshold to grow an artifact (lower values= wider artifacts)
```
wglsGThreshold=1.5
```
loadWglsImage: Select it to load final WGLS image generated by Unimap in the HIPE session.
```
loadWglsImage=False
```

(Note that many others parameters for Unimap are modifiable by the user changing the unimap_par.txt file available in the directory where the Unimap is installed on your machine)

Running UniHIPE

You can execute UniHIPE in interactive mode, setting all parameters via GUI ad described above or you can call it via command line writing a simple jython script.

An example of jython script is provided with the plugin and is available under HIPE menu > Tools > UniHipe Plugin.

To execute the jython script via command line you have to type:

    hipe myUniHipeScript.py

To allocate, e.g, 6gb of memory to the process:

    hipe -Xmx6g myUniHipeScript.py

How it works

UniHipe creates the FITS files for Unimap (unimap_obsid_<instrument>_<array>_<tag>.fits) in the subdirectory "tag" within the inOutDir directory. It also generates an auxiliary file "unimap_meta.dat" that will be managed by unimap to create the fits header

Unimap, if called, generates the final maps with the name unimap_<array>.fits: this is an image that stores all the maps generated by different Unimap steps as different layers. For a description on how Unimap works, please refers to Unimap website.

Getting help

Write a e-mail to Fabiana FaustinI fabiana.faustini@ssdc.asi.it

Comments and suggestions are welcome!

UniHipe is developed by SSDC (ASI Space Science Data Center) www.ssdc.asi.it

The SSDC is a facility managed by the Italian Space Agency, ASI

If you research benefits from the use of SSDC, we would appreciate the following acwnoledgment in your paper:

Part of this work based on archival data, software or online services provided by the ASI SPACE SCIENCE DATA CENTER (SSDC)