Python PDS4 Tools

From The SBN Wiki
Revision as of 17:32, 7 October 2015 by Lnagdi1 (talk | contribs) (Updated for v0.3 of pds4_tools)
Jump to navigation Jump to search

Introduction

This document describes the current status and usage of Python tools developed at PDS-SBN to read and visualize PDS4 data in Python. Please note that a PDS4 reader and visualizer for IDL is also available.

Reading and Displaying PDS4 Data

Introduction

This section describes a Python package that can read and display PDS4 data and meta data. In the future this tool is expected to support all PDS4 objects, currently support is limited to objects given in the Supported Objects section. The package expects labels that pass PDS4 Schema and Schematron validation.

Contact Lev Nagdimunov with questions or comments regarding this code or its description.

Requirements

Python 2.6 or 2.7

pds4_read: None
pds4_viewer: NumPy, matplotlib

You may use pds4_read to read-in data without any extra packages; pds4_viewer requires additional packages.

Optional Features

pds4_read: NumPy
Recommended for Arrays and Tables containing GROUP fields to allow for multi-dimensional indexing. Can result in significant improvements in memory usage and read-in speed for some data objects.

pds4_viewer: None

Supported Data Structures

PDS4 Data Standards < v1.3 are not officially supported but may work.
PDS4 Data Standards >= v1.3 are supported.

The table below lists the main PDS4 data objects and the current status.

Read-in column indicates support by pds4_read()
Display columns indicate support by pds4_viewer().

Object Read-in Display as Table Display as Image Display Columns as Plot
Array Yes Yes 2D and 3D only Under Development
Array_2D Yes Yes Yes Under Development
Array_2D_* Yes Yes Yes Under Development
Array_3D Yes Yes Yes Under Development
Array_3D_* Yes Yes Yes Under Development
Table_Character Yes Yes No Under Development
Table_Binary Yes, except BitFields Yes No Under Development
Table_Delimited Future development Future development Future Development Future Development

Download

Download the ZIP file File:PDS4 tools-0.3.zip

Installation

Option 1

Use "pip install PDS4_tools-0.3.zip" or "easy_install PDS4_tools-0.3.zip". You can also extract the ZIP file and use "python /path/to/extracted/setup.py install". Note that there is no uninstall script provided (although "pip uninstall pds4_tools" should work), and that this tool will be updated in the future.

Option 2

Extract the downloaded file to a directory Python can find. To use it follow the instructions in Example Usage except with the following lines first,

import sys
sys.path.extend(['/path/to/your/extraction/directory'])

# On a windows machine use backslashes (/) instead of windows' normal forward slashes to specify paths

Example Usage

pds4_read

You may call pds4_read from command line or from your own script. Typing the shell command python pds4_read.py -h prints out the help text:

usage: pds4_read.py [-h] [--quiet] [--use_numpy] [--object_num OBJECT_NUM]
                    [--object_name OBJECT_NAME] [--object_lid OBJECT_LID]
                    filename

positional arguments:
  filename              Filename, including full path, of the label

optional arguments:
  -h, --help            show this help message and exit
  --quiet               Suppresses all info/warnings
  --use_numpy           Returned data will be a numpy array and use numpy data types
  --object_num OBJECT_NUM
                        Only reads the data object specified by zero-based order (integer)
  --object_name OBJECT_NAME
                        Only reads the data object specified by name
  --object_lid OBJECT_LID
                        Only reads the data object specified by local identifier

If called from another module or a script, all of the above optional arguments would be available as optional named parameters of the function pds4_read(). Basic example usage is as follows:

""" Basic pds4_read example """

from pds4_tools import pds4_read

obj_list = pds4_read('/path/to/label.xml')

table = obj_list['table_name'] # or
table = obj_list[0]

# Dictionary-like access
column = table.data['field_name']
row_1_to_100 = column[0:100]

# List-like access
column = table.data[0]
row_1_to_100 = column[0:100]

# Meta-data access
column_meta = table.data.meta_data('field_name')
column_meta = table.data.meta_data(0)

print column_meta['description']
print column_meta['unit']

# Label access, provides ElementTree object
label = obj_list.label # Full label
label = table.label # Label section describing the table object

pds4_viewer

To display the objects in a label you may call pds4_viewer from the command line:

usage: pds4_viewer.py [-h] [--quiet] [--object_num OBJECT_NUM]
                    [--object_name OBJECT_NAME] [--object_lid OBJECT_LID]
                    [filename]

positional arguments:
  filename              Filename, including full path, of the label

optional arguments:
  -h, --help            show this help message and exit
  --quiet               Suppresses all info/warnings
  --object_num OBJECT_NUM
                        Only reads the data object specified by zero-based order (integer)
  --object_name OBJECT_NAME
                        Only reads the data object specified by name
  --object_lid OBJECT_LID
                        Only reads the data object specified by local identifier

It is not necessary to include the filename parameter for pds4_viewer, you may simplify call it without any options or arguments and a GUI will open from which you can open labels.

You may also call pds4_viewer from another module or script. All the above optional arguments are available as optional named parameters. A basic example usage is as follows:

""" Basic pds4_viewer example """

from pds4_tools import pds4_read, pds4_viewer

pds4_viewer()

# or

pds4_viewer('label.xml')

# or 

obj_list = pds4_read('label.xml')
pds4_viewer('label.xml', from_existing_objects=obj_list) # Won't re-read the data