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

From The SBN Wiki
Jump to navigation Jump to search
(Safety Save)
(Safety Save)
Line 379: Line 379:
 
''REQUIRED''
 
''REQUIRED''
  
The minimum sampled value for the reported spectrum, in the units indicated by ''spectral_rang_unit'', following.  If this number contains a decimal point, it ''must'' have at least one digit on both the left and right of the decimal.
+
The minimum sampled value for the reported spectrum, in the units indicated by ''spectral_range_unit'', following.  If this number contains a decimal point, it ''must'' have at least one digit on both the left and right of the decimal.
  
 
=== <spectral_range_max> ===
 
=== <spectral_range_max> ===
Line 385: Line 385:
 
''REQUIRED''
 
''REQUIRED''
  
The maximum sampled value for the reported spectrum, in the units indicated by ''spectral_rang_unit'', following.  If this number contains a decimal point, it ''must'' have at least one digit on both the left and right of the decimal.
+
The maximum sampled value for the reported spectrum, in the units indicated by ''spectral_range_unit'', following.  If this number contains a decimal point, it ''must'' have at least one digit on both the left and right of the decimal.
  
 
=== <spectral_range_unit> ===
 
=== <spectral_range_unit> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This attribute provides the unit of measure for the preceding range extrema.
  
 
=== <spectral_sampling_interval_min> ===
 
=== <spectral_sampling_interval_min> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
This attribute specifies the minimum distance between spectral band centers, in units of ''spectral_sampling_internal_unit'', following.  If the distance between band centers is constant, then this attribute should have the same value as ''spectral_sampling_interval_max''.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <spectral_sampling_interval_max> ===
 
=== <spectral_sampling_interval_max> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
This attribute specifies the maximum distance between spectral band centers, in units of
 +
''spectral_sampling_internal_unit'', following. If the distance between band centers is constant, then this attribute should have the same value as ''spectral_sampling_interval_min''.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <spectral_sampling_interval_unit> ===
 
=== <spectral_sampling_interval_unit> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
The unit of measure for the preceding sampling interval values.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
''The value of this attribute is not validated.''
 +
|}
  
 
=== <spectral_resolution_width_min> ===
 
=== <spectral_resolution_width_min> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
This attribute indicates the minimum width of a single spectral band, in units specified by ''spectral_resolution_unit'', following.  If all bands have the same width, this attribute should have the same value as ''spectral_resolution_width_max''.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <spectral_resolution_width_max> ===
 
=== <spectral_resolution_width_max> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
This attribute indicates the maximum width of a single spectral band, in units specified by ''spectral_resolution_unit'', following.  If all bands have the same width, this attribute should have the same value as ''spectral_resolution_width_min''.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <spectral_resolution_unit> ===
 
=== <spectral_resolution_unit> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
The unit of measure for the preceding spectral resolution extrema.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <measurement_reference_standard> ===
 
=== <measurement_reference_standard> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This free-format attribute is used to identify the calibration standard.
  
 
=== <measurement_geometry_type> ===
 
=== <measurement_geometry_type> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
Characteristic geometry used to record the spectral value.  This attribute must be one of the following values:
 +
{|
 +
|-
 +
| valign="top" |
 +
* '''Biconical'''
 +
* '''Bidirectional'''
 +
* '''Directional Hemispherical'''
 +
* '''Hemispherical Hemispherical'''
 +
* '''Unknown'''
 +
|}
  
 
=== <incidence_angle> ===
 
=== <incidence_angle> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
The angle between the local vertical at the intercept point and a vector from the intercept point to the detector. You must provide an angular unit of measure for this value.
  
 
=== <emission_angle> ===
 
=== <emission_angle> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
The angle between the local vertical at the intercept point and a vector from the intercept point to the sensor. You must provide an angular unit of measure for this value.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''The difference between "sensor" here and "detector" in the previous attribute is not at all clear.''
 +
|}
 +
  
 
=== <phase_angle> ===
 
