Difference between revisions of "Filling Out the Observation Area Classes"

From The SBN Wiki
Jump to navigation Jump to search
m ()
(: Updated to avoid future arguments and promote good metadata.)
 
(43 intermediate revisions by the same user not shown)
Line 24: Line 24:
 
''REQUIRED''
 
''REQUIRED''
  
This should be the UTC start date/time of the observation, in any of several standard date formats (day-of-year, YMD, etc.)  Maximum precision is four decimal places in the "seconds" field.  The UTC indicator ('Z') on the end is optional, but note that ''start_time'' will ''always'' be interpreted as UTC, regardless of whether the 'Z' is present.
+
This should be the UTC start date and time of the observation, in any of several standard date formats (day-of-year, YMD, etc.)  Maximum precision is four decimal places in the "seconds" field.  The UTC indicator ('Z') on the end is required, and of course your start time should be in UTC.
  
 
The ''<start_date_time>'' attribute is required.  On those rare occasions when it is not an applicable concept, use the ''nilReason'' attribute with a value of either "inapplicable" or "unknown", as appropriate, with no value for ''<start_date_time>'' itself.  It looks like this:
 
The ''<start_date_time>'' attribute is required.  On those rare occasions when it is not an applicable concept, use the ''nilReason'' attribute with a value of either "inapplicable" or "unknown", as appropriate, with no value for ''<start_date_time>'' itself.  It looks like this:
Line 36: Line 36:
 
(These two forms are equivalent. The first form uses the XML shorthand for an element with no value content.)
 
(These two forms are equivalent. The first form uses the XML shorthand for an element with no value content.)
  
'''''Note:''''' In order for this to work, you must have assigned the ''xsi'' namespace prefix to the '''XML Schema Instance''' namespace in the ''<Product_*>'' opening tag.  This may have been done for you automatically if you let your editor generate the XML template for you.  If '''xsi:nil''' generates a validation error, add ''xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'' to the list of namespaces in the ''<Product_*>'' tag.
+
'''''Note:''''' In order for this to work, you must have assigned the ''xsi'' namespace prefix to the '''XML Schema Instance''' namespace in the ''<Product_*>'' opening tag.  This will likely have been done for you automatically if you let your editor generate the XML template for you.  If '''xsi:nil''' generates a validation error, add ''xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'' to the list of namespaces in the ''<Product_*>'' tag. See the "[[Schema Referencing in PDS4 Labels]]" page on this wiki for gory details.
  
 
=== <stop_date_time> ===
 
=== <stop_date_time> ===
Line 48: Line 48:
 
=== Other Optional Attributes ===
 
=== Other Optional Attributes ===
  
These attributes are optional (but must appear in this order, after ''&lt;stop_time&gt;'') if present:  
+
These attributes are optional, but must appear in this order following ''&lt;stop_time&gt;'' if present:  
  
 
:; &lt;local_mean_solar_time&gt;
 
:; &lt;local_mean_solar_time&gt;
Line 60: Line 60:
 
''OPTIONAL''
 
''OPTIONAL''
  
This class contains attributes for high-level searching across large sections of the PDS archive.  For more detailed descriptive attributes, look for the ''&lt;Primary_Result_Details&gt;'' in the ''&lt;Discipline_Area&gt;''.
+
This class contains attributes for high-level searching across large sections of the PDS archive.  While it is optional in general, it is required in all observational data Collection labels to supply (at a minimum) the purpose and processing level for the collection data products.  You should also use it where it would make sense to use it to enable searching. This typically means the same or more detail will
 +
appear in observational product labels than in the collection label, where only the common values will appear.
  
 
The [[Standard Values Quick Reference]] page lists standard values for attributes below (among others).
 
The [[Standard Values Quick Reference]] page lists standard values for attributes below (among others).
 
