mth5 package

Subpackages

Submodules

mth5.helpers module

Helper functions for HDF5

Created on Tue Jun 2 12:37:50 2020

copyright:: Jared Peacock (jpeacock@usgs.gov)
license:: MIT

mth5.helpers.add_attributes_to_metadata_class_pydantic(obj: Type[Any]) → Type[Any][source]

Add MTH5-specific attributes to a pydantic metadata class.

This function enhances a pydantic class by adding two important fields: - mth5_type: derived from the class name, indicates the type of MTH5 group - hdf5_reference: stores the HDF5 internal reference

Parameters:: obj (type) – A pydantic class to enhance with MTH5 attributes
Returns:: An instance of the enhanced class with added MTH5-specific fields
Return type:: object
Raises:: TypeError – If the input is not a class

Notes

This function is used to dynamically add metadata fields that are required for MTH5 group management. The mth5_type field is derived from the class name by removing “Group” suffix, and the hdf5_reference field is initialized to None but will be set when the object is associated with an HDF5 group.

mth5.helpers.close_open_files() → None[source]

Close all open HDF5 files found in memory.

This function searches through all objects in memory using garbage collection to find and close any open HDF5 files. This is useful for cleanup operations to ensure no files are left open.

Notes

This function iterates through all objects in memory and attempts to close any h5py.File objects that are found. If a file is already closed, it will log that information. Any exceptions during the process are caught and logged.

mth5.helpers.coerce_value_to_expected_type(key: str, value: Any, expected_type: Any) → Any[source]

Coerce a value to the expected type based on metadata field definitions.

This method handles type conversions for older MTH5 files that may have stored metadata with less strict type enforcement. Uses the metadata’s attribute_information method to get expected types.

Parameters:

key (str) – Metadata field name (may include dots for nested attributes).
value (Any) – Value to coerce.
expected_type (Any) – Expected value type (can be a type object or string representation).

Returns:

Coerced value matching expected type, or original value if coercion fails.

Return type:

Any

Examples

>>> coerced = channel._coerce_value_to_expected_type('sample_rate', '256.0', float)
>>> print(type(coerced), coerced)
<class 'float'> 256.0

>>> coerced = channel._coerce_value_to_expected_type('channel_number', 1.0, int)
>>> print(type(coerced), coerced)
<class 'int'> 1

mth5.helpers.from_numpy_type(value: Any) → Any[source]

Convert a value from numpy/HDF5 format back to standard Python types.

This function handles the reverse conversion from numpy/HDF5 compatible types back to standard Python data types. It’s the counterpart to to_numpy_type.

Parameters:: value (any) – The value to convert from numpy/HDF5 format
Returns:: The converted value in standard Python format: - “none” string becomes None - JSON strings become dictionaries or lists - h5py References become strings - Numpy types become standard Python types - Byte arrays become string lists - Other arrays become Python lists
Return type:: various
Raises:: TypeError – If the value type is not understood or supported

Notes

This function reverses the conversions made by to_numpy_type, including: - Converting JSON strings back to dictionaries and lists - Converting “none” strings back to None - Converting numpy arrays back to Python lists - Handling deprecated numpy.bool types

For numbers and booleans, they are automatically mapped from h5py to numpy types. For strings, especially lists of strings, special handling is required. HDF5 deals with ASCII characters or Unicode, no binary data is allowed.

mth5.helpers.get_data_type(string_representation: str) → Type[Any][source]

Get the Python data type from its string representation.

Parameters:: string_representation (str) – String representation of the data type (e.g., ‘int’, ‘float’, ‘str’).
Returns:: Corresponding Python data type.
Return type:: type
Raises:: ValueError – If the string representation does not correspond to a known data type.

Notes

This function maps common string representations of data types to their corresponding Python types. It supports basic types like int, float, str, bool, list, and dict.

mth5.helpers.get_metadata_type_dict(metadata_class: MetadataBase) → dict[str, Type[Any]][source]

get dictionary of expected data types from the metadata object.

Parameters:: metadata_class (MetadataBase) – Metadata class to extract data types from
Returns:: Dictionary mapping metadata field names to their expected data types.
Return type:: dict[str, Type[Any]]

mth5.helpers.get_tree(parent: Group | File) → str[source]

