mth5.io.phoenix.readers.native

Submodules

Classes

NativeReader

Native sampling rate 'Raw' time series reader class.

Package Contents

class mth5.io.phoenix.readers.native.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

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

last_frame = 0
header_length = 128

Length of the header in bytes.

Returns:

Header length in bytes.

Return type:

int

data_scaling = 1
ad_plus_minus_range = 5.0
input_plusminus_range
scale_factor = 256
footer_idx_samp_mask = 0
footer_sat_mask = 0
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

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