mt_metadata.transfer_functions.core

Exceptions

TFError

Common base class for all non-exit exceptions.

Classes

`TF`	Generic container to hold information about an electromagnetic

Module Contents

class mt_metadata.transfer_functions.core.TF(fn=None, **kwargs)

Generic container to hold information about an electromagnetic transfer funtion

The thought here is to have a central container TF.dataset which is an xarray.Dataset that contains the impedance, tipper, errors and covariance values. There are helper functions to get and set these from the TF.dataset. Cause most of the time the user will want just the impedance or the tipper and associated errors. We are accommodating EMTF style covariances to accurately rotated data errors.

When reading and writing edi files this information will be lost.

property channel_nomenclature: dict

Channel nomenclature dictionary keyed by channel names.

For example:

{‘ex’: ‘ex’, ‘ey’: ‘ey’, ‘hx’: ‘hx’, ‘hy’: ‘hy’, ‘hz’: ‘hz’}

save_dir

property fn: pathlib.Path

reference to original data file

property inverse_channel_nomenclature: dict[str, str]

copy()

Create a deep copy of the current object.

Returns:: A deep copy of the current object.
Return type:: Self

property survey_metadata: mt_metadata.timeseries.Survey

Survey metadata.

property station_metadata: mt_metadata.transfer_functions.tf.Station

Station metadata from survey_metadata.stations[0]

property run_metadata: mt_metadata.timeseries.Run

Run metadata from survey_metadata.stations[0].runs[0]

property index_zxx: dict

property index_zxy: dict

property index_zyx: dict

property index_zyy: dict

property index_tzx: dict

property index_tzy: dict

property latitude: float

Latitude

property longitude: float

Longitude

property elevation: float

Elevation

property dataset: xarray.Dataset

This will return an xarray dataset with proper metadata

Returns:: The xarray dataset with metadata.
Return type:: xr.Dataset

has_transfer_function()

Check to see if the transfer function is not 0 and has transfer function components

Returns:: True if the transfer function is not 0 and has components, False otherwise.
Return type:: bool

property transfer_function: xarray.DataArray | None

returns: The transfer function data array or None if not set. :rtype: xr.DataArray | None

property transfer_function_error: xarray.DataArray | None

returns: The transfer function error data array or None if not set. :rtype: xr.DataArray | None

property transfer_function_model_error: xarray.DataArray | None

returns: The transfer function model error data array or None if not set. :rtype: xr.DataArray | None

has_impedance()

Check to see if the transfer function is not 0 and has transfer function components

Returns:: True if the transfer function has impedance components, False otherwise.
Return type:: bool

property impedance: xarray.DataArray | None

returns: The impedance data array or None if not set. :rtype: xr.DataArray | None

property impedance_error: xarray.DataArray | None

returns: The impedance error data array or None if not set. :rtype: xr.DataArray | None

property impedance_model_error: xarray.DataArray | None

returns: The impedance model error data array or None if not set. :rtype: xr.DataArray | None

has_tipper()

Check to see if the transfer function is not 0 and has transfer function components

Returns:: True if the transfer function has tipper components, False otherwise.
Return type:: bool

property tipper: xarray.DataArray | None

returns: The tipper data array or None if not set. :rtype: xr.DataArray | None

property tipper_error: xarray.DataArray | None

returns: The tipper error data array or None if not set. :rtype: xr.DataArray | None

property tipper_model_error: xarray.DataArray | None

returns: The tipper model error data array or None if not set. :rtype: xr.DataArray | None

has_inverse_signal_power()

Check to see if the transfer function is not 0 and has transfer function components

Returns:: True if the inverse signal power is set and not zero, False otherwise.
Return type:: bool

property inverse_signal_power: xarray.DataArray | None

Get the inverse signal power data array.

Returns:: The inverse signal power data array or None if not set.
Return type:: xr.DataArray | None

has_residual_covariance()

Check to see if the transfer function is not 0 and has transfer function components

Returns:: True if the residual covariance is set and not zero, False otherwise.
Return type:: bool

property residual_covariance: xarray.DataArray | None

Get the residual covariance data array.

Returns:: The residual covariance data array or None if not set.
Return type:: xr.DataArray | None

property period: numpy.ndarray | None

Periods of the transfer function

property frequency: numpy.ndarray | None

property station: str

station name

property survey: str

Survey ID

property tf_id: str

transfer function id

