Filling Out the Spectral Library Dictionary Classes

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.

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