Difference between revisions of "Filling Out the Old Spectral Dictionary Classes"

From The SBN Wiki
Jump to navigation Jump to search
m
m (Raugh moved page Filling Out the Spectral Dictionary Classes to Filling Out the Old Spectral Dictionary Classes without leaving a redirect: Replaced with new dictionary version)
 
(One intermediate revision by the same user not shown)
Line 250: Line 250:
  
 
This attribute contains a number, specifically an integer, by which this filter is identified - typically a sequential number in a filter wheel.
 
This attribute contains a number, specifically an integer, by which this filter is identified - typically a sequential number in a filter wheel.
 +
 +
 +
=== <Spectral_Lookup> ===
 +
----
 +
''OPTIONAL''
 +
 +
: ''[But '''''NOTE''''' that at least one of ''<Axis_Uniformly_Sampled>'', ''<Axis_Bin_Set>'', and ''<Spectral_Lookup>'' '''must''' be specified.]''
 +
 +
When the spectral bin characteristics are provided as a 2 dimensional look-up map, either as separate products or as data objects in the same product as the spectrum, use this class to provide a link to those look-up map.
 +
 +
This class must contain two subclasses - either ''Local_Internal_Reference'' or ''Internal_Reference''.  One of the subclasses must lead to the bin centers, the other to the bin widths.
 +
 +
==== <Local_Internal_Reference> ====
 +
 +
''OPTIONAL''
 +
 +
Use this class to indicate that another data object in this label contains either the bin centers or widths.
 +
 +
===== <local_identifier_reference> =====
 +
 +
''REQUIRED''
 +
 +
This attribute must contain the value of a ''<local_identifier>'' attribute found in another high-level data object class in this file (like an ''Array_2D_Image'', for example).
 +
 +
===== <local_reference_type> =====
 +
 +
''REQUIRED''
 +
 +
This must have one of the following values:
 +
 +
* '''spectral_characteristics_to_bin_center_values'''
 +
* '''spectral_characteristics_to_bin_width_values'''
 +
 +
===== <comment> =====
 +
 +
''OPTIONAL''
 +
 +
If there are any caveats or other situations worth noting, here's the place to note them.
 +
 +
 +
==== <Internal_Reference> ====
 +
 +
''OPTIONAL''
 +
 +
Use this class to indicate that the look-up information is in another product in the PDS.
 +
 +
Note that, while the class name ''Internal_Reference'' is in the Spectral Dictionary namespace, the attributes within it all come from the PDS core namespace.  You will need to specify the change in namespace.  This can get rather complicated, depending on how you've set up your label to reference different namespaces.  See the [[Using Local Dictionaries]] page on this wiki for gory details on that.  For the purposes of this description, we'll indicate the attributes in the PDS core namespace by adding an explicit "pds:" namespace abbreviation prefix to them.
 +
 +
===== <pds:lid_reference> or <pds:lidvid_reference> =====
 +
 +
''REQUIRED''
 +
 +
Exactly one of these must be present to indicate the logical identifier (and version, as applicable) of the PDS4 product containing the information indicated by ''<pds:reference_type>''.  If there is a chance the bin descriptions might change, then use the ''lidvid_reference", which includes a specific version number.
 +
 +
===== <pds:reference_type> =====
 +
 +
''REQUIRED''
 +
 +
This must have one of these two values:
 +
 +
* '''spectral_characteristics_to_bin_center_values'''
 +
* '''spectral_characteristics_to_bin_width_values'''
 +
 +
===== <pds:comment> =====
 +
 +
''OPTIONAL''
 +
 +
This attribute allows you to provide additional information, as appropriate, about the product being referenced or its application to the product in hand.

Latest revision as of 13:03, 31 July 2018

The Spectral Discipline Dictionary contains classes used in the <Discipline_Area> of a label to describe the spectral characteristics of an array-type data object.

This page was created for the 1.1.0.0 version of the Spectral Discipline Dictionary.

<Spectral_Characteristics>