Recursively print the contents of an HDF5 group in a formatted tree structure.

Parameters:: parent (h5py.Group or h5py.File) – HDF5 (sub-)tree to print
Returns:: Formatted string representation of the HDF5 tree structure
Return type:: str
Raises:: TypeError – If the provided object is not an h5py.File or h5py.Group object

Notes

This function creates a hierarchical text representation of an HDF5 file or group structure, showing groups and datasets with appropriate indentation and formatting.

mth5.helpers.inherit_doc_string(cls: Type[Any]) → Type[Any][source]

Class decorator to inherit docstring from parent classes.

This decorator searches through the method resolution order (MRO) of a class to find the first parent class with a docstring and applies it to the current class.

Parameters:: cls (type) – The class to apply docstring inheritance to
Returns:: The same class with inherited docstring if found
Return type:: type

Notes

This is useful for subclasses that should inherit documentation from their parent classes when they don’t have their own docstring defined.

mth5.helpers.read_attrs_to_dict(attrs_dict: dict[str, Any], metadata_object: MetadataBase) → dict[str, Any][source]

Read HDF5 attributes from a group or dataset into a dictionary.

Parameters:

attrs_dict (dict[str, Any]) – Dictionary of attributes to read and convert.
metadata_object (MetadataBase) – Metadata object to use for type information.

Returns:

Dictionary containing attribute names and their corresponding values.

Return type:

dict[str, Any]

mth5.helpers.recursive_hdf5_tree(group: Group | File | Dataset, lines: list[str] | None = None) → str[source]

Recursively traverse an HDF5 group and return a string representation of its structure.

Parameters:

group (h5py.Group, h5py.File, or h5py.Dataset) – HDF5 object to traverse
lines (list of str, optional) – List to accumulate the tree representation lines. If None, an empty list is used.

Returns:

String representation of the HDF5 tree structure

Return type:

str

Notes

This function recursively traverses HDF5 groups and files, building a text representation of the structure including groups, datasets, and attributes.

mth5.helpers.to_numpy_type(value: Any) → Any[source]

Convert a value to a numpy/HDF5 compatible type.

This function handles the conversion of various Python data types to formats that are compatible with both NumPy and HDF5. For numbers and booleans, this is straightforward as they are automatically mapped to numpy types. For strings and complex data structures, special handling is required.

Parameters:: value (any) – The value to convert to a numpy/HDF5 compatible type
Returns:: The converted value in a numpy/HDF5 compatible format: - None becomes “none” string - Dictionaries and lists become JSON strings - Type objects become string representations - h5py References become strings - Object arrays become string representations - Iterables with strings become numpy byte arrays - Other iterables become numpy arrays - Basic types (str, int, float, bool, complex) are returned as-is
Return type:: various

Notes

HDF5 should only deal with ASCII characters or Unicode. No binary data is allowed. This function ensures compatibility by converting complex Python objects to appropriate string or array representations.

Lists and dictionaries are converted to JSON strings for storage in HDF5, which can be reconstructed using from_numpy_type.

Validate that the input compression is supported.

Parameters:

compression (str or None) – Type of lossless compression. Options are ‘lzf’, ‘gzip’, ‘szip’, or None.
level (int, str, or None) – Compression level if supported. - int for ‘gzip’ (0-9) - str for ‘szip’ (‘ec-8’, ‘ee-10’, ‘nn-8’, ‘nn-10’) - None for ‘lzf’ or None compression

Returns:

compression (str or None) – Validated compression type
level (int, str, or None) – Validated compression level

Raises:

ValueError – If compression or level are not supported
TypeError – If compression is not a string or None, or if compression level type is incorrect for the specified compression type

mth5.helpers.validate_name(name: str | None, pattern: str | None = None) → str[source]

Validate and clean a name for HDF5 compatibility.

Parameters:

name (str or None) – The name to validate and clean
pattern (str, optional) – Pattern for validation (currently not used but reserved for future use)

Returns:

The cleaned name with spaces replaced by underscores and commas removed. Returns “unknown” if input name is None.

Return type:

str

Notes

This function ensures that names are compatible with HDF5 naming conventions by removing problematic characters. If the input name is None, it returns “unknown” as a default value.

mth5.mth5 module

MTH5

