mth5.io.phoenix.readers.native.native_reader

Module to read and parse native Phoenix Geophysics data formats of the MTU-5C Family.

This module implements Streamed readers for segmented-decimated time series formats of the MTU-5C family.

author:

Jorge Torres-Solis

Revised 2022 by J. Peacock

Attributes

AD_IN_AD_UNITS

AD_INPUT_VOLTS

INSTRUMENT_INPUT_VOLTS

Classes

NativeReader

Native sampling rate 'Raw' time series reader class.

Module Contents

mth5.io.phoenix.readers.native.native_reader.AD_IN_AD_UNITS = 0[source]
mth5.io.phoenix.readers.native.native_reader.AD_INPUT_VOLTS = 1[source]
mth5.io.phoenix.readers.native.native_reader.INSTRUMENT_INPUT_VOLTS = 2[source]
class mth5.io.phoenix.readers.native.native_reader.NativeReader(path: str | pathlib.Path, num_files: int = 1, scale_to: int = AD_INPUT_VOLTS, header_length: int = 128, last_frame: int = 0, ad_plus_minus_range: float = 5.0, channel_type: str = 'E', report_hw_sat: bool = False, **kwargs)[source]

Bases: mth5.io.phoenix.readers.TSReaderBase

Native sampling rate ‘Raw’ time series reader class.

This class reads native binary (.bin) files from Phoenix Geophysics MTU-5C instruments. The files are formatted with a header of 128 bytes followed by frames of 64 bytes each. Each frame contains 20 x 3-byte (24-bit) data points plus a 4-byte footer.

Parameters:

  • path (str or Path) – Path to the time series file

  • num_files (int, optional) – Number of files in the sequence, by default 1

  • scale_to (int, optional) – Data scaling mode (AD_IN_AD_UNITS, AD_INPUT_VOLTS, or INSTRUMENT_INPUT_VOLTS), by default AD_INPUT_VOLTS

  • header_length (int, optional) – Length of file header in bytes, by default 128

  • last_frame (int, optional) – Last frame number seen by the streamer, by default 0

  • ad_plus_minus_range (float, optional) – ADC plus/minus range in volts, by default 5.0

  • channel_type (str, optional) – Channel type identifier, by default “E”

  • report_hw_sat (bool, optional) – Whether to report hardware saturation, by default False

  • **kwargs – Additional keyword arguments passed to parent TSReaderBase class

last_frame[source]

Last frame number processed

Type:

int

data_scaling[source]

Current data scaling mode

Type:

int

ad_plus_minus_range[source]

ADC voltage range

Type:

float

input_plusminus_range[source]

Input voltage range after gain correction

Type:

float

scale_factor[source]

Calculated scaling factor for data conversion

Type:

float

footer_idx_samp_mask[source]

Bit mask for frame index in footer

Type:

int

footer_sat_mask[source]

Bit mask for saturation count in footer

Type:

int

last_frame = 0[source]
header_length = 128[source]

Length of the header in bytes.

Returns:

Header length in bytes.

Return type:

int

data_scaling = 1[source]
ad_plus_minus_range = 5.0[source]
input_plusminus_range[source]
scale_factor = 256[source]
footer_idx_samp_mask = 0[source]
footer_sat_mask = 0[source]
read_frames(num_frames: int) → numpy.ndarray[source]

Read the given number of frames from the data stream.

Note

The seek position is not reset, so iterating this method will read from the last position in the stream.

Parameters:

num_frames (int) – Number of frames to read

Returns:

Scaled data from the given number of frames with dtype float64

Return type:

np.ndarray

property npts_per_frame: int[source]

Get the number of data points per frame.

Returns:

Number of data points per frame (frame size - 4 footer bytes) / 3 bytes per sample

Return type:

int

read() → tuple[numpy.ndarray, numpy.ndarray][source]

Read the full data file using memory mapping and stride tricks.

Note

This uses numpy.lib.stride_tricks.as_strided which can be unstable if the bytes are not the correct length. See notes by numpy.

The solution is adapted from: https://stackoverflow.com/questions/12080279/how-do-i-create-a-numpy-dtype-that-includes-24-bit-integers

Returns:

Scaled time series data and footer data as (data, footer)

Return type:

tuple[np.ndarray, np.ndarray]

read_sequence(start: int = 0, end: int | None = None) → tuple[numpy.ndarray, numpy.ndarray][source]

Read a sequence of files into a single array.

Parameters:

  • start (int, optional) – Sequence start index, by default 0

  • end (int or None, optional) – Sequence end index, by default None

Returns:

Scaled time series data and footer data as (data, footer) - data: np.ndarray with dtype float32 - footer: np.ndarray with dtype int32

Return type:

tuple[np.ndarray, np.ndarray]

skip_frames(num_frames: int) → bool[source]

Skip frames in the data stream.

Parameters:

num_frames (int) – Number of frames to skip

Returns:

True if skip completed successfully, False if end of file reached

Return type:

bool

to_channel_ts(rxcal_fn: str | pathlib.Path | None = None, scal_fn: str | pathlib.Path | None = None) → mth5.timeseries.ChannelTS[source]

Convert to a ChannelTS object.

Parameters:

  • rxcal_fn (str, Path or None, optional) – Path to receiver calibration file, by default None

  • scal_fn (str, Path or None, optional) – Path to sensor calibration file, by default None

Returns:

Channel time series object with data, metadata, and calibration

Return type:

ChannelTS