Difference between revisions of "Filling Out the Spectral Library Dictionary Classes"
(Safety Save) |
(Safety Save) |
||
Line 379: | Line 379: | ||
''REQUIRED'' | ''REQUIRED'' | ||
− | The minimum sampled value for the reported spectrum, in the units indicated by '' | + | 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 '' | + | 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 | + | ''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 | + | ''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 | + | ''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 | + | ''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 | + | ''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 | + | ''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 | + | ''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 | + | ''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'' | + | ''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 | + | ''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 | + | ''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
- 1 <Spectral_Library_Product>
- 2 <Specimen_Parameters>
- 3 <Specimen_Classification>
- 3.1 <specimen_type>
- 3.2 <material_common_name>
- 3.3 <material_origin>
- 3.4 <synthetic_type>
- 3.5 <material_state>
- 3.6 <organic_type>
- 3.7 <material_type>
- 3.8 <material_subtype>
- 3.9 <mineral_type>
- 3.10 <mineral_subtype>
- 3.11 <rock_type>
- 3.12 <rock_subtype>
- 3.13 <volatile_type>
- 3.14 <processing_description>
- 4 <Measurement_Parameters>
- 4.1 <pds:Internal_Reference>
- 4.2 <measurement_type>
- 4.3 <spectral_range_parameter_name>
- 4.4 <spectral_range_min>
- 4.5 <spectral_range_max>
- 4.6 <spectral_range_unit>
- 4.7 <spectral_sampling_interval_min>
- 4.8 <spectral_sampling_interval_max>
- 4.9 <spectral_sampling_interval_unit>
- 4.10 <spectral_resolution_width_min>
- 4.11 <spectral_resolution_width_max>
- 4.12 <spectral_resolution_unit>
- 4.13 <measurement_reference_standard>
- 4.14 <measurement_geometry_type>
- 4.15 <incidence_angle>
- 4.16 <emission_angle>
- 4.17 <phase_angle>
- 4.18 <measurement_source_description>
- 4.19 <measurement_atmosphere_pressure>
- 4.20 <measurement_atmosphere_temperature>
- 4.21 <measurement_atmosphere_relative_humidity>
- 4.22 <measurement_atmosphere_description>
- 4.23 <measurement_date_time>
- 4.24 <data_producer_name>
- 4.25 <data_provider_name>
- 4.26 <measurement_requestor>
- 4.27 <measurement_notes>
<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:
- <Specimen_Parameters> must be present exactly once;
- <Specimen_Classification> must be present exactly once;
- <Measurement_Parameters> must be present at least once and may be repeated as desired; and
- <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:
|
|
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:
|
<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:
|
|
<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:
|
|
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:
|
|
<spectral_range_parameter_name>
REQUIRED
This attribute indicates the nature of the sampling interval for the spectrum. It must be one of the following:
|
<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:
|
<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.