Difference between revisions of "Filling Out Context Object Classes"

From The SBN Wiki
Jump to navigation Jump to search
(Update for Release 1.0)
 
(8 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
For additional explanation, see the PDS4 ''Standard Reference'', or contact your PDS node consultant.
 
For additional explanation, see the PDS4 ''Standard Reference'', or contact your PDS node consultant.
  
''Note that in the PDS4 master schema, all classes have capitalized names; attributes never do.
+
''Note that in the PDS4 master schema, all classes have capitalized names; attributes never do.''
  
  
Line 18: Line 18:
 
''REQUIRED''
 
''REQUIRED''
  
This ''must'' be identical to either the value of the ''<title>'' or one of the ''<alternate_title>" attributes listed in the ''Identification_Area''.
+
This ''must'' be identical to either the value of the ''<title>'' or one of the ''<alternate_title>'' attributes listed in the ''Identification_Area''.
  
 
=== <description> ===
 
=== <description> ===
Line 41: Line 41:
  
 
This must be one of the two standard values ''Laboratory'' or ''Observatory''.  If you need a different value, contact your PDS consultant.
 
This must be one of the two standard values ''Laboratory'' or ''Observatory''.  If you need a different value, contact your PDS consultant.
 
{| class="wikitable" style="background-color: yellow"
 
| '''''Note:''''' ''This attribute will be required for SBN-generated or reviewed ''Facility'' objects.
 
|}
 
  
 
=== <address> ===
 
=== <address> ===
Line 81: Line 77:
 
This must be one of the standard values listed in the [[Standard_Values_Quick_Reference#In_.3CProduct_Context.3E.2F.3CInstrument.3E|Standard Values Quick Reference]].  If the instrument you're describing corresponds to more than one of these values, you may repeat the ''<type>'' attribute.
 
This must be one of the standard values listed in the [[Standard_Values_Quick_Reference#In_.3CProduct_Context.3E.2F.3CInstrument.3E|Standard Values Quick Reference]].  If the instrument you're describing corresponds to more than one of these values, you may repeat the ''<type>'' attribute.
  
=== <model_id*gt; ===
+
=== <model_id> ===
  
 
''OPTIONAL''
 
''OPTIONAL''
Line 108: Line 104:
 
== <Instrument_Host> ==
 
== <Instrument_Host> ==
  
This class is for describing the hardware an ''Instrument'' is physically mounted on/to.
+
This class is for describing the (space) hardware an ''Instrument'' is physically mounted on, to, or in.  Practically speaking, this will generally be the spacecraft or vehicle (as opposed to a specific boom, platform, or dewar), at least in current usage. 
 +
 
 +
Do not use this context object for ground-based things like telescopes and observatories that live on Earth - they have their own specific context objects.
  
 
=== <name> ===
 
=== <name> ===
Line 115: Line 113:
  
 
This should be the same as or equivalent to the value of the ''<title>'' attribute in the ''Identification_Area''.
 
This should be the same as or equivalent to the value of the ''<title>'' attribute in the ''Identification_Area''.
 
=== <version_id> ===
 
 
''OPTIONAL''
 
 
{| class="wikitable" style="background-color: yellow"
 
| '''''Note:''''' ''The version of the ''Instrument_Host'' product is in the ''Identification_Area''.  This ''version_id'' should '''never''' be used in SBN Instrument_Host context products.''
 
|}
 
  
 
=== <type> ===
 
=== <type> ===
Line 128: Line 118:
 
''REQUIRED''
 
''REQUIRED''
  
This must be one of the standard values '''Earth Based''', '''Rover''' or '''Spacecraft'''.
+
This must be one of the standard values '''Lander''', '''Rover''', or '''Spacecraft''' (or '''Earth-Based''', but see the box following).
  
{| class="wikitable" style="background-color: yellow"
+
{| class="wikitable" style="background-color: lightcyan"
| '''''Note:''''' These values don't make sense in many cases, or when compared to each other. So for SBN data, use these rules (use them very roughly, if necessary):
+
| '''''Note:''''' These values don't correlate well to some cases, or sometimes when compared to each other. So for SBN data, use these rules (use them very roughly, if necessary):
* If it moves through space, it's a ''Spacecraft''
+
* If it moves through space, it's a ''Spacecraft''.
* If it moves through or on anything else, it's a ''Rover''
+
* If it is more-or-less permanently orbiting Earth, it's a ''Spacecraft''.
* If it doesn't move, it's ''Earth Based''
+
* If it moves around on something other than Earth, it's a ''Rover''.
 +
* If it doesn't move and it's not on Earth, it's a ''Lander''.
 +
* If it's on Earth, in Earth, or returns to Earth between observing runs, you're probably using the wrong context object.  Instead, use the appropriate ground-based context object, like ''Telescope'' or ''Facility''.  If there doesn't seem to be an appropriate ground-based context object, contact SBN.
 
|}
 
|}
  
Line 154: Line 146:
  
 
This is a free-format text description of the instrument host.
 
This is a free-format text description of the instrument host.
 
  
 
== <Investigation> ==
 
== <Investigation> ==
  
This class is for describing a mission, a coordinated observing campaign, or some other large-scale, organized effort to collect data.
+
This class is for describing a mission, a coordinated observing campaign, or some other large-scale, organized (and typically funded to ensure archiveable results) effort to collect data.
  
 
=== <name> ===
 
=== <name> ===
Line 165: Line 156:
  
 
This should be the same as or equivalent to the value of the ''<title>'' attribute in the ''Identification_Area''.
 
This should be the same as or equivalent to the value of the ''<title>'' attribute in the ''Identification_Area''.
 +
 
=== <type> ===
 
=== <type> ===
  
Line 175: Line 167:
 
''REQUIRED''
 
''REQUIRED''
  
The date of the start of the investigation, in ISO 8601 format.
+
The date of the start of the investigation, in ''YYYY-MM-DD'' format.
 
 
{| class="wikitable" style="background-color: yellow"
 
| '''Note:''' For some reason this is required for all investigations, and can never be ''nil''. If you are trying to write a context product for something without a clear starting point, seek advice from your PDS data consultant.
 
|}
 
  
 
=== <stop_date> ===
 
=== <stop_date> ===
Line 185: Line 173:
 
''REQUIRED''
 
''REQUIRED''
  
The date of the end of the investigation, in ISO 8601 format.
+
The date of the end of the investigation, in ''YYYY-MM-DD'' format.
  
 
If this is not available for some reason (most often that the investigation isn't over yet), you can use the <code>nilreason</code> attribute, like this:
 
If this is not available for some reason (most often that the investigation isn't over yet), you can use the <code>nilreason</code> attribute, like this:
Line 215: Line 203:
 
''Target'' products should be created when such a hub is wanted/needed.  For example, if the target is a piece of hardware, like a calibration lamp, with specific characteristics that can be/are described by associated document products in the archive (or published references outside the archive), a ''Target'' product can link the target name to those references via the ''&lt;Reference_List&gt;'' and could be very helpful to end users.  ''Target'' products for half a million anonymous asteroids - not so much.
 
''Target'' products should be created when such a hub is wanted/needed.  For example, if the target is a piece of hardware, like a calibration lamp, with specific characteristics that can be/are described by associated document products in the archive (or published references outside the archive), a ''Target'' product can link the target name to those references via the ''&lt;Reference_List&gt;'' and could be very helpful to end users.  ''Target'' products for half a million anonymous asteroids - not so much.
  
{| class="wikitable" style="background-color: yellow"
+
{| class="wikitable" style="background-color: lightcyan"
 
| '''NOTE: ''' SBN data preparers should never create ''Target'' context products for natural targets (comets, asteroids, planets, etc.).  If you should ever require one for some reason, SBN will create it for you.
 
| '''NOTE: ''' SBN data preparers should never create ''Target'' context products for natural targets (comets, asteroids, planets, etc.).  If you should ever require one for some reason, SBN will create it for you.
 
|}
 
|}
Line 241: Line 229:
 
This class is designed for identifying and providing key details about terrestrial telescopes, fixed and roving.
 
This class is designed for identifying and providing key details about terrestrial telescopes, fixed and roving.
  
=== &lt;name&gt; ===
 
 
''OPTIONAL''
 
 
This should be the same as or equivalent to the value of the ''&lt;title&gt;'' attribute in the ''Identification_Area''.
 
 
=== &lt;aperture&gt; ===
 
=== &lt;aperture&gt; ===
  
Line 259: Line 242:
 
''OPTIONAL''
 
''OPTIONAL''
  
The longitude of a permanent telescope mounting.  The value is a single floating-point number, and you will need to specify units for the value.  For example:
+
The East longitude of a permanent telescope mounting, in the rage 0-360&deg;.  The value is a single floating-point number, and you will need to specify units for the value.  For example:
 
<pre>
 
<pre>
 
   <telescope_longitude unit="deg">123.4567</telescope_longitude>
 
   <telescope_longitude unit="deg">123.4567</telescope_longitude>
 
</pre>
 
</pre>
 
{| class="wikitable" style="background-color: yellow"
 
| '''Note:''' This attribute is poorly defined in the PDS4 data dictionary, as the direction of measurement is not indicated and the unit is allowed to be any angular unit.  The range is 0-360 degrees.  Until these issues are corrected, always indicate the direction of measurement in the ''&lt;description&gt;'' attribute, and '''always''' state longitude in degrees.
 
|}
 
  
 
=== &lt;telescope_latitude&gt; ===
 
=== &lt;telescope_latitude&gt; ===
  
''REQUIRED''
+
''OPTIONAL''
  
North latitude of a permanent telescope mounting.  The value is a single floating-point value, and you will need to specify units for the value.  For example:
+
North latitude of a permanent telescope mounting, in the range &plusmn;90&deg;.  The value is a single floating-point value, and you will need to specify units for the value.  For example:
  
 
<pre>
 
<pre>
Line 278: Line 257:
 
</pre>
 
</pre>
  
{| class="wikitable" style="background-color: yellow"
+
=== &lt;telescope_altitude&gt; ===
| '''Note:''' The definition of this attributes in the PDS4 data dictionary is a little fuzzy.  It should be North latitude (South being indicated by negative numbers), and it must be stated in degrees.
 
|}
 
 
 
=== &lt;altitude&gt; ===
 
  
 
''REQUIRED''
 
''REQUIRED''
Line 293: Line 268:
 
=== &lt;coordinate_source&gt; ===
 
=== &lt;coordinate_source&gt; ===
  
''REQUIRED''
+
''OPTIONAL''
  
This must be one of the values in the [[Standard_Values_Quick_Reference#.3Ccoordinate_source.3E|Standard Value Quick Reference]].  If you have a value that doesn't fit, let me knowUse ''Unknown'' for mobile telescopes.
+
This is a free-format text field used to indicate the source of the telescope coordinates, if any.  If the coordinates are from a known definitive source (a USGS survey, for example), then definitely cite it hereIf the source is unknown or not intended to be particularly accurate, you can omit this attribute entirely.
  
 
=== &lt;description&gt; ===
 
=== &lt;description&gt; ===
Line 301: Line 276:
 
''OPTIONAL''
 
''OPTIONAL''
  
This is for a free-format text description of the telescope.
+
This is for a free-format text description of the telescope.
 +
 
 +
{| class="wikitable" style="background-color: lightcyan"
 +
| ''For telescopes that have no coordinates'': If the telescope being described has no latitude, longitude, or altitude because it is a mobile telescope, please do include a ''description'' that contains at least the words "mobile telescope". Otherwise, please use the ''description'' text to explain as precisely as possible what sort of telescope this is and where it is permanently located, so that others may find its coordinates when needed.
 +
|}

Latest revision as of 13:14, 23 March 2016

Following are the context object classes and their attributes. Only one instance of one of these may appear in any context product. Only the context objects that a data preparer is likely to use are listed. There are some additional objects used for PDS system maintenance. Your PDS consultant will advise you directly in the unlikely event you need to create context products for these.

NOTE: I believe it is true that in all cases it is the <title> attribute found in the <Identification_Area> that contains the official name of whatever it is the context object is describing, although this does not appear to be stated in the PDS4 documentation. While <title> is always required, <name> is frequently optional. If you do supply a value for <name>, the value should be very close to, if not the same as, the title in the Identification_Area.

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

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


<Agency>

This is used to provide basic information about an agency, like NASA or ESA.

<name>

REQUIRED

This must be identical to either the value of the <title> or one of the <alternate_title> attributes listed in the Identification_Area.

<description>

REQUIRED

This is for a brief description of the agency named.

<Facility>

This class is used for facilities like a terrestrial labs and observatories. Although every field within it is optional (because different facilities have different known attributes), you should never send an empty <Facility> class to SBN for archiving.

<name>

OPTIONAL

This should be the same as or equivalent to the value of the <title> attribute in the Identification_Area.

<type>

OPTIONAL

This must be one of the two standard values Laboratory or Observatory. If you need a different value, contact your PDS consultant.

<address>

OPTIONAL

This is a text field to hold the address (mailing address, street address or both) of the facility.

<country>

OPTIONAL

This attribute is for the name of the country. It's not clear why this is here. If you use it, I suggest you use it for the full name of the country, with the intention of using it for searching out ground-based observatories and related data by country of origin.

<description>

OPTIONAL

This is a place for free-format text to provide additional relevant details about the facility.


<Instrument>

Use this for anything that can be reasonably considered to be an instrument, in the "taking data" sense.

<name>

OPTIONAL

This should be the same as or equivalent to the value of the <title> attribute in the Identification_Area.

<type>

REQUIRED

This must be one of the standard values listed in the Standard Values Quick Reference. If the instrument you're describing corresponds to more than one of these values, you may repeat the <type> attribute.

<model_id>

OPTIONAL

If the instrument has a model number or the equivalent, it can be recorded here.

<naif_instrument_id>

OPTIONAL

If the instrument being described has a NAIF identification code, type it in here.

<serial_number>

OPTIONAL

If the instrument has a known serial number, this is the place for it.

<description>

REQUIRED

Free-format text description of the instrument.


<Instrument_Host>

This class is for describing the (space) hardware an Instrument is physically mounted on, to, or in. Practically speaking, this will generally be the spacecraft or vehicle (as opposed to a specific boom, platform, or dewar), at least in current usage.

Do not use this context object for ground-based things like telescopes and observatories that live on Earth - they have their own specific context objects.

<name>

OPTIONAL

This should be the same as or equivalent to the value of the <title> attribute in the Identification_Area.

<type>

REQUIRED

This must be one of the standard values Lander, Rover, or Spacecraft (or Earth-Based, but see the box following).

Note: These values don't correlate well to some cases, or sometimes when compared to each other. So for SBN data, use these rules (use them very roughly, if necessary):
  • If it moves through space, it's a Spacecraft.
  • If it is more-or-less permanently orbiting Earth, it's a Spacecraft.
  • If it moves around on something other than Earth, it's a Rover.
  • If it doesn't move and it's not on Earth, it's a Lander.
  • If it's on Earth, in Earth, or returns to Earth between observing runs, you're probably using the wrong context object. Instead, use the appropriate ground-based context object, like Telescope or Facility. If there doesn't seem to be an appropriate ground-based context object, contact SBN.

<naif_host_id>

OPTIONAL

If the host has a NAIF identification code, this is the place to put it.

<serial_number>

OPTIONAL

If the host has a known serial number, it can be recorded here for posterity,

<description>

REQUIRED

This is a free-format text description of the instrument host.

<Investigation>

This class is for describing a mission, a coordinated observing campaign, or some other large-scale, organized (and typically funded to ensure archiveable results) effort to collect data.

<name>

OPTIONAL

This should be the same as or equivalent to the value of the <title> attribute in the Identification_Area.

<type>

REQUIRED

This must be one of the four standard values: Individual Investigation, Mission, Observing Campaign, Other Investigation.

<start_date>

REQUIRED

The date of the start of the investigation, in YYYY-MM-DD format.

<stop_date>

REQUIRED

The date of the end of the investigation, in YYYY-MM-DD format.

If this is not available for some reason (most often that the investigation isn't over yet), you can use the nilreason attribute, like this:

    <stop_date xsi:nil="true" nil_reason="anticipated"/>

<description>

REQUIRED

This is a free-format text description of the investigation.

<Other>

Use this context class only if no other class is reasonably applicable.

<description>

REQUIRED

This free-form text should provide whatever key details about the context object are relevant to the archive. Best to be explicit about this if you're using the Other context object.


<Target>

Use this class when it is useful to define a target context object for an observational target. It provides a permanent hub for linking to additional description and information (via the Reference_List, primarily).

Target products should be created when such a hub is wanted/needed. For example, if the target is a piece of hardware, like a calibration lamp, with specific characteristics that can be/are described by associated document products in the archive (or published references outside the archive), a Target product can link the target name to those references via the <Reference_List> and could be very helpful to end users. Target products for half a million anonymous asteroids - not so much.

NOTE: SBN data preparers should never create Target context products for natural targets (comets, asteroids, planets, etc.). If you should ever require one for some reason, SBN will create it for you.

<name>

OPTIONAL

This should be the same as or equivalent to the value of the <title> attribute in the Identification_Area.

<type>

OPTIONAL

If present, the value must be one of the standard values from the list in the Standard Values Quick Reference. If more than one of these types applies to the Target, you may repeat the <type> attribute.

<description>

REQUIRED This free-format text field must contain a description of the target itself.


<Telescope>

This class is designed for identifying and providing key details about terrestrial telescopes, fixed and roving.

<aperture>

REQUIRED

This attribute holds the diameter of the telescope aperture. You must specify a unit of length for this value. For example:

    <aperture unit="m">1.3</aperture>

<telescope_longitude>

OPTIONAL

The East longitude of a permanent telescope mounting, in the rage 0-360°. The value is a single floating-point number, and you will need to specify units for the value. For example:

  <telescope_longitude unit="deg">123.4567</telescope_longitude>

<telescope_latitude>

OPTIONAL

North latitude of a permanent telescope mounting, in the range ±90°. The value is a single floating-point value, and you will need to specify units for the value. For example:

  <telescope_latitude unit="deg">-12.34567</telescope_latitude>

<telescope_altitude>

REQUIRED

This is the altitude of the telescope above sea level. You will have to specify units for this value:

    <altitude unit="m">14000</altitude>

<coordinate_source>

OPTIONAL

This is a free-format text field used to indicate the source of the telescope coordinates, if any. If the coordinates are from a known definitive source (a USGS survey, for example), then definitely cite it here. If the source is unknown or not intended to be particularly accurate, you can omit this attribute entirely.

<description>

OPTIONAL

This is for a free-format text description of the telescope.

For telescopes that have no coordinates: If the telescope being described has no latitude, longitude, or altitude because it is a mobile telescope, please do include a description that contains at least the words "mobile telescope". Otherwise, please use the description text to explain as precisely as possible what sort of telescope this is and where it is permanently located, so that others may find its coordinates when needed.