Catalog Objects for Ground-Based Observations

PDS catalog objects were developed around the spacecraft-born instrument paradigm. This is not a particularly good fit for ground-based data, however it is still entirely possible to provide useful information in the available catalog objects. The goal is to do so in a consistent manner. Note that the following design is based in part on the system proposed for use by the OLAF project, which was in turn developed in consultation with the SBN (Raugh) and the Central Node.

Reference is occasionally made to utilities and resources available to SBN personnel. Source code and documentation for these utilities is available from the SBN software archives (the sbdpds bundle) unless otherwise indicated.

Contents

General Notes
DATA_SET_COLLECTION File
DATA_SET File
INSTRUMENT_HOST File
INSTRUMENT File
TARGET File
REFERENCE File

General Notes

• Cross-referencing: The only catalog file that may directly reference or mention the data files, their contents and/or their observing circumstances is the DATA_SET catalog file. INSTRUMENT and INSTRUMENT_HOST files must be written to be generally applicable to any data in any data set produced by that instrument or host, now or in the future.

• Filter Descriptions: When a filter set is used in making the observations, its description should be included in the appropriate catalog object:
  • If the filter set is specific to the observations, i.e., it travels with the observer or was specifically developed for the observations in question, it should be described in the DATA_SET catalog file, in the DATA_SET_DESC text.

  • If the filter set is specific to the instrument used, i.e., it belongs to the observatory or is permanently affixed to the instrument, it should be described in the INSTRUMENT catalog file, in the INSTRUMENT_DESC text.

• Additional Keywords: Catalog objects are specific objects, which means that only keywords specifically listed in the data dictionary may be included in them. Also, all keywords listed in the data dictionary are required and must be present with appropriate values. Run lvtool on catalog files to check keyword content.

  In the event additional keywords are desired for node-specific reasons, these must appear outside the catalog object, preferably before the main object definition.

• PDS_VERSION_ID & LABEL_REVISION_NOTE: Every catalog file must begin with PDS_VERSION_ID, which must be immediately followed by LABEL_REVISION_NOTE. The LABEL_REVISION_NOTE contains a running change log. For SBN data sets, the general format is <date> <name> <change summary>. For example:

      LABEL_REVISION_NOTE = "
        23 Jul 2002   A.C.Raugh      Creation
        02 Sep 2002   A.C.Raugh      Lien-resolution editing
        "
  

  Every non-trivial change to a catalog file must be logged. Note also that when a catalog file is changed, it must be re-submitted to the Central Node.

• Text Formatting: Headers and formatting for descriptive text (DATA_SET_DESC, INSTRUMENT_DESC and INSTRUMENT_HOST_DESC, in particular) must follow the stylesheet presented in the PDS Standards Reference, where applicable. Specifically:
  • Headings must be underlined using equal (=) characters.
  • Required subsections must be present and use the exact headings prescribed. (Typically only the overview section is required; additional non-standard headings may be appended as appropriate.)
  • Lines must contain no more than 70 characters of text.

  SBN personnel who have configured their accounts to access local tools and man pages may see a summary of descriptive headings for data set and instrument descriptions by invoking man data_set_desc or man instrument_desc, respectively. Source code for these man pages is available on request from the SBN.

• Formatting: Catalog files should be appropriately indented to show structure, with quotes around all character-type keyword values (as in labels). SBN personnel may use the ppodl routine to apply automatic indenting and line spacing (but it will not wrap lines or attempt to redistribute words to fall within the line length restrictions). Lines must be padded to 80 bytes with CR/LF delimiters, using either ppodl or fixlen. Quotes around keyword values may be fixed by using the fixqt utility.

• _ID Values: When creating ids and names (DATA_SET_ID and DATA_SET_NAME, for example), the descriptive field should be used to provide details that will distinguish the item in question from any others now and in future. Pick the most significant difference to highlight in this section.

  For example, this DATA_SET_ID:

      EAR-C-CS2-5-RDR-MCDLND-V1.0
  

  implies that the data set contains every observation made of any comet by McDonald Observatory's CS2 spectrometer. This is almost certainly not true. In fact, the data set in question actually contained only observations of comet 122P/de Vico taken by a single observer for the purpose of producing a high-resolution spectral atlas of that object. The revised DATA_SET_ID:

      EAR-C-CS2-5-RDR-DEVICO-ATLAS-V1.0
  

  provides a better indication of the purpose and content of the data set and is much less likely to collide with names of future data sets from that observatory.

