mth5.io.phoenix.readers.header

Adopted from TimeSeries reader, making all attributes properties for easier reading and testing.

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

This module implements Streamed readers for segmented-decimated continuus-decimated and native sampling rate time series formats of the MTU-5C family.

author:

Jorge Torres-Solis

Revised 2022 by J. Peacock

Classes

Header

Phoenix Geophysics MTU-5C binary header reader and parser.

Module Contents

class mth5.io.phoenix.readers.header.Header(**kwargs: Any)

Phoenix Geophysics MTU-5C binary header reader and parser.

This class reads and parses the 128-byte binary header from Phoenix Geophysics MTU-5C data files. The header contains instrument configuration, GPS location, timing information, and recording parameters essential for proper data interpretation.

The header format is fixed at 128 bytes and contains information about: - Instrument type and serial number - Recording parameters (sample rate, channel configuration) - GPS location and timing information - Hardware configuration and gain settings - Data quality metrics (saturated/missing frames)

Parameters:

**kwargs (Any) – Additional keyword arguments to set as instance attributes.

logger

Logger instance for debugging and error reporting.

Type:

loguru.Logger

report_hw_sat

Flag to control hardware saturation reporting.

Type:

bool, default False

header_length

Length of the binary header in bytes.

Type:

int, default 128

ad_plus_minus_range

Differential voltage range of the A/D converter (board dependent).

Type:

float, default 5.0

channel_map

Mapping from channel IDs to channel names.

Type:

dict[int, str]

channel_azimuths

Mapping from channel names to azimuth angles in degrees.

Type:

dict[str, int]

Examples

>>> with open("phoenix_data.bin", "rb") as f:
...     header = Header()
...     header.unpack_header(f)
...     print(f"Sample rate: {header.sample_rate}")
...     print(f"GPS location: {header.gps_lat}, {header.gps_long}")

logger: loguru.Logger

report_hw_sat: bool = False

property header_length: int

Length of the header in bytes.

Returns:

Header length in bytes.

Return type:

int

ad_plus_minus_range: float = 5.0

channel_map: dict[int, str]

channel_azimuths: dict[str, int]

property file_type: int | None

File type indicator from binary header.

Returns:

File type identifier, or None if no header is loaded.

Return type:

int or None

property file_version: int | None

File version from binary header.

Returns:

File version identifier, or None if no header is loaded.

Return type:

int or None

property instrument_type: str | None

Instrument type string from binary header.

Returns:

Cleaned instrument type string, or None if no header is loaded.

Return type:

str or None

property instrument_serial_number: str | None

Instrument serial number from binary header.

Returns:

Decoded instrument serial number, or None if no header is loaded.

Return type:

str or None

property recording_id: int | None

Recording identifier from binary header or cached value.

Returns:

Recording ID as integer, or None if not available.

Return type:

int or None

property recording_start_time: mt_metadata.common.mttime.MTime | None

Recording start time from GPS timestamp.

The actual data recording starts 1 second after the set start time. This is caused by the data logger starting up and initializing filter. This is taken care of in the segment start time.

See https://github.com/kujaku11/PhoenixGeoPy/tree/main/Docs for more information.

The time recorded is GPS time.

Returns:

GPS start time, or None if recording ID is not available.

Return type:

MTime or None

property channel_id: int | None

Channel identifier from binary header or cached value.

Returns:

Channel ID, or None if not available.

Return type:

int or None

property file_sequence: int | None

File sequence number from binary header.

Returns:

File sequence number, or None if no header is loaded.

Return type:

int or None

property frag_period: int | None

Fragment period from binary header.

Returns:

Fragment period, or None if no header is loaded.

Return type:

int or None

property ch_board_model: str | None

Channel board model string from binary header.

Returns:

Board model string, or None if no header is loaded.

Return type:

str or None

property board_model_main: str | None

Main board model identifier.

Returns:

Main board model (first 5 characters), or None if not available.

Return type:

str or None

property board_model_revision: str | None

Board model revision identifier.

Returns:

Board revision (character 6), or None if not available.

Return type:

str or None

property ch_board_serial: int

Channel board serial number from binary header.

Returns:

Board serial number as integer, or 0 if not available or invalid.

Return type:

int

property ch_firmware: int | None

Channel firmware version from binary header.

Returns:

Firmware version, or None if no header is loaded.

Return type:

int or None

property hardware_configuration: tuple[Any, Ellipsis] | None

Hardware configuration bytes from binary header.

Returns:

Hardware configuration data, or None if no header is loaded.

Return type:

tuple of Any or None

property channel_type: str | None

Channel type determined from hardware configuration.

Returns:

‘E’ for electric, ‘H’ for magnetic, or None if no header.

Return type:

str or None

property detected_channel_type: str | None

Channel type detected by electronics.

This normally matches channel_type, but used in electronics design and testing.

Returns:

‘E’ for electric, ‘H’ for magnetic, or None if no header.

Return type:

str or None

property lp_frequency: int | None

Low-pass filter frequency based on hardware configuration.

Returns:

Filter frequency in Hz, or None if no header.

Return type:

int or None

property preamp_gain: float

Pre-amplifier gain factor.

Returns:

Gain factor, default 1.0.

Return type:

float

Raises:

Exception – If channel type is not determined before calculating gain.

property channel_main_gain: float

Main gain of the board.

Returns:

Main gain factor.

Return type:

float

property intrinsic_circuitry_gain: float