This is the wrapper class that should be used to identifier all the classes relevant to a single spectral data object. If your product contains spectral objects with differing characteristics, then this class should be repeated once for each unique set of characteristics. You can also indicate that the characteristics in this class apply to more than one spectrum in the product, when that is the case.


<comment>


OPTIONAL

This is a place for additional free-format text description, as needed.


<bin_width_desc>


REQUIRED

You must supply a description of how the bin width for this spectrum was determined or calculated. Include the shape of the bin (gaussian, square wave, etc.) and define what "bin width" means (e.g., full width at half max).


<Local_Internal_Reference>


REQUIRED

This class provides a reference to a spectral data object elsewhere in the label. It may be repeated for each spectral data object sharing these characteristics.

<local_identifier_reference>

REQUIRED

The value of this attribute must correspond to the value of a <local_identifier> attribute in one of the spectral data objects defined elsewhere in this product label. Case counts.

<local_reference_type>

REQUIRED

This attribute must have the value spectral_characteristics_to_array_object

<comment>

OPTIONAL

A place for free-format text notes to users.


<Axis_Uniformly_Sampled>


OPTIONAL

[But NOTE that at least one of <Axis_Uniformly_Sampled>, <Axis_Bin_Set>, and <Spectral_Lookup> must be specified.]

Use this class when the spectrum is uniformly sampled (i.e., in such a way that the bin centers and widths can be calculated) along an axis. You may repeat this class for each axis that is uniformly sample, if there is more than one.

<sampling_parameter_type>

REQUIRED

This attribute must contain one of the following values:

  • frequency
  • wavelength
  • wavenumber

<sampling_interval>

REQUIRED

This value indicates the point-to-point difference in the sampling bins in units appropriate to the sampling_parameter_type. You must specify the correct unit as an XML attribute. So, for example:

<sampling_interval unit="Hz">52</sampling_interval>

...assuming the sampling_parameter_type was "frequency".

Valid units for each sampling_parameter_type are (spelling and case count):

frequency
  • Hz
wavelength
  • Angstrom
  • cm
  • m
  • micrometer
  • mm
  • nm
wavenumber
  • 1/cm
  • 1/m
  • 1/nm

<bin_width>

REQUIRED

This attribute specifies the total width of a bin, in the same units as used for sampling_interval. You must specify the unit.

<first_center_value>

REQUIRED

This attribute is the value of the sampling parameter at the center of the first spectral bin, in the same units as used for sampling_interval. You must specify the unit.

<last_center_value>

REQUIRED

This attribute is the value of the sampling parameter at the center of the last spectral bin, in the same units as used for sampling_interval. You must specify the unit.

Note: While all the above are required, including both first and last bin center values, as of this writing no validation is done to insure that the first and last values have the correct mathematical relationship.

<Local_Internal_Reference>

REQUIRED

This class provides a reference to a specific axis named elsewhere in the label. It may be repeated in the extremely unlikely even that you have two axes which are uniformly sampled in precisely the same way.

<local_identifier_reference>

REQUIRED

The value of this attribute must correspond to the value of an <axis_name> attribute in one of the spectral data objects defined elsewhere in this product label. Case counts.

<local_reference_type>

REQUIRED

This attribute must have the value spectral_characteristics_to_array_axis

<comment>

OPTIONAL

A place for free-format text notes to users.


<Axis_Bin_Set>


OPTIONAL

[But NOTE that at least one of <Axis_Uniformly_Sampled>, <Axis_Bin_Set>, and <Spectral_Lookup> must be specified.]

Use this class to describe the unique characteristics of each bin increment along a named spectral axis of the referenced array.

<Local_Internal_Reference>

REQUIRED

This class provides a reference to a specific axis named elsewhere in the label. It may be repeated in the extremely unlikely even that you have two axes which are uniformly sampled in precisely the same way.

<local_identifier_reference>

REQUIRED

The value of this attribute must correspond to the value of an <axis_name> attribute in one of the spectral data objects defined elsewhere in this product label. Case counts.

<local_reference_type>

REQUIRED

This attribute must have the value spectral_characteristics_to_array_axis

<comment>

OPTIONAL

A place for free-format text notes to users.

<Bin>

REQUIRED

