Skip to content

Commit

Permalink
Document port
Browse files Browse the repository at this point in the history 
Ported documentation from sbnwiki site
  • Loading branch information
@acraugh
acraugh committed Apr 11, 2024
1 parent 1deb3a8 commit 1604d58
Show file tree
Hide file tree
Showing 22 changed files with 2,542 additions and 111 deletions.
Binary file removed docs/build/latex/examplenamespace.pdf
View file
Binary file not shown.
Binary file removed docs/examplenamespace.pdf
View file
Binary file not shown.
2 changes: 1 addition & 1 deletion docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

# -- Project information -----------------------------------------------------

project = 'Example Namespace'
project = 'Spectral/Spectrosopy Namespace'
# copyright = overidden by CSS specified below
author = 'NASA Planetary Data System'

Expand Down
29 changes: 29 additions & 0 deletions docs/source/detailed/attributeList.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
Alphabetical List of Attributes
**************************************************

A complete list of all attributes in the Spectral (sp) Dictionary, in alphabetical
order, is available through the `PDS4 Data Dictionary <https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1L00/webhelp/all/>`_
page, which is regenerated automatically with each release of the PDS4 Information Model.

To find the Spectral Discipline attribute list, look down the list of (alphabetically sorted)
dictionary prefixes in the left menu for "Attributes in the sp namespace".
Select that item and the list of attributes will be presented on both the left and the
right as clickable links.

Clicking on the specific attribute name will produce a grid with the full, formal
definition of the attribute, including data type, restrictions on values, and the
list of defined permissible values (if any) and their definitions.

**Note** that attributes might appear as members of different classes, and that their
definitions, or more likely their permissible values, might be context-dependent.

Clicking on the class name in the title bar of the attribute grid will take you to
the definition of the class containing that attribute.

If the attribute has an associated unit of measure type, that attribute *must* have
an XML attribute called "unit" in its tag when it is used. For example::

<nh:tdi_rate unit="Hz">40.4694</nh:tdi_rate>
You can see valid values to use for the "unit=" XML attribute by clicking on the
value of "Unit of Measure Type" in the grid.
22 changes: 22 additions & 0 deletions docs/source/detailed/classList.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
Alphabetical List of Classes
**************************************************

A complete list of all classes in the Spectral (sp) Dictionary, in alphabetical
order, is available through the `PDS4 Data Dictionary <https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1L00/webhelp/all/>`_
page, which is regenerated automatically with each release of the PDS4 Information Model.

To find the Spectral Discipline class list, look down the list of (alphabetically sorted)
dictionary prefixes in the left menu for "Classes in the sp namespace".
Select that item and the list of classes will be presented on both the left and
the right as clickable links.

Clicking on the specific class name will produce a grid with the full, formal
definition of the class.

Clicking on the class name in the "Referenced from:" line at the bottom of the
grid will take you to the containing class, where you can see the cardinality
of the class (i.e., whether it is required, optional, or repeatable) in the
containing class.

You can also click on the attribute names listed to see details of the
attribute definitions.
13 changes: 0 additions & 13 deletions docs/source/detailed/example.md
View file

This file was deleted.

125 changes: 125 additions & 0 deletions docs/source/detailed/outline.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
Spectral/Spectroscopy Discipline Namespace Outline
######################################################

*<sp:Spectral_Characteristics>* is the public entry point to the Spectral Discipline
namespace. This class contains all other Spectral classes and must be included to gain
access to them. Below is a summary outline of all classes and attributes
currently available in the Spectral Discipline dictionary, in the order in which they
would appear in a label if every single one was used.

Note that there are no real cases in which every single discipline class and
attribute would appear in a single label. The point of this outline is primarily
to catalog what is present and show the required ordering within classes when
they are included in a label.

**Note:** The abbreviated form "(Energy|Frequency|Wavelength|Wavenumber)" is used for
those parallel classes that have identical structure but names that are tied to the
requirements for units of measure. The form used must be consistent with the value
of the *sp:spectral_bin_type>* attribute.

::

<sp:Spectral_Characteristics>
<pds:Local_Internal_Reference>
<pds:comment>
<pds:local_identifier_reference>
<pds:local_reference_type>
<sp:description>
<sp:spectrum_format>
<sp:value_field_name>
<sp:value_field_number_list>
<sp:spectral_bin_type>
<sp:Observation_Parameters>
<sp:number_of_exposures>
<sp:net_integration_time>
<sp:resolution_limit_(energy|frequency|wavelength|wavenumber)>
<sp:solar_analog_star_name>
<sp:absolute_calibration_star_name>
<sp:comment>
<sp:Field_of_View>
<sp:description>
<sp:Circular_FOV>
<sp:diameter_angle>
<sp:Rectangular_FOV>
<sp:width_angle>
<sp:length_angle>
<sp:celestial_north_pole_angle>
<sp:body_positive_pole_angle>
<sp:Complex_FOV>
<sp:width_angle>
<sp:length_angle>
<sp:celestial_north_pole_angle>
<sp:body_positive_pole_angle>

