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

From The SBN Wiki
Jump to navigation Jump to search
m ()
(: Safety Save)
Line 152: Line 152:
  
 
{| class="wikitable" style="background-color: thistle"
 
{| class="wikitable" style="background-color: thistle"
| '''''Note:''''' ''While this class is currently allowed to be repeated, that is almost never logically valid.  If you think you need multiple ''<Observing_System>'' classes, contact your PDS consultant'' '''''first'''''.
+
| '''''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 &lt;Internal_Reference&gt; - the ''&lt;name&gt;'' 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.  See the notes on the page [[Questions#In_.3CObserving_System_Component.3E|Questions - &lt;Observing_System_Component&gt;]]
 +
 +
==== <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 [[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.
 +
 +
==== <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> ==
 
== <Target_Identification> ==

Revision as of 19:35, 28 November 2012

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

There is a useful list of standard values for the various attributes in this class on the Questions page

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 on the Questions page.

<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 on the Questions page.

<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. See the notes on the page Questions - <Observing_System_Component>

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


<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 difference discipline dictionaries can be referenced inside this class.