=== <phase_angle> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
The angle between the incidence and emission vectors. You must provide an angular unit of measure for this value.
  
 
=== <measurement_source_description> ===
 
=== <measurement_source_description> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This brief (255 ASCII characters) text field is used to identify the source of illumination, heat, etc. used to produce the spectrum.
  
 
=== <measurement_atmosphere_pressure> ===
 
=== <measurement_atmosphere_pressure> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
Atmospheric pressure of the measurement environment. You must supply units of pressure for this attribute.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <measurement_atmosphere_temperature> ===
 
=== <measurement_atmosphere_temperature> ===
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
Atmospheric temperature of the measurement environment. You must supply units of temperature for this attribute.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
|}
  
 
=== <measurement_atmosphere_relative_humidity> ===
 
=== <measurement_atmosphere_relative_humidity> ===
  
''REQUIRED'' and nillable
+
''REQUIRED''  
 +
 
 +
Atmospheric relative humidity of the measurement environment.
 +
 
 +
This attribute may be set to ''nil'', if appropriate.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''It is not clear if this value should be expressed as a fraction or percentage.''
 +
|}
  
 
=== <measurement_atmosphere_composition>
 
=== <measurement_atmosphere_composition>
  
''OPTIONAL'' and nillable
+
''OPTIONAL''
 +
 
 +
This attribute provides an unlimited-length text field for listing gases present in the measurement environment.
 +
 
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This attribute is both nillable and optional.''
 +
''Note that while this text field is unlimited in length, no formatting of any kind is preserved.''
 +
|}
  
 
=== <measurement_atmosphere_description> ===
 
=== <measurement_atmosphere_description> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This attribute can contain a string of up to 1000 ASCII characters describing the atmospheric conditions through which the data were taken.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''Note that while this text field can be rather long, no formatting of any kind is preserved.''
 +
|}
  
 
=== <measurement_date_time> ===
 
=== <measurement_date_time> ===
  
''REQUIRED'' and nillable
+
''REQUIRED''
 +
 
 +
This attribute provides the local date and time of measurement in the standard ''YYYY-MM-DD'''''T'''''hh:mm:ss.sss'' format.
 +
 
 +
If necessary, this attribute can be specified as ''nil''.
  
 
=== <data_producer_name> ===
 
=== <data_producer_name> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
This attribute indicates the name of the person, institution, pipeline, etc., that created the spectral data product.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This definition is ambiguous.''
 +
|}
  
 
=== <data_provider_name> ===
 
=== <data_provider_name> ===
  
 
''REQUIRED''
 
''REQUIRED''
 +
 +
The name of the person who submitted the spectral data to the source library.
 +
 +
{| class="wikitable" style="background-color: yellow"
 +
|
 +
''This definition is a bit of a guess.''
 +
|}
  
 
=== <measurement_requestor> ===
 
=== <measurement_requestor> ===
  
 
''REQUIRED'' repeatable and nillable.  And misspelled.
 
''REQUIRED'' repeatable and nillable.  And misspelled.
 +
 +
The name of a single person, institution, etc., who requested that the spectral measurement be made. This attribute may be repeated if there is more than one such name to list.  It may be set to ''nil'' if there is no name to list.
  
 
=== <measurement_notes> ===
 
=== <measurement_notes> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
 +
 +
This text string (up to 1000 ASCII characters) can be used to provide additional comments about how the measurement was made.  Note that no formatted will be preserved, however, including line or paragraph breaks or table spacing.

Revision as of 15:14, 18 August 2017

The spectral library 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 are used for spectral data products that result from laboratory observations. They are used to define the characteristics of the sample involved and the measurements made.

The reserved abbreviation for use with this dictionary is "speclib".

Last update: 17 August 2017, begin creation.

The Spectral Library Dictionary has an optional wrapper class which can be used to contain the four major subclasses, or each of the subclasses can be used individually in the <Discipline> area.

Contents

<Spectral_Library_Product>

OPTIONAL