<pds:Internal_Reference>
<pds:lid_reference> *or* <pds:lidvid_reference>
<pds:reference_type>
<pds:comment>
<sp:Bin_Description>
<sp:bin_profile_description>
<sp:Uniformly_Sampled_(Energy|Frequency|Wavelength|Wavenumber)>
<sp:axis_name>
<sp:sampling_interval_(energy|frequency|wavelength|wavenumber)>
<sp:sampling_scale>
<sp:sampling_base>
<sp:bin_width_(energy|frequency|wavelength|wavenumber)>
<sp:first_center_(energy|frequency|wavelength|wavenumber)>
<sp:last_center_(energy|frequency|wavelength|wavenumber)>
<sp:comment>
<sp:Axis_Bin_Set_(Energy|Frequency|Wavelength|Wavenumber)>
<sp:axis_name>
<sp:Bin_(Energy|Frequency|Wavelength|Wavenumber)>
<sp:bin_sequence_number>
<sp:center_(energy|frequency|wavelength|wavenumber)>
<sp:bin_width_(energy|frequency|wavelength|wavenumber)>
<sp:detector_number>
<sp:grating_position>
<sp:original_bin_number>
<sp:Filter>
<sp:filter_name>
<sp:filter_number>
<sp:comment>
<sp:Spectral_Lookup>
<sp:Bin_Center_Lookup>
<sp:bin_center_field_name>
<sp:bin_center_field_number_list>
<pds:Local_Internal_Reference>
<pds:comment>
<pds:local_identifier_reference>
<pds:local_reference_type>
<pds:Internal_Reference>
<pds:lid_reference> *or* <pds:lidvid_reference>
<pds:reference_type>
<pds:comment>
<sp:Bin_Width_Constant>
<sp:bin_width_(energy|frequency|wavelength|wavenumber)>
<sp:Bin_Width_Lookup>
<sp:bin_width_field_name>
<sp:bin_width_field_number_list>
<pds:Local_Internal_Reference>
<pds:comment>
<pds:local_identifier_reference>
<pds:local_reference_type>
<pds:Internal_Reference>
<pds:lid_reference> *or* <pds:lidvid_reference>
<pds:reference_type>
<pds:comment>

<sp:comment>
192 changes: 192 additions & 0 deletions docs/source/examples/1D-Lookup-DEMO.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
#######################################################################
1D Spectrum, Spectral Lookup
#######################################################################

