Transfer Function

Plot

Regression

Base

follows Gary’s TTF.m in iris_mt_scratch egbert_codes-20210121T193218Z-001/egbert_codes/matlabPrototype_10-13-20/TF/classes

class aurora.transfer_function.base.TransferFunction(decimation_level_id, frequency_bands, **kwargs)[source]

Bases: Base

Class to contain transfer function array.

Parameters:
  • TF (numpy array) – array of transfer functions: TF(Nout, Nin, Nperiods)

  • T (numpy array) – list of periods

  • cov_ss_inv (numpy array) – inverse signal power matrix. aka Cov_SS in EMTF matlab codes

  • cov_nn (numpy array) – noise covariance matrix: aka Cov_NN in EMTF matlab codes

  • num_segments (integer array?) – Number of samples used to estimate TF for each band, and for each output channel (might be different for different channels)

  • R2 (xarray.DataArray) – multiple coherence for each output channel / band

  • FullCov (boolean) – true if full covariance is provided

Returns:

  • properties (Dependent)

  • StdErr % standard errors of TF components, same size and order as TF

  • NBands

  • freqs % inverse of period

  • Nout

  • Nin

Attributes:
changed
emtf_tf_header
maximum_period
minimum_period
num_bands

_summary_

num_channels_in
num_channels_out
periods
tf
tf_header

Methods

add_base_attribute(name, value, value_dict)

Add an attribute to _attr_dict so it will be included in the output dictionary

attribute_information([name])

return a descriptive string of the attribute if none returns for all

copy()

Copy object

from_dict(meta_dict[, skip_none])

fill attributes from a dictionary

from_json(json_str)

read in a json string and update attributes of an object

from_series(pd_series)

Fill attributes from a Pandas series

from_xml(xml_element)

param xml_element:

XML element

get_attr_from_name(name)

Access attribute from the given name.

get_attribute_list()

return a list of the attributes

set_attr_from_name(name, value)

Helper function to set attribute from the given name.

set_tf(regression_estimator, period)

This sets TF elements for one band, using contents of regression_estimator object.

to_dict([nested, single, required])

make a dictionary from attributes, makes dictionary from _attr_list.

to_json([nested, indent, required])

Write a json string from a given object, taking into account other class objects contained within the given object.

to_series([required])

Convert attribute list to a pandas.Series

to_xml([string, required])

make an xml element for the attribute that will add types and units.

update(other[, match])

Update attribute values from another like element, skipping None

frequency_index

period_index

tf_to_df

property emtf_tf_header
frequency_index(frequency)[source]
property maximum_period
property minimum_period
property num_bands

_summary_

Returns:

num_bands – a count of the frequency bands associated with the TF

Return type:

int

property num_channels_in
property num_channels_out
period_index(period)[source]
property periods
set_tf(regression_estimator, period)[source]

This sets TF elements for one band, using contents of regression_estimator object. This version assumes there are estimates for Nout output channels

property tf
property tf_header
tf_to_df()[source]

EMTF Z File Helpers

These methods can possibly be moved under mt_metadata, or mth5

They extract info needed to setup emtf_z files.

aurora.transfer_function.emtf_z_file_helpers.clip_bands_from_z_file(z_path, n_bands_clip, output_z_path=None, n_sensors=5)[source]

This function takes a z_file and clips periods off the end of it. It can come in handy sometimes – specifically for manipulating matlab results of synthetic data.

Parameters:
  • z_path (Path or str) – path to the z_file to read in and clip periods from

  • n_periods_clip (integer) – how many periods to clip from the end of the zfile

  • overwrite (bool) – whether to overwrite the zfile or rename it

  • n_sensors

aurora.transfer_function.emtf_z_file_helpers.get_default_orientation_block(n_ch=5)[source]

Helper function used when working with matlab structs which do not have enough info to make headers

Parameters:

n_ch (int) – number of channels at the station

Returns:

orientation_strs – List of text strings, one per channel

Return type:

list

aurora.transfer_function.emtf_z_file_helpers.merge_tf_collection_to_match_z_file(aux_data, tf_collection)[source]

Currently this is only used for the synthtetic test, but maybe useful for other tests. Given data from a z_file, and a tf_collection, the tf_collection may have several TF estimates at the same frequency from multiple decimation levels. This tries to make a single array as a function of period for all rho and phi

Parameters:
  • aux_data (merge_tf_collection_to_match_z_file) – Object representing a z-file

  • tf_collection (aurora.transfer_function.transfer_function_collection) –

  • .TransferFunctionCollection – Object representing the transfer function returnd from the aurora processing

Returns:

result – Keyed by [“rho”, “phi”], below each of these is an [“xy”, “yx”,] entry. The lowest level entries are numpy arrays.

Return type:

dict of dicts

Iter Control

follows Gary’s IterControl.m in iris_mt_scratch/egbert_codes-20210121T193218Z-001/egbert_codes/matlabPrototype_10-13-20/TF/classes

class aurora.transfer_function.regression.iter_control.IterControl(max_number_of_iterations=10, max_number_of_redescending_iterations=2, **kwargs)[source]

Bases: object

Attributes:
continue_redescending
correction_factor

TODO: This is an RME specific property.

Methods

converged(b, b0)

param b:

the most recent regression estimate

