pds4_tools.reader.general_objects module

Classes

StructureList(structures, label, read_in_log)	Stores the label and all supported data structures of a PDS4 product.
Structure([structure_data, ...])	Stores a single PDS4 data structure.
Meta_Class	Contains meta data about any type of data.
Meta_Structure	Meta data about a PDS4 Data Structure.

Details

class StructureList(structures, label, read_in_log)

Bases: collections.abc.Sequence

Stores the label and all supported data structures of a PDS4 product.

An object of this type is returned by pds4_read. PDS4 supported data structures are forms of Arrays, Tables and Headers. This class allows both dict-like and list-like access to each individual PDS4 data structure inside.

Parameters

structureslist[Structure]

Each data Structure, including the data and the structure’s label portion, in the PDS4 product.

labelLabel

The entire label describing the PDS4 product.

read_in_logstr or unicode

Output of the log during read-in of the entire PDS4 product.

Examples

Supposing the label described two objects, an Array_2D_Image (named ‘Obs’) and a Table_Binary (unnamed) in the same order as described here, they can be accessed as follows:

>>> image_array = struct_list[0]
>>>            or struct_list['Obs']

>>> obs_table = struct_list[1]
>>>          or struct_list['TABLE_0']

See pds4_read and __getitem__ docstrings for more examples.

Attributes

structureslist[Structure]

Each data Structure, including the data and the structure’s label portion, in the PDS4 product.

labelLabel

The entire label describing the PDS4 product.

read_in_logstr or unicode

Output of the log during read-in of the entire PDS4 product.

__getitem__(key)

Searches StructureList for a specific data structure.

Parameters

keystr, unicode, int, slice or tuple

Selection for desired Structure. May be a string containing the name or local identifier of a single Structure, similar to dict indexing functionality. May be an integer or slice specifying which Structure(s) to select, similar to list or tuple indexing functionality. May be a two-valued tuple, with the first value providing the name or local identifier and the second value a zero-based count, providing which repetition of Structure by that name to select.

Returns

Structure or list[Structure]

Matched PDS4 data structure(s).

Raises

IndexError

Raised if key is a larger integer than the number of Structures.

KeyError

Raised if key is a name or local identifier and does not match any Structure.

Examples

>>> struct_list[0]
>>> struct_list['Observations']

If both of the first two data structures have the name ‘Observations’, then to select the second we can do,

>>> struct_list['Observations', 1]

We can select both of the first two data structures via,

>>> struct_list[0:2]

__len__()

Returns

int

Number of data structures contained.

property type

Examples of types include Product_Observational, Product_Ancillary, Product_Document, etc.

Returns

str or unicode

Root tag of a PDS4 label.

info(abbreviated=True, output=None)

Prints to stdout a summary of the contained data structures.

For Arrays the summary contains the type and dimensions of the Array, and for Tables it contains the type and number of fields. Set abbreviated parameter to False to output additional detail.

Parameters

abbreviatedbool, optional

If False, output additional detail. Defaults to True.

outputfile, bool or None, optional

A file-like object to write the output to. If set to False, does not output to a file and instead returns a list of lists representing info for each Structure. Writes to sys.stdout by default.

Returns

None

class Structure(structure_data=None, structure_meta_data=None, structure_label=None, full_label=None, parent_filename=None, structure_id=None)

Bases: object

Stores a single PDS4 data structure.

Subclassed by ArrayStructure, TableStructure and HeaderStructure.

Parameters

structure_dataany, optional

The data in this PDS4 data structure. If not given and never set, data can be read-in via from_file.

structure_meta_dataMeta_Structure, optional

Meta data describing this object (originating from the label).

full_labelLabel, optional

The entire label describing the PDS4 product this structure originated from.

structure_labelLabel, optional

The segment of the label describing only this data structure.

parent_filenamestr or unicode, optional

Filename, including full path, of the data file that contained the data for this structure.

structure_idstr or unicode, optional

If given, sets an ID for the structure. If not given, an attempt to obtain ID will be made from the meta data.

Examples

See pds4_read docstring for examples.

Attributes

parent_filenamestr or unicode

Filename of the data file that contained the data for this structure.

full_labelLabel

The entire label describing the PDS4 product this structure originated from.

labelLabel

The segment of the label describing only this data structure.

meta_dataMeta_Structure

Meta data describing this object (originating from the label).

dataany

The data of this PDS4 structure.

property id

Returns

str or unicode

The ID (either local identifier if given, or name if given) of this data structure. If neither was given, an ID was likely assigned.

property type

Returns

str, unicode or None

The official PDS4 data structure type name for this structure.

property data_loaded

Returns

bool

True if the data attribute has been set (e.g. data has been read from file or set), False otherwise.

abstract from_file(data_filename, structure_label, full_label, lazy_load=False, no_scale=False, decode_strings=False)

Create structure from relevant labels and file for the data.

Parameters

data_filenamestr or unicode

Filename of the data file that contained the data for this structure.

structure_labelLabel

The segment of the label describing only this data structure.

full_labelLabel

The entire label describing the PDS4 product this structure originated from.

lazy_loadbool, optional

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

no_scalebool, optional

If True, read-in data will 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

Structure

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

abstract info(abbreviated=False, output=None)

Prints a summary of this data structure.

Parameters

abbreviatedbool, optional

If False, output additional detail. Defaults to False.

outputfile, bool or None, optional

A file-like object to write the output to. If set to False then instead of outputting to a file a list representing the summary parameters for the Structure is returned. Writes to sys.stdout by default.

Returns

None or list

If output is False, then returns a list representing the summary parameters for the Structure. Otherwise returns None.

abstract data()

The data of this PDS4 structure.

Returns

Data for the structure; details are defined by the subclass.

is_array()

Returns

bool

True if this Structure is a form of a PDS4 array, false otherwise.

is_table()

Returns

bool

True if this Structure is a form of a PDS4 table, false otherwise.

is_header()

Returns

bool

True if this Structure is a form of a PDS4 header, false otherwise.

class Meta_Class

Bases: collections.OrderedDict

Contains meta data about any type of data.

Subclassed by all other Meta_* classes, subclasses OrderedDict. Most PDS4 meta data originates from the label, therefore we need a consistent interface to pull this meta data from a Label or ElementTree Element into an OrderedDict, which any Meta_Class ultimately subclasses.

Most often we do not use the actual OrderedDict constructor to populate the meta data, but instead use methods provided by this class to load the dictionary with keys directly from the XML.

Meta data stored in this class is accessed in dict-like fashion.

Parameters

(same as for ``OrderedDict``)

*args

Variable length argument list.

**kwargs

Arbitrary keyword arguments.

class Meta_Structure

Bases: pds4_tools.reader.general_objects.Meta_Class

Meta data about a PDS4 Data Structure.

Meta data stored in this class is accessed in dict-like fashion. Normally this meta data originates from the label.

Subclassed by a meta class for each data structure type.

property id

Returns

str or unicode

The local_identifier of the PDS4 data structure if it exists, otherwise the name if it exists. If neither was specified in the label, None is returned.