This is the optional wrapper class. If you use it, then it will include at least three of the following entry classes as indicated and in the following order:

  1. <Specimen_Parameters> must be present exactly once;
  2. <Specimen_Classification> must be present exactly once;
  3. <Measurement_Parameters> must be present at least once and may be repeated as desired; and
  4. <Ancillary_Products> is optional, and may also be repeated as desired.

<Specimen_Parameters>

OPTIONAL

This class describes the specimen that was the target of the spectrum. If used outside of the Spectral_Library_Product wrapper class, it may be repeated.

<specimen_id>

REQUIRED

A unique identifier for the specimen.

Note: The context for "unique" is not defined.

<specimen_name>

OPTIONAL

This is the name by which the specimen is known to the specimen curator.

Note: This is a guess - it is possible that specimen_name is the local name while specimen_id is the curator's identifier.

<specimen_description>

OPTIONAL

A short (300 ASCII characters or less), prose description of the specimen.

<source_specimen_id>

OPTIONAL

This is the identifier for a larger specimen from which the present specimen was derived.

It's not clear whether this "id" correlates in any way with either specimen_id or specimen_name.

This attribute is both optional and nillable, which is not in keeping with the PDS4 IM best practices.

<specimen_min_size>

REQUIRED

This attribute provides the minimum particle size comprising the sample. You must provide the appropriate units of length for this attribute. For example:

<specimen_min_size unit="mm">0.1</specimen_min_size>

NOTE: This is a guess. I don't understand this attribute and the one following.

<specimen_max_size>

REQUIRED

This attribute provides the maximum particle size comprising the sample. You must provide the appropriate units of length for this attribute.

<specimen_collection_location>

REQUIRED

This is the place where the specimen was collected.

While this attribute is required, it is not nillable. Rather, then dictionary instructs users to put a value of "Unknown" in the keyword. This is also not in keeping with PDS4 IM best practices, and present some issues for validation.

It is not clear if this refers to the specimen observed or the source specimen, when one exists.

<specimen_owner_location>

REQUIRED

This actually provides the name of a facility or other location where the specimen is permanently curated. If not known, this attribute can be defined as "nil" with a reason of "unknown", thus:

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

It is not clear if this refers to the specimen observed or the source specimen, when one exists.

<specimen_owner_name>

REQUIRED

The name of a facility or other location that "owns" the specimen. This attribute may be set to nil with an appropriate reason if needed.

It is not clear if this refers to the specimen observed or the source specimen, when one exists.

<Specimen_Classification>

OPTIONAL

This class provides a list of geological characteristics for classifying the specimen observed.

I'm assuming it's the "specimen observed" and not the "source specimen", although in many cases here that would be a distinction without a difference.

<specimen_type>

REQUIRED

This attribute is a general classification of the specimen by source body and method of recovery/acquisition. It must have one of the following values:

  • Lunar Meteorite
  • Mars Meteorite
  • Other Meteorite
  • Returned Asteroid Sample
  • Returned Lunar Sample
  • Synthetic Sample
  • Terrestrial Sample

You may repeat this attribute if that makes sense.

<material_common_name>

OPTIONAL

A fairly specific description of the sample content by common name. For example, if the specimen is a combination of kaolinite and opal, a value of "Kaolinite/Opal" would be appropriate. A value of "Unidentified" may also be specified.

What is the difference between specifying "Unidentified" and omitting this optional attribute?

<material_origin>

REQUIRED

This attribute must contain one of the two values Natural or Synthetic, appropriately.

<synthetic_type>

OPTIONAL

Use this attribute in the case where the specimen is synthetic to indicate how the specimen was synthesized. It must contain one of the following strings:

  • Entirely Synthetic
  • From Natural
  • Hardware
  • Natural and Synthetic

<material_state>

REQUIRED

The physical state of the specimen at the time of observation. This must be one of Gas, Liquid, or Solid.

<organic_type>

REQUIRED

This must have one of the values Inorganic, Organic, or Mixture.

<material_type>

REQUIRED

This must have one of the following values:

  • Ice
  • Mineral
  • Rock
  • Single Particle
  • Unconsolidated Mixture

