Filling Out the Observation Area Classes

From The SBN Wiki
Revision as of 13:24, 6 June 2017 by Raugh (talk | contribs) ()
Jump to navigation Jump to search

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, 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. 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. For example, if you are writing a collection label for a series of a thousand images that differ only by, say, pointing direction, then you would include a <Primary_Result_Summary> class in the collection label, but not in the individual Product_Observational labels for the images. This means a user would find the collection as a whole, rather than being swamped with thousands of indiscernible single-image results. On the other hand, if your collection also includes a table of photometry derived from those images, you should include a <Primary_Result_Summary> in the photometry table label, so that it can be found as a photometric product independent of the image data.

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

<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
  • Heliosphere
  • Interior
  • Interstellar
  • Ionosphere
  • Magnetosphere
  • 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
  • Imaging
  • Particles
  • 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 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. This context object doesn't exist yet, but it will as soon as we start real SBN production.

<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, as you might expect, "Null 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.

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

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