mth5.io.phoenix.readers.segmented.decimated_segmented_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

Classes

`SubHeader`	Class for subheader of segmented files.
`Segment`	A segment class to hold a single segment.
`DecimatedSegmentedReader`	Class to create a streamer for segmented decimated time series.
`DecimatedSegmentCollection`	Class to read multiple segments from a segmented decimated time series file.

Module Contents

class mth5.io.phoenix.readers.segmented.decimated_segmented_reader.SubHeader(**kwargs)[source]

Class for subheader of segmented files.

This class handles the parsing and access to subheader information in Phoenix Geophysics segmented time series files. The subheader contains metadata about each segment including timing, sample counts, and statistics.

Parameters:: **kwargs – Arbitrary keyword arguments that are set as attributes

header_length[source]

Length of the subheader in bytes (32 bytes)

Type:: int

_header[source]

Raw header bytes from the file

Type:: bytes or None

_unpack_dict[source]

Dictionary defining how to unpack different header fields

Type:: dict

header_length = 32[source]

property gps_time_stamp: mt_metadata.common.mttime.MTime | None[source]

GPS time stamp in UTC.

Returns:: GPS timestamp if header is available, None otherwise
Return type:: MTime or None

property n_samples: int | None[source]

Number of samples in the segment.

Returns:: Number of samples if header is available, None otherwise
Return type:: int or None

property saturation_count: int | None[source]

Number of saturated samples.

Returns:: Saturation count if header is available, None otherwise
Return type:: int or None

property missing_count: int | None[source]

Number of missing samples.

Returns:: Missing sample count if header is available, None otherwise
Return type:: int or None

property value_min: float | None[source]

Minimum value in the segment.

Returns:: Minimum value if header is available, None otherwise
Return type:: float or None

property value_max: float | None[source]

Maximum value in the segment.

Returns:: Maximum value if header is available, None otherwise
Return type:: float or None

property value_mean: float | None[source]

Mean value in the segment.

Returns:: Mean value if header is available, None otherwise
Return type:: float or None

unpack_header(stream: BinaryIO) → None[source]

Unpack the header from a binary stream.

Parameters:: stream (BinaryIO) – Binary stream to read header from

class mth5.io.phoenix.readers.segmented.decimated_segmented_reader.Segment(stream: BinaryIO, **kwargs)[source]

Bases: SubHeader

A segment class to hold a single segment.

This class represents a single time series segment with its associated metadata and data. It inherits from SubHeader to provide access to segment-specific header information.

Parameters:

stream (BinaryIO) – Binary file stream to read from
**kwargs – Additional keyword arguments passed to SubHeader

stream[source]

The file stream for reading data

Type:: BinaryIO

data[source]

Time series data for this segment

Type:: np.ndarray or None

stream[source]

data: numpy.ndarray | None = None[source]

read_segment(metadata_only: bool = False) → None[source]

Read the segment data from the file stream.

Parameters:: metadata_only (bool, optional) – If True, only read metadata without loading data, by default False

property segment_start_time: mt_metadata.common.mttime.MTime | None[source]

Get the segment start time.

Returns:: GPS timestamp of segment start, or None if not available
Return type:: MTime or None

property segment_end_time: mt_metadata.common.mttime.MTime | None[source]

Calculate the segment end time.

Returns:: Estimated end time based on start time, sample count and sample rate, or None if required information is not available
Return type:: MTime or None

class mth5.io.phoenix.readers.segmented.decimated_segmented_reader.DecimatedSegmentedReader(path: str | pathlib.Path, num_files: int = 1, report_hw_sat: bool = False, **kwargs)[source]

Bases: mth5.io.phoenix.readers.TSReaderBase

Class to create a streamer for segmented decimated time series.

This reader handles segmented decimated time series files such as ‘td_24k’. These files have sub headers containing metadata for each segment.

Parameters:

path (str or Path) – Path to the time series file
num_files (int, optional) – Number of files in the sequence, by default 1
report_hw_sat (bool, optional) – Whether to report hardware saturation, by default False
**kwargs – Additional keyword arguments passed to parent TSReaderBase class

sub_header[source]

SubHeader instance for parsing segment headers

Type:: SubHeader

subheader[source]

Dictionary for additional subheader information

Type:: dict

sub_header[source]

subheader[source]

read_segment(metadata_only: bool = False) → Segment[source]

Read a single segment from the file.

Parameters:: metadata_only (bool, optional) – If True, only read metadata without loading data, by default False
Returns:: Segment object containing data and metadata
Return type:: Segment
Raises:: ValueError – If stream is not available

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

class mth5.io.phoenix.readers.segmented.decimated_segmented_reader.DecimatedSegmentCollection(path: str | pathlib.Path, num_files: int = 1, report_hw_sat: bool = False, **kwargs)[source]

Bases: mth5.io.phoenix.readers.TSReaderBase

Class to read multiple segments from a segmented decimated time series file.

This reader handles files containing multiple segments of decimated time series data such as ‘td_24k’. Each segment has its own sub header with metadata.

Parameters:

path (str or Path) – Path to the time series file
num_files (int, optional) – Number of files in the sequence, by default 1
report_hw_sat (bool, optional) – Whether to report hardware saturation, by default False
**kwargs – Additional keyword arguments passed to parent TSReaderBase class

sub_header[source]

SubHeader instance for parsing segment headers

Type:: SubHeader

subheader[source]

Dictionary for additional subheader information

Type:: dict

sub_header[source]

subheader[source]

read_segments(metadata_only: bool = False) → list[Segment][source]

Read all segments from the file.

Parameters:: metadata_only (bool, optional) – If True, only read metadata without loading data, by default False
Returns:: List of Segment objects containing data and metadata
Return type:: list[Segment]
Raises:: ValueError – If stream is not available

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

Convert all segments to ChannelTS objects.

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:

List of ChannelTS objects, one for each segment

Return type:

list[ChannelTS]