mth5.io.metronix.metronix_atss

ATSS (Audio Time Series System) file reader for Metronix data.

This module provides functionality to read and process Metronix ATSS binary time series files and their associated JSON metadata files. ATSS files contain double precision floating point time series data equivalent to numpy arrays of type np.float64.

The ATSS format consists of two files: - .atss file: Binary time series data (np.float64 values) - .json file: Metadata in JSON format

This implementation is translated from: https://github.com/bfrmtx/MTHotel/blob/main/python/include/atss_file.py

Classes

ATSSMetronixFileNameMetadata: Main class for reading ATSS files and converting to ChannelTS objects.

Functions

read_atssfunction: Convenience function to read ATSS file and return ChannelTS object.

Notes

ATSS files store time series data as consecutive double precision floating point numbers in binary format, making them efficient for large datasets.

Examples

>>> from mth5.io.metronix.metronix_atss import ATSS, read_atss
>>>
>>> # Using the ATSS class directly
>>> atss = ATSS('data/station001.atss')
>>> data = atss.read_atss()
>>> channel_ts = atss.to_channel_ts()
>>>
>>> # Using the convenience function
>>> channel_ts = read_atss('data/station001.atss')

Author

jpeacock

Created

Tue Nov 26 15:54:12 2024

Classes

ATSS

ATSS (Audio Time Series System) file reader for Metronix data.

Functions

read_atss(→ mth5.timeseries.ChannelTS)

Generic tool to read ATSS file and return ChannelTS object.

Module Contents

class mth5.io.metronix.metronix_atss.ATSS(fn: str | pathlib.Path | None = None, **kwargs: Any)[source]

Bases: mth5.io.metronix.MetronixFileNameMetadata

ATSS (Audio Time Series System) file reader for Metronix data.

Handles reading and processing of Metronix ATSS binary time series files and their associated JSON metadata files. ATSS files contain double precision floating point time series data equivalent to numpy arrays of type np.float64.

Parameters:

fn (str or Path, optional) – Path to the ATSS file. If provided, metadata will be automatically loaded if the corresponding JSON file exists.
**kwargs – Additional keyword arguments passed to parent class.

header[source]

Metadata handler for the associated JSON file.

Type:: MetronixChannelJSON

Notes

ATSS files come in pairs: - .atss file: Binary time series data (np.float64) - .json file: Metadata in JSON format

Examples

>>> atss = ATSS('data/station001_run001_ch001.atss')
>>> data = atss.read_atss()
>>> channel_ts = atss.to_channel_ts()

header[source]

property metadata_fn: pathlib.Path | None[source]

Path to the metadata JSON file.

Returns the path to the JSON metadata file that corresponds to this ATSS file. The JSON file has the same base name as the ATSS file but with a .json extension.

Returns:: Path to the JSON metadata file, or None if no ATSS file is set.
Return type:: Path or None

Examples

>>> atss = ATSS('data/station001.atss')
>>> atss.metadata_fn
PosixPath('data/station001.json')

has_metadata_file() → bool[source]

Check if metadata JSON file exists.

Returns:: True if the metadata JSON file exists, False otherwise.
Return type:: bool

Examples

>>> atss = ATSS('data/station001.atss')
>>> atss.has_metadata_file()
True

read_atss(fn: str | pathlib.Path | None = None, start: int = 0, stop: int = 0) → numpy.ndarray[source]

Read binary ATSS time series data.

Reads double precision floating point time series data from the ATSS binary file. Data is stored as consecutive np.float64 values.

Parameters:

fn (str or Path, optional) – Path to ATSS file. If None, uses the current file path.
start (int, default 0) – Starting sample index (0-based).
stop (int, default 0) – Ending sample index. If 0, reads to end of file.

Returns:

Time series data as 1D array of np.float64 values.

Return type:

np.ndarray

Raises:

ValueError – If stop index exceeds the number of samples in the file.

Examples

>>> atss = ATSS('data/station001.atss')
>>> data = atss.read_atss()  # Read entire file
>>> data_slice = atss.read_atss(start=1000, stop=2000)  # Read subset

write_atss(data_array: numpy.ndarray, filename: str | pathlib.Path) → None[source]

Write time series data to ATSS binary file.

