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)

Bases: Base

Class to contain transfer function array.

Parameters: TF : numpy array

array of transfer functions: TF(Nout, Nin, Nperiods)

Tnumpy array

list of periods

Headertransfer_function_header.TransferFunctionHeader object.

TF header contains local site header, remote site header if appropriate, and information about estimation approach???

cov_ss_invnumpy array

inverse signal power matrix. aka Cov_SS in EMTF matlab codes

cov_nnnumpy array

noise covariance matrix: aka Cov_NN in EMTF matlab codes

num_segmentsinteger array?

Number of samples used to estimate TF for each band, and for each output channel (might be different for different channels)

R2xarray.DataArray

multiple coherence for each output channel / band

FullCovboolean

true if full covariance is provided

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

Returns num_bands : int

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)

property maximum_period

property minimum_period

property num_bands

Returns num_bandsint

a count of the frequency bands associated with the TF

---

property num_channels_in

property num_channels_out

period_index(period)

property periods

set_tf(regression_estimator, period)

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()

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)

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

Returns:

aurora.transfer_function.emtf_z_file_helpers.get_default_orientation_block(n_ch=5)

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

List of text strings, one per channel

aurora.transfer_function.emtf_z_file_helpers.merge_tf_collection_to_match_z_file(aux_data, tf_collection)

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: dict of dicts

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

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)

Bases: object

Attributes:

continue_redescending

correction_factor

TODO: This is an RME specific property.

Methods

converged(b, b0)

Parameters:

property continue_redescending

converged(b, b0)

Parameters:

bcomplex-valued numpy array

the most recent regression estimate

b0complex-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

TODO: 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_factorfloat

correction factor used for scaling the residual error_variance

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)

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)	Parameters:
rho_phi_plot([show, aux_data, xy_or_yx, ...])	One-off plotting method intended only for the synthetic test data for aurora dev Parameters ---------- show aux_data xy_or_yx ttl_str

get_merged_dict

property channel_list

check_all_channels_present(channel_nomenclature)

Parameters:

channel_nomenclature: mt_metadata.transfer_functions.processing.aurora.channel_nomenclature.ChannelNomenclature

Scheme according to how channels are named

get_merged_dict(channel_nomenclature)

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], **kwargs)

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

Returns:

property total_number_of_channels

property total_number_of_frequencies

Transfer Function Header

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)

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

Returns num_bands : int

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, ...)	ap_res(...) : computes app.
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:
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)

ap_res(…) : 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)

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()

Returns:

standard_error: xr.DataArray