pds4_tools.reader.read_arrays module

Functions

read_array(full_label, array_label, ...[, ...])	Create the ArrayStructure, containing label, data and meta data for a PDS4 Array from a file.
read_array_data(array_structure, no_scale, ...)	Reads and properly formats the data for a single PDS4 array structure, modifies array_structure to contain all extracted fields for said table.
new_array(input[, no_scale, no_bitmask, ...])	Create an ArrayStructure from PDS-compliant data or meta data.

Details

read_array(full_label, array_label, data_filename, lazy_load=False, no_scale=False)

Create the ArrayStructure, containing label, data and meta data for a PDS4 Array from a file.

Used for all forms of PDS4 Arrays (e.g., Array, Array_2D_Image, Array_3D_Spectrum, etc).

Parameters

full_labelLabel

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

array_labelLabel

Portion of label that defines the PDS4 array data structure.

data_filenamestr or unicode

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

lazy_loadbool, optional

If True, does not read-in the data of this array 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.

Returns

ArrayStructure

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

Raises

TypeError

Raised if called on a non-array according to array_label.

read_array_data(array_structure, no_scale, masked, memmap=False)

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

Parameters

array_structureArrayStructure

The PDS4 Array data structure to which the data should be added.

no_scalebool

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

maskedbool

Returned data will have numeric Special_Constants masked.

memmapbool, optional

If True, extracted data is memory mapped. Only guaranteed for unscaled data or for no_scale; otherwise returned data maybe a copy. Defaults to False.

Returns

None

new_array(input, no_scale=False, no_bitmask=False, masked=None, copy=True, **structure_kwargs)

Create an ArrayStructure from PDS-compliant data or meta data.

Parameters

inputPDS_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. 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 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 False, no scaling or data type conversions will be done.

no_bitmaskbool, 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.

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

copy: bool, optional

If True, a copy of input is made, ensuring that it does not get modified during processing. If False, then the input may change if it 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 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.

Notes

The data attribute will not be a view of the original input (if it is a data array), but rather a new array. However, the input passed into this method may still be modified in-place to save memory, see copy. A method to get a view of the original data, if conditions are satisfied, is to also pass input as a kwarg of the name structure_data.