to_ts_station_metadata()

need a convinience function to translate to ts station metadata for MTH5

from_ts_station_metadata(ts_station_metadata)

need a convinience function to translate to ts station metadata for MTH5

merge(other, period_min=None, period_max=None, inplace=False)

metadata will be assumed to be from self.

Merge transfer functions together. other can be another TF object or a tuple of TF objects

to set bounds should be of the format

[{“tf”: tf_01, “period_min”: .01, “period_max”: 100},: {“tf”: tf_02, “period_min”: 100, “period_max”: 1000}]

or to just use whats in the transfer function [tf_01, tf_02, …]

The bounds are inclusive, so if you want to merge at say 1 s choose the best one and set the other to a value lower or higher depending on the periods for that transfer function, for example

[{“tf”: tf_01, “period_min”: .01, “period_max”: 100},: {“tf”: tf_02, “period_min”: 100.1, “period_max”: 1000}]

Parameters:

other (TF, list of dicts, list of TF objects, dict) – other transfer functions to merge with
period_min (float) – minimum period for the original TF
period_max (float) – maximum period for the original TF
inplace (bool) – whether to modify the original TF or return a new one

Returns:

merged transfer function or None if inplace=True

Return type:

TF | None

write(fn=None, save_dir=None, fn_basename=None, file_type='edi', **kwargs)

Write an mt file, the supported file types are EDI and XML.

Parameters:

fn (str | Path | None) – Full path to file to save to.
save_dir (str | Path | None) – Full path save directory.
fn_basename (str | None) – Name of file with or without extension.
file_type (Literal["edi", "xml", "zmm", "avg", "j"]) – Type of file to write.
Arguments (Optional Keyword)
---------------------------
longitude_format (string) – whether to write longitude as longitude or LONG. options are ‘longitude’ or ‘LONG’, default ‘longitude’
longitude_format
latlon_format (format of latitude and longitude in output edi,) – degrees minutes seconds (‘dms’) or decimal degrees (‘dd’)

Returns:

str – Full path to the written file.
Example: :: – >>> tf_obj.write(file_type=’xml’)

write_tf_file(**kwargs)

read_tf_file(**kwargs)

read(fn=None, file_type=None, get_elevation=False, **kwargs)

Read an TF response file.

Note

Currently only .edi, .xml, .j, .zmm/rr/ss, .avg files are supported

Parameters:

fn (str | Path | None) – Full path to input file.
file_type (str | None) – Type of file to read. If None, automatically detects file type by the extension. Options are [edi | j | xml | avg | zmm | zrr | zss | …]
get_elevation (bool) – Whether to get elevation from US National Map DEM

:param>>> import mt_metadata.transfer_functions import TF

>>> tf_obj = TF()
>>> tf_obj.read(fn=r"/home/mt/mt01.xml")

:type : Example: :: :param .. note:: If your internet is slow try setting ‘get_elevation’ = False: It can get hooked in a slow loop and slow down reading. :param : It can get hooked in a slow loop and slow down reading.

to_edi()

Convert the TF object to a mt_metadata.transfer_functions.io.edi.EDI object. From there attributes of an EDI object can be manipulated previous to writing to a file.

Return type:: EDI object

>>> from mt_metadata.transfer_functions import TF
>>> from mt_metadata import TF_XML
>>> t = TF(TF_XML)
>>> t.read()
>>> edi_object = t.to_edi()
>>> edi_object.Header.acqby = "me"
>>> edi_object.write()

from_edi(edi_obj, get_elevation=False, **kwargs)

Read in an EDI file or a mt_metadata.transfer_functions.io.edi.EDI object

Parameters:

edi_obj (str | Path | EDI) – Path to EDI file or EDI object If a path is provided, the file will be read from disk. If an EDI object is provided, it will be used directly.
get_elevation (bool) – Try to get elevation from US National Map, defaults to False

Raises:

TypeError – If input is incorrect

to_emtfxml()

Convert TF to a mt_metadata.transfer_function.io.emtfxml.EMTFXML object.

Returns:

return: EMTFXML object
rtype: mt_metadata.transfer_function.io.emtfxml.EMTFXML
>>> from mt_metadata.transfer_functions import TF
>>> from mt_metadata import TF_XML
>>> t = TF(TF_XML)
>>> t.read()
>>> xml_object = t.to_emtfxml()
>>> xml_object.site.country = “Here”
>>> xml_object.write()

