Useful to know!

In this section we report some general information that might be useful when running OSA software. Most of these information can be found also in the IBIS Cookbook.

• How do I get some help with the executables?
  All the available help files are stored under $ISDC_ENV/help. To visualize a help file interactively type tool_name -h once your environment is set (i.e. the command which tool_name should return the path to it).
• Where are the parameter files and how can I modify them?
  All the available executables for the analysis of INTEGRAL data are under $ISDC_ENV/bin. The corresponding parameter files are stored under $ISDC_ENV/pfiles/*.par. The first time you launch a script, the system will copy the specific tool.par from $ISDC_ENV/pfiles/ to a local directory (/user_name/pfiles/). The parameter file in the local directory is the one used for the analysis and is the one you can modify. If this parameter file is missing (e.g. you have deleted it), the system will just re-copy it from $ISDC_ENV/pfiles/ as soon as you launch the script again. The system knows what to copy from where thanks to the $PFILES environment variable that is also used in FTOOLS (http://heasarc.gsfc.nasa.gov/ftools/). Each parameter is characterized with a letter that specifies the parameter type, i.e:
  ``q'' (query) parameters are always asked to the user
  ``h'' (hidden) parameters are not asked to the user and the indicated value is used
  ``l'' (learned) parameters are updated with the user's value during the use of the program.
  The GUI is a fast and easy way to change the parameters, see also the explanation at the end of this section.

• What are groups and indices?
  The ISDC software makes extensive use of groups and indices. While it is not necessary to grasp all the details of these concepts, a basic understanding is certainly quite useful.

  As implied by their names, "groups" make possible the grouping of data that are logically connected. Groups can be seen as a kind of data container, not completely unlike standard directories. At ISDC, we create separate groups for each pointing, in which we store the many different data types produced by INTEGRAL and its instruments. The user then only has to care about one file, the group, many tens of files being silently included. Several pointings (the ``Science Window Groups'') can be arbitrarily grouped into bigger groups (the ``Observation Group'') to select data very efficiently according to the user's needs.

  Indices are a special kind of groups, which differ only in the fact that all the the data sets they contain are similar and that the indices know the properties of the data sets they contain. Indices are a kind of poor man's database. For example, an imaging program creates several images of different types (flux map, significance map,...) in different energy bands. These images are stored in an index, in which the image type and energy band information is replicated. ISDC software is then able to select very efficiently the needed images. The user can also make use of the indices; just by looking at the index (for instance using ``fv''), the user can identify immediately the content of each image.

• Why do I need ``[1]'' after a FITS file name?
  A FITS file can have many extensions and sometimes it is necessary to specify as input to a given parameter not the file name alone (file.fits) but the extension too (file.fits[1], or file.fits[2], etc). The file name with a specified data structure (extension) is called DOL (Data Object Locator). When you modify the parameter file itself (see above) or use the GUI, the extension will be correctly interpreted in the file.fits[1] case. On the command line though, the normal CFITSIO and FTOOLS rules apply, i.e. you have to specify it as one of the following
  file.fits [1]
  file.fits+1
  "file.fits[1]".
  Note that if no extension is specified explicitly then the first one ([1]) will be used by default.
  

• What are the general functionalities of the GUI?
  When you launch the analysis, by default the GUI is launched, providing an opportunity to set the values of all desired parameters, see Figure 10. On the right side of the panel you see the following buttons:
  • Save as - With the ``Save As'' - button a file is created. This file stores all parameters as they are currently defined in the GUI as a command line script. This file is an executable one and calling it from the command line will launch the instrument analysis program with the parameters as they were defined in the GUI.
  • Load With the ``Load'' - button a previously saved file (see ``Save As'') can be read and the GUI will update all parameters with the values as they are defined in the loaded file.
  • Reset With the ``Reset'' - button the parameters in the GUI will be reset to the default values as they are defined in the parameter file of the instrument analysis program and stored in the $ISDC_ENV/pfiles directory.
  • Run With ``Run'' - button the analysis is launched.
  • Quit With ``Quit'' - button you quit the program without analysis launch.
  • Help With ``Help'' - button the help file of the main script is opened in a separate window.
  • hidden With the ``hidden'' - button you have an access to the hidden parameters with values defined by the instrumental teams. Change them with care!

  The environment variable COMMONSCRIPT is used to disable/enable the GUI (see section 6.3).