<material_subtype>

OPTIONAL

This attribute may be repeated up to 10 times, if that seems appropriate.

This attribute is not well-defined. A single value is allowed to be up to 255 ASCII character long, and there is no indication of what a reasonable value is, let alone why you'd need 10 of them if you get 255 characters for each.

<mineral_type>

OPTIONAL

This attribute must have one of the following values:

  • Carbonate
  • Cyclosilicate
  • Inosilicate
  • Nesosilicate
  • Phyllosilicate
  • Sorosilicate
  • Tektosilicate
  • Nitrate/Iodate/Borate
  • Halogenide
  • Oxide
  • Phosphate
  • Sulfate
  • Sulfide
  • Native Element
  • Organic Compound
  • Unclassified

This attribute may be repeated, if that makes sense.

<mineral_subtype>

OPTIONAL

This attribute may be repeated up to 10 times, if that seems appropriate.

This attribute is not well-defined. A single value is allowed to be up to 255 ASCII character long, and there is no indication of what a reasonable value is, let alone why you'd need 10 of them if you get 255 characters for each.

<rock_type>

OPTIONAL

This attribute provides the general classification of a rock specimen. It must have one of the values Igneous, Sedimentary, or Metamorphic.

<rock_subtype>

OPTIONAL

This attribute may be repeated up to 10 times, if that seems appropriate.

This attribute is not well-defined. A single value is allowed to be up to 255 ASCII character long, and there is no indication of what a reasonable value is, let alone why you'd need 10 of them if you get 255 characters for each.

<volatile_type>

OPTIONAL

This attribute must have one of the values Poor, Rich, or Unknown.


This attribute may be repeated up to 10 times, if that seems appropriate.

This attribute is optional and nillable, which violates best practices, and also has a standard value of "Unknown", further complicating the issue. On top of that, it includes an undefined acronym in its definition.

<processing_description>

OPTIONAL

This attribute may be used to provide a brief (no more than 255 ASCII characters) description of how a synthetic specimen was processed.


This attribute may be repeated up to 10 times, if that seems appropriate.

This attribute is only supposed to be used with synthetic specimens, but that is not enforced.


<Measurement_Parameters>

OPTIONAL

This class lists attributes and identifies people relevant to the actual measurement performed.

<pds:Internal_Reference>

REQUIRED

There is no indication of what must be referenced at this point, and no defined <reference_type> value.

<pds:lid_reference> or <pds:lidvid_reference>

REQUIRED

<pds:reference_type>

REQUIRED

<pds:comment>

OPTIONAL


<measurement_type>

REQUIRED

This attribute identifies the type of spectroscopy performed. It must be one of the following values:

  • Attenuated Total Reflectance
  • Emission
  • LIBS
  • Raman
  • Reflectance
  • Transmission
  • X-Ray Diffraction
  • X-Ray Flourescence

<spectral_range_parameter_name>

REQUIRED

This attribute indicates the nature of the sampling interval for the spectrum. It must be one of the following:

  • Angle
  • Energy
  • Frequency
  • Time
  • Wavelength
  • Wavenumber

<spectral_range_min>

REQUIRED

The minimum sampled value for the reported spectrum, in the units indicated by spectral_range_unit, following. If this number contains a decimal point, it must have at least one digit on both the left and right of the decimal.

<spectral_range_max>

REQUIRED

The maximum sampled value for the reported spectrum, in the units indicated by spectral_range_unit, following. If this number contains a decimal point, it must have at least one digit on both the left and right of the decimal.

<spectral_range_unit>

REQUIRED

This attribute provides the unit of measure for the preceding range extrema.

<spectral_sampling_interval_min>

OPTIONAL

This attribute specifies the minimum distance between spectral band centers, in units of spectral_sampling_internal_unit, following. If the distance between band centers is constant, then this attribute should have the same value as spectral_sampling_interval_max.

This attribute is both nillable and optional.

<spectral_sampling_interval_max>

OPTIONAL

