fitsreport

Description

This tool is designed to create formatted and unformatted file-by-file reports from fits headers, or fits files.

fitsreport reads from a configuration file all the keys to be displayed:

• their format
• any substring information applicable
• support and delimiter strings added at the begin or the end of the retrieved key (this makes sense for unformatted reports).
• header lines.

It also has advanced functions like

• transformation (e.g. transform fractions of days into DATE_TIME format)
• multiplicity (multiple keys are supported meaning you can specify ins.det*.ron and get the content of ins.det1.ron or ins.det2.ron, whatever exists in the fits file)
• retrieve non-FITS information (file name, path name).

This tool is a DFS tool created by the SDD back-end team.

Output

The output goes to stdout. If specified, a plain text file is created. The file is ready to print, or to include in a final report which has more information than just file-by-file key content.

fitsreport is a level 2 tool. It is typically called by createReport or createAB. It can also run stand-alone.

How to use

Type

fitsreport -H

for on-line help. There is an extended manpage here.

Type fitsreport -v to get the current version.

The typical call is:

fitsreport -c fitsreport_raw.cfg ${DFO_RAW_DIR}/${DATE}/*fits -o out

The tool reads all fits files in the given path, evaluates the configuration file fitsreport_raw.cfg (to be in ${DFO_CONFIG_DIR}) and dumps the output into out.

This is the simplest call. The tool has many more options, e.g. to do selection on input files and use a where clause to scan e.g. only those files with exposure time -gt 200. Check out the documentation for more.

Configuration files

fitsreport uses a configuration file with extension .cfg. [This is an internal convention to distinguish such config files from those serving the dfos tools (starting with config).]

The installation package comes with fitsreport_raw.cfg. It is the one operational for GIRAFFE and can be used as a template for your installation (check out here). It produces formatted output. But if you want to explore nice features like conversion or multiplicity, have a look at the tutorial config file. There are more fitsreport configuration files as part of the createReport and createAB packages.

The syntax for the config file is simple:

- anything after a "#" is a comment
- anything between "Parameter Name" and the next "Parameter Name" is considered as part of the parameter ( = key) definition
- anything before the first colon ":" is a name of an attribute (e.g. Header1; Value Format)
- anything after the colon is an attribute value.

The attributes "Parameter Name", "Header1", "Type" and "Value Format" are mandatory for formatted reports. All others are optional.

Unformatted reports only need the "Parameter Name" which may be decorated by "Support" and/or "Delimiter". These two additional strings can be used to make a string, as returned by the tool, unique. For instance, the content of det.win1.binx is 1, which is not particularly well suited for pattern matching. If you add "BINX" as support string, and maybe "X" as delimiter string, the returned value will become "BINX1X" which is much better suited for unix-grep oriented pattern matching. Another example are pro.catg values like "LINE_TABLE" and "LINE_TABLE1" which can be made unique using short support and delimiter strings like e.g. "Y": "YLINE_TABLEY" and "YLINE_TABLE1Y" is fine for unix-grep. As mentioned before, this becomes important for the unformatted, technical reports which feed the association tool.

There are "general parameters" and "parameters to display". This is more evident in the other config file, fitsreport_raw.cfg. The general parameters control general behaviour, like "Missing keyword value"; "Keyword for blocking"; "Sorting criteria". The blocking parameter is useful to make the report better readable. Sorting is obviously best done by ARCFILE but there are other use cases with e.g. OB sorting.

Installation

Use dfosExplorer, or type dfosInstall -t fitsreport .

Notes:

• Edit the $LD_LIBRARY_PATH as described in the README file. Path definition should not be done in .dfosrc, but in your standard RC file, e.g. .qcrc.
• The version of the binary executable assumes Linux9 as OS. Check out here if you need another version.

Operational aspects

• The tool can run both on fits and on header files. Make sure that the headers are downloaded from the archive (using the DFOS tool dataclient).
  
  

• The tool is designed to create the following types of reports:

  • the core of the raw file/header reports (night by night)
  • the end-user-oriented file reports in the SM directories
  • the technical (unformatted) reports feeding the association tools

  The difference in calling fitsreport for these use case is simply to call a different configuration file, and specify different input and output files. The template config files for each of these cases are delivered as part of the createReport and createAB packages.