• _NAME Values: Name values corresponding to id fields (DATA_SET_NAME and DATA_SET_ID, for example) must provide a succinct - generally 60 characters or less - field-by-field translation of the associated id.

• Repeating Objects: Sub-objects of catalog objects should never be repeated. Instead, list multiple values inside braces, separated by commas. For example:

      OBJECT     = DATA_SET_TARGET
        TARGET_NAME = { "IDA", "GASPRA" }
      END_OBJECT = DATA_SET_TARGET
  

  not:

      OBJECT     = DATA_SET_TARGET
        TARGET_NAME = "IDA"
      END_OBJECT = DATA_SET_TARGET
  
      OBJECT     = DATA_SET_TARGET
        TARGET_NAME = "GASPRA"
      END_OBJECT = DATA_SET_TARGET
  

  And:

      OBJECT     = DATA_SET_REFERENCE_INFORMATION
        REFERENCE_KEY_ID = { "COCHRANETAL1992",
                             "COCHRAN&BARKER1999",
                             "ARVESENETAL1969" }
      END_OBJECT = DATA_SET_REFERENCE_INFORMATION
  

  not:

      OBJECT     = DATA_SET_REFERENCE_INFORMATION
        REFERENCE_KEY_ID = "COCHRANETAL1992"
      END_OBJECT = DATA_SET_REFERENCE_INFORMATION
  
      OBJECT     = DATA_SET_REFERENCE_INFORMATION
        REFERENCE_KEY_ID = "COCHRAN&BARKER1999"
      END_OBJECT = DATA_SET_REFERENCE_INFORMATION
  
      OBJECT     = DATA_SET_REFERENCE_INFORMATION
        REFERENCE_KEY_ID = "ARVESENETAL1969"
      END_OBJECT = DATA_SET_REFERENCE_INFORMATION
  

• Quoting text: Any text quoted from another source must be attributed. Non-trivial passages of newly composed text should be signed by the author.

DATA_SET_COLLECTION File

• Create a data set collection only when it provides some substantial, positive benefit to potential users. The data set collection is generally unsupported within the PDS, and does not fit into the new standard repository structure in any meaningful way.

DATA_SET File

• DATA_SET_DESC: The first header in the DATA_SET_DESC must be "Data Set Overview". The first paragraph under this heading should be a brief summary of the entire contents.

• DATA_SET_TERSE_DESC: This should be a sentence or two (limit 255 characters) that is suitable for use as a title or thumbnail description in a web interface application. It must include the distinguishing characteristics of the data set.

• ARCHIVE_STATUS: For SBN data, archive status will never progress beyond "LOCALLY_ARCHIVED". Specifically, we will not edit our own copies of catalog files after they have been accepted by Central Node. Copies of catalog objects we keep here are for convenience (ours and our users) only. All official, archived copies of catalog files must come from Central Node.

• DATA_SET_LOCAL_ID: SBN data sets that are bound for the online archives must have this keyword. The ID should be mnemonic and distinctive. The name of the data set catalog file should be "<DATA_SET_LOCAL_ID>.cat". The DATA_SET_LOCAL_ID keyword must appear above the DATA_SET object definition.

• DATA_SET_UPDATE_PERIOD: SBN data sets that are expected to be regularly updated should use this keyword. It must be located above the DATA_SET object definition.

INSTRUMENT_HOST File

The INSTRUMENT_HOST file must never reference a particular data set. Instrument host descriptions must be independent of the data.

• "Instrument Host" Definition: For ground-based data, the instrument host comprises everything up to the focal plane. In general, this means the observatory and the telescope. For mobile telescopes, this means the telescope owner (a person or institution) and the telescope. Note that this will result in multiple INSTRUMENT_HOST files for those observatories with more than one telescope.

• INSTRUMENT_HOST_DESC: There are no prescribed headings for this text. For ground-based data at the SBN, we will use these standard headings:

  Observatory

  General description of the observatory, including coordinates and elevation. URLs for observatory home pages are appropriate here. This section may be identical in INSTRUMENT_HOST files for different telescopes from the same observatory.

  Telescope

  The description of the particular telescope. Include specific coordinates and elevation of the telescope, if known. List characteristics of the focal point, or focal points if more than one.

