Difference between revisions of "Python PDS4 Tools"
m |
(Updated for v0.3 of pds4_tools) |
||
Line 2: | Line 2: | ||
== Introduction == | == 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 | + | 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 [http://pds-smallbodies.astro.umd.edu/tools/tools_readPDS.shtml PDS4 reader and visualizer for IDL] is also available. |
− | == Reading | + | == Reading and Displaying PDS4 Data == |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== Introduction === | === Introduction === | ||
− | This section describes a Python package that can read and display PDS4 | + | 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 |Supported Objects]] section. The package expects labels that pass PDS4 Schema and Schematron validation. |
Contact [[User:lnagdi1|Lev Nagdimunov]] with questions or comments regarding this code or its description. | Contact [[User:lnagdi1|Lev Nagdimunov]] with questions or comments regarding this code or its description. | ||
Line 72: | Line 14: | ||
=== Requirements === | === Requirements === | ||
− | Python 2.6 or 2.7 | + | Python 2.6 or 2.7 |
pds4_read: None <br> | pds4_read: None <br> | ||
− | pds4_viewer: [http://www.numpy.org/ NumPy] | + | pds4_viewer: [http://www.numpy.org/ NumPy], [http://www.matplotlib.org/ matplotlib] |
You may use <tt>pds4_read</tt> to read-in data without any extra packages; <tt>pds4_viewer</tt> requires additional packages. | You may use <tt>pds4_read</tt> to read-in data without any extra packages; <tt>pds4_viewer</tt> requires additional packages. | ||
Line 86: | Line 28: | ||
pds4_viewer: None | pds4_viewer: None | ||
− | === Supported | + | === Supported Data Structures === |
PDS4 Data Standards < v1.3 are not officially supported but may work.<br> | PDS4 Data Standards < v1.3 are not officially supported but may work.<br> | ||
PDS4 Data Standards >= v1.3 are supported. | PDS4 Data Standards >= v1.3 are supported. | ||
− | The | + | The table below lists the main [[Filling_Out_the_File_Area_Observational_Classes#Data_Structures|PDS4 data objects]] and the current status. <br><br> |
− | + | Read-in column indicates support by <tt>pds4_read()</tt> <br> | |
− | + | Display columns indicate support by <tt>pds4_viewer()</tt>. | |
− | |||
− | No | + | {| class="wikitable" style="text-align: center; width: 800px; " |
+ | |- | ||
+ | ! Object | ||
+ | ! Read-in | ||
+ | ! Display as Table | ||
+ | ! Display as Image | ||
+ | ! Display Columns as Plot | ||
+ | |- | ||
+ | | style="text-align: left;" | Array | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | 2D and 3D only | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Array_2D | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Array_2D_* | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Array_3D | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Array_3D_* | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Table_Character | ||
+ | | Yes | ||
+ | | Yes | ||
+ | | No | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Table_Binary | ||
+ | | Yes, except BitFields | ||
+ | | Yes | ||
+ | | No | ||
+ | | Under Development | ||
+ | |- | ||
+ | | style="text-align: left;" | Table_Delimited | ||
+ | | Future development | ||
+ | | Future development | ||
+ | | Future Development | ||
+ | | Future Development | ||
+ | |} | ||
=== Download === | === Download === | ||
− | Download the ZIP file [[File:PDS4_tools-0. | + | Download the ZIP file [[File:PDS4_tools-0.3.zip]] |
=== Installation === | === Installation === | ||
==== Option 1 ==== | ==== Option 1 ==== | ||
+ | |||
+ | Use "<tt>pip install PDS4_tools-0.3.zip</tt>" or "<tt>easy_install PDS4_tools-0.3.zip</tt>". You can also extract the ZIP file and use "<tt>python /path/to/extracted/setup.py install</tt>". Note that there is no uninstall script provided (although "<tt>pip uninstall pds4_tools</tt>" 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 [[Python_PDS4_Tools#Example_Usage|Example Usage]] except with the following lines first, | Extract the downloaded file to a directory Python can find. To use it follow the instructions in [[Python_PDS4_Tools#Example_Usage|Example Usage]] except with the following lines first, | ||
Line 114: | Line 114: | ||
# On a windows machine use backslashes (/) instead of windows' normal forward slashes to specify paths | # On a windows machine use backslashes (/) instead of windows' normal forward slashes to specify paths | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
− | |||
=== Example Usage === | === Example Usage === |
Revision as of 17:32, 7 October 2015
Contents
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