pds4_tools.reader.table_objects module

Classes

TableStructure([structure_data, ...])	Stores a single PDS4 table data structure.
Meta_TableStructure(*args, **kwds)	Meta data about a PDS4 table data structure.
TableManifest([items, table_type, table_label])	Stores a single table’s Meta_Fields and Meta_Groups
Meta_TableElement(*args, **kwds)	Stores meta data about any table element.
Meta_Field(*args, **kwds)	Stores meta data about a single <Field_*>.
Meta_FieldCharacter(*args, **kwds)	Stores meta data about a single <Field_Character>.
Meta_FieldBinary(*args, **kwds)	Stores meta data about a single <Field_Binary>.
Meta_FieldDelimited(*args, **kwds)	Stores meta data about a single <Field_Delimited>.
Meta_FieldUniformlySampled(*args, **kwds)	Stores meta data about a single <Uniformly_Sampled>.
Meta_Group(*args, **kwds)	Stores meta data about a single <Group_Field_*>.

Functions

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

Bases: pds4_tools.reader.general_objects.Structure

Stores a single PDS4 table data structure.

Contains the table’s data, meta data and label portion. All forms of PDS4 tables (e.g. Table_Character, Table_Binary and Table_Delimited) are stored by this class.

See Structure‘s and pds4_read‘s docstrings for attributes, properties and usage instructions of this object.

Inherits all Attributes and Parameters from Structure. Overrides info method to implement it.

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

Create a table structure from relevant labels and file for the data.

Parameters:

data_filename : str or unicode

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

structure_label : Label

The segment of the label describing only this table structure.

full_label : Label

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

no_scale : bool, optional

Read-in data will not be adjusted according to the offset and scaling factor. Defaults to False.

decode_strings : bool, 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.

lazy_load : bool, optional

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

Returns:

TableStructure

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

classmethod from_fields(fields, no_scale=False, decode_strings=False, masked=None, **structure_kwargs)

Create a table structure from PDS-compliant data or meta data.

Parameters:

fields : list[PDS_ndarray, PDS_marray or Meta_Field]

A list of either fields with data, where each must contain a valid PDS4 meta_data attribute defining the field, or a list of valid Meta_Field’s.

no_scale : bool, 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_strings : bool, 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.

masked : bool 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.

structure_kwargs : dict, 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.

info(abbreviated=False, output=None)

Prints a summary of this data structure.

Contains the type, number of fields and number of records in the Table. If abbreviated is True then also outputs the name and number of elements for each field in the table.

Parameters:

abbreviated : bool, optional

If False, output additional detail. Defaults to False.

output : file, 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.

__getitem__(key)

Get data for specific field in TableStructure.

In the case of GROUP fields, the key can include the full location for disambiguation, (e.g. field_name = ‘GROUP_1, GROUP_0, field_name’). See info method for full locations of all fields.

Parameters:

key : str, unicode, int, slice or tuple

Selection for desired field. May be a string containing the name of a field to search for, similar to dict indexing functionality. May be an integer or slice specifying which field(s)’ data to select, similar to list or tuple indexing functionality. May be a two-valued tuple, with the first value providing the field name and the second value a zero-based repetition selector count if there are multiple fields with the same name.

Returns:

PDS_ndarray, PDS_marray or None

The data for the matched field, or None if no match found.

Raises:

IndexError

Raised if key is a larger int than there are fields in the table.

ValueError

Raised if key contains a name that does not match any field in the table.

Examples

>>> table_struct['First_Field_Name']
>>> table_struct.field(0)

To access two fields at the same time by name,

>>> table_struct[['First_Field', 'Second_Field']]

In-case of GROUP fields, we can use the full name (as given by the info method) for disambiguation,

>>> table_struct['GROUP_1, GROUP_0, field_name']

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

>>> table_structure['Field_Name [1]']
>>> table_struct.field('Field_Name', 1)

We can also record record-wise. To obtain all fields for the first five records,

>>> table_struct[0:5]

__len__()

Returns:

int

Number of fields contained in the table.

field(key, repetition=0, all=False)

Get data for specific field in table.

In the case of GROUP fields, the key can include the full location for disambiguation, (e.g. key = ‘GROUP_1, GROUP_0, field_name’). See info method for full locations of all fields.

Parameters:

