Using the Spectral Dictionary

From The SBN Wiki
Jump to navigation Jump to search


The Spectral Discipline Dictionary is used to provide observational and binning parameters for lightwave spectra. Other pages on this wiki you may wish to consult either before or during your perusal of this page:

This page assumes you're already familiar with the concepts introduced in the first document, and leaves details on Spectral classes and schema referencing to the other two documents. This page is concerned with mechanics and techniques for properly and effectively using the Spectral Dictionary classes.

For some measure of convenience, when you see the little clipboard icon following some sample text, like this:

<clippy show="true">Click the icon to copy this text to your clipboard.</clippy>

you can click the icon to copy, and then paste the text into your label at the appropriate place. The little icon is not artificially intelligent, however, so you will need to edit the string to match your specific circumstances.

For the purposes of the following examples, the IM (a.k.a. "1C00") version of the Spectral Dictionary is used. You will likely need to edit specific version numbers and file names to meet your particular version and environment needs.

Setting up the Label for Validation

If you use the recommended method for defining references for validation (as described in Schema Referencing in PDS4 Labels), the <?xml-model> processing instructions at the top of your label will look like this:

<clippy show="true"><?xml-model href="" schematypens=""?></clippy>

Similarly, if you're following the recommendations on that page for XSD referencing, then inside the <Product_Observational> tag you will need to add this namespace definition:

<clippy show="true">xmlns:sp=""</clippy>

and this pair inside the quotes of your xsi:schemaLocation XML attribute:

<clippy show="true"></clippy>

The sp: prefix is reserved by PDS for classes and attributes from the Spectral Discipline Dictionary.

Data Structures and Metadata Requirements

Spectral data comes in a wide variety of formats, only some of which are supported by the Spectral Dictionary. (If you need to use an unsupported data structure application for your spectral data, please do contact the PDS node that will be reviewing and archiving your data so that metadata requirements can be agreed on well in advance of review.)

Four basic data structures are supported, the first of which has a couple of formatting variations. The associated metadata varies a bit from structure to structure.

Typographic Conventions

In defining the metadata requirements here and following, XPath expressions are used. Only very simple XPath expressions will be used to represent the class hierarchy in the label. For example, for all lightwave spectra, the wavelength regime should be indicated. The attribute used to define wavelength regime is in the <Science_Facets> sub-class of the <Primary_Result_Summary> class, which itself is an optional subclass of the <Observation_Area>. (We're going to assume you know where Observation_Area is in a product label.) This attribute may be repeated if a spectrum extends across regimes. So the requirement to specify wavelength regime looks like this:

  • Observation_Area/Primary_Result_Summary/Science_Facets/wavelength_range must be specified (may be repeated)

Classes and attributes in the pds: core namespace will not have a namespace prefix. Classes and attributes from the Spectral Dictionary will be prefixed with "sp:", as they typically would be in labels. So a specific value required for <sp:spectrum_format&gt: would follow this format:

  • sp:Spectral_Characteristics/sp:spectrum_format must be Tabulated-Flat.

Where appropriate, standard values that must be typed exactly will be bold.

General Metadata Requirements

For all data products where the Spectral Discipline Dictionary is employed:

  • Observation_Area/Primary_Result_Summary/Science_Facets/wavelength_range must be specified (may be multi-valued)
  • Observation_Area/Primary_Result_Summary/Science_Facets/discipline_name should be Spectroscopy.
  • The spectral data structure (table or array) must have a <local_identifier>.

Tabulated Spectra

When a table (character, binary, or delimited) contains one spectrum per table record, the spectral structure is referred to as "tabulated". There are three supported format variations for tabulated spectra:

Data Structure: Each spectral bin is defined as a separate Field class - there are no Group_Field classes.
Metadata Requirements:
  • Primary_Result_Summary/Science_Facets/facet1 should be Tabulated
  • sp:Spectral_Characteristics/sp:spectrum_format must be Tabulated-Flat
  • All Field classes must contain valid, unique <field_number> attributes.
  • sp:Spectral_Charateristics/sp:value_field_number_list must be used to identify the measured spectral point values.
Grouped Parameters
Data Structure: Group_Field classes are provided for each type of data so that parameter values are stored contiguously in the record - that is, there is one Group_Field with only a single member Field for the measured intensities, a Group_Field for the bin centers Field, and so on.
Metadata Requirements:
  • Primary_Result_Summary/Science_Facets/facet1 should be Tabulated
  • sp:Spectral_Characteristics/sp:spectrum_format must be Tabulated-Parameter Groups
  • The Field class within the Group_Field for each parameter to be referenced must have a <name> attribute with a unique value.
Grouped Points
Data Structure: A single Group_Field class is used to hold all parameters associated with a single spectral point; the Group_Field contains Field definitions for intensity, bin center, bin width, etc., and that group repeats for the number of points in the spectrum.
Metadata Requirements:
  • Primary_Result_Summary/Science_Facets/facet1 should be Tabulated
  • sp:Spectral_Characteristics/sp:spectrum_format must be Tabulated-Point Groups
  • The Field classes for each parameter to be referenced within the Group_Field must have <name> attributes with unique values.