Quick Introduction to the Spectral Dictionary
The Spectral Discipline Dictionary is used to provide metadata that describes how a light spectrum is presented in a data object. This guide defines the terminology used in the Spectral Dictionary and provides a brief overview of the various methods available for defining the relevant metadata in your product labels.
The reserved abbreviation for the Spectral Dictionary namespace is sp:.
The steward of the Spectral Dictionary is Anne Raugh, at the Small Bodies Node at the University of Maryland.
First off, note that the Spectral Dictionary is designed only for light spectra. More specifically, it is designed to describe wavelength, frequency, and wavenumber spectra. It does not describe mass spectra, time-of-flight spectra, or any spectra that are not the direct result of gathering photons.
Further, the Spectral Dictionary can only handle spectra that are in one of the following data structures:
- A table in which each row of the table contains a complete spectrum ("Tabulated Spectra")
- A table in which each row of the table contains a single point in a spectrum, and the entire table comprises a single spectrum ("1D Spectrum")
- An image array (specifically, an <Array_2D_Spectrum> object) , where either the axes of the array are aligned with the spectral dimensions, or the array contains an image which presents a recorded spectrum
- A stack of images (<Array_3D_Spectrum>), where each plane is a 2D spectrum (as in the previous bullet)
If you have spectral data that doesn't fit those models, talk to your PDS Node consultant about the best course of action.
Terminology and Concepts
The bulk of the Spectral Dictionary is concerned with defining the quantization of the spectrum - in other words, what range of wavelengths (or frequencies, or wavenumbers, as appropriate) is represented by each pixel (or row, or column) along the spectral dimension of the data structure.
The term binning is used to refer to the spectral quantization throughout the Spectral Dictionary, irrespective of data structure. The bin corresponds to the spectral range associate with a single point:
- In tabulated spectra, individual fields represent bins.
- In 1D spectra, each row is a bin.
- In 2D spectra, each pixel along the spectral axis is a bin.
- In 3D spectra, each pixel along the spectral axis (which corresponds to a plane in the perpendicular axes) is a bin
These data structure bins may or may not correspond to the bins of the original detector, either because of re-binning of digital data or digitization of analog data. Regardless, the relationship between detector bins and data structure bins should be well-documented, and in every case when the Spectral Dictionary refers to "bins", it is the data structure bins that are intended.
Field of View (FOV)
In the Spectral Dictionary, field of view or FOV is the generalized terminology used to refer to what is traditionally thought of as the slit or aperture that governs the light path producing the spectrum, which is then recorded by the detector. "Slits" can be complex in structure, so the metadata descriptions are intended to provide good descriptions of traditional slits and apertures, and a heads-up and a reference to details for non-traditional "slits".
If you are working with a complex slit/aperture, you will need a reference (ideally, a reference to something also in the PDS4 archive) to a document that describes it in some detail. You may have to write this document if none exists; including pictures and diagrams is greatly appreciated by users.
It is common for the values defining the spectral bins to be located either in their own data object within the product, or in another product entirely. When a spectral bin parameter is not explicitly stated in the label metadata (and must instead be read from a data file), the term "lookup" is used in the class name even if the data to be "looked up" are in the same data file as the observational data. Details of the look-up class will make it clear where the data reside; PDS4 LID references will be used, when needed, to identify other archive products containing bin parameters.
The full details of the Spectral Dictionary classes are on the Filling Out the Spectral Dictionary Classes page on this wiki. Following is a brief overview.
The Spectral Dictionary is a discipline dictionary. As such, its classes are included in the <Discipline_Area> of your label. You must use the <Spectral_Characteristics> class in order to use any of the other classes and attributes in the Spectral Dictionary. In general, you will only have one <sp:Spectral_Characteristics> class in your label even for data structures (like tabulated spectra and spectral cubes) that contain multiple spectra. For very complex cases, it is (just barely) conceivable that you might need more than one <sp:Spectral_Characteristics> class in a single label, but check with your PDS Node consultant first.
- (For this and the rest of this discussion, I'm going to elide the "sp:" prefix in the interest of clarity for explanations, but bear in mind that all the attributes and classes described below must be placed in the Spectral namespace in PDS4 labels. If that sounds like gibberish to you, see the Using Local Dictionaries page on this wiki.)
At the top of the Spectral_Characteristics class is a <pds:Local_Internal_Reference> class that identifies the data object containing the spectral data described by the rest of the class. Following that, the Spectral_Characteristics class has four major sections (in order):
- Spectrum type parameters: These attributes at the top of the Spectral_Characteristics class identify the data structure (tabulated, 1D, 2D, etc.), the spectral bin type (wavelength, frequency, or wavenumber), and for tabulated spectra the location of the recorded values for each spectral bin.
- <Observation_Parameters>: This class contains attributes related to: how the data were collected (integration time, number of exposures); the detector (resolution limit); and calibration, where appropriate (calibration star names).
- <Field_of_View>: This class is for describing the field of view. There are subclasses for the simple cases (circular and rectangular), and a more general class for complex FOVs. If you have a complex FOV, this is where you provide a test description for users and a link to the more detailed documentation.
- <Bin_Description>: This is the class where you define how the spectral data is binned. The first field is a text description in which you should describe how the bin parameters were determined.
The <Bin_Description> Subclass
Bin description being the primary function of the Spectral Dictionary, the <Bin_Description> class provides three different methods for specifying the bin centers and widths: explicit definition; calculation; and look-up.
- <Axis_Bin_Set> - Explicit Definition
- The <Axis_Bin_Set> class and its subclasses are used to provide specific parameters for each bin along the spectral dimension. The bins must be labeled with a sequence number, and at a minimum the center and bin width must be provided. In this case you may also identify a specific filter, grating setting, or detector associated with the bin.
- <Uniformly_Sampled> - Calculation
- The <Uniformly_Sampled> class lets you define your bins mathematically, by indicating the first and last bin centers and defining the intervening interval. In this case bin width is assumed to be uniform as well, and you specify it as a constant.
- <Spectral_Lookup> - Look-up
- The <Spectral_Lookup> class is used to direct a user (or program) to a file location where the bin center and width data can be programmatically read. The parameters can be referenced as fields within a spectral table, as data objects within the same file via a <pds:Local_Internal_Reference> class, or as data objects in another PDS archive product via a <pds:Internal_Reference> class.
Unknown Bin Widths
As of Spectral Dictionary version 188.8.131.52:
- In those rare cases where the bin widths are not known and cannot be determined, the bin width attributes within the Axis_Bin_Set and Uniformly_Sampled options can be declared to be nil with a reason of "unknown". Examples of how to do this are included in the main Spectral Dictionary page on this wiki.
- For the Spectral_Lookup case where no widths are available to look up, a Bin_Width_Constant option has been added to the <Spectral_Lookup> class that can either be used to indicate a constant nominal bin width, or to explicitly declare the bin widths as nil (and unknown).