MTH5 deals with reading and writing an MTH5 file, which are HDF5 files developed for magnetotelluric (MT) data. The code is based on h5py and numpy. The main purpose is to provide an object-oriented interface for managing MT data in the HDF5 format.

This module implements the MTH5 class which provides a container for the hierarchical structure of MT data collection:

Version 0.1.0: Survey → Stations → Runs → Channels
Version 0.2.0: Experiment → Surveys → Stations → Runs → Channels

All timeseries data are stored as individual channels with appropriate metadata for electric, magnetic, and auxiliary data.

Created on Sun Dec 9 20:50:41 2018

copyright:: Jared Peacock (jpeacock@usgs.gov)
license:: MIT

Notes

For detailed information about the MTH5 format and metadata standards, see https://github.com/kujaku11/MTarchive/

Examples

Create a new MTH5 file and add a station:

>>> from mth5 import mth5
>>> mth5_obj = mth5.MTH5(file_version='0.2.0')
>>> mth5_obj.open_mth5('test.mth5', 'w')
>>> survey = mth5_obj.add_survey('survey_001')
>>> station = mth5_obj.add_station('MT001', survey='survey_001')

See also

h5py: HDF5 library used for file I/O
mt_metadata: Metadata standards for MT data

class mth5.mth5.MTH5(filename=None, compression='gzip', compression_opts=4, shuffle=True, fletcher32=True, data_level=1, file_version='0.2.0')[source]

Bases: object

MTH5 is the main container for the HDF5 file format developed for MT data

It uses the metadata standards developled by the IRIS PASSCAL software group and defined in the metadata documentation.

MTH5 is built with h5py and therefore numpy. The structure follows the different levels of MT data collection:

For version 0.1.0:

Survey

Reports

Standards

Filters

Stations

Run

Channel

For version 0.2.0:

Experiment

Reports

Standards

Surveys

Reports

Standards

Filters

Stations

Run

-Channel

All timeseries data are stored as individual channels with the appropriate metadata defined for the given channel, i.e. electric, magnetic, auxiliary.

Each level is represented as a mth5 group class object which has methods to add, remove, and get a group from the level below. Each group has a metadata attribute that is the approprate metadata class object. For instance the SurveyGroup has an attribute metadata that is a mth5.metadata.Survey object. Metadata is stored in the HDF5 group attributes as (key, value) pairs.

All groups are represented by their structure tree and can be shown at any time from the command line.

Each level has a summary array of the contents of the levels below to hopefully make searching easier.

Parameters:

filename (string or pathlib.Path) – name of the to be or existing file
compression –
compression type. Supported lossless compressions are
- ’lzf’ - Available with every installation of h5py
  (C source code also available). Low to moderate compression, very fast. No options.
- ’gzip’ - Available with every installation of HDF5,
  so it’s best where portability is required. Good compression, moderate speed. compression_opts sets the compression level and may be an integer from 0 to 9, default is 3.
- ’szip’ - Patent-encumbered filter used in the NASA
  community. Not available with all installations of HDF5 due to legal reasons. Consult the HDF5 docs for filter options.
compression_opts (string or int depending on compression type) – compression options, see above
shuffle (boolean) – Block-oriented compressors like GZIP or LZF work better when presented with runs of similar values. Enabling the shuffle filter rearranges the bytes in the chunk and may improve compression ratio. No significant speed penalty, lossless.
fletcher32 (boolean) – Adds a checksum to each chunk to detect data corruption. Attempts to read corrupted chunks will fail with an error. No significant speed penalty. Obviously shouldn’t be used with lossy compression filters.
data_level (integer, defaults to 1) –
level the data are stored following levels defined by NASA ESDS
- 0 - Raw data
- 1 - Raw data with response information and full metadata
- 2 - Derived product, raw data has been manipulated
file_version (string, optional) – Version of the file [ ‘0.1.0’ | ‘0.2.0’ ], defaults to “0.2.0”

Usage:

Open a new file and show initialized file

>>> from mth5 import mth5
>>> mth5_obj = mth5.MTH5(file_version='0.1.0')
>>> # Have a look at the dataset options
>>> mth5.dataset_options
{'compression': 'gzip',
 'compression_opts': 3,
 'shuffle': True,
 'fletcher32': True}
