pds4_tools.reader.read_tables module

Functions

read_table(full_label, table_label, ...[, ...])	Create the TableStructure, containing label, data and meta data for a PDS4 Table from a file.
read_table_data(table_structure, no_scale, ...)	Reads and properly formats the data for a single PDS4 table structure, modifies table_structure to contain all extracted fields for said table.
new_table(fields[, no_scale, ...])	Create a TableStructure from PDS-compliant data or meta data.
table_data_size_check(table_structure[, quiet])	Checks, and warns, if table is estimated to have a large amount of data.

Details

read_table(full_label, table_label, data_filename, lazy_load=False, no_scale=False, decode_strings=False)

Create the TableStructure, containing label, data and meta data for a PDS4 Table from a file.

Used for all forms of PDS4 Tables (i.e., Table_Character, Table_Binary and Table_Delimited).

Parameters

full_labelLabel

The entire label for a PDS4 product, from which table_label originated.

table_labelLabel

Portion of label that defines the PDS4 table data structure.

data_filenamestr or unicode

Filename, including the full path, of the data file that contains the data for this table.

lazy_loadbool, optional

If True, does not read-in the data of this table until the first attempt to access it. Defaults to False.

no_scalebool, optional

If True, returned data will not be adjusted according to the offset and scaling factor. Defaults to False.

decode_stringsbool, optional

If True, strings data types contained in the returned data will be decoded to the unicode type in Python 2, and to the str type in Python 3. If False, leaves string types as byte strings. Defaults to False.

Returns

TableStructure

An object representing the table; contains its label, data and meta data.

Raises

TypeError

Raised if called on a non-table according to table_label.

read_table_data(table_structure, no_scale, decode_strings, masked)

Reads and properly formats the data for a single PDS4 table structure, modifies table_structure to contain all extracted fields for said table.

Parameters

table_structureTableStructure

The PDS4 Table data structure to which the table’s data fields should be added. Should have been initialized via TableStructure.from_file method.

no_scalebool

Returned data will not be adjusted according to the offset and scaling factor.

maskedbool

Returned data will have numeric Special_Constants masked.

decode_stringsbool

If True, character data types contained in the returned data will be decoded to the unicode type in Python 2, and to the str type in Python 3. If False, leaves character types as byte strings.

Returns

None

new_table(fields, no_scale=False, decode_strings=False, masked=None, copy=True, **structure_kwargs)

Create a TableStructure from PDS-compliant data or meta data.

Parameters

fieldslist[PDS_ndarray, PDS_marray or Meta_Field]

A list of either fields with data, which each must contain a valid PDS4 meta_data attribute defining the field, or a list of valid Meta_Field’s. If input is data, the base data type will be taken from its actual dtype, rather than from the meta data it must still contain.

no_scalebool, optional

If True, and input is a list of fields with data, then the data will scaled according to the scaling_factor and value_offset meta data. If the fields is meta data only, then the output data type will be large enough to store the scaled values. If False, no scaling or data type conversions will be done. Defaults to False.

decode_stringsbool, optional

If True, then fields containing character byte data will be converted to a dtype of unicode. If False, then for character data the obtained dtype will remain byte strings. Defaults to False.

maskedbool or None, optional

If True, and input is a list of fields with data, then the data will retain any masked values and in additional have numeric Special_Constants values masked. If False, any masked values in the input fields will be unmasked and data assignments will not preserve masked values. If None, masked values in the input will be retained only if any are present. Defaults to None.

copy: bool, optional

If True, a copy of fields is made, ensuring that they do not get modified during processing. If False, then the fields may change if each is an array of data. In either case, the output data will not be a view. Defaults to True.

structure_kwargsdict, optional

Keywords that are passed directly to the TableStructure constructor.

Returns

TableStructure

An object representing the PDS4 table structure. The data will contain a structured array that can store values for fields (or does store it, if input is a list of fields with data). Other attributes may be specified via structure_kwargs.

Notes

The data attribute will not be a view of the original fields (if they are data arrays), but rather a new array. However, the fields passed into this method may still be modified in-place to save memory, see copy. If fields originated from a single structured ndarray, then a method to get a view of the original data, if conditions are satisfied, is to also pass that single structured ndarray as a kwarg of the name``structure_data``.

table_data_size_check(table_structure, quiet=False)

Checks, and warns, if table is estimated to have a large amount of data.

This estimate is done from the meta-data only and excludes nested fields (fields inside groups fields) and repetitions. A more accurate meta-data only estimate could be obtained via TableManifest.

Parameters

table_structureStructure

The table structure whose data to check for size.

quietbool, optional

If True, does not output warning if table contains a large amount of data. Defaults to False.

Returns

bool

True if the table structure exceeds pre-defined parameters for size of its data, False otherwise.