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

From The SBN Wiki
Jump to navigation Jump to search
(: Replace "Questions" links)
m (: Updated "Questions" link)
Line 188: Line 188:
 
''REQUIRED''
 
''REQUIRED''
  
This must be one of the pre-defined standard values.  See the notes on the page [[Questions#In_.3CObserving_System_Component.3E|Questions - <Observing_System_Component>]]
+
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]].
  
 
==== <description> ====
 
==== <description> ====

Revision as of 16:51, 24 January 2013

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

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.

The <start_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_time> itself. It looks like this:

<start_time nilReason="inapplicable"/>

or this:

<start_time nilReason="inapplicable"></start_time>

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

<stop_time>

REQUIRED

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

As with <start_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, after <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. For more detailed descriptive attributes, look for the <Primary_Result_Details> in the <Discipline_Area>.

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

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.

<purpose>

REQUIRED

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

  1. Calibration
  2. Checkout
  3. Engineering
  4. Navigation
  5. Science

<data_regime>

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.

<description>

OPTIONAL

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

<processing_level_id>

REQUIRED

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

  1. Calibrated
  2. Derived
  3. Raw
  4. Reduced

<Investigation_Area>

REQUIRED

This class is used primarily to identify the mission or organized observing campaign that collected or produced the data/documentation comprising this product.


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.

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

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

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 <Observing_System> classes, contact your PDS consultant first.

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

<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 must be the same as that in the cited product.

<observing_system_component_type>

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.

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

<External_Reference>

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.

<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 produced by the 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.

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.

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

<type>

REQUIRED

This attribute is required to be present, single-valued and one of the enumerated list values you can find on the page Questions - <Target_Identification>/<type>

Note: A single-valued <type> 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.

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

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


<Discipline_Area>

OPTIONAL

This class is a wrapper to hold classes and attributes from one or more discipline dictionaries.

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