>>> mth5_obj.open_mth5(r"/home/mtdata/mt01.mth5", 'w')
>>> mth5_obj
/:
====================
    |- Group: Survey
    ----------------
        |- Group: Filters
        -----------------
            --> Dataset: summary
            ......................
        |- Group: Reports
        -----------------
            --> Dataset: summary
            ......................
        |- Group: Standards
        -------------------
            --> Dataset: summary
            ......................
        |- Group: Stations
        ------------------
            --> Dataset: summary
            ......................

Add metadata for survey from a dictionary

>>> survey_dict = {'survey':{'acquired_by': 'me', 'archive_id': 'MTCND'}}
>>> survey = mth5_obj.survey_group
>>> survey.metadata.from_dict(survey_dict)
>>> survey.metadata
{
"survey": {
    "acquired_by.author": "me",
    "acquired_by.comments": null,
    "archive_id": "MTCND"
    ...}
}

Add a station from the convenience function

>>> station = mth5_obj.add_station('MT001')
>>> mth5_obj
/:
====================
    |- Group: Survey
    ----------------
        |- Group: Filters
        -----------------
            --> Dataset: summary
            ......................
        |- Group: Reports
        -----------------
            --> Dataset: summary
            ......................
        |- Group: Standards
        -------------------
            --> Dataset: summary
            ......................
        |- Group: Stations
        ------------------
            |- Group: MT001
            ---------------
                --> Dataset: summary
                ......................
            --> Dataset: summary
            ......................
>>> station
/Survey/Stations/MT001:
====================
    --> Dataset: summary
    ......................

>>> data.schedule_01.ex[0:10] = np.nan
>>> data.calibration_hx[...] = np.logspace(-4, 4, 20)

Note

if replacing an entire array with a new one you need to use […] otherwise the data will not be updated.

Warning

You can only replace entire arrays with arrays of the same size. Otherwise you need to delete the existing data and make a new dataset.

add_channel(station_name: str, run_name: str, channel_name: str, channel_type: str, data, channel_dtype: str = 'int32', max_shape: tuple[int | None, ...] = (None,), chunks: bool = True, channel_metadata=None, survey: str | None = None) → ElectricDataset | MagneticDataset | AuxiliaryDataset[source]

Add a channel to a given run and station.

Parameters:

station_name (str) – Existing station name.
run_name (str) – Existing run name.
channel_name (str) – Name of the channel (component, e.g., ‘Ex’, ‘Hy’).
channel_type (str) – Type of channel: ‘electric’, ‘magnetic’, or ‘auxiliary’.
data (ndarray) – Channel data array.
channel_dtype (str, default 'int32') – NumPy data type for storage.
max_shape (tuple[int | None, ...], default (None,)) – Maximum shape (allows resizing). None allows unlimited growth.
chunks (bool, default True) – Enable HDF5 chunking for better performance.
channel_metadata (mt_metadata.timeseries.Electric | Magnetic | Auxiliary, optional) – Channel metadata container. Default is None.
survey (str, optional) – Survey ID. Required for file version 0.2.0. Default is None.

Returns:

The added channel dataset object.

Return type:

groups.ElectricDataset | groups.MagneticDataset | groups.AuxiliaryDataset

Raises:

MTH5Error – If channel type is not valid.

Examples

Add an electric field channel:

>>> import numpy as np
>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'w')
>>> data = np.random.random(1000)
>>> ch = mth5_obj.add_channel('MT001', 'MT001a', 'Ex', 'electric',
...                            data, survey='survey_001')

See also

get_channel: Retrieve existing channel
remove_channel: Delete a channel

add_run(station_name: str, run_name: str, run_metadata=None, survey: str | None = None) → RunGroup[source]

Add a run to a given station.

Parameters:

station_name (str) – Existing station name.
run_name (str) – Name of the run (typically archive_id followed by a-z).
run_metadata (mt_metadata.timeseries.Run, optional) – Run metadata container. Default is None.
survey (str, optional) – Survey ID. Required for file version 0.2.0. Default is None.

Returns:

The added or existing run group object.

Return type:

groups.RunGroup

Examples

Add a run to a station:

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'w')
>>> run = mth5_obj.add_run('MT001', 'MT001a', survey='survey_001')

See also