Return type:

mt_metadata.transfer_functions.io.EMTFXML

from_emtfxml(emtfxml_obj, get_elevation=False, **kwargs)

Parameters:

emtfxml_obj (str | Path | EMTFXML) – The input object to convert from.
get_elevation (bool) – Try to get elevation from US National Map, defaults to True.

Return type:

None

abstractmethod to_jfile()

Translate TF object ot JFile object.

Note

Not Implemented yet

Returns:: JFile object
Return type:: mt_metadata.transfer_functions.io.jfile.JFile

from_jfile(j_obj, get_elevation=False, **kwargs)

Parameters:

jfile_obj (str | Path | JFile) – The input object to convert from.
get_elevation (bool) – Try to get elevation from US National Map, defaults to True.

Return type:

None

make_zmm_run(zmm_obj, number_dict)

Helper function to provide a run for a zmm object to aid writing z-file

Parameters:

zmm_obj (ZMM) – A ZMM that will be written to file, that needs a run associated.
number_dict (dict) – Mapping between hexy keys and integers, needed for emtf z-files, e.g. {“hx”: 1, “hy”: 2, “hz”: 3, “ex”: 4, “ey”: 5}

:param : :type : type number_dict: dictionary :param : :type : return: run :param : :type : rtype: :class:` mt_metadata.timeseries.run.Run`

to_zmm()

Translate TF object to ZMM object.

Returns:: ZMM object
Return type:: mt_metadata.transfer_function.io.zfiles.ZMM

>>> from mt_metadata.transfer_functions import TF
>>> from mt_metadata import TF_XML
>>> t = TF(TF_XML)
>>> t.read()
>>> zmm_object = t.to_zmm()
>>> zmm_object.processing_type = "new and fancy"
>>> zmm_object.write()

from_zmm(zmm_obj, get_elevation=False, **kwargs)

Parameters:

zmm_obj (str | Path | ZMM) – Path to .zmm file or ZMM object
get_elevation (bool) – Try to get elevation from US National Map, defaults to True
kwargs (dict) –
Keyword arguments for ZMM object Can include channel_nomenclature, inverse_channel_nomenclature rotate_to_measurement_coordinates : bool, optional

If True, rotate impedance to the provided reference frame of the channel metadata, by default True

use_declinationbool, optional
If True, rotate impedance to true north using declination value in metadata, by default False

to_zrr()

Translate TF object to ZMM object.

Returns:: ZMM object
Return type:: mt_metadata.transfer_function.io.zfiles.ZMM

>>> from mt_metadata.transfer_functions import TF
>>> from mt_metadata import TF_XML
>>> t = TF(TF_XML)
>>> t.read()
>>> zmm_object = t.to_zmm()
>>> zmm_object.processing_type = "new and fancy"
>>> zmm_object.write()

from_zrr(zrr_obj, get_elevation=False, **kwargs)

Parameters:

zmm_obj (str | Path | ZMM) – Path to .zmm file or ZMM object
get_elevation (bool) – Try to get elevation from US National Map, defaults to True
kwargs (dict) – Keyword arguments for ZMM object

to_zss()

Translate TF object to ZMM object.

Returns:: ZMM object
Return type:: mt_metadata.transfer_function.io.zfiles.ZMM

>>> from mt_metadata.transfer_functions import TF
>>> from mt_metadata import TF_XML
>>> t = TF(TF_XML)
>>> t.read()
>>> zmm_object = t.to_zmm()
>>> zmm_object.processing_type = "new and fancy"
>>> zmm_object.write()

from_zss(zss_obj, get_elevation=False, **kwargs)

Parameters:

zss_obj (str | Path | ZMM) – Path to .zss file or ZMM object
get_elevation (bool) – Try to get elevation from US National Map, defaults to True

to_avg()

Translate TF object to ZongeMTAvg object.

Note

Not Implemented yet

Returns:: ZongeMTAvg object
Return type:: mt_metadata.transfer_function.io.zonge.ZongeMTAvg

from_avg(avg_obj, get_elevation=False, **kwargs)

Parameters:

avg_obj (str | Path | ZongeMTAvg) – Path to .avg file or ZongeMTAvg object
get_elevation (bool) – Try to get elevation from US National Map, defaults to True

exception mt_metadata.transfer_functions.core.TFError

Bases: Exception

Common base class for all non-exit exceptions.