• INSTRUMENT_HOST_ID: This id must be short, mnemonic and unique. It should be in the general form <observatory><telescope>. For example, "MCD27M" indicates the 2.7meter telescope at the McDonald Observatory; "PAL200" indicates the 200 inch telescope at Palomar.

• File Name: The INSTRUMENT_HOST file name should be of the form <INSTRUMENT_HOST_ID>host.cat. For example: mcd27mhost.cat.

INSTRUMENT File

The INSTRUMENT file must never reference a particular data set. Instrument descriptions must be independent of the data.

• "Instrument" Definition: For ground-based data, the instrument comprises everything from the focal plane to the data recorder. It includes filters and apertures where those are specific to the instrument. Some instruments are unique to a particular institution or telescope; some instruments are mobile; some INSTRUMENT files may be written to describe a generic instrument type used in a series of coordinated or collected observations. The level of detail provided in the description should be commensurate with the type of instrument being described.

• INSTRUMENT_DESC: The first heading must be "Instrument Overview", the first paragraph of which should supply a succinct summary. If an instrument is unique to a single observatory/telescope, that may be acknowledged in the instrument description. In this case the description should include any known specific operating parameters, e.g.: the focus on which the instrument is mounted; instrument scientist; first light or decomission date; etc.

  If the instrument is not unique to a single host, then the description should not reference a specific host, which would imply a (non-existent) unique relationship.

• Calibration Description: If a calibration procedure is included in the instrument description, it should include only that part of the calibration relevant to removing instrumental effects. Calibration that is specific to the observations made and their interpretation should be covered in the DATA_SET file description.

• Other INSTRUMENT_DESC Subheadings: Do not include INSTRUMENT_DESC subheadings that are not limited in scope to the instrument itself ("Location" and "Optics", for example). Rather, make sure that these topics are covered in the INSTRUMENT_HOST file description, where they are directly relevant.

• File Name: The INSTRUMENT file name should be of the form <INSTRUMENT_ID>inst.cat. For example: cs2inst.cat.

TARGET File

A TARGET catalog file must be supplied for every target appearing as a TARGET_NAME keyword value.

• Existing Targets: When a target catalog file already exists for an object, the latest version should be downloaded from Central Node, updated as needed and included in the catalog directory.

• Asteroid Names: For asteroid targets, the TARGET_NAME value should be in one of the following forms:

  Numbered, Named	<number><name>	Example: "243 IDA"
  Numbered, Unnamed	ASTEROID <number>	Example: "ASTEROID 12527"
  Unnumbered	ASTEROID <principal provisional ID>	Example: "ASTEROID 2002 XK5"

• Comet Names: TARGET_NAME values for comets will consist of the following parts, in order:
  1. Periodic Comet Number, if any
  2. Single-letter type indicator, followed by a slash (/)
  3. Name, if any
  4. Definitive IAU discovery designation, in parentheses

  For example, Halley's comet is "1P/HALLEY (1682 Q1)".

• File Names: Target objects should appear each in its own file. For asteroid targets, the name of the file should be the TARGET_NAME value, stripped of non-alphanumerics and without the word "ASTEROID", appended to targ.cat. File names corresponding to the above examples would be: 243idatarg.cat; 12527targ.cat; and 2002xk5targ.cat, respectively. For comets, the file name should begin with the definitive IAU discovery designation without blanks. For the comet Halley example, the file name should be 1682q1targ.cat.

For more details and examples of small body names and TARGET_NAME equivalents, see SBN TARGET_NAME Conventions.

REFERENCE File

• Reference Files: There should be one file of reference objects in each catalog subdirectory. For SBN products, this file should be called references.cat. It must contain REFERENCE objects for all REFERENCE_KEY_ID values mentioned anywhere (catalog files or labels) in the relevant data set or volume.

• Format: The reference file should be sorted. SBN personnel may run the sortref tool to accomplish this. The file must also be padded to 80 bytes with CR/LF delimiters.

• REFERENCE_KEY_ID Collisions: Any proposed REFERENCE_KEY_IDs must be checked against the current Central Node catalog to ensure they do not collide with existing references. SBN personnel may use the srchref utility to check a local copy of the CN reference database for existing REFERENCE_KEY_ID values and their corresponding REFERENCE objects.

22 September 2003, A.C.Raugh