get_run: Retrieve existing run
remove_run: Delete a run

add_station(station_name: str, station_metadata=None, survey: str | None = None) → StationGroup[source]

Convenience function to add a station.

Adds a new station with optional metadata. For v0.2.0 files, a survey must be specified.

Parameters:

station_name (str) – Name of the station (should match metadata.archive_id).
station_metadata (mt_metadata.timeseries.Station, optional) – Station metadata container. Default is None.
survey (str, optional) – Survey ID. Required for file version 0.2.0. Default is None.

Returns:

The added or existing station group object.

Return type:

groups.StationGroup

Raises:

ValueError – If survey is required (v0.2.0) but not provided.

Examples

Add a station to v0.2.0 file:

>>> mth5_obj = MTH5(file_version='0.2.0')
>>> mth5_obj.open_mth5('test.mth5', 'w')
>>> station = mth5_obj.add_station('MT001', survey='survey_001')

See also

get_station: Retrieve existing station
remove_station: Delete a station

add_survey(survey_name, survey_metadata=None)[source]

Add a survey with metadata if given with the path:: /Experiment/Surveys/survey_name

If the survey already exists, will return that survey and nothing is added.

Parameters:

survey_name (string) – Name of the survey, should be the same as metadata.id
survey_metadata (mth5.metadata.survey, optional) – survey metadata container, defaults to None

Returns:

A convenience class for the added survey

Return type:

mth5_groups.SurveyGroup

Example:

>>> from mth5 import mth5
>>> mth5_obj = mth5.MTH5()
>>> mth5_obj.open_mth5(r"/test.mth5", mode='a')
>>> # one option
>>> new_survey = mth5_obj.add_survey('MT001')
>>> # another option
>>> new_station = mth5_obj.experiment_group.surveys_group.add_survey('MT001')

add_transfer_function(tf_object, update_metadata=True)[source]: Add a transfer function :param tf_object: DESCRIPTION :type tf_object: TYPE :return: DESCRIPTION :rtype: TYPE

property channel_summary: ChannelSummaryTable[source]

Get channel summary table.

Returns:: Summary of all channels in the file with metadata.
Return type:: ChannelSummaryTable

Examples

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'r')
>>> summary = mth5_obj.channel_summary

close_mth5() → None[source]

Close MTH5 file.

Flushes all data to disk, updates summary tables, and closes the file. Safe to call on already-closed files.

Examples

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'w')
>>> mth5_obj.close_mth5()

Notes

Can be called automatically using context manager:

>>> with MTH5().open_mth5('test.mth5', 'w') as m:
...     # do work
...     pass  # file closed automatically

property data_level[source]: data level

property dataset_options: dict[str, str | int | bool][source]

Get HDF5 dataset compression and storage options.

Returns:: Dictionary containing compression, compression_opts, shuffle, and fletcher32.
Return type:: dict[str, str | int | bool]

Examples

>>> mth5_obj = MTH5()
>>> opts = mth5_obj.dataset_options
>>> print(opts['compression'])
'gzip'

property experiment_group[source]: Convenience property for /Experiment group

property fc_summary: FCSummaryTable[source]

Get Fourier coefficient summary table.

Returns:: Summary of all Fourier coefficients in the file.
Return type:: FCSummaryTable

property file_attributes[source]

property file_type[source]: File Type should be MTH5

property file_version[source]: mth5 file version

property filename[source]: file name of the hdf5 file

property filters_group[source]: Convenience property for /Survey/Filters group

from_experiment(experiment, survey_index=0, update=False)[source]

Fill out an MTH5 from a mt_metadata.timeseries.Experiment object given a survey_id

Parameters:

experiment (mt_metadata.timeseries.Experiment) – Experiment metadata
survey_index (int, defaults to 0) – Index of the survey to write

from_reference(h5_reference)[source]

Get an HDF5 group, dataset, etc from a reference

Parameters:: h5_reference (TYPE) – DESCRIPTION
Returns:: DESCRIPTION
Return type:: TYPE

get_channel(station_name, run_name, channel_name, survey=None)[source]

Convenience function to get a channel using mth5.stations_group.get_station().get_run().get_channel()

Get a channel from an existing name. Returns the appropriate container.

Parameters:

