Difference between revisions of "Quick Introduction to the Spectral Dictionary"

From The SBN Wiki
Jump to navigation Jump to search
(Safety Save)
Line 57: Line 57:
  
 
# '''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.  
 
# '''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>:'''
+
# '''<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>:'''
+
# '''<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>:'''
+
# '''<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 ''&lt;Bin_Description&gt;'' class provides three different methods for specifying the bin centers and widths: explicit definition; uniform sampling calculation; and look-up.
 +
 
 +
==== Explicit Definition: <Axis_Bin_Set> ====
 +
 
 +
The ''&lt;Axis_Bin_Set&gt;'' 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.
 +
 
 +
==== Uniform Sampling Calculation: <Uniformly_Sampled> ====
 +
 
 +
The ''&lt;Uniformly_Sampled&gt;'' 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.
 +
 
 +
==== Look-up: <Spectral_Lookup> ====
 +
 
 +
The ''&lt;Spectral_Lookup&gt;'' 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 ''&lt;pds:Local_Internal_Reference&gt;'' class, or as data objects in another PDS archive product via a ''&lt;pds:Internal_Reference&gt;'' class.

Revision as of 15:49, 2 May 2019

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.

Preliminaries

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.

Spectral "Bins"

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.

Look-up

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.

Label Structures

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.

<Spectral_Characteristics>

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):

  1. 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.
  2. <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).
  3. <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.
  4. <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; uniform sampling calculation; and look-up.

Explicit Definition: <Axis_Bin_Set>

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.

Uniform Sampling Calculation: <Uniformly_Sampled>

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.

Look-up: <Spectral_Lookup>

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.