key : str, unicode, int or slice

Selection for desired field. May be an integer or slice specifying which field(s)’ data to select, similar to list or tuple indexing functionality. May be a string containing the name of a field to search for.

repetition : int, optional

If there are multiple fields with the same name, specifies a zero-based repetition count to return. Defaults to 0.

all : bool, optional

If there are multiple fields with the same name, setting to True indicates that all fields should be returned in a list. If set, and no match is found then an empty list will be returned. Defaults to False.

Returns:

PDS_ndarray or PDS_marray

The data for the field(s).

Raises:

IndexError

Raised if key is a larger integer than there are fields in the table.

ValueError

Raised if key is a name that does not match any field.

Examples

See TableStructure.__getitem__() method examples.

data

All data in the PDS4 table data structure.

This property is implemented as a thread-safe cacheable attribute. Once it is run for the first time, it replaces itself with an attribute having the exact data that was originally returned.

Unlike normal properties, this property/attribute is settable without a __set__ method. To never run the read-in routine inside this property, you need to manually create the the .data attribute prior to ever invoking this method (or pass in the data to the constructor on object instantiation, which does this for you).

Returns:

PDS_ndarray or PDS_marray

A structured array (either effectively np.ndarray or np.ma.MaskedArray) representing all the fields in this table.

fields

Returns:

list[PDS_ndarray or PDS_marray]

All the fields in this table.

set_field(data, meta_data)

Set a field in the table.

Parameters:

data : array_like

Data for the field to be added.

meta_data : Meta_Field

Meta data of the field to be added.

Returns:

None

Notes

Prior to calling this method, self.data must be set to a structured ndarray that will be used to store each field. See TableStructure.from_fields.

as_masked()

Obtain a new TableStructure, where numeric fields with Special_Constants are masked.

Returns:

TableStructure

A new structure, where numeric fields with Special_Constants are masked. The data, labels and meta data are all effectively views, no copies are made.

Notes

The returned Structure may not be easily converted back to unmasked. However, the original Structure can continue to be used to access the unmasked data.

data_loaded

Returns:

bool

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

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.

is_array()

Returns:

bool

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

is_header()

Returns:

bool

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

is_table()

Returns:

bool

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

type

Returns:

str, unicode or None

The official PDS4 data structure type name for this structure.

class Meta_TableStructure(*args, **kwds)

Bases: pds4_tools.reader.general_objects.Meta_Structure

Meta data about a PDS4 table data structure.

Meta data stored in this class is accessed in dict-like fashion. Stores meta data about all forms of Table (e.g. Table_Character, Table_Binary, and Table_Delimited). Normally this meta data originates from the label (e.g., if this is an Table_Character then everything from the opening tag of Table_Character to its closing tag will be stored in this object), via the from_label method.

Inherits all Attributes, Parameters and Properties from Meta_Structure.

Examples

Supposing the following Table definition from a label:

<Table_Binary>
  <local_identifier>data_Integration</local_identifier>
  ....
  <Record_Binary>
    <fields>9</fields>
    <groups>0</groups>
    <record_length unit="byte">65</record_length>
    <Field_Binary>
      <name>TIMESTAMP</name>
      ...
   ...
...
</Table_Binary>

>>> meta_table = Meta_TableStructure.from_label(structure_xml, full_label)

>>> print(meta_table['local_identifier'])
data_Integration