station_name (string) – existing station name
run_name (string) – existing run name
channel_name (string) – name of the channel
survey (string) – existing survey name, needed for file version >= 0.2.0

Returns:

Channel container

Return type:

[ mth5.mth5_groups.ElectricDatset | mth5.mth5_groups.MagneticDatset | mth5.mth5_groups.AuxiliaryDatset ]

Raises:

MTH5Error – If no channel is found

Example:

>>> existing_channel = mth5_obj.get_channel(station_name,
>>> ...                                     run_name,
>>> ...                                     channel_name)
>>> existing_channel
Channel Electric:
-------------------
                component:        Ex
        data type:        electric
        data format:      float32
        data shape:       (4096,)
        start:            1980-01-01T00:00:00+00:00
        end:              1980-01-01T00:00:01+00:00
        sample rate:      4096

get_reference_path(h5_reference)[source]

Get the HDF5 path from a reference

Parameters:: h5_reference (TYPE) – DESCRIPTION
Returns:: DESCRIPTION
Return type:: TYPE

get_run(station_name, run_name, survey=None)[source]

Convenience function to get a run using mth5.stations_group.get_station(station_name).get_run()

get a run from run name for a given station

Parameters:

station_name (string) – existing station name
run_name (string) – existing run name
survey (string) – existing survey name, needed for file version >= 0.2.0

Returns:

Run object

Return type:

mth5.mth5_groups.RunGroup

Example:

>>> existing_run = mth5_obj.get_run('MT001', 'MT001a')

get_station(station_name: str, survey: str | None = None) → StationGroup[source]

Get an existing station from the MTH5 file.

Parameters:

station_name (str) – Name of the station to retrieve.
survey (str, optional) – Survey ID. Required for file version 0.2.0. Default is None.

Returns:

The requested station group object.

Return type:

groups.StationGroup

Raises:

MTH5Error – If the station cannot be found.

Examples

Get a station:

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'r')
>>> station = mth5_obj.get_station('MT001', survey='survey_001')

See also

add_station: Create a new station
remove_station: Delete a station

get_survey(survey_name)[source]

Get a survey with the same name as survey_name

Parameters:: survey_name (string) – existing survey name
Returns:: convenience survey class
Return type:: mth5.mth5_groups.surveyGroup
Raises:: MTH5Error – if the survey name is not found.
Example:

>>> from mth5 import mth5
>>> mth5_obj = mth5.MTH5()
>>> mth5_obj.open_mth5(r"/test.mth5", mode='a')
>>> # one option
>>> existing_survey = mth5_obj.get_survey('MT001')
>>> # another option
>>> existing_staiton = mth5_obj.experiment_group.surveys_group.get_survey('MT001')
MTH5Error: MT001 does not exist, check groups_list for existing names

get_transfer_function(station_id, tf_id, survey=None)[source]

Get a transfer function

Parameters:

survey_id (TYPE) – DESCRIPTION
station_id (TYPE) – DESCRIPTION
tf_id (TYPE) – DESCRIPTION

Returns:

DESCRIPTION

Return type:

TYPE

h5_is_read() → bool[source]

Check if HDF5 file is open and readable.

Returns:: True if file is open and readable, False otherwise.
Return type:: bool

Examples

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'r')
>>> mth5_obj.h5_is_read()
True

h5_is_write() → bool[source]

Check if HDF5 file is open in write mode.

Returns:: True if file is open and writable, False otherwise.
Return type:: bool

Examples

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'w')
>>> mth5_obj.h5_is_write()
True

has_group(group_name)[source]: Check to see if the group name exists

open_mth5(filename: str | Path | None = None, mode: str = 'a', **kwargs) → MTH5[source]

Open an MTH5 file.

Opens an existing MTH5 file or creates a new one. Validates file structure and initializes summary datasets if needed.

Parameters:

filename (str | Path, optional) – Path to MTH5 file. If None, uses stored filename.
mode (str, default 'a') –
File opening mode:
- ’r’ : Read-only
- ’a’ : Read/write, create if doesn’t exist
- ’w’ : Write, overwrite if exists
- ’x’ : Write, fail if exists
- ’w-’ : Write, fail if exists (same as ‘x’)
- ’r+’ : Read/write, file must exist
**kwargs – Additional arguments passed to h5py.File()

Returns:

