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

From The SBN Wiki
Jump to navigation Jump to search
(Safety Save)
(Update - Safety Save)
Line 1: Line 1:
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 Spectral Dictionary is a ''discipline dictionary'', which means that its classes will appear in the ''<Discipline_Area>'' 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 [[Schema_Referencing_in_PDS4_Labels#Namespace_References|"Namespace References"]] section of the [[Schema_Referencing_in_PDS4_Labels|"Schema Reference in PDS4 Labels"]] page for additional information on ways of typing attributes and classes to namespaces.
 
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 [[Schema_Referencing_in_PDS4_Labels#Namespace_References|"Namespace References"]] section of the [[Schema_Referencing_in_PDS4_Labels|"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''
+
Note that data products that contain spectra should generally have a ''<Primary_Result_Summary>'' class (in the ''Observation_Area'') that contains the ''<Science_Facets>'' subclass with a ''<discipline>'' value of '''Spectroscopy''' and a ''<facet1>'' value corresponding to the ''spectrum_format'' attribute described below.
 +
 
 +
''Update: 01 August 2017 - continuing re-write for new Spectral Dictionary nearing the end of development''
  
 
= <Spectral_Characteristics> =
 
= <Spectral_Characteristics> =
Line 12: Line 14:
  
 
If you have a different type of spectrum, contact Anne Raugh at the Small Bodies Node at the University of Maryland for assistance.
 
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> ==
 
== <pds:Local_Internal_Reference> ==
Line 47: Line 43:
 
* '''spectral_characteristics_to_table_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'''.
 
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'''.
 +
 +
== <description> ==
 +
 +
''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.
 +
 +
== <spectrum_format> ==
 +
 +
''REQUIRED''
 +
 +
This attribute indicates the dimensionality of the spectrum.  It must contain one of the values '''1D''', '''2D''', or '''3D''', and when the ''&lt;Primary_Result_Summary&gt;'' is present, the ''&lt;Science_Facets&gt;/&lt;discipline&gt;'' value should be '''Spectroscopy''' and the ''&lt;Science_Facets&gt;/&lt;facet1&gt;'' value should correspond:
 +
:;1D
 +
:: The spectrum is linear; presented as a table object where each row contains the information about one point in the spectrum.  ''&lt;facet1&gt;'' should have a value of '''Linear'''.
 +
:;2D
 +
:: The spectrum is in an ''Array_2D_Spectrum'' object.  In this case ''&lt;facet1&gt;'' might contain either ''2D'' or ''Spectral Image'', depending on whether or not, respectively, the image axes align with the spectral axes.
 +
:;3D
 +
:: The spectrum is in an ''Array_3D_Spectrum'' object.  The value of ''&lt;facet1&gt;'' should be '''Spectral Cube'''.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
This is not currently validated.  Type carefully.
 +
|}
 +
 +
== <value_field_name> ==
 +
 +
''REQUIRED'' for 1D format spectrum; otherwise ''PROHIBITED''
 +
 +
This attribute is required if ''&lt;spectrum_format&gt;'' is '''1D''', and forbidden otherwise.  For 1D spectra, you must indicate which field in the table actually contains the measured spectral value.  The value of the ''&lt;name&gt;'' attribute from the ''Field_Character'' definition is specified as the value of this attribute.
  
 
== <spectral_bin_type> ==
 
== <spectral_bin_type> ==
Line 80: Line 105:
 
''REQUIRED''
 
''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 "nil" with a ''nilReason'' of "unknown".  For example, if the spectral resolution of a wavelength spectrum is unknown, do something like this:
+
One of these attributes must be provided to indicate the smallest possible distinguishable spectral interval 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 "nil" with a ''nilReason'' of "unknown".  For example, if the spectral resolution of a wavelength spectrum is unknown, do something like this:
 
::<code>&lt;spectral_resolution_wavelength unit="Angstrom" xsi:nil="true" nilReason="unknown"/&gt;</code>
 
::<code>&lt;spectral_resolution_wavelength unit="Angstrom" xsi:nil="true" nilReason="unknown"/&gt;</code>
 
(Yes, the ''unit'' part is required - this is a quirk of the attribute definition we just have to roll with for now.)
 
(Yes, the ''unit'' part is required - this is a quirk of the attribute definition we just have to roll with for now.)
Line 88: Line 113:
 
''OPTIONAL''
 
''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.
+
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 for additional starts.  ''Do not'' repeat this attribute to provide alternate names for the same star.
  
 
=== <absolute_calibration_star_name> ===
 
=== <absolute_calibration_star_name> ===
Line 94: Line 119:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute provides a name in a standard format (i.e., one that is recognized by the SIMBAD system) for the star used to reduce the raw spectral data to the (non-reflectance) units presented in this spectrum.  You may repeat this attribute if needed.
+
This attribute provides a name in a standard format (i.e., one that is recognized by the SIMBAD system) for the star used to reduce the raw spectral data to the (non-reflectance) units presented in this spectrum.  You may repeat this attribute if needed for additional starts.  ''Do not'' repeat this attribute to provide alternate names for the same star.
  
 
== <Field_of_View> ==
 
== <Field_of_View> ==
Line 100: Line 125:
 
''REQUIRED''
 
''REQUIRED''
  
This class describes the aperture or slit used to make the observation.  Exactly one of the "FOV" sub-classes ''must'' be present.
+
This class describes the aperture or slit used to make the observation.  One of the "*_FOV" sub-classes ''must'' be present.
  
 
=== <description> ===
 
=== <description> ===
Line 106: Line 131:
 
''REQUIRED''
 
''REQUIRED''
  
This is a text description of the slit.  Often this will be a simple sentence.  In the case of a complex aperture shape, though, this should be more expansive.
+
This is a text description of the slit.  Often this will be a simple sentence.  In the case of a complex aperture shape, though, this should be more expansive.
  
 
=== <Circular_FOV> ===
 
=== <Circular_FOV> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
''One of ''Circular_FOV'', ''Rectangular_FOV'', and ''Complex_FOV'' must be specified.''
  
 
This class indicates a circular aperture and defines the angular diameter of the field.
 
This class indicates a circular aperture and defines the angular diameter of the field.
Line 118: Line 145:
 
''REQUIRED''
 
''REQUIRED''
  
The angle subtended on the sky of the diameter of the aperture.  You must specify units of angle.
+
The angle subtended on the sky by the diameter of the aperture.  You must specify units of angle.
  
 
=== <Rectangular_FOV> ===
 
=== <Rectangular_FOV> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
''One of ''Circular_FOV'', ''Rectangular_FOV'', and ''Complex_FOV'' must be specified.''
  
 
This class is used to describe a rectangular field of view, as for a traditional simple slit.
 
This class is used to describe a rectangular field of view, as for a traditional simple slit.
Line 149: Line 178:
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
''One of ''Circular_FOV'', ''Rectangular_FOV'', and ''Complex_FOV'' must be specified.''
  
 
This class is used to provide some level of description for a complex aperture.  As much as makes sense to include should be included.
 
This class is used to provide some level of description for a complex aperture.  As much as makes sense to include should be included.
Line 176: Line 207:
 
''OPTIONAL''
 
''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.
+
Use this class to link to a document that provides a detailed description of the slit or field of view.  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.
  
 
While technically optional, it is hard to imagine a data product with a complex aperture passing review without a good description of the aperture shape and size being included.
 
While technically optional, it is hard to imagine a data product with a complex aperture passing review without a good description of the aperture shape and size being included.
Line 203: Line 234:
 
== <Bin_Description> ==
 
== <Bin_Description> ==
  
This class provides four different ways to define the spectral bin characteristics: implicitly, as a uniformly sampled set; explicitly, as individual bin descriptions provided in the label; or externally, in another data object in this product or even in a separate product altogether.  You are required to provide at least a minimal text description of the bins.  To pass review, most data products will require a more precise description.  Check with your PDS node consultant if you have any questions or doubts.
+
This class provides four different ways to define the spectral bin characteristics: nominally, as a constant; implicitly, as a uniformly sampled set; explicitly, as individual bin descriptions provided in the label; or externally, in another data object in this product or even in a separate product altogether.  You are required to provide at least a minimal text description of the bin profiles (how the bin widths were determined).  To pass review, most data products will require a more precise description.  Check with your PDS node consultant if you have any questions or doubts.
  
=== <bin_width_desc> ===
+
=== <bin_profile_description> ===
  
 
''REQUIRED''
 
''REQUIRED''
  
This is a free-format text field for describing the spectral bins.  It is required to be present and non-null. It does not need to be exhaustive - it just needs to provide a user with the essential details needed to understand the spectrum.  So do include things like bandpass shape or how the bins were defined for analysis and data reduction.  If the situation is complicated but well-documented, use the ''&lt;Reference_list&gt;'' class in the upper part of the product label to include an explicit reference to the explanatory document.  If the situation is complicated but not well-documented, please consider writing that document and then referencing it.
+
This is a free-format text field for describing the shape of the spectral bins and how their "widths", defined in the following attributes, were determined.  It is required to be present and non-null. It does not need to be exhaustive - it just needs to provide a user with the essential details needed to understand the spectrum.  If the situation is complicated but well-documented, the ''&lt;pds:Reference_List&gt;'' class in the upper part of the product label should include an explicit reference to the explanatory document elsewhere in the archive or in the literature.  If the situation is complicated but not well-documented, please consider writing that document, archiving it, and then referencing it.
  
 
=== <Bin_Width_Constant> ===
 
=== <Bin_Width_Constant> ===
Line 215: Line 246:
 
''OPTIONAL''
 
''OPTIONAL''
  
This class is used for those cases where the bin width is actually constant, as well as when it is not well know and thus approximated by a constant, or is unknown.  This class should contain exactly one attribute, corresponding the the spectral type.  If the bin width is unknown, then that attribute should be declared "nil" with a reason of "unknown", and the ''&lt;bin_width_description&gt;'' attribute should provide as much information as is known (or an explanation of why nothing is known).
+
This class is used for those cases where the bin width is actually constant, as well as when it is not well know and thus approximated by a constant, or is unknown.  This class should contain exactly one attribute, corresponding the the spectral type.  If the bin width is unknown, then that attribute should be declared "nil" with a reason of "unknown", and the ''&lt;bin_profile_description&gt;'' attribute should provide as much information as is known (or an explanation of why nothing is known).
  
==== <bin_width_frequency> ====
+
==== <bin_width_frequency> ''or'' <bin_width_wavelenght> ''or'' <bin_width_wavenumber> ====
  
''OPTIONAL''
+
''REQUIRED''
 
 
Use this attribute for the bin width when the ''&lt;spectral_type&gt;'' is '''frequency'''.
 
 
 
==== <bin_width_wavelength> ====
 
 
 
''OPTIONAL''
 
 
 
Use this attribute for the bin width when the ''&lt;spectral_type&gt;'' is '''wavelength'''.
 
 
 
==== <bin_width_wavenumber> ====
 
 
 
''OPTIONAL''
 
 
 
Use this attribute for the bin width when the ''&lt;spectral_type&gt;'' is '''wavenumber'''.
 
  
 +
Exactly one of these attributes is required.  The attribute must correspond to the ''&lt;spectral_type&gt;'' value.
  
 
=== <Uniformly_Sampled_[unit]> ===
 
=== <Uniformly_Sampled_[unit]> ===

Revision as of 21:10, 1 August 2017

The Spectral Dictionary is a discipline dictionary, which means that its classes will appear in the <Discipline_Area> 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.

Note that data products that contain spectra should generally have a <Primary_Result_Summary> class (in the Observation_Area) that contains the <Science_Facets> subclass with a <discipline> value of Spectroscopy and a <facet1> value corresponding to the spectrum_format attribute described below.

Update: 01 August 2017 - continuing re-write for new Spectral Dictionary nearing the end of development

Contents

<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.

<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.

<description>

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.

<spectrum_format>

REQUIRED

This attribute indicates the dimensionality of the spectrum. It must contain one of the values 1D, 2D, or 3D, and when the <Primary_Result_Summary> is present, the <Science_Facets>/<discipline> value should be Spectroscopy and the <Science_Facets>/<facet1> value should correspond:

1D
The spectrum is linear; presented as a table object where each row contains the information about one point in the spectrum. <facet1> should have a value of Linear.
2D
The spectrum is in an Array_2D_Spectrum object. In this case <facet1> might contain either 2D or Spectral Image, depending on whether or not, respectively, the image axes align with the spectral axes.
3D
The spectrum is in an Array_3D_Spectrum object. The value of <facet1> should be Spectral Cube.

This is not currently validated. Type carefully.

<value_field_name>

REQUIRED for 1D format spectrum; otherwise PROHIBITED

This attribute is required if <spectrum_format> is 1D, and forbidden otherwise. For 1D spectra, you must indicate which field in the table actually contains the measured spectral value. The value of the <name> attribute from the Field_Character definition is specified as the value of this attribute.

<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.

<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 that 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 spectral interval 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 "nil" with a nilReason of "unknown". For example, if the spectral resolution of a wavelength spectrum is unknown, do something like this:

<spectral_resolution_wavelength unit="Angstrom" xsi:nil="true" nilReason="unknown"/>

(Yes, the unit part is required - this is a quirk of the attribute definition we just have to roll with for now.)

<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 for additional starts. Do not repeat this attribute to provide alternate names for the same star.

<absolute_calibration_star_name>

OPTIONAL

This attribute provides a name in a standard format (i.e., one that is recognized by the SIMBAD system) for the star used to reduce the raw spectral data to the (non-reflectance) units presented in this spectrum. You may repeat this attribute if needed for additional starts. Do not repeat this attribute to provide alternate names for the same star.

<Field_of_View>

REQUIRED

This class describes the aperture or slit used to make the observation. One of the "*_FOV" sub-classes must be present.

<description>

REQUIRED

This is a text description of the slit. Often this will be a simple sentence. In the case of a complex aperture shape, though, this should be more expansive.

<Circular_FOV>

OPTIONAL

One of Circular_FOV, Rectangular_FOV, and Complex_FOV must be specified.

This class indicates a circular aperture and defines the angular diameter of the field.

<diameter_angle>

REQUIRED

The angle subtended on the sky by the diameter of the aperture. You must specify units of angle.

<Rectangular_FOV>

OPTIONAL

One of Circular_FOV, Rectangular_FOV, and Complex_FOV must be specified.

This class is used to describe a rectangular field of view, as for a traditional simple slit.

<width_angle>

REQUIRED

The width_angle is the angle subtended on the sky by the short dimension of a simple slit. On those extremely rare occasions where this value is unknown, it may be defined as "nil" with a reason of "unknown":

<width_angle xsi:nil="true" nilReason="unknown"/>

In this case, as much as is known about the slit should be included in the <description> attribute of the containing class.

<length_angle>

REQUIRED

The length_angle attribute provides the angle subtended on the sky by the long dimension of a simple slit. When it is not known, it can be defined as "nil" (see width_angle, above).

<position_angle>

REQUIRED

The 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. In the very unlikely event that this is not known, it can be declared as "nil" (see width_angle, above).

<Complex_FOV>

OPTIONAL

One of Circular_FOV, Rectangular_FOV, and Complex_FOV must be specified.

This class is used to provide some level of description for a complex aperture. As much as makes sense to include should be included.

<width_angle>

OPTIONAL

If there is an applicable "width" for the aperture, it can be specified here as a subtended angle. This value can be repeated, if that makes sense.

<length_angle>

OPTIONAL

If there is an applicable "length" for the aperture, it can be specified here as a subtended angle. This value can be repeated, if that makes sense.

<position_angle>

REQUIRED

This attribute specifies the angle that the long axis makes with respect to celestial north, measured eastward of celestial north in the range 0-180 degrees. If appropriate, this attribute can be defined as "nil", either because it is unknown, or because the concept is not applicable. For example:

<position_angle unit="degree" xsi:nil="true" nilReason="inapplicable"/>


<pds:Internal_Reference>

OPTIONAL

Use this class to link to a document that provides a detailed description of the slit or field of view. 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.

While technically optional, it is hard to imagine a data product with a complex aperture passing review without a good description of the aperture shape and size being included.

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.


<Bin_Description>

This class provides four different ways to define the spectral bin characteristics: nominally, as a constant; implicitly, as a uniformly sampled set; explicitly, as individual bin descriptions provided in the label; or externally, in another data object in this product or even in a separate product altogether. You are required to provide at least a minimal text description of the bin profiles (how the bin widths were determined). To pass review, most data products will require a more precise description. Check with your PDS node consultant if you have any questions or doubts.

<bin_profile_description>

REQUIRED

This is a free-format text field for describing the shape of the spectral bins and how their "widths", defined in the following attributes, were determined. It is required to be present and non-null. It does not need to be exhaustive - it just needs to provide a user with the essential details needed to understand the spectrum. If the situation is complicated but well-documented, the <pds:Reference_List> class in the upper part of the product label should include an explicit reference to the explanatory document elsewhere in the archive or in the literature. If the situation is complicated but not well-documented, please consider writing that document, archiving it, and then referencing it.

<Bin_Width_Constant>

OPTIONAL

This class is used for those cases where the bin width is actually constant, as well as when it is not well know and thus approximated by a constant, or is unknown. This class should contain exactly one attribute, corresponding the the spectral type. If the bin width is unknown, then that attribute should be declared "nil" with a reason of "unknown", and the <bin_profile_description> attribute should provide as much information as is known (or an explanation of why nothing is known).

<bin_width_frequency> or <bin_width_wavelenght> or <bin_width_wavenumber>

REQUIRED

Exactly one of these attributes is required. The attribute must correspond to the <spectral_type> value.

<Uniformly_Sampled_[unit]>

OPTIONAL

This class occurs in three flavors, one for each possible value of <spectral_bin_type>. Use the version of the class and its attributes corresponding to that value - indicated by the string "[unit]" in the descriptions that follow. The class provides the parameters needed to calculate the bin dimensions, in the specified unit, at each point along the spectral dimension of the data object.

<axis_name>

REQUIRED (for Array Spectra)

For spectra presented as 2D or 3D arrays, this attribute is required to be present and must contain the value of an <axis_name> attribute from the referenced data object. It is the name of the axis representing the spectral dimension in the corresponding object.

For spectra presented as tables, the rows correspond to the spectral dimension and this attribute is prohibited.

<sampling_interval_[unit]>

REQUIRED

This attribute provides the spacing from bin center to bin center in the indicated unit of measure.

<sampling_scale>

REQUIRED

This attribute indicates the type of scale used for sampling. It must have one of two values: Linear or Logarithmic. In the latter case, you must specify the base of the log using <sampling_base>.

<sampling_base>

see description

This attribute is required to be present if the preceding sampling_scale attribute is Logarithmic, otherwise it is forbidden. The value should be a number, so for the natural log a numeric approximation of e to an appropriate precision (e.g., "2.7182818") should be used.

<bin_width_[unit]>

REQUIRED

The width of one spectral bin in the appropriate units. How "width" is determined should have been indicated by the required bin_width_desc at the top of the Uniformly_Sampled_[unit] class.

<first_center_[unit]>

REQUIRED

This attribute provides the value, in the corresponding unit, at the center of the first spectral bin.

<last_center_[unit]>

REQUIRED

This attributes provides the value, in the corresponding unit, at the center of the last spectral bin.

<comment>

OPTIONAL

This free-format text field is provided as a place to note any peculiarities or caveats not otherwise noted about the bins and their definition.


<Axis_Bin_Set_[unit]>

OPTIONAL

This is the class to use if your spectral bins are not uniform but it is reasonable to provide individual bin parameters in the product label. This is often the case, for example, if your spectrum is a composite of points obtained by discrete detectors or observations through a series of filters, or has been resampled or selected from another (hopefully archival) spectrum product. If your bins are so numerous or complex that describing them individually in the label is not practical, you should probably be looking into the <Spectral_Lookup> class, following.

The Axis_Bin_Set class occurs in three flavors, one for each possible value of <spectral_bin_type>. Use the version of the class and its attributes corresponding to that value - indicated by the string "[unit]" in the descriptions that follow. This class provides parameters for defining each individual bin along the spectral axis of a 2D or 3D array structure. It is not used for tables, where typically (and preferably) bin parameters are included as columns in the table structure itself.

<axis_name>

REQUIRED

This attribute must contain the value of an <axis_name> attribute from the referenced data object. It is the name of the axis representing the spectral dimension in the corresponding object.

<Bin_[unit]>

REQUIRED

This sub-class is repeated once for each spectral bin along the named axis. It defines the dimensions of a single bin in the corresponding spectral units.

Note that it is difficult, if not impossible, to validate schematically that bins are being described in their physical sequence along the axis, but this should certainly be the case and reviewers and end-users will expect it.

<bin_sequence_number>

REQUIRED

Detailed bin descriptions make for a long and difficult-to-read string of XML. This attribute is used to help map bin descriptions to sequential positions along the spectral axis. It should start with "1" an increment for each bin described.

<center_[unit]>

REQUIRED

This attribute contains the spectral value at the center of the bin being described.

<bin_width_[unit]>

REQUIRED

This is the width of the particular bin. How the bin width was measured or otherwise determined should be described at least briefly in the <bin_width_desc> attribute at the top of the Bin_Description class.

<detector_number>

OPTIONAL

If you spectrum is a composite from several detectors, this attribute can be used to provide an identifying sequence number. Documentation elsewhere in the label or in the archive submission should map the sequence numbers here to specific detectors.

<grating_position>

OPTIONAL

Use this attribute to indicate that the spectral bin corresponds to a specific grating position. Typically, grating positions begin at zero and increase with wavelength (or equivalent).

<original_bin_number>

OPTIONAL

If your spectrum has been resampled or otherwise extracted from another spectrum product - preferably one that is or will also be in the PDS archives - you can use this attribute to indicate the original bin sequence number in that other product.

This attribute only takes a single integer and mat not be repeated. If the relationship to the original data is more complex than that, please explain in the optional <comment> field provided. If you are referring to a source product that is also in the PDS, please remember to reference it in the Reference_List section in the top part of the product label.

<Filter>

OPTIONAL

If your spectral bin corresponds to the bandpass of a filter, use this class to identify the filter. Filters specific to missions, projects, or observatories should be described in documentation also included in the PDS archives (and references in the Reference_List section of this product label). Standard ground-based filter sets should be identified using the full, formal name wherever possible (i.e., "Johnson V", not just "V").

<Spectral_Lookup>

OPTIONAL

Often the spectral bin parameters for 2D and 3D spectral arrays are supplied as parallel arrays with explicit values for each pixel. These parameter arrays may be included in the same data product, or as one or more separate products. It is also common for spectra provided as tables to include bin parameters as additional fields in the table object. In either event, this class is provided to link to the data objects that provide the essential bin parameters.

<Bin_Center_Lookup>

REQUIRED

This class provides a link to the values at the center of each spectral bin. Note that exactly one of the following subclasses must be included.

<bin_center_field_name>

see description

This attribute is required if the spectrum object is a table. It contains the value of the <name> attribute of one field in the table - the field containing the center value (in the unit indicated by <spectral_bin_type> at the top of the Spectral_Characteristics class) for each row/bin. It may not be used with spectral arrays.

<pds:Local_Internal_Reference>

OPTIONAL

If your spectral object is a 2D or 3D array, and the bin centers are provided as a separate array but are included as part of this data product (could be in the same data file as the spectrum or a separate one - as long as they are both described by this label), the you should use this class to indicate the <local_identifier> of the array corresponding to the bin centers. You will, of course, have to include a unique <local_identifier> attribute in that array object to reference.

This class is filled out similarly to the pds:Local_Internal_Reference class mentioned at the top of this page, except that the <reference_type> value must be spectral_characteristics_to_bin_center_values.

<pds:Internal_Reference>

OPTIONAL

If your spectral object is a 2D or 3D array and the bin centers are provided as a data object in a different PDS archive product, use this class to reference that other product. This is filled out similarly to the pds:Internal_Reference class detailed for the Slit_Parameters class, except that the <reference_type> value must be spectral_characteristics_to_bin_center_values.


<Bin_Width_Lookup>

REQUIRED

This class provides a link to the values at the center of each spectral bin. Note that no more than one of the following subclasses may be included.

<Bin_Width_Constant>

REQUIRED

The Bin_Width_Constant class is used for cases where the bin width is either not well known or


<bin_width_field_name>

OPTIONAL

This attribute should be provided wherever possible when the spectrum object is a table. It contains the value of the <name> attribute of one field in the table - the field containing the bin width for each row/bin. It may not be used with spectral arrays.

If the bin widths are not explicitly included in the table, this field may be omitted. In that case, because the containing Bin_Width_Lookup class is required, you should use the optional <comment> field (below) to state directly what, if anything, is known about the bin widths in addition to whatever is already stated in the <bin_width_desc> at the top of the Spectral_Characteristics class.

<pds:Local_Internal_Reference>

OPTIONAL

If your spectral object is a 2D or 3D array, and the bin widths are provided as a separate array but are included as part of this data product (could be in the same data file as the spectrum or a separate one - as long as they are both described by this label), the you should use this class to indicate the <local_identifier> of the array corresponding to the bin widths. You will, of course, have to include a unique <local_identifier> attribute in that array object to reference.

This class is filled out similarly to the pds:Local_Internal_Reference class mentioned at the top of this page, except that the <reference_type> value must be spectral_characteristics_to_bin_width_values.

<pds:Internal_Reference>

OPTIONAL

If your spectral object is a 2D or 3D array and the bin widths are provided as a data object in a different PDS archive product, use this class to reference that other product. This is filled out similarly to the pds:Internal_Reference class detailed for the Slit_Parameters class, except that the <reference_type> value must be spectral_characteristics_to_bin_width_values.

<comment>

OPTIONAL

This attribute, which occurs at the bottom of the <Spectral_Lookup> class (in case you've lost track), is for any notes or caveats about the lookup process that you'd like to provide for users.