1.7. Retrieving an observation from disk

Prerequisites. You must have downloaded one or more observations from the Herschel Science Archive (see Section 1.4 ) and loaded them into HIPE (see Section 1.5 ). Optionally you may have already reprocessed your data and saved the results to disk (see Section 1.10 ).

GUI Method: Using the Product Browser

Figure 1.23. The Product Browser.

Follow these steps to find observations on your disk:

Open the Product Browser perspective by clicking the icon on the HIPE toolbar, or by choosing Window → Show Perspectives → Product Browser perspective .
Select the data sources you want to query in the Data Source panel (see Figure 1.23 ). Those of interest to you are the following:
- MyHSA, On-line : the Herschel Science Archive. This is an alternative way of browsing the HSA.
- MyHSA, Off-line : the observations you have downloaded from the Herschel Science Archive and loaded into HIPE.
- Local Pools : the data pools on your disk where you save Herschel data after you have reprocessed them.
Set your query parameters in the Observations tab. Typically you will want to indicate an observation ID. You can add more query parameters by clicking on the small plus icon at the bottom of the list in the Search parameters panel. Then you can select a metadata value, an operator (such as == ) and a value.
Click Run to execute the query.
- Result. Your result is shown in the table below the query parameters area and stored in a variable called QUERY_RESULT , for the first query, or QUERY_RESULT_x for subsequent queries, where x is a number. If no result is found then no QUERY_RESULT is produced.
  
  For expert users: the result variable may be used as argument in a ProductStorage.select() statement.
  results=storage.select(MetaQuery(...),QUERY_RESULT_1)
  Example 1.20. Perform a query on a local store using the result of another query.
- Versions. Versions are created whenever saved data are modified and stored again. If you ticked the Show all versions checkbox, you will see all versions of your data, instead of just the latest one.
- Tags. Tags are keywords or phrases you can associate to a product, to better describe and remember its contents. For example, you could assign to a product the tag "to be completed" to remember that you have not finished processing it. When defining tags, you are free to use the keywords and phrases that work best for you.
  If the data was saved with a tag assigned to it, you will see the tag displayed in the tag column. If you do not see a tag column, right click on any column header and choose Select layout → Standard Table Layout . See Section 1.10 for how to add tags when saving observations to disk.
Review the results.
- Select a row to further inspect it in the Outline view. This also creates a variable called selected .
- Double click a row to create a variable in the Variables view. This is not the same as the selected variable, whose contents change according to the selected row.
- Right click on the table to do the following on the selected rows:
  - Create variables in the Variables view (same as double click).
  - Remove the data from the pool. You can also remove an entire observation, including all child products. Removing does not work for data in the MyHSA area.
  - Export the data to FITS.
See Section 1.8 for how to customise the layout of the result area.
Inspect selected results in the Outline view.
- Double click an item to open it with the default viewer. Be aware that HIPE may have to load the item first, which could be a time and memory consuming operation for large products.
- Right click on an item and choose Open With to open it with a viewer of your choice in the Editor view.

Tip

	Tip
The Product Browser does not find data I know to be present. Check the following: Make sure that the location of your data is selected in the Data Source panel. If in doubt, select more data locations. Make sure you are searching for the right kind of data. For example, you may be in the Observations tab, thus searching for entire observations when instead you want to look for a data product inside an observation. If so, switch to the Products tab and make sure that the Product type field has the correct value. If in doubt, choose `herschel.ia.dataset.Product` to search for any data product.

The Product Browser does not find data I know to be present. Check the following:

Make sure that the location of your data is selected in the Data Source panel. If in doubt, select more data locations.
Make sure you are searching for the right kind of data. For example, you may be in the Observations tab, thus searching for entire observations when instead you want to look for a data product inside an observation. If so, switch to the Products tab and make sure that the Product type field has the correct value. If in doubt, choose herschel.ia.dataset.Product to search for any data product.

Command-line method: getObservation

With getObservation you must keep track of, and provide to the task, the OBSID, and possibly also the name and location of the pool where you saved your data, if these are not the defaults.

If your data were saved with the default name (the OBSID) and location (your lstore directory), they can be loaded by specifying the OBSID:
```
myObs = getObservation(obsid=1342231345)
```
Example 1.21. Retrieve an observation given the observation ID.
HIPE will search for the observation in the following locations (see Section 1.3 for more information on where your data are stored):
- A pool named like the obsid in your local pool directory (by default .hcss/lstore in your home directory).
- Any other pool in your local pool directory.
- The MyHSA pool.
If your data were saved in a non-default pool location, this must be specified:
```
myObs = getObservation(obsid=1342183046, poolLocation=myDirectory)
```
Example 1.22. Load an observation from disk specifying both the observation ID and the pool directory.
HIPE will look in the non-default location for a pool with the same name as the obsid.
If your data were saved in a non-default pool location and with a non-default pool name (different from the obsid), both must be specified:
```
myObs = getObservation(obsid=1342183046, poolName=myPool, poolLocation=myDirectory)
```
Example 1.23. Load an observation from disk specifying the observation ID, the local pool name and the pool location.
HIPE will look in the non-default location for a pool with the specified name.

Here are some further examples:

# Most useful task parameters
myObs = getObservation(obsid=<int|string> [,poolName=<string>]
      [,poolLocation=<string>] [,useHsa=<boolean>] [,save=<boolean>]
      [,tag=<string>])
      
# Most common uses:

# Get your data from [HOME]/.hcss/lstore/134211111
myObs = getObservation(obsid=134211111)

# Get your data from [HOME]/.hcss/lstore/MyFirstDataset
myObs = getObservation(obsid=134211111, poolName="MyFirstDataSet")

# Get your data from /BigDisc/PACS/MyFirstDataSet
myObs = getObservation(obsid=134211111, poolLocation="/BigDisc/PACS/", poolName="MyFirstDataSet")

# Get your data using a tag
myObs = getObservation(obsid=134211111, tag="Reprocessed version 2")

# Get your data from the MyHSA pool
myObs = getObservation(obsid=134211111, poolName="MyHSA")

Example 1.24. Several examples using the getObservation task.