This attribute specifies the maximum distance between spectral band centers, in units of spectral_sampling_internal_unit, following. If the distance between band centers is constant, then this attribute should have the same value as spectral_sampling_interval_min.

This attribute is both nillable and optional.

<spectral_sampling_interval_unit>

OPTIONAL

The unit of measure for the preceding sampling interval values.

This attribute is both nillable and optional. The value of this attribute is not validated.

<spectral_resolution_width_min>

OPTIONAL

This attribute indicates the minimum width of a single spectral band, in units specified by spectral_resolution_unit, following. If all bands have the same width, this attribute should have the same value as spectral_resolution_width_max.

This attribute is both nillable and optional.

<spectral_resolution_width_max>

OPTIONAL

This attribute indicates the maximum width of a single spectral band, in units specified by spectral_resolution_unit, following. If all bands have the same width, this attribute should have the same value as spectral_resolution_width_min.

This attribute is both nillable and optional.

<spectral_resolution_unit>

OPTIONAL

The unit of measure for the preceding spectral resolution extrema.

This attribute is both nillable and optional.

<measurement_reference_standard>

OPTIONAL

This free-format attribute is used to identify the calibration standard.

<measurement_geometry_type>

REQUIRED

Characteristic geometry used to record the spectral value. This attribute must be one of the following values:

  • Biconical
  • Bidirectional
  • Directional Hemispherical
  • Hemispherical Hemispherical
  • Unknown

<incidence_angle>

REQUIRED

The angle between the local vertical at the intercept point and a vector from the intercept point to the detector. You must provide an angular unit of measure for this value.

<emission_angle>

REQUIRED

The angle between the local vertical at the intercept point and a vector from the intercept point to the sensor. You must provide an angular unit of measure for this value.

The difference between "sensor" here and "detector" in the previous attribute is not at all clear.


<phase_angle>

REQUIRED

The angle between the incidence and emission vectors. You must provide an angular unit of measure for this value.

<measurement_source_description>

OPTIONAL

This brief (255 ASCII characters) text field is used to identify the source of illumination, heat, etc. used to produce the spectrum.

<measurement_atmosphere_pressure>

OPTIONAL

Atmospheric pressure of the measurement environment. You must supply units of pressure for this attribute.

This attribute is both nillable and optional.

<measurement_atmosphere_temperature>

OPTIONAL

Atmospheric temperature of the measurement environment. You must supply units of temperature for this attribute.

This attribute is both nillable and optional.

<measurement_atmosphere_relative_humidity>

REQUIRED

Atmospheric relative humidity of the measurement environment.

This attribute may be set to nil, if appropriate.

It is not clear if this value should be expressed as a fraction or percentage.

=== <measurement_atmosphere_composition>

OPTIONAL

This attribute provides an unlimited-length text field for listing gases present in the measurement environment.

This attribute is both nillable and optional. Note that while this text field is unlimited in length, no formatting of any kind is preserved.

<measurement_atmosphere_description>

REQUIRED

This attribute can contain a string of up to 1000 ASCII characters describing the atmospheric conditions through which the data were taken.

Note that while this text field can be rather long, no formatting of any kind is preserved.

<measurement_date_time>

REQUIRED

This attribute provides the local date and time of measurement in the standard YYYY-MM-DDThh:mm:ss.sss format.

If necessary, this attribute can be specified as nil.

<data_producer_name>

REQUIRED

This attribute indicates the name of the person, institution, pipeline, etc., that created the spectral data product.

This definition is ambiguous.

<data_provider_name>

REQUIRED

The name of the person who submitted the spectral data to the source library.

This definition is a bit of a guess.

<measurement_requestor>

REQUIRED repeatable and nillable. And misspelled.

The name of a single person, institution, etc., who requested that the spectral measurement be made. This attribute may be repeated if there is more than one such name to list. It may be set to nil if there is no name to list.

<measurement_notes>

OPTIONAL

This text string (up to 1000 ASCII characters) can be used to provide additional comments about how the measurement was made. Note that no formatted will be preserved, however, including line or paragraph breaks or table spacing.