pds4_tools.reader.array_objects module

Classes

ArrayStructure([structure_data, ...]) Stores a single PDS4 array data structure.
Meta_ArrayStructure(*args, **kwds) Meta data about a PDS4 array data structure.
ArraySection(array_structure[, no_scale]) Stores and allows retrieval of a section of an array.

Details

class ArrayStructure(structure_data=None, structure_meta_data=None, structure_label=None, full_label=None, parent_filename=None, structure_id=None)[source]

Bases: pds4_tools.reader.general_objects.Structure

Stores a single PDS4 array data structure.

Contains the array’s data, meta data and label portion. All forms of Array (e.g. Array, Array_2D, Array_3D_Image, etc) 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, Parameters and Properties 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=None)[source]

Create an array 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 array structure.

structure_label : Label

The segment of the label describing only this array structure.

full_label : Label

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

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.

no_scale : bool, optional

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

decode_strings : None, optional

Has no effect because Arrays may not contain string data. Defaults to None.
Returns:

ArrayStructure

An object representing the PDS4 array structure; contains its label, data and meta data.
classmethod from_array(input, no_scale=False, no_bitmask=False, masked=None, **structure_kwargs)[source]

Create an array structure from PDS-compliant data or meta data.

Parameters:

input : PDS_ndarray, PDS_marray or Meta_ArrayStructure

Either an array containing the data, which must also have a valid PDS4 meta_data attribute describing itself, or an instance of valid Meta_ArrayStructure.

no_scale : bool, optional

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

no_bitmask : bool, optional

If False, and input is an array of data, then the bitmask indicated in the meta data will be applied. If True, the bitmask will not be used. Defaults to False.

masked : bool or None, optional

If True, and input is an array of 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 array 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 ArrayStructure constructor.
Returns:

ArrayStructure

An object representing the PDS4 array structure. The data attribute will contain an array that can store input values (or does store it, if input is an array of data). Other attributes may be specified via structure_kwargs.
info(abbreviated=False, output=None)[source]

Prints a summary of this data structure.

Contains the type and dimensions of the Array, and if abbreviated is False then also outputs the name and number of elements of each axis in the array.

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.
data

All data in the PDS4 array 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

An array (either effectively np.ndarray or np.ma.MaskedArray) representing all the data in this array structure.
section

A section of the data in the PDS4 array data structure.

This property is implemented as a thread-safe cacheable attribute. See docstring of .data for more info.

Returns:

ArraySection

An object that allows access to sections of the array without reading the entire array into memory.
as_masked()[source]

Obtain a view of this ArrayStructure, with numeric Special_Constants masked.

Returns:

ArrayStructure

A view of this structure, where the data is masked for numeric Special_Constants. 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_ArrayStructure(*args, **kwds)[source]

Bases: pds4_tools.reader.general_objects.Meta_Structure

Meta data about a PDS4 array data structure.

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

Examples

Supposing the following Array definition from a label:

<Array_3D_Spectrum>
  <local_identifier>data_Primary</local_identifier>
  ...
  <Axis_Array>
    <axis_name>Time</axis_name>
    <elements>21</elements>
    <sequence_number>1</sequence_number>
  </Axis_Array>
  ...
</Array_3D_Spectrum>

>>> meta_array = Meta_ArrayStructure.from_label(structure_xml, full_label)

>>> print(meta_array['local_identifier'])
data_Primary

>>> print(meta_array['Axis_Array']['elements']
21

Attributes

display_settings (Meta_DisplaySettings) Meta data about the Display Settings for this array data structure.
spectral_characteristics (Meta_SpectralCharacteristics) Meta data about the Spectral Characteristics for this array data structure.
Inherits all Attributes, Parameters and Properties from Meta_Structure.  
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_array, full_label=None)[source]

Create a Meta_ArrayStructure from XML originating from a label.

Parameters:

xml_array : Label or ElementTree Element

Portion of label that defines the Array data structure.

full_label : Label or ElementTree Element, optional

The entire label from which xml_array originated.
Returns:

Meta_ArrayStructure

Instance containing meta data about the array structure, as taken from the XML label.
Raises:

PDS4StandardsException

Raised if required meta data is absent.
dimensions()[source]
Returns:

list

Dimensions of the array.
num_axes()[source]
Returns:

int

Number of axes/dimensions in the array.
get_axis_arrays(sort=True)[source]

Convenience method to always obtain Axis_Arrays as a list.

Parameters:

sort : bool, optional

Sorts returned Axis Arrays by sequence_number if True. Defaults to True.
Returns:

list

List of OrderedDict‘s containing meta data about each Axis_Array.
get_axis_array(axis_name=None, sequence_number=None)[source]

Searches for a specific Axis_Array.

Either axis_name, sequence_number or both must be specified. When both are given, then the result must match both values.

Parameters:

axis_name : str or unicode, optional

Searches for an Axis_Array with this name.

sequence_number : int, optional

Searches for an Axis_Array with this sequence number.
Returns:

OrderedDict or None

The matched Axis_Array, or None if no match was found.
class ArraySection(array_structure, no_scale=False)[source]

Bases: object

Stores and allows retrieval of a section of an array.

Used to extract and scale (if necessary) a portion of a PDS4 array. Usually this would be used for an array that is too large to hold entirely in memory.

Parameters:

array_structure : ArrayStructure

A PDS4 array structure. The data attribute in this structure should be memory-mapped.

no_scale : bool, optional

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

Notes

We use this instead of memory mapping to access extremely large arrays because the latter does not work for scaled arrays in which the scaled data type is different from the data type on disk.