P2PP: IMPEX Reference Guide

This reference guide was originally written by A. Maurizio Chavan.

P2PP V.2.x Import/Export Files

Introduction

Observation Blocks, Calibration Blocks, and associated objects (like configuration files, finding charts, and Readme files) can be saved to disk, and read back, as ASCII files called Import/Export (or IMPEX) files.

The Import/Export mechanism in particular is useful in the following situations:

exchanging files between collaborators
creating and/or editing OBs off-line (e.g. on a portable computer while traveling)
automatically creating large sets of repetitive OBs from a target list
migrating OBs to and from other applications.

This document describes the format of V.2.x exported OB files. Notice that the format of P2PP IMPEX files may change in the future, as more features are added to the system. When exporting OBs containing finding charts or ephemerides files, these exported components are simply the original JPEG file (finding charts) or ASCII file (ephemerides) as originally attached to the OB.

Starting with P2PP v2.9, README files can also be exported and imported following an analogous format to those of exported OBs. The format of IMPEX README files is not described in the present document.

Technical note: Although Import/Export (IMPEX) files are similar to the Observation Block Descriptor (OBD) files, IMPEX and OBD files are not interchangeable.

An example is given at the end of this document.

General description of IMPEX files produced

IMPEX files are ASCII text files, and their syntax is quite straightforward. Below are a few lines extracted from the target section of an example IMPEX file; a full example is at the end of this document.


# comment line, will be ignored.

TARGET.NAME         "B 1950 target"

ra                  " 12:34:56.001"

dec                 "-78:59:11.001"

epoch               "2000.0";

equinox             "B1950";		# Valid values are "J2000", etc.