>>> print(meta_table['Record_Binary']['record_length']
65

Attributes

record	(OrderedDict) Convenience attribute for the Record_* portion of this table’s meta data.
type	(str or unicode) Type of table. One of ‘Character’, ‘Binary’, or ‘Delimited’.

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.

classmethod from_label(xml_table, full_label=None)

Create a Meta_TableStructure from the XML portion describing the Table structure.

Parameters:

xml_table : Label or ElementTree Element

Portion of label that defines the Table data structure.

full_label : Label or ElementTree Element, optional

The entire label from which xml_table originated.

Returns:

Meta_TableStructure

Instance containing meta data about the table structure, as taken from the XML label.

Raises:

PDS4StandardsException

Raised if required meta data is absent.

dimensions()

Obtains the number of fields and records for the table.

Count does not include Group_Fields, but includes any non-group fields with-in them.

Returns:

list

Dimensions of the table, i.e., the number of fields and records, respectively.

is_fixed_width()

Returns:

bool

True if the table is fixed-width (Table_Character and Table_Binary), false otherwise.

is_delimited()

Returns:

bool

True if the table is delimited (Table_Delimited), false otherwise.

class TableManifest(items=None, table_type=None, table_label=None)

Bases: _abcoll.Sequence

Stores a single table’s Meta_Fields and Meta_Groups

The manifest is a representation the table, with fields and groups in the same order as they physically appear in the label, created by adding the appropriate Meta_Field and Meta_Group structures.

The manifest is normally initialized from the label portion describing the Table, via from_label.

Parameters:

items : list[Meta_Field or Meta_Group], optional

A list of Meta_Fields or Meta_Groups describing the Fields and Groups in this TableManifest.

table_type : str or unicode, optional

The type of table. One of

table_label : Label or ElementTree Element, optional

Portion of label that defines the PDS4 table data structure.

__getitem__(key)

Parameters:

key : int or slice

Index of requested field or group.

Returns:

Meta_Field or Meta_Group

Matched field or group meta data.

__len__()

Returns:

int

Total number of fields and groups in the table.

classmethod from_label(table_label)

Create a TableManifest from the XML portion describing the Table structure.

Parameters:

table_label : Label or ElementTree Element

Portion of label that defines the PDS4 table data structure.

Returns:

TableManifest

Instance containing all appropriate Meta_Field’s and Meta_Group’s.

num_items

Returns:

int

Total number of fields and groups in the table manifest.

num_records

fields(skip_uniformly_sampled=False)

Obtain all fields in the table manifest.

Parameters:

skip_uniformly_sampled : bool, optional

If True, uniformly sampled fields not added to the returned list. Defaults to False.

Returns:

list[Meta_Field]

All fields in the table manifest.

uniformly_sampled_fields()

Returns:

list[Meta_FieldUniformlySampled]

All Uniformly Sampled fields in the table manifest.

groups()

Returns:

list[Meta_Group]

All groups in the table manifest.

get_field_by_full_name(field_full_name)

Returns field(s) matched by full name.

In the case of GROUP fields, the full name will include the full location for disambiguation, (e.g. field_full_name = ‘GROUP_1, GROUP_0, field_name’). The full location includes the names of the groups necessary to reach this field.

Parameters:

field_full_name : str or unicode

The full name of the field(s) to search for.

Returns:

list[Meta_Field]

List of matched fields.

get_children_by_idx(parent_idx, direct_only=False, return_idx=False)

Obtains the child items (Meta_Fields and Meta_Groups) of the parent_idx item.

Child items of a Group field are other Fields and Groups inside said Group field, and the children of those groups, etc.

Parameters:

parent_idx : int

The index (in this TableManifest) of the Meta_Group whose children to find. A value of -1 indicates to find all items in the entire manifest.

direct_only : bool, optional

If True, only the immediate children of the parent_idx element are returned. Defaults to False.

return_idx : bool, optional

If True, changes the return type to a list containing the indicies (in this TableManifest) of the matched children. Defaults to False.

Returns:

TableManifest

A new table manifest containing only the matched children.

get_parent_by_idx(child_idx, return_idx=False)

Obtains the parent Meta_Group of the child item given by child_idx.

Parameters:

child_idx : int

The index (in this TableManifest) of the Meta_Field or Meta_Group whose parent to find.

return_idx : bool, optional

If True, changes the return type to an int, which is the index (in this TableManifest) of the parent Meta_Group instead of the group itself. Returns -1 if a parent was not found. Defaults to False.

Returns:

Meta_Group or None

The parent of the specified child, or None if a parent was not found.

get_parents_by_idx(child_idx, return_idx=False)

Obtains all Meta_Group parents of the child item given by child_idx.

Parameters:

child_idx : int

The index (in this TableManifest) of the Meta_Field or Meta_Group whose parent to find.

return_idx : bool, optional

If True, changes the return type to a list of int‘s, each of which is an index (in this TableManifest) of the parent Meta_Group instead of the group itself. A value of -1 will be present in the list if no parent is found. Defaults to False.

Returns:

list[Meta_Group]

The parents of the specified child, or empty list if no parents were not found.

get_field_offset(field_idx, parent_idx=None)

Obtains the number of data values between parent_idx and field_idx in a single record.

Each value in a record is a single field value, or a single repetition of a field value. If all the data values for all fields in a single record were combined into an array, then data_array[offset] (with the default parent_idx) would select that field’s value (or the value of its first repetition, for fields inside groups).

Parameters:

field_idx : int

The index (in this TableManifest) of the Meta_Field whose offset to find.

parent_idx : int, optional

The parent index (index of one of the group fields that field_idx is inside of), from which to calculate the offset to field_idx. If None, calculates the offset from the beginning of the record. Defaults to None.

Returns:

int

The number of values, where each repetition of any field also counts as a separate value, that are between parent_idx and field_idx (inclusive).

get_field_skip_factors(field_idx, parent_idxs=None)

Obtains the number of data values between each repetition of field_idx for every parent group.

Each value in a record is a single field value, or a single repetition of a field value. If each skip factor were multiplied by the max number of repetitions for that group, and the results were added together then that skip value would represent the number of data values between the first value in the field and the last value in the field.

Parameters:

field_idx : int

The index (in this TableManifest) of the Meta_Field whose offset to find.

parent_idxs : list[int], optional

The parent indexes (indexes of group fields that field_idx is inside of) for which to calculate the skip factors. If None, selects the parent indexes for all groups that field_idx is inside of. Defaults to None.

Returns:

list[int]

Each item in the list is the number of values, where each repetition of any field also counts as a separate value, between each repetition of the field for that group. The values are in reverse order from parent_idxs.

class Meta_TableElement(*args, **kwds)

Bases: pds4_tools.reader.general_objects.Meta_Class

Stores meta data about any table element.

Table elements are Fields and Group fields. Subclassed by Meta_Field, Meta_Group and their derivatives.

Meta data stored in this class is accessed in dict-like fashion. See docstring for Meta_Class for additional documentation.

Parameters:

(same as for `Meta_Class` and ``OrderedDict``)

*args

Variable length argument list.

**kwargs

Arbitrary keyword arguments.

Attributes

full_location	(list[dict]) See docstring for TableManifest._create_full_locations.
group_level	(int) The depth the element is nested from the <Record_*>. 0 means direct child.

classmethod from_label(element_xml)

Initializes the meta data from an XML description of the element.

Parameters:

element_xml : Label or ElementTree Element

Portion of the label describing this element.

Returns:

Meta_TableElement

Instance containing meta data from element_xml.

Raises:

NotImplementedError

Each type of Meta_TableElement subclassing this class must implement its own from_label method.

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

is_field()

Returns:

bool

True if this element is a Field (i.e. Field_*), false otherwise.

is_group()

Returns:

bool

True if this element is a Group field (i.e. Group_Field_*), false otherwise.

class Meta_Field(*args, **kwds)

Bases: pds4_tools.reader.table_objects.Meta_TableElement

Stores meta data about a single <Field_*>.

Subclassed by Meta_FieldCharacter, Meta_FieldBinary, Meta_FieldDelimited and Meta_FieldUniformlySampled.

Inherits full_location and group_level attributes from Meta_TableElement.

Notes

Keys starting with the ‘field_’ prefix have this prefix removed. All other keys preserve their XML names.

Examples

Supposing the following Field definition from a label:

<Field_Binary>
  <name>UTC</name>
  <field_location unit="byte">17</field_location>
  <data_type>ASCII_String</data_type>
  <field_length unit="byte">33</field_length>
  <unit>UTC date string</unit>
  <description>Time that the integration began</description>
</Field_Binary>

>>> field = Meta_Field.from_label(field_xml)

>>> print(field['name'])
UTC

>>> print(field['length'])
33

>>> print(field.keys())
['name', 'location', 'data_type', 'length', 'unit', 'description']

Attributes

shape

(tuple[int]) The dimensions of the field’s data. For fields not inside groups, this will be equivalent to the number of records.

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

classmethod from_label(field_xml)

Initializes the meta data from an XML description of the Field.

Parameters:

field_xml : Label or ElementTree Element

Portion of the label describing this Field.

Returns:

Meta_Field

Contains meta data for the field.

class Meta_FieldCharacter(*args, **kwds)

Bases: pds4_tools.reader.table_objects.Meta_Field

Stores meta data about a single <Field_Character>.

Inherits full_location and group_level attributes from Meta_Field.

See docstring of Meta_Field for usage information.

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

classmethod from_label(field_xml)

Initializes the meta data from an XML description of the element.

Parameters:

field_xml : Label or ElementTree Element

Portion of the label describing this Field.

Returns:

Meta_FieldCharacter

Contains meta data for a Field_Character.

class Meta_FieldBinary(*args, **kwds)

Bases: pds4_tools.reader.table_objects.Meta_Field

Stores meta data about a single <Field_Binary>.

Inherits full_location and group_level attributes from Meta_Field.

See docstring of Meta_Field for usage information.

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

classmethod from_label(field_xml)

Initializes the meta data from an XML description of the Field.

Parameters:

field_xml : Label or ElementTree Element

Portion of the label describing this Field.

Returns:

Meta_FieldBinary

Contains meta data for a Field_Binary.

class Meta_FieldDelimited(*args, **kwds)

Bases: pds4_tools.reader.table_objects.Meta_Field

Stores meta data about a single <Field_Delimited>.

Inherits full_location and group_level attributes from Meta_Field.

See docstring of Meta_Field for usage information.

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

classmethod from_label(field_xml)

Initializes the meta data from an XML description of the Field.

Parameters:

field_xml : Label or ElementTree Element

Portion of the label describing this Field.

Returns:

Meta_FieldDelimited

Contains meta data for a Field_Delimited.

class Meta_FieldUniformlySampled(*args, **kwds)

Bases: pds4_tools.reader.table_objects.Meta_Field

Stores meta data about a single <Uniformly_Sampled>.

See docstring of Meta_Field for usage information.

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

classmethod from_label(uniformly_sampled_xml)

Initializes the meta data from an XML description of the Uniformly_Sampled.

Parameters:

uniformly_sampled_xml : Label or ElementTree Element

Portion of the label describing this Uniformly Sampled field.

Returns:

Meta_FieldUniformlySampled

Contains meta data for a Uniformly_Sampled field.

class Meta_Group(*args, **kwds)

Bases: pds4_tools.reader.table_objects.Meta_TableElement

Stores meta data about a single <Group_Field_*>.

Notes

Keys starting with the ‘group_’ prefix have this prefix removed. All other keys preserve their XML names.

Examples

Supposing the following Group field definition from a label:

<Group_Field_Binary>
  <repetitions>12</repetitions>
  <fields>1</fields>
  <groups>0</groups>
  <group_location unit="byte">1</group_location>
  <group_length unit="byte">24</group_length>
  <Field_Binary>
    ...
  </Field_Binary>
</Group_Field_Binary>

>>> group = Meta_Group.from_label(group_field_xml)

>>> print(group['repetitions'])
12

>>> print(group['location'])
1

>>> print(group.keys())
['repetitions', 'fields', 'groups', 'location', 'length', 'Field_Binary']

full_name(separator=u', ', skip_parents=False)

The full name of the element.

The full name always includes an overlap disambiguator, to resolve two elements in the same location with the same name. Normally it also includes the name of any parent groups necessary to reach this element from the beginning of the record description.

Parameters:

separator : str or unicode, optional

Used as the string separating each parent group and the name of the element. Defaults to ‘, ‘.

skip_parents : bool, optional

If True, parent groups of the element are excluded from the full name. Defaults to False.

Returns:

str or unicode

The name, including overlap disambiguator and parent groups if enabled, of the element.

Examples

Suppose the following Example Label Outline:

Table_Binary: Observations
    Field: order
    Field: wavelength           (1)
    Group: unnamed
            Field: pos_vector   (2)
    Group: unnamed
        Group: example_group
            Field: pos_vector
            Field: pos_vector   (3)

The full name of each element, with the default separator, is:

1. wavelength
2. GROUP_0, pos_vector
3. GROUP_1, example_group, pos_vector [1]

Enabling skip_parents for element (3) would result in ‘pos_vector [1]’, which includes the overlap disambiguator, but excludes all parent groups.

classmethod from_label(group_field_xml)

Initializes the meta data from an XML description of the Group_Field.

Parameters:

group_field_xml : Label or ElementTree Element

Portion of the label describing this group field.

Returns:

Meta_Group

Contains meta data for Group_Field_* fields.