{| class="wikitable" style="background-color: thistle"
 
| '''''Note:''''' ''While this class is currently optional, SBN will require that this class be provided for just about all observational data products.''
 
|}
 
 
=== <type> ===
 
 
''OPTIONAL''
 
 
The ''type'' attribute is a broad categorization of the discipline of the observation.  It has values like '''Astrometry''' or '''Image'''.  The value for this attribute must be one of the recognized standard values listed in the PDS4 Information Model (also found in the master ''Schematron'' file used for validation).  Values current as of this writing are listed for handy reference in the [[Standard_Values_Quick_Reference#In_.3CPrimary_Result_Summary.3E_4|Standard Values Quick Reference]].
 
  
 
=== <purpose> ===
 
=== <purpose> ===
Line 78: Line 69:
 
''REQUIRED''
 
''REQUIRED''
  
This attribute describes the immediate goal for recording the observation. The value must be one of the five defined standard values:
+
This attribute describes the immediate goal for recording the observation. The value must be one of the six defined standard values:
  
 
#Calibration
 
#Calibration
Line 84: Line 75:
 
#Engineering
 
#Engineering
 
#Navigation
 
#Navigation
 +
#Observation Geometry
 
#Science
 
#Science
 +
#Supporting Observation
  
=== <data_regime> ===
+
=== <processing_level> ===
  
 
''REQUIRED''
 
''REQUIRED''
  
This attribute classifies the observation by broad wavelength range or the equivalent for non-photon data.  The value must be one of the standard values defined for this attribute.  The values as of this writing are summarized in the [[Standard_Values_Quick_Reference#In_.3CPrimary_Result_Summary.3E|Standard Values Quick Reference]].
+
This attribute must have one of the following defined standard values:
 +
 
 +
#Calibrated
 +
#Derived
 +
#Partially Processed
 +
#Raw
 +
#Telemetry
  
 
=== <description> ===
 
=== <description> ===
Line 96: Line 95:
 
''OPTIONAL''
 
''OPTIONAL''
  
This attribute can be used for additional free-format text decription.
+
This attribute can be used for additional free-format text description.
 +
 
 +
=== <Science_Facets> ===
 +
 
 +
''OPTIONAL''
 +
 
 +
This class should be used when it makes sense to provide values for facet-based searching (a way of drilling down through a result set based on broad characteristics).  It can be repeated for inter-disciplinary products.  The facet values are hierarchical, and the allowed values for a sub-facet are dependent on the primary facet.  There is a table on the "[[Standard_Values_Quick_Reference#In_.3CPrimary_Result_Summary.3E.2F.3CScience_Facets.3E_3|Standard Values Quick Reference]]" page you can check for supplying the facets.
 +
 
 +
==== <wavelength_range> ====
  
=== <processing_level_id> ===
+
''OPTIONAL''
 +
 
 +
This attribute provides a human-readable category of
 +
wavelength range for data that is measuring photons. Values include:
 +
* Far Infrared
 +
* Gamma Ray
 +
* Infrared
 +
* Microwave
 +
* Millimeter
 +
* Near Infrared
 +
* Radio
 +
* Submillimeter
 +
* Ultraviolet
 +
* Visible
 +
* X-ray
 +
You may repeat this attribute if your product covers more than one of these categories.
 +
 
 +
==== <domain> ====
 +
 
 +
''OPTIONAL''
 +
 
 +
This attribute describes the observation in terms of regions measured outward from the center of a target body.  Values include:
 +
* Atmosphere
 +
* Dynamics
 +
* Heliosheath
 +
* Heliosphere
 +
* Interior
 +
* Interstellar
 +
* Ionosphere
 +
* Magnetosphere
 +
* Rings
 +
* Surface
 +
You may repeat this attribute if your product spans more than one of these domains.
 +
 
 +
==== <discipline_name> ====
  
 
''REQUIRED''
 
''REQUIRED''
  
This attribute must have one of the following four defined standard values:
+
This attribute provides a very high-level characterization of the data as a kind of observation.  It is intended to support inter-disciplinary (and cross-node) searching. Use the value that is most specific to your product from this list:
 +
* Atmospheres
 +
* Fields
 +
* Flux Measurements
 +
* Geosciences
 +
* Imaging
 +
* Particles
 +
* Radio Science
 +
* Ring-Moon Systems
 +
* Small Bodies
 +
* Spectroscopy
 +
So in other words, if your product contains spectroscopy of asteroids, use ''Spectroscopy'' rather than ''Small Bodies'' as the value of this attribute.
 +
 
 +
What values you can use for the following ''<facet1>'' and ''<facet2>'' values, below, depend on what you select for this attribute. Not all disciplines have values available for both ''facets''.
  
#Calibrated
+
==== <facet1> ====
#Derived
+
 
#Raw
+
''OPTIONAL''
#Reduced
+
 
 +
This attribute will give a broad category related to the value of ''<discipline_name>''.  What values may be used depends on the value of ''<discipline_name>''.  In turn, the values that can be used in ''<subfacet1>'' depend on the value in this attribute.  A table of ''discipline'':''facet1'' values is available on the [[Standard_Values_Quick_Reference#.3CfacetN.3E|Standard Values Quick Reference]] page.
 +
 
 +
==== <subfacet1> ====
 +
 
 +
''OPTIONAL''
 +
 
 +
This provides a further sub-categorization of the corresponding ''<facet1>''.  Valid values must come from a list dependent on the value of ''<facet1>''.
 +
 
 +
''As of this writing, ''&lt;subfacet1&gt;'' is reserved for future use.
 +
 
 +
==== <facet2> ====
 +
 
 +
''OPTIONAL''
 +
 
 +
This attribute will give a broad category related to the value of ''<discipline_name>''.  What values may be used depends on the value of ''<discipline_name>''.  In turn, the values that can be used in ''<subfacet2>'' depend on the value in this attribute.
 +
 
 +
Not all ''&lt;discipline_name&gt;'' values have a list of ''&lt;facet2&gt;'' values.  A table of ''discipline'':''facet1'' values is available on the [[Standard_Values_Quick_Reference#.3CfacetN.3E|Standard Values Quick Reference]] page.
 +
 
 +
==== <subfacet2> ====
 +
 
 +
''OPTIONAL''
 +
 
 +
This provides a further sub-categorization of the corresponding ''<facet2>''.  Valid values must come from a list dependent on the value of ''<facet2>''.
 +
 
 +
''As of this writing, ''&lt;subfacet2&gt;'' is reserved for future use.
  
 
== <Investigation_Area> ==
 
== <Investigation_Area> ==
Line 113: Line 192:
 
''REQUIRED''
 
''REQUIRED''
  
This class is used primarily to identify the mission or organized observing campaign that collected or produced the data/documentation comprising this product.   
+
This class is used to identify the mission, proposal, or observing campaign that collected or produced the data/documentation comprising this product. It must reference an existing PDS4 "context product". Contact your PDS node consultant for the appropriate reference informationExperienced archivers may prefer to browse the [https://pds.nasa.gov/data/pds4/context-pds4/ Context Product Repository] directly.
 
 
  
{| class="wikitable" style="background-color: thistle"
+
{| class="wikitable" style="background-color: lightcyan"
| '''''Note:''''' ''For SBN data that do not have an associated mission or observing campaign, use the '''Null Investigation''' and its associated reference for this class.''
+
| '''''Note:''''' ''For data headed for the SBN that do not have an associated mission or observing campaign, use '''No Specific Investigation'''. In your label, it will look like this:''
 
|}
 
|}
 +
<pre>
 +
    <Investigation_Area>
 +
        <name>No Specific Investigation</name>
 +
        <type>Individual Investigation</type>
 +
        <Internal_Reference>
 +
            <lid_reference>urn:nasa:pds:context:investigation:individual.none</lid_reference>
 +
            <reference_type>data_to_investigation</reference>
 +
        </Internal_Reference>
 +
    </Investigation_Area>
 +
</pre>
  
 
=== <name> ===
 
=== <name> ===
Line 124: Line 212:
 
''REQUIRED''
 
''REQUIRED''
  
This is the name of the mission or funded observing campaign.  It should be the same as the ''&lt;title&gt;'' in the corresponding investigation context object, which must exist.
+
This is the name of the mission or funded observing campaign.  It should be the same as the ''&lt;title&gt;'' in the corresponding investigation context object, which must exist.  For the null investigation this is "No Specific Investigation".
 +
 
 +
Note that the name you enter is not actually validated against anything.
  
 
=== <type> ===
 
=== <type> ===
Line 132: Line 222:
 
This must have one of these four values:
 
This must have one of these four values:
 
* '''Mission''' - Use this for any funded mission.
 
* '''Mission''' - Use this for any funded mission.
* '''Observing_Campaign''' - Use this for funded and/or formally coordinated observing campaigns (like the International Halley Watch)
+
* '''Observing Campaign''' - Use this for funded and/or formally coordinated observing campaigns (like the International Halley Watch)
* '''Individual_Investigation''' - Use this for data resulting from specifically funded research with an archiving obligation, like data sets resulting from Data Analysis Program funding not associated with the original mission team.
+
* '''Individual Investigation''' - Use this for data resulting from specifically funded research with an archiving obligation, like data sets resulting from Data Analysis Program funding not associated with the original mission team.
* '''Other_Investigation''' - Use this when you're also using the ''Null Investigation'' reference.
+
* '''Other Investigation''' - Use this when you're also using the ''Null Investigation'' reference.
  
The value here must be identical to the ''&lt;type&gt;'' value in the context object cited in the ''&lt;Internal_Reference&gt;''.
+
The value here should be identical to the ''&lt;type&gt;'' value in the context object cited in the ''&lt;Internal_Reference&gt;''.
  
 
=== <Internal_Reference> ===
 
=== <Internal_Reference> ===
Line 150: Line 240:
 
This class documents the significant pieces of the observing equipment.  It is used, for example, to associate instruments, spacecraft, or telescopes with the product.
 
This class documents the significant pieces of the observing equipment.  It is used, for example, to associate instruments, spacecraft, or telescopes with the product.
  
{| class="wikitable" style="background-color: thistle"
+
Use multiple ''Observing_System'' classes only when your data product contains data from two or more disparate sources.
| '''''Note:''''' ''While this class is currently allowed to be repeated, that is almost never logically valid for small bodies data sets.  If you think you need multiple ''&lt;Observing_System&gt;'' classes, contact your PDS consultant'' '''''first'''''.
+
 
|}
 
  
 
=== <name> ===
 
=== <name> ===
Line 177: Line 266:
 
You may wish to include additional components if there is some aspect of the instrumentation that requires a significant amount of explanation or has associated products to characterize it.  For example, it may be useful to define a filter wheel as a separate component if the filters have unique properties that are documented in one or more PDS4 products.
 
You may wish to include additional components if there is some aspect of the instrumentation that requires a significant amount of explanation or has associated products to characterize it.  For example, it may be useful to define a filter wheel as a separate component if the filters have unique properties that are documented in one or more PDS4 products.
  
For SBN data sets, "doing something reasonable" is generally good enough.  Contact your PDS consultant if you have questions or concerns.
+
For SBN data sets, "doing something reasonable" is generally good enough.  Contact your PDS consultant if you have questions or concerns. You can also browse the [https://pds.nasa.gov/data/pds4/context-pds4/ Context Product Repository]
  
 
==== <name> ====
 
==== <name> ====
Line 183: Line 272:
 
''REQUIRED''
 
''REQUIRED''
  
Your component must have a name.  If there is an associated PDS4 product for this component - that is, if you're going to include an &lt;Internal_Reference&gt; - the ''&lt;name&gt;'' value must be the same as that in the cited product.
+
Your component must have a name.  If there is an associated PDS4 product for this component - that is, if you're going to include an &lt;Internal_Reference&gt; - the ''&lt;name&gt;'' value should be the same as that in the cited product.
  
==== <observing_system_component_type> ====
+
==== <type> ====
  
 
''REQUIRED''
 
''REQUIRED''
  
This must be one of the pre-defined standard values.  SBN data prepares should read the notes following the values listed for this attribute in the [[Standard_Values_Quick_Reference#.3Cobserving_system_component_type.3E|Standard Values Quick Reference]].
+
This must be one of the pre-defined standard values.  Standard values can be found in the data dictionary, and summarized in this wiki on the [[Standard_Values_Quick_Reference#.3Cobserving_system_component_type.3E|Standard Values Quick Reference]] page.
  
 
==== <description> ====
 
==== <description> ====
Line 201: Line 290:
 
''OPTIONAL''
 
''OPTIONAL''
  
If there is a PDS4 context product associated with this component, it should be referenced here.  Fill it out the same way you would for internal references in the [[Filling Out the Reference List Classes|''&lt;Reference_List&gt;'']], except in this case for ''&lt;reference_type&gt;'' you must use one of the standard values appropriate to [[Questions#In_.3CObserving_System_Component.3E| &lt;Observing_System_Component&gt;]] references.
+
If there is a PDS4 context product associated with this component, it should be referenced here.  Fill it out the same way you would for internal references in the [[Filling Out the Reference List Classes|''&lt;Reference_List&gt;'']], except in this case for ''&lt;reference_type&gt;'' you must use one of the standard values appropriate to ''&lt;Observing_System_Component&gt;'' references (see the [[Standard_Values_Quick_Reference#In_.3CObserving_System_Component.3E.2F.3CInternal_Reference.3E|Standard Values Quick Reference]] page).
  
 
==== <External_Reference> ====
 
==== <External_Reference> ====
Line 207: Line 296:
 
''OPTIONAL''
 
''OPTIONAL''
  
Use an external reference if there is useful information ''permanently'' available from a source outside PDS.  Note that the archive is supposed to survive for generations, so references to electronic resources are never appropriate here.
+
Use an external reference if there is useful information permanently
 +
available from a source outside PDS.  "Permanent" should be judged on the basis of the expected lifetime of the archive itself. Note that the archive is supposed to survive for generations, so references to electronic resources are never appropriate here.
  
 
== <Target_Identification> ==
 
== <Target_Identification> ==
Line 219: Line 309:
 
''REQUIRED''
 
''REQUIRED''
  
This should be the full, formal name of the target.  In small body products looking at any natural solar system object (comet, asteroid, moon, planet, meteorite, etc.) the string to put here should be the formal name string produced by the [http://pdssbn.astro.umd.edu/tools/form_sbxid.shtml Small Bodies Cross-Identification Data Base] when you find the object in question in the database.  If the object isn't there, check with your friendly, neighborhood SBN representative.
+
This should be the full, formal name of the target.  In small body products looking at any natural solar system object (comet, asteroid, moon, planet, meteorite, etc.) the string to put here should be the formal name string you should get from your friendly, neighborhood SBN representative.
  
{| class="wikitable" style="background-color: thistle"
+
{| class="wikitable" style="background-color: lightcyan"
| '''''Note:''''' ''There are numerous name collisions between Solar System bodies of various types.  The name string produced by the Small Bodies Cross-ID search usually contains multiple IDs to assist in disambiguation in string searches.  Consequently, SBN will require that all Solar System bodies be identified by this format of name string.
+
| '''''Note:''''' ''There are numerous name collisions between Solar System bodies of various types.  The name string used by the Small Bodies Node usually contains multiple IDs to assist in disambiguation in string searches.  Consequently, SBN will require that all Solar System bodies be identified by this format of name string.
 
|}
 
|}
  
Line 229: Line 319:
 
''OPTIONAL''
 
''OPTIONAL''
  
This will rarely be used in SBN products for Solar System objects (see the comments under ''name'', above), but might be useful if, for example, an on-board calibrator has one or more nicknames in common use.
+
This will rarely be used in SBN products for Solar System objects (see the comments under ''name'', above), but might be useful if, for example, an on-board calibrator has one or more nicknames in common use, or if the target is not planetary (calibration stars, for example).
  
 
=== <type> ===
 
=== <type> ===
Line 235: Line 325:
 
''REQUIRED''
 
''REQUIRED''
  
This attribute is required to occur exactly once.  The value must be one of the enumerated list values you can find in the [[Standard_Values_Quick_Reference#In_.3CTarget_Identification.3E|Standard Values Quick Reference]].
+
This attribute is required and may be repeated.  The value(s) must come from the enumerated list values you can find in the [[Standard_Values_Quick_Reference#In_.3CTarget_Identification.3E|Standard Values Quick Reference]].
  
{| class="wikitable" style="background: thistle"
+
{| class="wikitable" style="background: lightcyan"
| '''''Note:''''' ''A single-valued ''&lt;type&gt;'' is problematic for many small bodies, and the current standard value list propagates the PDS3 confusion among various taxonomies that produce useful "types".  (Conflating dynamic and spectral types, for example.)  For the time-being use what seems reasonable, but let your SBN consultant know what the specific problem is so we can try to get a reasonable solution.
+
| '''''Note:''''' ''A single-valued ''&lt;type&gt;'' is problematic for many small bodies. You should use multiple ''&lt;type&gt;'' attributes when that seems reasonable based on what you see in the standard value list linked above. Let your SBN consultant know if you are having any difficulty finding an appropriate ''&lt;type&gt;'' or deciding what a reasonable value or value(s) might be for any particular small body.
 
|}
 
|}
  
Line 251: Line 341:
 
''OPTIONAL''
 
''OPTIONAL''
  
If there is a PDS4 product that provides additional information about this target, cite it here.  This is filled out the same as for the [[Filling_Out_the_Reference_List_Classes#.3CInternal_Reference.3E|&lt;Reference_List&gt;]], but the ''&lt;reference_type&gt;'' must have the value ''data_to_target''.
+
If there is a PDS4 product that provides additional information about this target, cite it here.  This is filled out the same as for the [[Filling_Out_the_Reference_List_Classes#.3CInternal_Reference.3E|&lt;Reference_List&gt;]], but the ''&lt;reference_type&gt;'' must have the value '''data_to_target'''.
  
 
Note that only one ''&lt;Internal_Reference&gt;'' is allowed, at most.  It should be to a PDS4 Target context product.  Any additional references should be listed in that context product, rather than here.
 
Note that only one ''&lt;Internal_Reference&gt;'' is allowed, at most.  It should be to a PDS4 Target context product.  Any additional references should be listed in that context product, rather than here.
Line 259: Line 349:
 
''OPTIONAL''
 
''OPTIONAL''
  
This class is a wrapper to hold classes and attributes from one or more ''mission dictionaries'', or equivalent non-mission ''local dictionaries'' for data not associated with a mission.
+
This class is a wrapper to hold classes and attributes from one or more ''mission dictionaries'', or equivalent non-mission ''local dictionaries'' for data not associated with a mission.  See the [[Using Local Dictionaries]] page on this wiki for details on how to create and use mission dictionary classes in your label.
 
 
The ''&lt;Mission_Area&gt;'' may not be repeatedAny number of different local dictionaries can be referenced inside this class.
 
 
 
  
 +
The ''&lt;Mission_Area&gt;'' may not be repeated.  Any number of different local dictionaries may be referenced inside this class.
  
 
== <Discipline_Area> ==
 
== <Discipline_Area> ==
Line 269: Line 357:
 
''OPTIONAL''
 
''OPTIONAL''
  
This class is a wrapper to hold classes and attributes from one or more ''discipline dictionaries''.
+
This class is a wrapper to hold classes and attributes from one or more ''discipline dictionaries''.  See the [[Using Local Dictionaries]] page on this wiki for details on how to use discipline dictionary classes in your label.
  
The ''&lt;Discpline_Area&gt;'' may not be repeated.  Any number of different ''discipline dictionaries'' can be referenced inside this class.
+
The ''&lt;Discpline_Area&gt;'' may not be repeated.  Any number of different ''discipline dictionaries'' may be referenced inside this class.

Latest revision as of 15:29, 13 April 2022

The <Observation_Area> contains a series of classes used to describe the overall parameters of observational data (target, observing instrument, UTC, etc.). It is required in observational products, and may also be used in collection and bundle products, if desired.

For additional explanation, see the PDS4 Standards Reference, or contact your PDS node consultant.

Following are the attributes and subclasses you'll find in the Observation_Area, in label order.

Note that in the PDS4 master schema, all classes have capitalized names; attributes never do.

<comment>

OPTIONAL

Free-format text for any additional comments or description you might care to include.


<Time_Coordinates>

REQUIRED

This class most often contains just the start_time and stop_time attributes, but may also contain surface-based time measurements, like local solar times.

<start_date_time>

REQUIRED

This should be the UTC start date and time of the observation, in any of several standard date formats (day-of-year, YMD, etc.) Maximum precision is four decimal places in the "seconds" field. The UTC indicator ('Z') on the end is required, and of course your start time should be in UTC.

The <start_date_time> attribute is required. On those rare occasions when it is not an applicable concept, use the nilReason attribute with a value of either "inapplicable" or "unknown", as appropriate, with no value for <start_date_time> itself. It looks like this:

<start_date_time xsi:nil="true" nilReason="inapplicable"/>

or this:

<start_date_time xsi:nil="true" nilReason="inapplicable"></start_date_time>

(These two forms are equivalent. The first form uses the XML shorthand for an element with no value content.)

Note: In order for this to work, you must have assigned the xsi namespace prefix to the XML Schema Instance namespace in the <Product_*> opening tag. This will likely have been done for you automatically if you let your editor generate the XML template for you. If xsi:nil generates a validation error, add xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" to the list of namespaces in the <Product_*> tag. See the "Schema Referencing in PDS4 Labels" page on this wiki for gory details.

<stop_date_time>

REQUIRED

This should be the UTC stop date/time of the observation. It has the same format constraints and caveats as <start_date_time>.

As with <start_date_time>, use a nilReason of "inapplicable" or "unknown" if there is no stop time available for some reason.

Other Optional Attributes

These attributes are optional, but must appear in this order following <stop_time> if present:

<local_mean_solar_time>
<local_true_solar_time>
<solar_longitude>

See the PDS4 data dictionary if they seem appropriate to the data set you're preparing, to make sure the definition matches your use. If it doesn't, check with PDS consultant to see if there is a discipline dictionary attribute that is suitable and can be included in the Discipline_Area; otherwise, create suitable keywords in your local dictionary to reference in the Mission_Area.

<Primary_Result_Summary>

OPTIONAL

This class contains attributes for high-level searching across large sections of the PDS archive. While it is optional in general, it is required in all observational data Collection labels to supply (at a minimum) the purpose and processing level for the collection data products. You should also use it where it would make sense to use it to enable searching. This typically means the same or more detail will appear in observational product labels than in the collection label, where only the common values will appear.

The Standard Values Quick Reference page lists standard values for attributes below (among others).

<purpose>

REQUIRED

This attribute describes the immediate goal for recording the observation. The value must be one of the six defined standard values:

  1. Calibration
  2. Checkout
  3. Engineering
  4. Navigation
  5. Observation Geometry
  6. Science
  7. Supporting Observation

<processing_level>

REQUIRED

This attribute must have one of the following defined standard values:

  1. Calibrated
  2. Derived
  3. Partially Processed
  4. Raw
  5. Telemetry

<description>

OPTIONAL

This attribute can be used for additional free-format text description.

<Science_Facets>

OPTIONAL

This class should be used when it makes sense to provide values for facet-based searching (a way of drilling down through a result set based on broad characteristics). It can be repeated for inter-disciplinary products. The facet values are hierarchical, and the allowed values for a sub-facet are dependent on the primary facet. There is a table on the "Standard Values Quick Reference" page you can check for supplying the facets.

<wavelength_range>

OPTIONAL

This attribute provides a human-readable category of wavelength range for data that is measuring photons. Values include:

  • Far Infrared
  • Gamma Ray
  • Infrared
  • Microwave
  • Millimeter
  • Near Infrared
  • Radio
  • Submillimeter
  • Ultraviolet
  • Visible
  • X-ray

You may repeat this attribute if your product covers more than one of these categories.

<domain>

OPTIONAL

This attribute describes the observation in terms of regions measured outward from the center of a target body. Values include:

  • Atmosphere
  • Dynamics
  • Heliosheath
  • Heliosphere
  • Interior
  • Interstellar
  • Ionosphere
  • Magnetosphere
  • Rings
  • Surface

You may repeat this attribute if your product spans more than one of these domains.

<discipline_name>

REQUIRED

This attribute provides a very high-level characterization of the data as a kind of observation. It is intended to support inter-disciplinary (and cross-node) searching. Use the value that is most specific to your product from this list:

  • Atmospheres
  • Fields
  • Flux Measurements
  • Geosciences
  • Imaging
  • Particles
  • Radio Science
  • Ring-Moon Systems
  • Small Bodies
  • Spectroscopy

So in other words, if your product contains spectroscopy of asteroids, use Spectroscopy rather than Small Bodies as the value of this attribute.

What values you can use for the following <facet1> and <facet2> values, below, depend on what you select for this attribute. Not all disciplines have values available for both facets.

<facet1>

OPTIONAL

This attribute will give a broad category related to the value of <discipline_name>. What values may be used depends on the value of <discipline_name>. In turn, the values that can be used in <subfacet1> depend on the value in this attribute. A table of discipline:facet1 values is available on the Standard Values Quick Reference page.

<subfacet1>

OPTIONAL

This provides a further sub-categorization of the corresponding <facet1>. Valid values must come from a list dependent on the value of <facet1>.

As of this writing, <subfacet1> is reserved for future use.

<facet2>

OPTIONAL

This attribute will give a broad category related to the value of <discipline_name>. What values may be used depends on the value of <discipline_name>. In turn, the values that can be used in <subfacet2> depend on the value in this attribute.

Not all <discipline_name> values have a list of <facet2> values. A table of discipline:facet1 values is available on the Standard Values Quick Reference page.

<subfacet2>

OPTIONAL

This provides a further sub-categorization of the corresponding <facet2>. Valid values must come from a list dependent on the value of <facet2>.

As of this writing, <subfacet2> is reserved for future use.

<Investigation_Area>

REQUIRED

This class is used to identify the mission, proposal, or observing campaign that collected or produced the data/documentation comprising this product. It must reference an existing PDS4 "context product". Contact your PDS node consultant for the appropriate reference information. Experienced archivers may prefer to browse the Context Product Repository directly.

Note: For data headed for the SBN that do not have an associated mission or observing campaign, use No Specific Investigation. In your label, it will look like this:
    <Investigation_Area>
        <name>No Specific Investigation</name>
        <type>Individual Investigation</type>
        <Internal_Reference>
            <lid_reference>urn:nasa:pds:context:investigation:individual.none</lid_reference>
            <reference_type>data_to_investigation</reference>
        </Internal_Reference>
    </Investigation_Area>

<name>

REQUIRED

This is the name of the mission or funded observing campaign. It should be the same as the <title> in the corresponding investigation context object, which must exist. For the null investigation this is "No Specific Investigation".

Note that the name you enter is not actually validated against anything.

<type>

REQUIRED

This must have one of these four values:

  • Mission - Use this for any funded mission.
  • Observing Campaign - Use this for funded and/or formally coordinated observing campaigns (like the International Halley Watch)
  • Individual Investigation - Use this for data resulting from specifically funded research with an archiving obligation, like data sets resulting from Data Analysis Program funding not associated with the original mission team.
  • Other Investigation - Use this when you're also using the Null Investigation reference.

The value here should be identical to the <type> value in the context object cited in the <Internal_Reference>.

<Internal_Reference>

REQUIRED

This must be a reference to the context object associated with the investigation named above. It has the same form as in Filling Out the Reference_List Classes - <Internal_Reference>, but the <reference_type> in this case must have the value data_to_investigation.

<Observing_System>

REQUIRED

This class documents the significant pieces of the observing equipment. It is used, for example, to associate instruments, spacecraft, or telescopes with the product.

Use multiple Observing_System classes only when your data product contains data from two or more disparate sources.


<name>

OPTIONAL

You can assign a name to your observing system, if you like. This can be useful if you expect users to search for an observing system that is already known by a name or title. These names are not vetted by any software, though.

<description>

OPTIONAL

This is a free-format text description which can be included, if desired, to provide additional information or caveats about the observing system as a whole.

<Observing_System_Component>

REQUIRED

At least one component must be included for each observing system, and this class can be repeated as needed. Divide the observing system into pieces that are logical for understanding how the data were recorded. Some examples:

  • In traditional spacecraft data, there are usually two components - the spacecraft on which the instrument is mounted, and the instrument itself.
  • In data from a ground-based observatory, there are generally three components - the observatory, the telescope, and the instrument or detector.

You may wish to include additional components if there is some aspect of the instrumentation that requires a significant amount of explanation or has associated products to characterize it. For example, it may be useful to define a filter wheel as a separate component if the filters have unique properties that are documented in one or more PDS4 products.

For SBN data sets, "doing something reasonable" is generally good enough. Contact your PDS consultant if you have questions or concerns. You can also browse the Context Product Repository

<name>

REQUIRED

Your component must have a name. If there is an associated PDS4 product for this component - that is, if you're going to include an <Internal_Reference> - the <name> value should be the same as that in the cited product.

<type>

REQUIRED

This must be one of the pre-defined standard values. Standard values can be found in the data dictionary, and summarized in this wiki on the Standard Values Quick Reference page.

<description>

OPTIONAL

Another opportunity to provide additional explanation.

<Internal_Reference>

OPTIONAL

If there is a PDS4 context product associated with this component, it should be referenced here. Fill it out the same way you would for internal references in the <Reference_List>, except in this case for <reference_type> you must use one of the standard values appropriate to <Observing_System_Component> references (see the Standard Values Quick Reference page).

<External_Reference>

OPTIONAL

Use an external reference if there is useful information permanently available from a source outside PDS. "Permanent" should be judged on the basis of the expected lifetime of the archive itself. Note that the archive is supposed to survive for generations, so references to electronic resources are never appropriate here.

<Target_Identification>

REQUIRED

This class associates a target name with the product. It can be repeated as many times as needed. If you think you have a product that doesn't have any target, contact your PDS node consultant for what to put in here.

<name>

REQUIRED

This should be the full, formal name of the target. In small body products looking at any natural solar system object (comet, asteroid, moon, planet, meteorite, etc.) the string to put here should be the formal name string you should get from your friendly, neighborhood SBN representative.

Note: There are numerous name collisions between Solar System bodies of various types. The name string used by the Small Bodies Node usually contains multiple IDs to assist in disambiguation in string searches. Consequently, SBN will require that all Solar System bodies be identified by this format of name string.

<alternate_designation>

OPTIONAL

This will rarely be used in SBN products for Solar System objects (see the comments under name, above), but might be useful if, for example, an on-board calibrator has one or more nicknames in common use, or if the target is not planetary (calibration stars, for example).

<type>

REQUIRED

This attribute is required and may be repeated. The value(s) must come from the enumerated list values you can find in the Standard Values Quick Reference.

Note: A single-valued <type> is problematic for many small bodies. You should use multiple <type> attributes when that seems reasonable based on what you see in the standard value list linked above. Let your SBN consultant know if you are having any difficulty finding an appropriate <type> or deciding what a reasonable value or value(s) might be for any particular small body.

<description>

OPTIONAL

This is space for additional description as needed.

<Internal_Reference>

OPTIONAL

If there is a PDS4 product that provides additional information about this target, cite it here. This is filled out the same as for the <Reference_List>, but the <reference_type> must have the value data_to_target.

Note that only one <Internal_Reference> is allowed, at most. It should be to a PDS4 Target context product. Any additional references should be listed in that context product, rather than here.

<Mission_Area>

OPTIONAL

This class is a wrapper to hold classes and attributes from one or more mission dictionaries, or equivalent non-mission local dictionaries for data not associated with a mission. See the Using Local Dictionaries page on this wiki for details on how to create and use mission dictionary classes in your label.

The <Mission_Area> may not be repeated. Any number of different local dictionaries may be referenced inside this class.

<Discipline_Area>

OPTIONAL

This class is a wrapper to hold classes and attributes from one or more discipline dictionaries. See the Using Local Dictionaries page on this wiki for details on how to use discipline dictionary classes in your label.

The <Discpline_Area> may not be repeated. Any number of different discipline dictionaries may be referenced inside this class.