This class gives the characteristics of an individual spectral bin. It should be repeated for each bin along the spectral axis (i.e., the number of <Bin> classes should be equal to the number of elements in the axis identified by the associated <Local_Identifier_Reference>.

<bin_sequence_number>

REQUIRED

This attribute indicates the the order of the bins along the specified axis.

Note: If you are preparing data for SBN, then bin sequence numbers must start with 1 (one) and be monotonically increasing as you read down the label.
<center_value>

REQUIRED

This attribute defines the center of the bin as either a frequency, wavelength, or wavenumber. You must specify an appropriate unit, and you must use the same unit for all center_value attributes and all bin_wdith values in this <Axis_Bin_Set> class.

Valid units for each type of bin are (spelling and case count):

frequency
  • Hz
wavelength
  • Angstrom
  • cm
  • m
  • micrometer
  • mm
  • nm
wavenumber
  • 1/cm
  • 1/m
  • 1/nm
<bin_width>

REQUIRED

This attribute defines the full width of the particular spectral bin, in the same units as the preceding center_value. You must specify the unit.

<detector_number>

OPTIONAL

This attribute is for specifying the spectrometer detector number corresponding to this band in a spectral cube.

<grating_position>

OPTIONAL

This attribute is used for specifying grating position as a code number in spectral cubes. Typically these numbers start with 0 and increase with wavelength.

<original_bin_number>

OPTIONAL

This attribute is used for documenting spectral objects that represent a subset of some larger object. The number here corresponds to the <bin_sequence_number> of this band in the source data.

<Filter>

OPTIONAL

This class provides a way to identify a specific filter by name and/or number.

<filter_name>

OPTIONAL

This attribute contains a name (a string) by which the filter is known, either popularly or in any associated documentation.

<filter_number>

OPTIONAL

This attribute contains a number, specifically an integer, by which this filter is identified - typically a sequential number in a filter wheel.


<Spectral_Lookup>


OPTIONAL

[But NOTE that at least one of <Axis_Uniformly_Sampled>, <Axis_Bin_Set>, and <Spectral_Lookup> must be specified.]

When the spectral bin characteristics are provided as a 2 dimensional look-up map, either as separate products or as data objects in the same product as the spectrum, use this class to provide a link to those look-up map.

This class must contain two subclasses - either Local_Internal_Reference or Internal_Reference. One of the subclasses must lead to the bin centers, the other to the bin widths.

<Local_Internal_Reference>

OPTIONAL

Use this class to indicate that another data object in this label contains either the bin centers or widths.

<local_identifier_reference>

REQUIRED

This attribute must contain the value of a <local_identifier> attribute found in another high-level data object class in this file (like an Array_2D_Image, for example).

<local_reference_type>

REQUIRED

This must have one of the following values:

  • spectral_characteristics_to_bin_center_values
  • spectral_characteristics_to_bin_width_values
<comment>

OPTIONAL

If there are any caveats or other situations worth noting, here's the place to note them.


<Internal_Reference>

OPTIONAL

Use this class to indicate that the look-up information is in another product in the PDS.

Note that, while the class name Internal_Reference is in the Spectral Dictionary namespace, the attributes within it all come from the PDS core namespace. You will need to specify the change in namespace. This can get rather complicated, depending on how you've set up your label to reference different namespaces. See the Using Local Dictionaries page on this wiki for gory details on that. For the purposes of this description, we'll indicate the attributes in the PDS core namespace by adding an explicit "pds:" namespace abbreviation prefix to them.

<pds:lid_reference> or <pds:lidvid_reference>

REQUIRED

Exactly one of these must be present to indicate the logical identifier (and version, as applicable) of the PDS4 product containing the information indicated by <pds:reference_type>. If there is a chance the bin descriptions might change, then use the lidvid_reference", which includes a specific version number.

<pds:reference_type>

REQUIRED

This must have one of these two values:

  • spectral_characteristics_to_bin_center_values
  • spectral_characteristics_to_bin_width_values
<pds:comment>

OPTIONAL

This attribute allows you to provide additional information, as appropriate, about the product being referenced or its application to the product in hand.