mth5.io.metronix package

Submodules

mth5.io.metronix.metronix_atss module

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

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

Bases: 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()
property channel_metadata: Electric | Magnetic | 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: 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

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
property metadata_fn: 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')
read_atss(fn: str | Path | None = None, start: int = 0, stop: int = 0) → 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
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 run_metadata: 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_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 station_metadata: 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_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 survey_metadata: 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 | Path | None = None) → 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
write_atss(data_array: ndarray, filename: str | 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')
mth5.io.metronix.metronix_atss.read_atss(fn: str | Path, calibration_fn: str | Path | None = None, logger_file_handler: Any = None) → 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")

mth5.io.metronix.metronix_collection module

Metronix collection utilities for managing ATSS files.

This module provides classes for collecting and managing Metronix ATSS (Audio Time Series System) files and creating pandas DataFrames with metadata for processing workflows.

Classes

MetronixCollection

Collection class for managing Metronix ATSS files

Created on Fri Nov 22 13:22:44 2024

@author: jpeacock

class mth5.io.metronix.metronix_collection.MetronixCollection(file_path: str | Path | None = None, **kwargs: Any)[source]

Bases: Collection

Collection class for managing Metronix ATSS files.

This class extends the base Collection class to handle Metronix ATSS (Audio Time Series System) files and their associated JSON metadata files. It provides functionality to create pandas DataFrames with comprehensive metadata for processing workflows.

Parameters:

  • file_path (Union[str, Path, None], optional) – Path to directory containing Metronix ATSS files, by default None

  • **kwargs – Additional keyword arguments passed to parent Collection class

file_ext[source]

List of file extensions to search for ([“atss”])

Type:

list[str]

Examples

>>> from mth5.io.metronix import MetronixCollection
>>> collection = MetronixCollection("/path/to/metronix/files")
>>> df = collection.to_dataframe(sample_rates=[128, 256])
assign_run_names(df: DataFrame, zeros: int = 0) → DataFrame[source]

Assign formatted run names based on sample rate and run number.

If zeros is 0, run names are unchanged. Otherwise, run names are formatted as ‘sr{sample_rate}_{run_number:0{zeros}d}’ where the run number is extracted from the original run name after the first underscore.

Parameters:

  • df (pd.DataFrame) – DataFrame containing run information with ‘run’ and ‘sample_rate’ columns

  • zeros (int, optional) – Number of zeros for zero-padding run numbers. If 0, run names are unchanged, by default 0

Returns:

DataFrame with updated run names

Return type:

pd.DataFrame

Examples

>>> df = pd.DataFrame({
...     'run': ['run_1', 'run_2'],
...     'sample_rate': [128, 256]
... })
>>> collection = MetronixCollection()
>>> result = collection.assign_run_names(df, zeros=3)
>>> print(result['run'].tolist())
['sr128_001', 'sr256_002']

Notes

The method expects run names to be in format ‘prefix_number’ where ‘number’ can be extracted and converted to an integer for formatting.

to_dataframe(sample_rates: list[int] = [128], run_name_zeros: int = 0, calibration_path: str | Path | None = None) → DataFrame[source]

Create DataFrame for Metronix timeseries ATSS + JSON file sets.

Processes all ATSS files in the collection directory, extracts metadata, and creates a comprehensive pandas DataFrame with information about each channel including timing, location, and instrument details.

Parameters:

  • sample_rates (list[int], optional) – List of sample rates to include in Hz, by default [128]

  • run_name_zeros (int, optional) – Number of zeros for zero-padding run names. If 0, run names are unchanged. If > 0, run names are formatted as ‘sr{sample_rate}_{run_number:0{zeros}d}’, by default 0

  • calibration_path (Union[str, Path, None], optional) – Path to calibration files (currently unused), by default None

Returns:

DataFrame with columns: - survey: Survey ID - station: Station ID - run: Run ID - start: Start time (datetime) - end: End time (datetime) - channel_id: Channel number - component: Component name (ex, ey, hx, hy, hz) - fn: File path - sample_rate: Sample rate in Hz - file_size: File size in bytes - n_samples: Number of samples - sequence_number: Sequence number (always 0) - dipole: Dipole length (always 0) - coil_number: Coil serial number (magnetic channels only) - latitude: Latitude in decimal degrees - longitude: Longitude in decimal degrees - elevation: Elevation in meters - instrument_id: Instrument/system number - calibration_fn: Calibration file path (always None)

Return type:

pd.DataFrame

Examples

>>> collection = MetronixCollection("/path/to/files")
>>> df = collection.to_dataframe(sample_rates=[128, 256])
>>> df = collection.to_dataframe(run_name_zeros=4)  # Zero-pad run names

mth5.io.metronix.metronix_metadata module

Metronix metadata parsing utilities.

This module provides classes for parsing and managing metadata from Metronix ATSS (Audio Time Series System) files and associated JSON metadata files.

Classes

MetronixFileNameMetadata

Parse metadata from Metronix filename conventions

MetronixChannelJSON

Read and parse Metronix JSON metadata files

Created on Fri Nov 22 13:23:42 2024

@author: jpeacock

class mth5.io.metronix.metronix_metadata.MetronixChannelJSON(fn: str | Path | None = None, **kwargs: Any)[source]

Bases: MetronixFileNameMetadata

Read and parse Metronix JSON metadata files.

This class extends MetronixFileNameMetadata to handle JSON metadata files containing channel configuration and calibration information.

Parameters:

  • fn (Union[str, Path, None], optional) – Path to Metronix JSON file, by default None

  • **kwargs – Additional keyword arguments passed to parent class

metadata[source]

Parsed JSON metadata as a SimpleNamespace object

Type:

SimpleNamespace or None

property fn: Path | None[source]

Get the file path.

Returns:

File path object or None if not set

Return type:

Path or None

get_channel_metadata() → Electric | Magnetic | None[source]

Translate to mt_metadata.timeseries.Channel object.

Creates either Electric or Magnetic metadata objects based on the component type and applies calibration filters.

Returns:

mt_metadata object based on component type, or None if no metadata

Return type:

Union[Electric, Magnetic, None]

Raises:

ValueError – If component type is not recognized

get_channel_response() → ChannelResponse[source]

Get all filters needed to calibrate the data.

Returns:

Channel response object containing all calibration filters

Return type:

ChannelResponse

get_sensor_response_filter() → FrequencyResponseTableFilter | None[source]

Get the sensor response frequency-amplitude-phase filter.

Creates a FrequencyResponseTableFilter from the sensor calibration data stored in the JSON metadata.

Returns:

Sensor response filter if calibration data exists, None otherwise

Return type:

FrequencyResponseTableFilter or None

read(fn: str | Path | None = None) → None[source]

Read JSON metadata from file.

Parameters:

fn (Union[str, Path, None], optional) – Path to JSON file, by default None (uses self.fn)

Raises:

IOError – If JSON file cannot be found

class mth5.io.metronix.metronix_metadata.MetronixFileNameMetadata(fn: str | Path | None = None, **kwargs: Any)[source]

Bases: object

Parse and manage metadata from Metronix filename conventions.

This class extracts metadata information from Metronix ATSS filenames including system information, channel details, and file properties.

Parameters:

  • fn (Union[str, Path, None], optional) – Path to Metronix file, by default None

  • **kwargs – Additional keyword arguments (currently unused)

system_number[source]

System identification number

Type:

str or None

system_name[source]

Name of the system

Type:

str or None

channel_number[source]

Channel number (parsed from C## format)

Type:

int or None

component[source]

Component designation (e.g., ‘ex’, ‘ey’, ‘hx’, ‘hy’, ‘hz’)

Type:

str or None

sample_rate[source]

Sampling rate in Hz

Type:

float or None

file_type[source]

Type of file (‘metadata’ or ‘timeseries’)

Type:

str or None

property duration: float[source]

Get estimated duration of the file in seconds.

Returns:

Duration in seconds

Return type:

float

property file_size: int[source]

Get file size in bytes.

Returns:

File size in bytes, 0 if file is None

Return type:

int

property fn: Path | None[source]

Get the file path.

Returns:

File path object or None if not set

Return type:

Path or None

property fn_exists: bool[source]

Check if the file exists.

Returns:

True if file exists, False otherwise

Return type:

bool

property n_samples: float[source]

Get estimated number of samples in file.

Assumes 8 bytes per sample (double precision).

Returns:

Estimated number of samples

Return type:

float

Module contents

Created on Fri Nov 22 13:55:28 2024

@author: jpeacock

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

Bases: 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

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()
property channel_metadata: Electric | Magnetic | Auxiliary

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: ChannelResponse

Channel response information from the JSON header file.

Returns:

Channel response/calibration information.

Return type:

ChannelResponse

property channel_type: str

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

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
property metadata_fn: Path | None

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')
read_atss(fn: str | Path | None = None, start: int = 0, stop: int = 0) → 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
property run_id: str | None

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 run_metadata: Run

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_id: str | None

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 station_metadata: Station

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_id: str | None

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 survey_metadata: Survey

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 | Path | None = None) → 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
write_atss(data_array: ndarray, filename: str | 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')
class mth5.io.metronix.MetronixChannelJSON(fn: str | Path | None = None, **kwargs: Any)[source]

Bases: MetronixFileNameMetadata

Read and parse Metronix JSON metadata files.

This class extends MetronixFileNameMetadata to handle JSON metadata files containing channel configuration and calibration information.

Parameters:

  • fn (Union[str, Path, None], optional) – Path to Metronix JSON file, by default None

  • **kwargs – Additional keyword arguments passed to parent class

metadata

Parsed JSON metadata as a SimpleNamespace object

Type:

SimpleNamespace or None

property fn: Path | None

Get the file path.

Returns:

File path object or None if not set

Return type:

Path or None

get_channel_metadata() → Electric | Magnetic | None[source]

Translate to mt_metadata.timeseries.Channel object.

Creates either Electric or Magnetic metadata objects based on the component type and applies calibration filters.

Returns:

mt_metadata object based on component type, or None if no metadata

Return type:

Union[Electric, Magnetic, None]

Raises:

ValueError – If component type is not recognized

get_channel_response() → ChannelResponse[source]

Get all filters needed to calibrate the data.

Returns:

Channel response object containing all calibration filters

Return type:

ChannelResponse

get_sensor_response_filter() → FrequencyResponseTableFilter | None[source]

Get the sensor response frequency-amplitude-phase filter.

Creates a FrequencyResponseTableFilter from the sensor calibration data stored in the JSON metadata.

Returns:

Sensor response filter if calibration data exists, None otherwise

Return type:

FrequencyResponseTableFilter or None

read(fn: str | Path | None = None) → None[source]

Read JSON metadata from file.

Parameters:

fn (Union[str, Path, None], optional) – Path to JSON file, by default None (uses self.fn)

Raises:

IOError – If JSON file cannot be found

class mth5.io.metronix.MetronixCollection(file_path: str | Path | None = None, **kwargs: Any)[source]

Bases: Collection

Collection class for managing Metronix ATSS files.

This class extends the base Collection class to handle Metronix ATSS (Audio Time Series System) files and their associated JSON metadata files. It provides functionality to create pandas DataFrames with comprehensive metadata for processing workflows.

Parameters:

  • file_path (Union[str, Path, None], optional) – Path to directory containing Metronix ATSS files, by default None

  • **kwargs – Additional keyword arguments passed to parent Collection class

file_ext

List of file extensions to search for ([“atss”])

Type:

list[str]

Examples

>>> from mth5.io.metronix import MetronixCollection
>>> collection = MetronixCollection("/path/to/metronix/files")
>>> df = collection.to_dataframe(sample_rates=[128, 256])
assign_run_names(df: DataFrame, zeros: int = 0) → DataFrame[source]

Assign formatted run names based on sample rate and run number.

If zeros is 0, run names are unchanged. Otherwise, run names are formatted as ‘sr{sample_rate}_{run_number:0{zeros}d}’ where the run number is extracted from the original run name after the first underscore.

Parameters:

  • df (pd.DataFrame) – DataFrame containing run information with ‘run’ and ‘sample_rate’ columns

  • zeros (int, optional) – Number of zeros for zero-padding run numbers. If 0, run names are unchanged, by default 0

Returns:

DataFrame with updated run names

Return type:

pd.DataFrame

Examples

>>> df = pd.DataFrame({
...     'run': ['run_1', 'run_2'],
...     'sample_rate': [128, 256]
... })
>>> collection = MetronixCollection()
>>> result = collection.assign_run_names(df, zeros=3)
>>> print(result['run'].tolist())
['sr128_001', 'sr256_002']

Notes

The method expects run names to be in format ‘prefix_number’ where ‘number’ can be extracted and converted to an integer for formatting.

to_dataframe(sample_rates: list[int] = [128], run_name_zeros: int = 0, calibration_path: str | Path | None = None) → DataFrame[source]

Create DataFrame for Metronix timeseries ATSS + JSON file sets.

Processes all ATSS files in the collection directory, extracts metadata, and creates a comprehensive pandas DataFrame with information about each channel including timing, location, and instrument details.

Parameters:

  • sample_rates (list[int], optional) – List of sample rates to include in Hz, by default [128]

  • run_name_zeros (int, optional) – Number of zeros for zero-padding run names. If 0, run names are unchanged. If > 0, run names are formatted as ‘sr{sample_rate}_{run_number:0{zeros}d}’, by default 0

  • calibration_path (Union[str, Path, None], optional) – Path to calibration files (currently unused), by default None

Returns:

DataFrame with columns: - survey: Survey ID - station: Station ID - run: Run ID - start: Start time (datetime) - end: End time (datetime) - channel_id: Channel number - component: Component name (ex, ey, hx, hy, hz) - fn: File path - sample_rate: Sample rate in Hz - file_size: File size in bytes - n_samples: Number of samples - sequence_number: Sequence number (always 0) - dipole: Dipole length (always 0) - coil_number: Coil serial number (magnetic channels only) - latitude: Latitude in decimal degrees - longitude: Longitude in decimal degrees - elevation: Elevation in meters - instrument_id: Instrument/system number - calibration_fn: Calibration file path (always None)

Return type:

pd.DataFrame

Examples

>>> collection = MetronixCollection("/path/to/files")
>>> df = collection.to_dataframe(sample_rates=[128, 256])
>>> df = collection.to_dataframe(run_name_zeros=4)  # Zero-pad run names
class mth5.io.metronix.MetronixFileNameMetadata(fn: str | Path | None = None, **kwargs: Any)[source]

Bases: object

Parse and manage metadata from Metronix filename conventions.

This class extracts metadata information from Metronix ATSS filenames including system information, channel details, and file properties.

Parameters:

  • fn (Union[str, Path, None], optional) – Path to Metronix file, by default None

  • **kwargs – Additional keyword arguments (currently unused)

system_number

System identification number

Type:

str or None

system_name

Name of the system

Type:

str or None

channel_number

Channel number (parsed from C## format)

Type:

int or None

component

Component designation (e.g., ‘ex’, ‘ey’, ‘hx’, ‘hy’, ‘hz’)

Type:

str or None

sample_rate

Sampling rate in Hz

Type:

float or None

file_type

Type of file (‘metadata’ or ‘timeseries’)

Type:

str or None

property duration: float

Get estimated duration of the file in seconds.

Returns:

Duration in seconds

Return type:

float

property file_size: int

Get file size in bytes.

Returns:

File size in bytes, 0 if file is None

Return type:

int

property fn: Path | None

Get the file path.

Returns:

File path object or None if not set

Return type:

Path or None

property fn_exists: bool

Check if the file exists.

Returns:

True if file exists, False otherwise

Return type:

bool

property n_samples: float

Get estimated number of samples in file.

Assumes 8 bytes per sample (double precision).

Returns:

Estimated number of samples

Return type:

float

mth5.io.metronix.read_atss(fn: str | Path, calibration_fn: str | Path | None = None, logger_file_handler: Any = None) → 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")