Step 4: Checking the Result and Finishing Up

After running NPB the archive release is nearly done. Nevertheless a successful NPB execution is not necessarily a synonym of a successful archive increment generation. Reasons for that could be:

• incorrect input data (kernels, ORBNUM files or SPICEDS)

• incorrect Configuration File

• a bug in NPB

Although NPB already performs a number of checks, as described in the section Checks performed by NPB, it is recommended to spend some time and effort to check the result of the execution. Look at the WARNING and/or ERROR messages provided in the NPB run log file, checking the SPICEDS file, and especially checking the Meta-kernel(s), even if you generated them manually.

If you think you have found a bug in NPB or the archiving process please do as indicated in Reporting Bugs.

The following sections provide you some hints to perform checks on the archive.

Checking PDS artifacts

Amongst the PDS artifacts generated by NPB, labels are the ones that are most prone to error. It makes sense to visually inspect some or even all of them. In some cases doing this allows one to catch typos and incorrect information in the description, coverage, observer, target, and LID tags.

One of the ways to look at the labels is simply using Unix more to inspect them:

foreach ( `grep FILE working/maven_release_26.file_list | sed 's/^FILE *= *//g' )
   echo label for $FF
   more $FF:r.xml
end

What might be more interesting than examining individual labels is to compare them to similar labels. NPB facilitates this task with the -d DIFF --diff DIFF argument. More details are provided in Optional Arguments Description. The strategy with which NPB chooses similar labels is described in Product Comparison.

You can check other PDS artifacts, such as inventories, in a similar manner.

If any problems are found as the result of this examination, their causes should be fixed –probably by correcting the “Kernel List” section of the Configuration File–, the NPB execution must be cleared (using the -c CLEAR --clear CLEAR argument) and NPB must be re-run.

Verifying the Archive using the PDS Validate Tool

Although NPB and the instructions given above provide a lot of safeguard to ensure production of a fully PDS-compliant archive, many inputs to the configuration file are done “by hand” and for this reason are prone to errors. Because of this the archive producer should validate the SPICE archive using the validation tool provided by the PDS Engineering Node.

The Validate Tool performs the validation of the archive for PDS standards compliance. validate is a command line application well suited for batch mode processing.

The Validate tool package can be obtained from the PDS Engineering node from Validate Tool Documentation.

Once installed per instructions provided with the package, validate can be run to generate the full validation report for the final archive as follows.

A successful NPB run will generate a PDS validate tool configuration file to validate the resulting bundle with. More information is provided in PDS Validate Tool Configuration File. NPB will also try to download the PDS Schema and Schematron for you. However you can always run validate “manually” as indicated in the section hereunder.

Running Validate manually

After installing validate and generating the bundle you can run it as follows:

validate -t <path_to_archive> -R pds4.bundle -x <pds_im_schema> -S <pds_im_schematron> --strict-field-checks -r <path_to_working_dir>/<sc>_release_??.validate

where

<path_to_archive>: is the absolute or relative path of the archive pointing to the archive <sc>_spice

<path_to_working_dir>: is the absolute or relative path pointing to the working directory of the workspace.

<sc>_release_??.validate: is the suggested validate report name using the mission acronym and the release version.

<pds_im_schema>: is the local path of PDS IM schema for the IM of the bundle, e.g.: working/PDS4_PDS_1H00.xsd

<pds_im_schematron>: is the local path of PDS IM schematron for the IM of the bundle, working/PDS4_PDS_1H00.sch

You can download the PDS4 IM adequate schema and schematron from PDS Data Standards - Data Dictionaries, choose the adequate IM version and download the PDS4_PDS_????.xsd and PDS4_PDS_????.sch or the PDS4_PDS_????.zip files. NAIF recommends to put these files in the NPB working directory.

If you have included context products in the configuration file the Validate Tool might provide you the following error messages:

FAIL: file:/Users/mcosta/workspace/em16/em16_003/em16_spice/bundle_em16_spice_v003.xml
 ERROR  [error.label.context_ref_not_found]   line 34: 'Context product not found: urn:esa:psa:context:investigation:mission.em16
 ERROR  [error.label.context_ref_not_found]   line 43: 'Context product not found: urn:esa:psa:context:instrument_host:spacecraft.tgo
   1 product validation(s) completed

If so, you need to include the following argument when calling validate: --add-context-products and provide the path to a local JSON file containing the missing context products as follows:

{
"Product_Context": [
     {
          "name": [
               "em16"
          ],
          "type": [
               "Mission"
          ],
          "lidvid": "urn:esa:psa:context:investigation:mission.em16::1.0"
     },
      {
          "name": [
               "tgo"
          ],
          "type": [
               "Spacecraft"
          ],
          "lidvid": "urn:esa:psa:context:instrument_host:spacecraft.tgo::1.0"
     },{
          "name": [
               "edm"
          ],
          "type": [
               "Spacecraft"
          ],
          "lidvid": "urn:esa:psa:context:instrument_host:spacecraft.edm::1.0"
     }
]
}

Then you can run validate as follows:

validate -t em16/em16_spice --add-context-products registered_context_products.json -R pds4.bundle -x working/PDS4_PDS_1B00.xsd -S working/PDS4_PDS_1B00.sch --strict-field-checks -r working/em16_release_03.validate

Following the inclusion of this argument, you will still get the following warning message:

WARNING  [warning.product_not_registered]   Non-registered context products should only be used during archive development. All context products must be registered for a valid, released archive bundle.
   1 product validation(s) completed

This warning can be ignored. There should be no other errors or warnings in the report. If any other errors are present they should be investigated and fixed before the archive is released.

Alternatively you can run validate without checking the context products by using the argument: --skip-context-validation

NAIF recommends to set severity level of the Validation Tool reporting to Info (-v 1 --verbose 1). This will mainly help to find issues in the context products. The resulting recommended way to run Validate is:

validate -v 1 -t em16/em16_spice --skip-context-validation -R pds4.bundle -x working/PDS4_PDS_1B00.xsd -S working/PDS4_PDS_1B00.sch --strict-field-checks -r working/em16_release_03.validate

Please note that the Validate Tool is in continuous development with new releases for each PDS IM, therefore the details provided in this section might differ from the version of the Validate Tool you use. The results provided here are obtained using Validate Tool’s:

Version 2.0.6
Release Date: 2021-05-25 12:08:21

Deploying to the Final Archive Area

After the archive has been validated, the new archive-ready files should be copied from the bundle directory of the workspace area to the final archive area, from which the archive will be served to customers or delivered to the responsible PDS node.

The way of copying the files should be the one that best fits the data preparer’s hardware infrastructure – scp, rsync, wget, tar, or simply cp.

NAIF has the workspace area and the final archive area file systems mounted to the workstation on which archive preparation is done and uses tar to perform the copy. For example if the NPB bundle_directory of the MAVEN archive is located at:

/home/naif/maven/pds/maven_spice

and has under it the file:

/home/naif/maven/pds/working/maven_release_26.file_list

generated by the NPB run listing the files that should be copied to the final archive directory located at:

/ftp/pub/naif/pds/pds4/maven/maven_spice/

then this tar command can be used to perform the copy (the cd and more commands are included to show that tar should be run from, and the file names in the list should be relative to, the volume’s root directory in the staging area):

$ cd /home/naif/maven/pds/working/

$ more maven_release_26.file_list
...

$ tar cBf - `maven_release_26.file_list` | \
  (cd /ftp/pub/naif/pds/pds4/maven/maven_spice/; \
  tar xBf -)

For peace of mind, since at this point all kernels and meta-kernels are in the right place in the final archive area, it would make sense to verify all meta-kernels included in the archive running the NAIF utility BRIEF from the volume root directory in the final archive area as follows:

$ brief spice_kernels/mk/*.tm

BRIEF will display a summary for all SPK files in the archive and should generate no “file could not be located” errors.

Cleaning up the Workspace

After the archive is done it makes sense to do some cleanup in the workspace area. Although not required, NAIF recommends removing all the files in the staging area. In addition, NAIF recommends not to delete the NPB Execution by-products from the working_directory. Keeping them serves as a backup copy, allows for reproducibility of the archive, and can allow its use for future releases.

In addition, NAIF recommends maintaining a directory in the workspace replicating the bundle directory structure in order to store the files that are generated manually: SPICEDS files and potentially, Meta-kernels.

Here’s an example of the Workspace for LADEE:

.
|-- bundle
|   |-- document
|   |   +-- spiceds_v001.html
|   +-- spice_kernels
|       +-- mk
|           +-- ladee_v01.tm
|-- ladee_archive_generation.md
|-- staging
|   +-- ladee_spice
+-- working
    |-- ladee_release_01.checksum
    |-- ladee_release_01.file_list
    |-- ladee_release_01.kernel_list
    |-- ladee_release_01.log
    |-- ladee_release_01.plan
    |-- ladee_release_01.validate_report
    +-- ladee_release_01.xml

where ladee_archive_generation.md is a MarkDown text file that provides a LADEE-specific archiving guide. You might find writing such a file useful. The bundle_directory and kernels_directory are located somewhere else in the volume.