Understanding AstrOmatic metadata files

Several AstrOmatic software packages (MissFITS, PSFEx, SCAMP, SExtractor, STIFF, SWarp and WeightWatcher) offer the possibility to generate metadata in XML-VOTable format at the end of an execution run. For this to happen, the configuration parameter WRITE_XML must be set to Y. The XML-VOTable format was chosen  to facilitate integration in Virtual Observatory services, although it is somewhat cumbersome to use.

Content of a metadata file

A metadata file consists essentially of a VOTable RESOURCE named “MetaData” containing several sections:

• a set of PARAM elements describing the execution run (date/time, user, path, etc.),
• a series of TABLEs containing various tool-dependent results, such as measurements, calibration results, statistics, …
• a “Warnings” TABLE listing all warnings issued during processing,with date and time of occurence,
• a “Config” sub-RESOURCE with all the configuration parameters and their values for the run, as well as the full command-line.

Note that the medata file is written even if an error occurs, in which case a PARAM element named “Error_Msg” is added in the first section. In the case of SExtractor, the metadata is included in the output catalogue, together with the full list of extracted source measurements,  if CATALOG_TYPE is set to ASCII_VOTABLE.

Accessing the metadata file content

The content of a metadata file can be parsed and read by VOTable-compliant VO tools and libraries, such as TOPCAT or the libVOTable. But as any other XML document, it can also be “translated” into another (more user-friendly) format using an XSLT stylesheet. The URL of an XSLT stylesheet must be specified at the beginning of XML file using the ?xml-stylesheet start-tag.

Every AstrOmatic software package that writes metadata VOTables comes with its own XSLT stylesheet, installed by default in /usr/share/<software_name>/ or /usr/local/share/<software_name>/ (the URL in the example above is file:///usr/share/missfits/missfits.xsl, it can be changed using the XSL_URL software configuration parameter, or obviously by hand directly in the metadata file). This XSLT stylesheet contains all the information needed to convert the metadata VOTable to plain old, eye-friendly XHTML. The result can be visualized by pointing your favorite web browser to the metadata file, either locally (e.g. in the example above file://missfits.xml) or remotely (e.g. https://www.astromatic.net/missfits.xml). Tables are expandable and rows are sortable by clicking on the header cells, thanks to a small JavaScript code (see below).

An XML-VOTable metadata file generated with SCAMP and visualized in the Firefox web browser. Click on the image to view a real example.

Be warned that since its version 3, the Firefox browser blocks by default access to XSLT stylesheets not located in the same directory as the XML file (among other things). A consequence on Linux is that the shell command firefox scamp.xml will return only an unformatted page with “flat” text, by default. This behaviour may be overridden in Firefox by changing the flag security.fileuri.strict_origin_policy to false in the about:config preference settings, as shown below.

References

Bertin, E. & Tissier, G. 2007: VOTables in TERAPIX Software, ASP Conference Series, Vol. 376, 2007, Richard A. Shaw, Frank Hill and David J. Bell., eds, p.507 [PDF] [BibTeX entry].