property continue_redescending
converged(b, b0)[source]
Parameters:
  • b (complex-valued numpy array) – the most recent regression estimate

  • b0 (complex-valued numpy array) – The previous regression estimate

Returns:

  • converged (bool) – True of the regression has terminated, False otherwise

  • Notes

  • The variable maximum_change finds the maximum amplitude component of the vector

  • 1-b/b0. Looking at the formula, one might want to cast this instead as

  • 1 - abs(b/b0), however, that will be insensitive to phase changes in b,

  • which is complex valued. The way it is coded np.max(np.abs(1 - b / b0)) is

  • correct as it stands.

property correction_factor

This is an RME specific property. Suggest move r0, u0 and this method into an RME-config class.

See notes on usage in transfer_function.regression.helper_functions.rme_beta

Returns:

correction_factor – correction factor used for scaling the residual error_variance

Return type:

float

Type:

TODO

Transfer Function Collection

This is a container to hold: 1. TransferFunctionHeader 2. Dictionary of TransferFunction Objects

Note that a single transfer function object is associated with a station, which we call the “local_station”. In a database of TFs we could add a column for local_station and one for reference station.

class aurora.transfer_function.transfer_function_collection.TransferFunctionCollection(**kwargs)[source]

Bases: object

Attributes:
channel_list
header
local_station_id
number_of_decimation_levels
remote_station_id
total_number_of_channels
total_number_of_frequencies

Methods

check_all_channels_present(channel_nomenclature)

param channel_nomenclature:

Scheme according to how channels are named

rho_phi_plot([show, aux_data, xy_or_yx, ...])

One-off plotting method intended only for the synthetic test data for aurora dev :param show: :param aux_data: :param xy_or_yx: :param ttl_str:

get_merged_dict

property channel_list
check_all_channels_present(channel_nomenclature)[source]
Parameters:

channel_nomenclature (mt_metadata.transfer_functions.processing.aurora.channel_nomenclature.ChannelNomenclature) – Scheme according to how channels are named

get_merged_dict(channel_nomenclature)[source]
property header
property local_station_id
property number_of_decimation_levels
property remote_station_id
rho_phi_plot(show=True, aux_data=None, xy_or_yx='xy', ttl_str='', x_axis_fontsize=25, y_axis_fontsize=25, ttl_fontsize=16, markersize=10, rho_ylims=[10, 1000], phi_ylims=[0, 90], figures_path=PosixPath('/home/runner/work/aurora/aurora/data/figures'), **kwargs)[source]

One-off plotting method intended only for the synthetic test data for aurora dev :param show: :param aux_data: :param xy_or_yx: :param ttl_str:

property total_number_of_channels
property total_number_of_frequencies

TTFZ

follows Gary’s TTFZ.m in iris_mt_scratch/egbert_codes-20210121T193218Z-001/egbert_codes/matlabPrototype_10-13-20/TF/classes

class aurora.transfer_function.TTFZ.TTFZ(*args, **kwargs)[source]

Bases: TransferFunction

subclass to support some more MT impedance specficic functions – initially just apparent resistivity and pbase for diagonal elements + rotation/fixed coordinate system

properties rho rho_se phi phi_se

Attributes:
changed
emtf_tf_header
maximum_period
minimum_period
num_bands

_summary_

num_channels_in
num_channels_out
periods
tf
tf_header

Methods

add_base_attribute(name, value, value_dict)

Add an attribute to _attr_dict so it will be included in the output dictionary

apparent_resistivity(...), phase, errors, ...)

param units:

one of ["MT","SI"]

attribute_information([name])

return a descriptive string of the attribute if none returns for all

copy()

Copy object

from_dict(meta_dict[, skip_none])

fill attributes from a dictionary

from_json(json_str)

read in a json string and update attributes of an object

from_series(pd_series)

Fill attributes from a Pandas series

from_xml(xml_element)

param xml_element:

XML element

get_attr_from_name(name)

Access attribute from the given name.

get_attribute_list()

return a list of the attributes

set_attr_from_name(name, value)

Helper function to set attribute from the given name.

set_tf(regression_estimator, period)

This sets TF elements for one band, using contents of regression_estimator object.

standard_error()

returns:

standard_error

to_dict([nested, single, required])

make a dictionary from attributes, makes dictionary from _attr_list.

to_json([nested, indent, required])

Write a json string from a given object, taking into account other class objects contained within the given object.

to_series([required])

Convert attribute list to a pandas.Series

to_xml([string, required])

make an xml element for the attribute that will add types and units.

update(other[, match])

Update attribute values from another like element, skipping None

frequency_index

period_index

tf_to_df

apparent_resistivity(...) : computes app. res., phase, errors, given imped., cov. %USAGE: [rho, rho_se, ph, ph_se] = ap_res(z, sig_s, sig_e, periods) ; % Z = array of impedances (from Z_***** file) % sig_s = inverse signal covariance matrix (from Z_****** file) % sig_e = residual covariance matrix (from Z_****** file) % periods = array of periods (sec)[source]
Parameters:
  • units (str) – one of [“MT”,”SI”]

  • channel_nomenclature

  • mt_metadata.transfer_functions.processing.aurora.channel_nomenclature.ChannelNomenclature – has a dict that you

standard_error()[source]
Returns:

standard_error

Return type:

xr.DataArray