mth5.io.metronix

Created on Fri Nov 22 13:55:28 2024

@author: jpeacock

Submodules

Classes

`MetronixFileNameMetadata`	Parse and manage metadata from Metronix filename conventions.
`MetronixChannelJSON`	Read and parse Metronix JSON metadata files.
`MetronixCollection`	Collection class for managing Metronix ATSS files.

Package Contents

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

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

system_number: str | None = None

system_name: str | None = None

channel_number: int | None = None

component: str | None = None

sample_rate: float | None = None

file_type: str | None = None

property fn: pathlib.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 file_size: int

Get file size in bytes.

Returns:: File size in bytes, 0 if file is None
Return type:: int

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

property duration: float

Get estimated duration of the file in seconds.

Returns:: Duration in seconds
Return type:: float

class mth5.io.metronix.MetronixChannelJSON(fn: str | pathlib.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

metadata: types.SimpleNamespace | None = None

read(fn: str | pathlib.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

get_channel_metadata() → mt_metadata.timeseries.Electric | mt_metadata.timeseries.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_sensor_response_filter() → mt_metadata.timeseries.filters.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

get_channel_response() → mt_metadata.timeseries.filters.ChannelResponse[source]

Get all filters needed to calibrate the data.

Returns:: Channel response object containing all calibration filters
Return type:: ChannelResponse

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

Bases: mth5.io.collection.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])

file_ext: list[str] = ['atss']

to_dataframe(sample_rates: list[int] = [128], run_name_zeros: int = 0, calibration_path: str | pathlib.Path | None = None) → pandas.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

assign_run_names(df: pandas.DataFrame, zeros: int = 0) → pandas.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.