Operation
This document describes how to operate the Extract Table tool. The software extracts tabular data from a PDS4 product and writes it to an output file or the console, in fixed-width or CSV format. It can also list the tables and fields present. If multiple tables are present in the product, a table can be selected. The output format can also be set to fixed-width text or CSV, and the output line and field separators can be set to desired values.
The following topics can be found in this document:
The command-line examples below reference example PDS4 products which can be found in the examples/data/ folder of the PDS4 Tools release package. Also, the command-line examples have been broken into multiple lines for readability. The commands should be reassembled into a single line prior to execution.
Quick Start
This section is intended to give a quick and easy way to run the Extract Table Tool. For a more detailed explanation on other ways to run the tool, go to the Advanced Usage section.
The command below shows how to extract tabular data from a PDS4 product:
%> extract-table Product_Table_Character.xml
To format the data into Comma-Separated Value (CSV) format and output the results into a file, run the command below using the -c and -o flag options:
%> extract-table Product_Table_Character.xml -c -o product_table_character.csv
Command-Line Options
The following table describes the command-line options available to the tool:
| Command-Line Option | Description |
|---|---|
| -c, --csv | Output in CSV format |
| -f, --fields <FIELD_LIST> | Comma-separated list of field names or numbers to extract. Default is to extract all fields. |
| -l, --list-tables | List tables present in the product. |
| -n, --index <NUMBER> | Select the table to extract if more than one table is present (1...N). Default is to extract data from the first table. |
| -d, --data-file <FILE> | Specify the data file name of the table to extract. Default is to extract table data from the first data file specified in the product label. |
| -a, --all | Specify to extract data from all tables and all data files found in the product label. Default is to extract data from the first table and first data file. |
| -o, --output-file <FILE> | Specify the output file name. Default is to output the data to standard out. |
| -P, --platform | Output the data using the target platform line separator. This is the default behavior. |
| -q, --quote-character <CHAR> | Quote character for CSV output. Default is to use the double-quote, ", character. |
| -t, --field-separator <SEP> | Specify the output field separator. Default is a space for fixed-with tables, or comma for CSV output. |
| -U, --unix | Specify this flag to output the table using Unix line separator (LF). |
| -w, --fixed-width | Specify this flag to output the table in fixed-width format. (default behavior) |
| -W, --windows | Specify this flag to output the table using Windows line separators. (CRLF) |
| -h, --help | Display Tool usage. |
Advanced Usage
This section describes more advanced ways to run the tool, as well as its behaviors and caveats.
Tool Execution
This section demonstrates some of the ways that the tool can be executed using the command-line option flags:
- Extracting Table Data From Multiple Tables
- Extracting Table Data From Multiple Data Files
- Extracting Specific Fields From a Table
- Specifying Another Field Separator
Extracting Table Data From Multiple Tables
For PDS4 data product labels containing more than 1 table, the default behavior of the tool is to extract the 1st table found. To select specific tables, use the -n flag option.
The following command lists all tables found in the data product label:
% extract-table ~/transform-1.4.0-dev/examples/Product_Table_Multiple_Tables.xml -l
file: PDS4_ATM_TABLE_CHAR_MULTIPLE.TAB
table 1: fixed-width character table
field 1: SOL (ASCII_Integer)
field 2: LTST (ASCII_Real)
field 3: LMST (ASCII_Real)
field 4: V (ASCII_Real)
field 5: DV+ (ASCII_Real)
field 6: DV- (ASCII_Real)
field 7: DIR (ASCII_Real)
field 8: DDIR (ASCII_Real)
field 9: EXPOSURE TIME (ASCII_Real)
field 10: FILE NAME (ASCII_File_Name)
table 2: fixed-width character table
field 1: SOL (ASCII_Integer)
field 2: LTST (ASCII_Real)
field 3: LMST (ASCII_Real)
field 4: V (ASCII_Real)
field 5: DV+ (ASCII_Real)
field 6: DV- (ASCII_Real)
field 7: DIR (ASCII_Real)
field 8: DDIR (ASCII_Real)
field 9: EXPOSURE TIME (ASCII_Real)
field 10: FILE NAME (ASCII_File_Name)
The following command extracts the table data from the 2nd table:
% extract-table ~/transform-1.4.0-dev/examples/Product_Table_Multiple_Tables.xml -n 2
Extracting Table Data From Multiple Data Files
For PDS4 data product labels containing tables located in more than 1 data file, the default behavior of the tool is to extract the 1st table in the 1st data file found. To select a specific table from a specific data file, use the -d flag option.
The following command lists all tables found in the data product label:
% extract-table Product_Table_Multiple_Datafiles.xml -l
file: PDS4_ATM_TABLE_CHAR.TAB
table 1: fixed-width character table
field 1: SOL (ASCII_Integer)
field 2: LTST (ASCII_Real)
field 3: LMST (ASCII_Real)
field 4: V (ASCII_Real)
field 5: DV+ (ASCII_Real)
field 6: DV- (ASCII_Real)
field 7: DIR (ASCII_Real)
field 8: DDIR (ASCII_Real)
field 9: EXPOSURE TIME (ASCII_Real)
field 10: FILE NAME (ASCII_File_Name)
file: PDS4_TABLE_DELIMITED.csv
table 1: delimited table
field 1: CHANNEL_NUMBER (ASCII_Integer)
field 2: SPECTRA_01 (ASCII_Integer)
field 3: SPECTRA_02 (ASCII_Integer)
field 4: SPECTRA_03 (ASCII_Integer)
field 5: SPECTRA_04 (ASCII_Integer)
field 6: SPECTRA_05 (ASCII_Integer)
field 7: SPECTRA_06 (ASCII_Integer)
field 8: SPECTRA_07 (ASCII_Integer)
field 9: SPECTRA_08 (ASCII_Integer)
field 10: SPECTRA_09 (ASCII_Integer)
field 11: SPECTRA_10 (ASCII_Integer)
field 12: SPECTRA_11 (ASCII_Integer)
field 13: SPECTRA_12 (ASCII_Integer)
file: 2d234493326edratf3d2537n0m1.dat
table 1: fixed-width binary table
field 1: SCLK_SECONDS (UnsignedMSB4)
field 2: SCLK_SUBSECONDS (UnsignedMSB2)
field 3: SPARE (UnsignedMSB2)
field 4: ROTATION_MOTOR_POSITION (IEEE754MSBDouble)
field 5: ROTATION_MOTOR_CURRENT_SENSOR (IEEE754MSBDouble)
field 6: REVOLUTION_MOTOR_POSITION (IEEE754MSBDouble)
field 7: REVOLUTION_MOTOR_CURRENT_SENSOR (IEEE754MSBDouble)
field 8: Z_MOTOR_POSITION (IEEE754MSBDouble)
field 9: Z_MOTOR_CURRENT_SENSOR (IEEE754MSBDouble)
field 10: TEMPERATURE_SENSOR (IEEE754MSBDouble)
field 11: BUTTERFLY_SWITCH_1 (UnsignedMSB4)
field 12: BUTTERFLY_SWITCH_2 (UnsignedMSB4)
field 13: RAT_OVER_CURRENT_ALARM (UnsignedMSB4)
field 14: Z_AXIS_MOTOR_CONTROLLER_STATUS (UnsignedByte)
field 15: REVOLVE_MOTOR_CONTROLLER_STATUS (UnsignedByte)
field 16: GRIND_MOTOR_CONTROLLER_STATUS (UnsignedByte)
field 17: SPARE (UnsignedByte)
field 18: ROVER_BUS_VOLTAGE (IEEE754MSBDouble)
field 19: ALGORITHM_STATE (UnsignedMSB4)
field 20: ANOMALY_FLAG (UnsignedMSB4)
The following command extracts the table located in the data file PDS4_TABLE_DELIMITED.csv:
% extract-table Product_Table_Multiple_Datafiles.xml -d PDS4_TABLE_DELIMITED.csv
To extract all tables from all the data files, run the following command:
% extract-table Product_Table_Multiple_Datafiles.xml -a
Extracting Specific Fields From a Table
To extract specific fields from the table, use the -f flag option.
The example table product consists of the following fields:
% extract-table Product_Table_Character.xml -l
file: PDS4_ATM_TABLE_CHAR.TAB
table 1: fixed-width character table
field 1: SOL (ASCII_Integer)
field 2: LTST (ASCII_Real)
field 3: LMST (ASCII_Real)
field 4: V (ASCII_Real)
field 5: DV+ (ASCII_Real)
field 6: DV- (ASCII_Real)
field 7: DIR (ASCII_Real)
field 8: DDIR (ASCII_Real)
field 9: EXPOSURE TIME (ASCII_Real)
field 10: FILE NAME (ASCII_File_Name)
The following command extracts field 5:
% extract-table Product_Table_Character.xml -f 5
Specify a comma-separated list to extract multiple fields. The following command extracts field 5 and field 9:
% extract-table Product_Table_Character.xml -f 5,9
Specifying Another Field Separator
The -t flag option provides the capability to specify another field separator in the output. The default is to use a space for fixed-width tables and to use a comma for CSV output.
The following command tells the tool to output the table using the vertical bar character as the field separator:
% extract-table ../examples/data/Product_Table_Character.xml -t '\|'
Note that the backslash character preceding the vertical bar character is needed in order to pass in the vertical bar character properly into the tool. This, along with the single quotes surrounding the value, is needed so that the shell interpreter will treat this character as a string literal.