Difference between revisions of "Filling Out the Nuclear Spectroscopy Dictionary Classes"

From The SBN Wiki
Jump to navigation Jump to search
(Created page with "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 ob...")
 
()
 
Line 93: Line 93:
 
{| class="wikitable" style="background-color: yellow"
 
{| class="wikitable" style="background-color: yellow"
 
|
 
|
The definition refers to "links", but this terms has a very specific PDS4 meaning that involves LIDs and LIDVIDs, and thus is problematic here.
+
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?  
 
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?  

Latest revision as of 16:13, 4 March 2019

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.

<NucSpec_Observation_Properties>

REQUIRED

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.

<Energy_Calibration>

OPTIONAL

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.

<Polynomial>

OPTIONAL

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

<Polynomial_Term>

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?

<coefficient>

REQUIRED

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

<order>

REQUIRED

The integral order of the term.

<Instrument_Settings>

OPTIONAL

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.

<State_Table>

OPTIONAL

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.

<pds:Internal_Reference>

REQUIRED

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?

<State_Table_Entry>

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?

<state_index>

REQUIRED

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

<Applicable_Records>

OPTIONAL, repeatable

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

Subclasses:

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

First_Last

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.

First_Count

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.

<State_Time>

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"?