Writes numpy array data as double precision floating point values to a binary ATSS file.

Parameters:

data_array (np.ndarray) – Time series data to write. Will be converted to np.float64.
filename (str or Path) – Output file path for the ATSS binary file.

Examples

>>> import numpy as np
>>> atss = ATSS()
>>> data = np.random.randn(10000)
>>> atss.write_atss(data, 'output.atss')

property channel_metadata: mt_metadata.timeseries.electric.Electric | mt_metadata.timeseries.magnetic.Magnetic | mt_metadata.timeseries.auxiliary.Auxiliary[source]

Channel metadata from the JSON header file.

Returns:: Channel metadata object based on the channel type.
Return type:: Electric or Magnetic or Auxiliary

property channel_response: mt_metadata.timeseries.filters.ChannelResponse[source]

Channel response information from the JSON header file.

Returns:: Channel response/calibration information.
Return type:: ChannelResponse

property channel_type: str[source]

Determine channel type from component name.

Channel type is determined from the component identifier in the filename: - Components starting with ‘e’: electric - Components starting with ‘h’: magnetic - All others: auxiliary

Returns:: Channel type: ‘electric’, ‘magnetic’, or ‘auxiliary’.
Return type:: str

property run_id: str | None[source]

Extract run ID from file path.

Expects file path structure: …/station/run/timeseries.atss The run ID is extracted from the parent directory name.

Returns:: Run identifier, or None if file doesn’t exist.
Return type:: str or None

property station_id: str | None[source]

Extract station ID from file path.

Expects file path structure: …/station/run/timeseries.atss The station ID is extracted from the grandparent directory name.

Returns:: Station identifier, or None if file doesn’t exist.
Return type:: str or None

property survey_id: str | None[source]

Extract survey ID from file path.

Expects file path structure: …/survey/stations/station/run/timeseries.atss The survey ID is extracted from the great-great-grandparent directory name.

Returns:: Survey identifier, or None if file doesn’t exist.
Return type:: str or None

property run_metadata: mt_metadata.timeseries.Run[source]

Generate run-level metadata.

Creates a Run metadata object populated with information from the ATSS file and its associated JSON metadata.

Returns:: Run metadata object with data logger info, sample rate, and channel metadata.
Return type:: Run

property station_metadata: mt_metadata.timeseries.Station[source]

Generate station-level metadata.

Creates a Station metadata object populated with location information from the JSON metadata and run information.

Returns:: Station metadata object with location coordinates and run metadata.
Return type:: Station

property survey_metadata: mt_metadata.timeseries.Survey[source]

Generate survey-level metadata.

Creates a Survey metadata object that includes station metadata and overall time period information.

Returns:: Survey metadata object containing station information.
Return type:: Survey

to_channel_ts(fn: str | pathlib.Path | None = None) → mth5.timeseries.ChannelTS[source]

Create a ChannelTS object from ATSS data.

Converts the ATSS time series data and metadata into a ChannelTS object suitable for use with MTH5 workflows.

Parameters:: fn (str or Path, optional) – Path to ATSS file. If None, uses current file path.
Returns:: Time series object with data, metadata, and response information.
Return type:: ChannelTS

Warning

Can be slow due to pandas datetime index creation for large datasets. A warning is logged if the metadata JSON file is missing.

Examples

>>> atss = ATSS('data/station001.atss')
>>> channel_ts = atss.to_channel_ts()
>>> print(channel_ts.sample_rate)
1024.0

mth5.io.metronix.metronix_atss.read_atss(fn: str | pathlib.Path, calibration_fn: str | pathlib.Path | None = None, logger_file_handler: Any = None) → mth5.timeseries.ChannelTS[source]

Generic tool to read ATSS file and return ChannelTS object.

Convenience function that creates an ATSS object and converts it to a ChannelTS in a single call.

Parameters:

fn (str or Path) – Path to the ATSS file to read.
calibration_fn (str or Path, optional) – Path to calibration file (currently unused).
logger_file_handler (Any, optional) – Logger file handler (currently unused).

Returns:

Time series object with data and metadata from the ATSS file.

Return type:

ChannelTS

Examples

>>> channel_ts = read_atss('data/station001.atss')
>>> print(f"Loaded {len(channel_ts.ts)} samples")