mth5.io.phoenix.readers.native package

Submodules

mth5.io.phoenix.readers.native.native_reader module

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

class mth5.io.phoenix.readers.native.native_reader.NativeReader(path: str | Path, num_files: int = 1, scale_to: int = 1, 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: 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

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[ndarray, 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_frames(num_frames: int) → 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

read_sequence(start: int = 0, end: int | None = None) → tuple[ndarray, 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 | Path | None = None, scal_fn: str | Path | None = None) → 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

Module contents

class mth5.io.phoenix.readers.native.NativeReader(path: str | Path, num_files: int = 1, scale_to: int = 1, 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: 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

Last frame number processed

Type:

int

data_scaling

Current data scaling mode

Type:

int

ad_plus_minus_range

ADC voltage range

Type:

float

input_plusminus_range

Input voltage range after gain correction

Type:

float

scale_factor

Calculated scaling factor for data conversion

Type:

float

footer_idx_samp_mask

Bit mask for frame index in footer

Type:

int

footer_sat_mask

Bit mask for saturation count in footer

Type:

int

property npts_per_frame: int

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[ndarray, 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_frames(num_frames: int) → 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

read_sequence(start: int = 0, end: int | None = None) → tuple[ndarray, 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 | Path | None = None, scal_fn: str | Path | None = None) → 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