Empty lines and lines containing only whitespace are ignored, and so are lines beginning with the hash character (#). These lines can be used to insert remarks in an IMPEX files, but note that such remarks will be lost during import.

Meaningful lines include a keyword and a value: the value is always included in double quotes, and may be followed by an optional semicolon.

Optional comments can be appended at the end of a line, in which case they must be separated from the value by a semicolon and a hash character.

Notes

An IMPEX file is divided in sections; sections boundaries are marked by the following keywords
IMPEX.VERSION TARGET.NAME CONSTRAINT.SET.NAME OBSERVATION.DESCRIPTION.NAME Keywords ACQUISITION.TEMPLATE.NAME and TEMPLATE.NAME introduce template definitions.
Keywords TARGET.NAME and ACQUISITION.TEMPLATE.NAME (and the corresponding section and definition) are not found in Calibration Block IMPEX files.
An IMPEX file may have zero or more TEMPLATE.NAME keywords.
Parameter keyword/value lines must follow the corresponding TEMPLATE.NAME keywords.
Some keyword/value lines of each IMPEX file are optional, meaning that they can be omitted from the file, or that the value can be the empty string: in this case, the keyword will take its default value. In the following sections, optional keyword/value lines are marked by the "Default:" comment.
The import/export software will ignore all keyword/value lines that it can't recognize.
Repeated keyword/value lines are accepted; the last read value overrides all previous values for the same keyword.
In V.2.x, import does not fail if an object with the same name exists already.

IMPEX files

As explained above, an IMPEX file is structured as a sequence of sections, each introduced by a section keyword.
A P2PP V.2.x IMPEX file must begin with the following keyword/value pair:


IMPEX.VERSION "2.0"

IMPEX filenames are identified by the ".obx" extension.

Main section

The IMPEX.VERSION keyword introduces the main section, where OB-level information is specified, like its name and priority. For instance:


IMPEX.VERSION           "2.0"

name                    "B 1950 OB"

type                    "O"

userComments            "Generic user comment."

userPriority            "1"

calibrationReq          "No special requirements"

absolute_times_list 	"{2000-06-07T12:00:00 2000-06-21T21:00:00 1} "

IMPEX.VERSION

a P2PP V.2.x IMPEX file must begin with this keyword/value pair.

name

a string, max 32 chars. Notice that the base filename of an IMPEX file should be the same as the value of this keyword, which means that characters like "(", "&" "/", ">", etc. should be avoided in the Observation Block name. Spaces should be translated to underscores. For instance, an Observation Block whose name is "Test OB" should be represented by IMPEX file "Test_OB.obx"

type

"O" for Observing, "C" for Calibration. Default is "O".

userComments

Any string, up to 255 chars. Default is "".

userPriority

An integer number between 1 (highest) and 10 (lowest). Default is 1.

calibrationReq

Any string, up to 255 chars. Default is "".

absolute_times_list

List of time intervals specifications: OB can be executed only during these intervals. An interval specification is surrounded by braces and has three elements:

start time and date in ISO format: yyyy-mm-ddThh:mm:ss
end time and date in ISO format
preference value (1-5)

Interval specifications are separated by whitespace.
Default: "" (no absolute time intervals).

Target section

The TARGET.NAME keyword introduces the Target section, where target information is specified, like its coordinates and name. For instance:


TARGET.NAME         "B 1950 target"

ra                  " 12:34:56.001"

dec                 "-78:59:11.001"

epoch               "2000.0"

equinox             "B1950"

propDec             "0.0"

propRA              "0.0"

diffRA              "0.0"

diffDec             "0.0"

comments            ""

objectClass         "Unknown"

TARGET.NAME: Any string, max 32 chars
ra: Right Ascension of target, HH:MM:SS.SSS
dec: Declination of target, DD:MM:SS.SSS
equinox: Valid values are of the form Annnn, where A can be "B" or "J", and nnnn can be any four digit number.
epoch: Epoch of target; any number. Default: 0.0
comments: Any string, up to 255 chars. Default is "" (empty).
propRA: Proper motion in RA, arcsecs per century. Default: 0.0
propDec: Proper motion in Dec, arcsecs per century. Default: 0.0
diffRA: Differential motion in RA, arcsecs per century. Default: 0.0
diffDec: Differential motion in Dec, arcsecs per century. Default: 0.0
comments: Any string, up to 255 chars. Default: empty.
objectClass: One of the ESO specified object classification codes, like KuiperBelt or Brown_dwarf. Default: unknown.

Constraint Set section

The CONSTRAINT.SET.NAME keyword introduces the Constraint Set section, where observing constraints are specified, like seeing and sky transparency. For instance:


CONSTRAINT.SET.NAME           "Example CS"

air_mass                      "5.0"

fractional_lunar_illumination "1.0"

sky_transparency              "Photometric"

moon_angular_distance         "30"

seeing                        "2.0"

description                   ""

CONSTRAINT.SET.NAME: Any string, max 32 chars
seeing: Any number, 0.2 to 5.0. Default: 5.0
sky_transparency: Valid values are Photometric, Clear, Variable, thin cirrus and Variable, thick cirrus. Default: Variable, thick cirrus.
air_mass: Any number, 1.0 to 5.0. Default: 5.0
fractional_lunar_illumination: Any number, 0.0 to 1.0. Default: 1.0
moon_angular_distance: Any number, 0 to 180. Default: 30
description: Any string, up to 255 chars. Default: empty

Observation Description section

The OBSERVATION.DESCRIPTION.NAME keyword introduces the Observation Description section, where the acquisition and observing templates are listed. For instance:


OBSERVATION.DESCRIPTION.NAME "No Name"

longDescription              ""

instrument                   "FORS1"



ACQUISITION.TEMPLATE.NAME    "FORS1_img_acq"

INS.COLL.NAID                "COLL_SR+1"



TEMPLATE.NAME                "FORS1_img_obs_crsplit"

SEQ.NEXPO                    "1"

DET.WIN1.UIT1                "25.0"

Only three keywords make up the observation description section proper:

OBSERVATION.DESCRIPTION.NAME: Any string, max 32 chars
instrument: A valid instrument, like FORS2, ISAAC, EMMI, EFOSC, etc.
longDescription: Any string, up to 255 chars. Default: empty.

Template definitions

A template definition is simply an ACQUISITION.TEMPLATE.NAME or TEMPLATE.NAME keyword/value line, followed by a list of parameter keyword/value lines.

Note that *all* parameter keyword/value lines are optional: missing lines correspond to default parameter values (described in the documentation of the individual templates). In the example above, all parameters of template FORS1_img_obs_crsplit take their default values, but for the exposure parameters.

It is therefore possible give a template name with no parameters at all; in this case, though, the ACQUISITION.TEMPLATE.NAME or TEMPLATE.NAME keyword/value line must be followed by at least one blank line.

Note that TEL.TARG.xxx parameters of acquisition templates are never imported/exported.

Paramfile parameters

Template parameters of type paramfile are exported to, and imported from, individual files.

Let's assume, for instance, that a VIMOS OB was created, including a template which in turns includes paramfile parameter INS.ADP1; and that parameter file vmCatQuad1Mask1.adp was associated to such parameter.

Upon export, the generated IMPEX file will contain:


INS.ADP1      "vmCatQuad1Mask1.adp"

and file vmCatQuad1Mask1.adp will be copied to the same directory.

When importing the IMPEX file, the import procedure will look for file vmCatQuad1Mask1.adp in the same directory, and associate it to the INS.ADP1 parameter.

An example

An annotated example IMPEX file follows.


#****************************************

# MAIN SECTION                          *

#****************************************



IMPEX.VERSION 		"2.0";		# This is a V.2.x IMPEX file



name                    "Observation Block 0"

type                    "O"

userComments            "This OB was generated from an example IMPEX file."

userPriority            "1"

calibrationReq          "No special calibration requirements."

absolute_times_list 	"{2000-06-07T12:00:00 2000-06-21T21:00:00 1} "





#****************************************

# TARGET SECTION                        *

#****************************************



TARGET.NAME         "Target 0"

ra                  " 12:34:56.001"

dec                 "-78:59:11.001"

epoch               "2000.0"

equinox             "B1950"

propDec             "0.0"

propRA              "0.0"

diffRA              "0.0"

diffDec             "0.0"

comments            "This is a generic target"

objectClass         ""





#****************************************

# CONSTRAINT SET SECTION                *

#****************************************



CONSTRAINT.SET.NAME           "Constraint Set 0"

air_mass                      "5.0"

fractional_lunar_illumination "1.0"

sky_transparency              "Photometric"

moon_angular_distance         "30"

seeing                        "2.0"

description                   "This is a generic Constraint Set"





#****************************************

# OBSERVATION DESCRIPTION SECTION       *

#****************************************



OBSERVATION.DESCRIPTION.NAME "Observation Description 0"

longDescription              "This is a generic Observation Description"

instrument                   "FORS1"



ACQUISITION.TEMPLATE.NAME	"FORS1_img_acq"

INS.COLL.NAID        		"COLL_SR+1"

TEL.ROT.OFFANGLE     		"0"

TEL.AG.GUIDESTAR     		"CATALOGUE"



TEMPLATE.NAME		"FORS1_img_obs_crsplit"

SEQ.NEXPO		"1"

DET.WIN1.UIT1		"250"

DET.READ.CLKIND		"ABCD,1x1,high"

DET.WIN1.ST		"F"

INS.FILT1.NAME		"B_BESS+34"

INS.FILT2.NAME		"none"