Intrinsic circuitry gain based on sensor range configuration.

This function adjusts the intrinsic circuitry gain based on the sensor range configuration in the configuration fingerprint.

For the Electric channel, calibration path, or H-legacy sensors all go through a 1/4 gain stage, and then they get a virtual x2 gain from Single-ended-diff before the A/D. In the case of newer sensors (differential) instead of a 1/4 gain stage, there is only a 1/2 gain stage.

Therefore, in the E, cal and legacy sensor case the circuitry gain is 1/2, while for newer sensors it is 1.

Returns:

Intrinsic gain factor.

Return type:

float

Raises:

Exception – If channel type is not determined before calculating gain.

Notes

Circuitry Gain not directly configurable by the user.

property attenuator_gain: float

Attenuator gain factor.

Returns:

Attenuator gain factor, default 1.0.

Return type:

float

Raises:

Exception – If channel type is not determined before calculating gain.

property total_selectable_gain: float

Total gain that is selectable by the user.

Combines attenuator, preamp, and main channel gains.

Returns:

Total selectable gain factor.

Return type:

float

property total_circuitry_gain: float

Total board gain including both intrinsic and user-selectable gains.

Returns:

Total circuitry gain factor.

Return type:

float

property sample_rate_base: int | None

Base sample rate from binary header.

Returns:

Base sample rate, or None if no header.

Return type:

int or None

property sample_rate_exp: int | None

Sample rate exponent from binary header.

Returns:

Sample rate exponent, or None if no header.

Return type:

int or None

property sample_rate: float | None

Calculated sample rate.

Returns:

Sample rate in Hz, or None if no header.

Return type:

float or None

property bytes_per_sample: int | None

Number of bytes per sample.

Returns:

Bytes per sample, or None if no header.

Return type:

int or None

property frame_size: int | None

Frame size from binary header.

Returns:

Frame size value, or None if no header.

Return type:

int or None

property data_footer: int | None

Data footer extracted from frame size.

Returns:

Data footer value, or None if no frame size.

Return type:

int or None

property frame_size_bytes: int | None

Frame size in bytes.

Returns:

Frame size in bytes, or None if no frame size.

Return type:

int or None

property decimation_node_id: int | None

Decimation node identifier.

Returns:

Decimation node ID, or None if no header.

Return type:

int or None

property frame_rollover_count: int | None

Frame rollover count.

Returns:

Rollover count, or None if no header.

Return type:

int or None

property gps_long: float | None

GPS longitude.

Returns:

Longitude in degrees, or None if no header.

Return type:

float or None

property gps_lat: float | None

GPS latitude.

Returns:

Latitude in degrees, or None if no header.

Return type:

float or None

property gps_elevation: float | None

GPS elevation.

Returns:

Elevation in meters, or None if no header.

Return type:

float or None

property gps_horizontal_accuracy: float | None

GPS horizontal accuracy.

Returns:

Horizontal accuracy in meters (converted from millimeters), or None if no header.

Return type:

float or None

property gps_vertical_accuracy: float | None

GPS vertical accuracy.

Returns:

Vertical accuracy in meters (converted from millimeters), or None if no header.

Return type:

float or None

property timing_status: tuple[Any, Ellipsis] | None

Timing status information.

Returns:

Timing status data, or None if no header.

Return type:

tuple of Any or None

property timing_flags: Any | None

Timing flags from timing status.

Returns:

Timing flags, or None if no timing status.

Return type:

Any or None

property timing_sat_count: Any | None

Satellite count from timing status.

Returns:

Satellite count, or None if no timing status.

Return type:

Any or None

property timing_stability: Any | None

Timing stability from timing status.

Returns:

Timing stability value, or None if no timing status.

Return type:

Any or None

property future1: Any | None

Future field 1 (reserved).

Returns:

Future field value, or None if no header.

Return type:

Any or None

property future2: Any | None

Future field 2 (reserved).

Returns:

Future field value, or None if no header.

Return type:

Any or None

property saturated_frames: int | None

Number of saturated frames.

Returns:

Saturated frame count, or None if no header.

Return type:

int or None

property missing_frames: int | None

Number of missing frames.

Returns:

Missing frame count, or None if no header.

Return type:

int or None

property battery_voltage_v: float | None

Battery voltage in volts.

Returns:

Battery voltage in volts (converted from millivolts), or None if no header.

Return type:

float or None

property min_signal: Any | None

Minimum signal value.

Returns:

Minimum signal value, or None if no header.

Return type:

Any or None

property max_signal: Any | None

Maximum signal value.

Returns:

Maximum signal value, or None if no header.

Return type:

Any or None

unpack_header(stream: BinaryIO) → None

Read and unpack binary header from stream.

Parameters:

stream (BinaryIO) – Binary stream to read header from.

get_channel_metadata() → mt_metadata.timeseries.Magnetic | mt_metadata.timeseries.Electric

Translate metadata to channel metadata.

Returns:

Channel metadata object populated with header data.

Return type:

Magnetic or Electric

Raises:

• KeyError – If channel ID is not found in channel map.

• ValueError – If required fields are None or invalid.

get_run_metadata() → mt_metadata.timeseries.Run

Translate to run metadata.

Returns:

Run metadata object populated with header data.

Return type:

Run

Raises:

ValueError – If required fields are None.

get_station_metadata() → mt_metadata.timeseries.Station

Translate to station metadata.

Returns:

Station metadata object populated with header data.

Return type:

Station