Filling Out the Spectral Dictionary Classes

From The SBN Wiki
Revision as of 00:42, 21 April 2017 by Raugh (talk | contribs) ()
Jump to navigation Jump to search

The Spectral Dictionary is a discipline dictionary, which means that its classes will appear in the <Discipline_Are> at the bottom of the <Observation_Area> in observational product labels (and in the <Context_Area>, if appropriate, in non-observational products). The classes in this dictionary describe the spectral characteristics of the data objects presented in the product.

The standard abbreviation for the Spectral Discipline Dictionary namespace is "sp:". Typically, every class and attribute from this dictionary would be prefixed with the "sp:" abbreviation, but this has been omitted in these pages in the interest of readability. See the "Namespace References" section of the "Schema Reference in PDS4 Labels" page for additional information on ways of typing attributes and classes to namespaces.

Update: 19 April 2017 - begin re-write for new Spectral Dictionary nearing the end of development

<Spectral_Characteristics>

REQUIRED

This is the wrapper class for spectral characteristics. Repeat it once for each spectral-type object you have in your observational product. The Spectral Discipline Dictionary can currently accommodate spectra measured in wavelength, wavenumber, and frequency that are presented as either image cubes, images, or tables (i.e., linear spectra where each row presents one point in the spectrum).

If you have a different type of spectrum, contact Anne Raugh at the Small Bodies Node at the University of Maryland for assistance.

<comment>

OPTIONAL

This is a free-format text field you can use to provide any additional explanation or caveats about the information that follows that would be helpful to an end user.

<pds:Local_Internal_Reference>

REQUIRED

Use this class to identify the spectral-type data object in this product for which this class provides the characteristics. Typically, an observational product will contain only a single spectral object (though it might be a spectral cube). This class is required even in that case.

Note that this class and its elements are in the pds: core namespace, rather than the Spectral Dictionary namespace, so you will need to make the appropriate change of namespace for this class. See "Schema Referencing in PDS4 Labels: Namespace References" for details.

<pds:comment>

OPTIONAL

This is a free-format text field that you can use if there is something about the relationship between the referenced spectrum and its characteristics that requires additional explanation.

<pds:local_identifier_reference>

REQUIRED

This attribute must contain a <local_identifier> string of a spectral data object described elsewhere in this label. Spelling and capitalization count.

<pds:local_reference_type>

OPTIONAL

This attribute must have one of these values:

  • spectral_characteristics_to_array_object
  • spectral_characteristics_to_table_object

The value you use must correspond to the type of the data object you're linking to. So if your local_identifier points to an Array_2D_Spectrum then the local_reference_type must be spectral_characteristics_to_array_object. If your local_identifier points to a linear spectrum in a Table_Character object, then the local_reference_type must be spectral_characteristics_to_table_object.

<spectral_bin_type>

REQUIRED

This attribute indicates the unit of measure for the spectral bin dimensions. It must be one of the following vaues:

  • frequency
  • wavelength
  • wavenumber

The bin descriptions you provide in the subsequent classes and attributes must correspond to the spectral_bin_type specified here.

<Target_Parameters>

OPTIONAL

This class provides known spectral attributes of the target observed (as identified in the <Target_Identification> area of the label). The class may be omitted if it is not needed.

<apparent_magnitude>

OPTIONAL

This attribute provides the apparent magnitude of the target at the time of the observation.

<apparent_magnitude_band_name>

OPTIONAL

This attribute provides the band name or filter ID in which the apparent_magnitude was measured


<Observation_Parameters>

REQUIRED

This class is required to be present and includes various attributes related to the observing circumstances.

<number_of_exposures>

REQUIRED

This attribute indicates the number of individual exposures or distinct integrations were combined to produce the spectrum in the data object.

<net_integration_time>

REQUIRED

The net_integration_time is the sum total of the exposure/integration times for all exposures combined to produce this spectrum.

<spectral_resolution_frequency> or <spectral_resolution_wavelength> or <spectral_resolution_wavenumber>

REQUIRED

One of these attributes must be provided to indicate the smallest possible distinguishable interval in frequency for the instrument in units corresponding to the spectral_bin_type indicated in the parent class. If the spectral resolution is unknown, use the corresponding type of spectral resolution, but set it to

<solar_analog_star_name>

OPTIONAL

The solar_analog_star_name attribute provides a name in a standard format (i.e., one that is recognized by the SIMBAD system) for the solar analog star used to reduce the raw spectral data to the reflectance units presented in this spectrum. You may repeat this attribute if needed.


<Slit_Parameters>

REQUIRED

This class contains attributes to characterize the slit and its projection on the sky. At the least, you must supply the angular slit width.

<slit_position_angle>

OPTIONAL

The slit_position_angle attribute provides the angle the long axis of the slit makes with respect to celestial north, measured eastward of celestial north in the range 0-180 degrees.

<slit_width_angle>

REQUIRED

The slit_width_angle is the angle subtended on the sky by the short dimension of a simple slit.

<slit_length_angle>

OPTIONAL

The slit_length_angle attribute provides the angle subtended on the sky by the long dimension of a simple slit.

<slit_description>

OPTIONAL

The slit_description attribute provides a free-format text field where you can provide a description of the slit shape. This should only be used for cases where the slit is something other than a simple, rectangular slit. For complex slit descriptions, provide a reference to a detailed document using the (optional) <pds:Internal_Reference> class, following.

<pds:Internal_Reference>

OPTIONAL

Use this class to link to a document that provides a detailed description of the slit. This could be a text description, a graphic representation, or a larger document (an instrument SIS for example) that includes this information. Use the pds:comment field to indicate a specific section or page if you are referencing a part of a larger document. This class may be repeated, if needed.

Note that, like the <pds:Local_Internal_Reference> above, this class and its attributes are in the pds: namespace.

<pds:lid_reference> or <pds:lidvid_reference>

REQUIRED

Either a logical identifier without a version number (a "LID"), or a logical identifier with a version number (a "LIDVID"), must be provided for the product you wish to reference. You may not provide both, or repeat this attribute.

<pds:reference_type>

REQUIRED

This attribute must have the value spectral_characteristics_to_document.

<pds:comment>

OPTIONAL

This is a free-format text field in which you can provide additional explanation for why you're referencing the previously mentioned product. If the relevant information is actually in a subsection of the document (rather than comprising the whole document) a section number or page range reference would be an excellent thing to include here.