Filling Out the Nuclear Spectroscopy Dictionary Classes

From The SBN Wiki
Revision as of 16:13, 4 March 2019 by Raugh (talk | contribs) ()
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The Nuclear Spectroscopy 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 data products resulting from nuclear spectroscopy.

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

Last update: 04 March 2019, begin creation.



This is the wrapper class that contains all the other classes and attributes of this dictionary. You may repeat this class in your <Discipline_Area>, if that makes sense.



This class says it "Specifies methods and data used to determine the pulse height," but in fact it does no such thing. All it does is provide a single polynomial solution for calculating pulse height. And that looks like an integrated or overall pulse height, since it defines a single polynomial with terms for all channels, not for each channel individually (but perhaps pulse height is cumulatively calculated at each channel? Don't know - not a nuclear spectroscopist. If it's obvious to a nuclear spectroscopist, then that's probably OK.



This class is the only sub-class of Energy_Calibration, yet it is optional. This makes no sense. The class should, at worst, be required until such time as there is an additional option - at which point at least one of them should be required. If there will never be any other sub-class of Energy_Calibration, then one of the two levels should be removed.

This class is not defined. The "definition" of this class does not actually describe the class, but rather describes how a "pulse height" is calculated in the case of a multi-channel instrument. The terminology here ("channel number" and the undefined coefficients "a") does not match the terminology used for the individual terms, which refer to "coefficient" (explicitly) and "order".


REQUIRED, repeatable

This class defines a single term in the polynomial defining the pulse height. At least one term must be present.

There is no validatable metadata provided and no validation done on either the coefficients or, in particular, the orders. For example, there is no attribute that indicates the number of channels present in the data - is that variable? The order is allowed to be non-positive - does that make sense? Are the orders required to be strictly increasing? Are they required to be sequential?

Does it make sense to have a "polynomial" that consists of a single term?



The real number coefficient corresponding to the <order> value, following.



The integral order of the term.



This class makes reference to adding things to the mission dictionary. This is inappropriate for a discipline dictionary and archival data. An end-user reading this dictionary, for example, is not adding anything to any dictionary.

At least one of the sub-classes should be required to be present, but there is no such requirement.



The name of this class is "State_Table" but the definition refers to "state_index". The definition does not appear to describe the point of the class, but rather a non-existent attribute.



This class cannot be used because the Schematron file does not define any values for <pds:reference_type>, which is itself required and must have a context-specific value.

There seem to be assumptions being made about structure in this referenced product that cannot be enforced by schematic validation of this product. Is there a standard being applied here at all?


REQUIRED, repeatable

The definition refers to "links", but "link" is a very generic concept. It would be more useful to define how the linkage is made rather than simply asserting it exists.

It is not clear what the intention is, here. If the table is being referenced, why do we appear to have classes designed to define a table and its rows?



The definition says this points to "a row of a look up table", but the value is allowed to be non-positive.


OPTIONAL, repeatable

The definition is circular. What does it mean to repeat this sub=class?


At least one of the subclasses should be required to be present, but there is no such requirement defined.


It is not clear what "records" are being referenced. If they are "records" in a data product, then there should be a link to a data product at the top level of the <NucSpec_Observation_Properties> class (via pds:Local_Internal_Reference), but there is not.

The description implies that <first_record> must be positive, but that is not validated. It also implies first_record should be less than last_record; this is also not validated.

The <last_record> attribute is optional. What does it mean to omit it? Also, last_record is not constrained to be positive, or to be larger than first_record.

There is no validation that either first_record or last_record does not exceed the number of records in whatever it is that contains the "records" being referenced.


It is not clear what "records" are being referenced. If they are "records" in a data product, then there should be a link to a data product at the top level of the <NucSpec_Observation_Properties> class (via pds:Local_Internal_Reference), but there is not.

The first_record attribute is optional. That makes no sense. It is also not required to be positive.

Record_count is not required to be positive.

Assuming this refers to records in a data object, there is no validation that first_record+record_count does not exceed the number of records in the data object.


OPTIONAL, repeatable

It's not clear to me that "this state", as mentioned in the definition, is well-defined. The only required attribute is an index. Is that sufficient for a user to know what "this state" is? Perhaps so.

This class requires two spacecraft event times. Can spacecraft event time be universally defined? This also seems to preclude any ground- or lab-based nuclear spectroscopy. Is that the intention?

How does spacecraft event time "link records in the state table with records in the data product"?