Returns self for method chaining.

Return type:

MTH5

Raises:

MTH5Error – If file is invalid or mode is not understood.

Examples

Open an existing file for reading:

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('data.mth5', 'r')

Create a new file:

>>> mth5_obj = MTH5(file_version='0.2.0')
>>> mth5_obj.open_mth5('new_file.mth5', 'w')

See also

close_mth5: Close the MTH5 file

remove_channel(station_name, run_name, channel_name, survey=None)[source]

Convenience function to remove a channel using mth5.stations_group.get_station().get_run().remove_channel()

Remove a channel from a given run and station.

Note

Deleting a channel is not as simple as del(channel). In HDF5 this does not free up memory, it simply removes the reference to that channel. The common way to get around this is to copy what you want into a new file, or overwrite the channel.

Parameters:

station_name (string) – existing station name
run_name (string) – existing run name
channel_name (string) – existing station name
survey (string) – existing survey name, needed for file version >= 0.2.0

Example:

>>> mth5_obj.remove_channel('MT001', 'MT001a', 'Ex')

remove_run(station_name, run_name, survey=None)[source]

Remove a run from the station.

Note

Deleting a run is not as simple as del(run). In HDF5 this does not free up memory, it simply removes the reference to that station. The common way to get around this is to copy what you want into a new file, or overwrite the run.

Parameters:

station_name (string) – existing station name
run_name (string) – existing run name
survey (string) – existing survey name, needed for file version >= 0.2.0

Example:

>>> mth5_obj.remove_station('MT001', 'MT001a')

remove_station(station_name, survey=None)[source]

Convenience function to remove a station using

Remove a station from the file.

Note

Deleting a station is not as simple as del(station). In HDF5 this does not free up memory, it simply removes the reference to that station. The common way to get around this is to copy what you want into a new file, or overwrite the station.

Parameters:

station_name (string) – existing station name
survey (string) – existing survey name, needed for file version >= 0.2.0

Example:

>>> mth5_obj.remove_station('MT001')

remove_survey(survey_name)[source]

Remove a survey from the file.

Note

Deleting a survey is not as simple as del(survey). In HDF5 this does not free up memory, it simply removes the reference to that survey. The common way to get around this is to copy what you want into a new file, or overwrite the survey.

Parameters:

survey_name (string) – existing survey name

Example:

>>> from mth5 import mth5
>>> mth5_obj = mth5.MTH5()
>>> mth5_obj.open_mth5(r"/test.mth5", mode='a')
>>> # one option
>>> mth5_obj.remove_survey('MT001')
>>> # another option
>>> mth5_obj.experiment_group.surveys_group.remove_survey('MT001')

remove_transfer_function(station_id, tf_id, survey=None)[source]

remove a transfer function

Parameters:

survey_id (TYPE) – DESCRIPTION
station_id (TYPE) – DESCRIPTION
tf_id (TYPE) – DESCRIPTION

Returns:

DESCRIPTION

Return type:

TYPE

property reports_group[source]: Convenience property for /Survey/Reports group

property run_summary[source]

Get run summary with MTH5 file path.

Returns:: Summary of runs with mth5_path column added.
Return type:: pandas.DataFrame

property software_name[source]: software name that wrote the file

property standards_group[source]: Convenience property for /Standards group

property station_list[source]: list of existing stations names

property stations_group[source]: Convenience property for /Survey/Stations group

property survey_group[source]: Convenience property for /Survey group

property surveys_group[source]: Convenience property for /Surveys group

property tf_summary: TFSummaryTable[source]

Get transfer function summary table.

Returns:: Summary of all transfer functions in the file.
Return type:: TFSummaryTable

to_experiment(has_data=True)[source]

Create an mt_metadata.timeseries.Experiment object from the metadata contained in the MTH5 file.

Returns:: mt_metadata.timeseries.Experiment

validate_file() → bool[source]

Validate an open MTH5 file.

Checks file attributes, version, data level, and group structure for compliance with MTH5 format specifications.

Returns:: True if file is valid, False otherwise.
Return type:: bool

Examples

>>> mth5_obj = MTH5()
>>> mth5_obj.open_mth5('test.mth5', 'r')
>>> is_valid = mth5_obj.validate_file()

Module contents

Top-level package for MTH5.