.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1L00.sch" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<?xml-model href="https://pds.nasa.gov/pds4/sp/v1/PDS4_SP_1L00_1320.sch" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<!--
This "label" is intended only to demonstrate how to use certain features of the Spectral
Dictionary, and pretty much nothing else. It is not a real label in any sense, even though
it should produce no errors when validated against the PDS schema. A real label would have
references to additional dictionaries, for example, from the mission, for geometry, and/or
for any other related discipline or local namespaces. Any "data" you see here is fictitious,
and provided merely to remove any validation errors that might otherwise occur.
Note, in particular, that any conscientious reviewer would consider the data structure classes
to be inadequate without appropriate descriptions, extrema, null data indicates, and similar
essential metadata.
This label demonstrates:
- Using <sp:Spectral_Characteristics> for a "1D" table spectrum;
- Using the <sp:Complex_FOV> to describe the aperture; and
- Using the <sp:Spectral_Lookup> class to identify bin centers and widths as fields in
the table.
-->
<Product_Observational xmlns="http://pds.nasa.gov/pds4/pds/v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sp="http://pds.nasa.gov/pds4/sp/v1"
xsi:schemaLocation="http://pds.nasa.gov/pds4/pds/v1 https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1L00.xsd
http://pds.nasa.gov/pds4/sp/v1 http://pds.nasa.gov/pds4/sp/v1/PDS4_SP_1L00_1320.xsd">
<Identification_Area>
<logical_identifier>urn:nasa:pds:bundle:collection:product</logical_identifier>
<version_id>1.0</version_id>
<title>Test Label 1 for Spectral Dictionary - Valid Label</title>
<information_model_version>1.21.0.0</information_model_version>
<product_class>Product_Observational</product_class>
</Identification_Area>
<Observation_Area>
<Time_Coordinates>
<start_date_time xsi:nil="true" nilReason="inapplicable"/>
<stop_date_time xsi:nil="true" nilReason="inapplicable"/>
</Time_Coordinates>
<Investigation_Area>
<name>None</name>
<type>Individual Investigation</type>
<Internal_Reference>
<lid_reference>urn:nasa:pds:context:investigation:individual.none</lid_reference>
<reference_type>data_to_investigation</reference_type>
</Internal_Reference>
</Investigation_Area>
<Observing_System>
<Observing_System_Component>
<name>None</name>
<type>Telescope</type>
</Observing_System_Component>
</Observing_System>
<Target_Identification>
<name>None</name>
<type>Comet</type>
</Target_Identification>
<Discipline_Area>
<!-- Spectral Lookup for 1D spectrum (table), in Table fields -->
<sp:Spectral_Characteristics>
<Local_Internal_Reference>
<comment>
The spectral bin centers are included in the table in the named field. In
this case, FWHM values are also included in the table as a separate field.
Table field classes must have 'name' attributes (although these are not
currently required to be unique).
</comment>
<local_identifier_reference>TableChar1D</local_identifier_reference>
<local_reference_type>spectral_characteristics_to_table_object</local_reference_type>
</Local_Internal_Reference>
<sp:spectrum_format>1D</sp:spectrum_format>
<sp:value_field_name>Intensity</sp:value_field_name>
<sp:spectral_bin_type>wavelength</sp:spectral_bin_type>
<sp:Observation_Parameters>
<sp:number_of_exposures>1</sp:number_of_exposures>
<sp:net_integration_time unit="s">20</sp:net_integration_time>
<sp:resolution_limit_wavelength unit="nm">5</sp:resolution_limit_wavelength>
</sp:Observation_Parameters>
<sp:Field_of_View>
<sp:description>
This field of view is not a regular shape. Typically this should be
described in some detail in a document that is referenced within this
class (we'll assume one exists in this case as a demonstration). For
example, the Alice spectrometer on New Horizons has a "lollipop" shaped
slit. I don't know the actual dimensions of that slit, so the
description below is fake. This description would specify how the
'width' value indicated here correspond to the slit design, for example.
</sp:description>
<sp:Complex_FOV>
<sp:width_angle unit="arcsec">10</sp:width_angle>
<sp:width_angle unit="arcsec">5</sp:width_angle>
<sp:length_angle unit="arcsec">100</sp:length_angle>
<sp:celestial_north_position_angle unit="deg">70</sp:celestial_north_position_angle>
</sp:Complex_FOV>
<Internal_Reference>
<lid_reference>urn:nasa:pds:nh_docs:slit_specs</lid_reference>
<reference_type>spectral_characteristics_to_document</reference_type>
<comment>
This document provides both a diagram and specific physical
measurements of the lollipop-shaped slit.
</comment>
</Internal_Reference>
</sp:Field_of_View>
<sp:Bin_Description>
<sp:bin_profile_description>
Bin widths indicated in the table are those listed in the manufacturer's
specifications.
</sp:bin_profile_description>
<sp:Spectral_Lookup>
<sp:Bin_Center_Lookup>
<sp:bin_center_field_name>Center Wavelength</sp:bin_center_field_name>
</sp:Bin_Center_Lookup>
<sp:Bin_Width_Lookup>
<sp:bin_width_field_name>FWHM</sp:bin_width_field_name>
</sp:Bin_Width_Lookup>
</sp:Spectral_Lookup>
</sp:Bin_Description>
</sp:Spectral_Characteristics>
</Discipline_Area>
</Observation_Area>
<File_Area_Observational>
<File>
<file_name>No.Data</file_name>
</File>
<!-- 1D Spectral Table -->
<Table_Character>
<local_identifier>TableChar1D</local_identifier>
<offset unit="byte">0</offset>
<records>100</records>
<description>
This is just one of many possible structures for a set of
spectra in tabulated format.
</description>
<record_delimiter>Carriage-Return Line-Feed</record_delimiter>
<Record_Character>
<fields>4</fields>
<groups>0</groups>
<record_length unit="byte">50</record_length>
<Field_Character>
<name>Intensity</name>
<field_location unit="byte">1</field_location>
<data_type>ASCII_Real</data_type>
<field_length unit="byte">5</field_length>
</Field_Character>
<Field_Character>
<name>Error</name>
<field_location unit="byte">6</field_location>
<data_type>ASCII_Real</data_type>
<field_length unit="byte">4</field_length>
</Field_Character>
<Field_Character>
<name>Center Wavelength</name>
<field_location unit="byte">12</field_location>
<data_type>ASCII_Integer</data_type>
<field_length unit="byte">4</field_length>
<unit>nanometer</unit>
</Field_Character>
<Field_Character>
<name>FWHM</name>
<field_location unit="byte">20</field_location>
<data_type>ASCII_Real</data_type>
<field_length unit="byte">6</field_length>
<unit>angstrom</unit>
</Field_Character>
</Record_Character>
</Table_Character>
</File_Area_Observational>
</Product_Observational>
Loading

0 comments on commit 1604d58

Please sign in to comment.