aurora.transfer_function package¶

Subpackages¶

Submodules¶

aurora.transfer_function.TTFZ module¶

This module contains an extension of aurora’s TransferFunction base class. This class can return estimates of standard error, apparent resistivity and phase.

Development Notes: This class follows Gary’s legacy matlab code TTFZ.m from iris_mt_scratch/egbert_codes-20210121T193218Z-001/egbert_codes/matlabPrototype_10-13-20/TF/classes TODO: This should be replaced by methods in mtpy.

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

Bases: TransferFunction

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

TODO: This class should be deprecated and mt_metadata TF object should be used instead.

Attributes:

emtf_tf_header: Returns ——- emtf_tf_header: None or OrderedDict A legacy construction from the old EMTF codes with some metadata about the TF.
maximum_period: return the maximum (longest) period in self.periods
minimum_period: return the minimum (shortest) period in self.periods
num_bands: Get number of bands associated with TF
num_channels_in: return the number of input channels in the TF
num_channels_out: return the number of output channels in the TF
periods
tf
tf_header: returns the emtf_header

Methods

`apparent_resistivity`(channel_nomenclature[, ...])	Computes the apparent resistivity and phase.
`frequency_index`(frequency)	Gets the index of the tf array associated with the input frequency
`period_index`(period)	Gets the index of the tf array associated with the input period.
`set_tf`(regression_estimator, period)	Sets TF elements for one band, using contents of regression_estimator object.
`standard_error`()	estimate the standard error, used for error bars and inversion.

apparent_resistivity(channel_nomenclature, units='SI')[source]¶

Computes the apparent resistivity and phase.

Development notes: Original Matlab Documentation: 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 maps the channel names in TF to the standard channel labellings.

standard_error()[source]¶

estimate the standard error, used for error bars and inversion.

Development Notes: The standard error is normally thought of as the sqrt of the error variance. since the code here sets std_err = np.sqrt(np.abs(cov_ss_inv * cov_nn)) that means the inverse signal covariance times the noise covariance is like the error variance.

Returns:: standard_error
Return type:: xr.DataArray

aurora.transfer_function.base module¶

This module contains a base class for Transfer function information.

Development Notes:: The class is based on Gary’s TTF.m in iris_mt_scratch egbert_codes-20210121T193218Z-001/egbert_codes/matlabPrototype_10-13-20/TF/classes

TODO: This class should be updated to use mt_metadata.transfer_function.TF, or replaced by it (issue #203)

class aurora.transfer_function.base.TransferFunction(decimation_level_id: int, frequency_bands: FrequencyBands, processing_config: Processing | None = None, **kwargs)[source]¶

Bases: object

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

Attributes:

emtf_tf_header: Returns ——- emtf_tf_header: None or OrderedDict A legacy construction from the old EMTF codes with some metadata about the TF.
maximum_period: return the maximum (longest) period in self.periods
minimum_period: return the minimum (shortest) period in self.periods
num_bands: Get number of bands associated with TF
num_channels_in: return the number of input channels in the TF
num_channels_out: return the number of output channels in the TF
periods
tf
tf_header: returns the emtf_header

Methods

`frequency_index`(frequency)	Gets the index of the tf array associated with the input frequency
`period_index`(period)	Gets the index of the tf array associated with the input period.
`set_tf`(regression_estimator, period)	Sets TF elements for one band, using contents of regression_estimator object.

property emtf_tf_header¶: returns: emtf_tf_header – A legacy construction from the old EMTF codes with some metadata about the TF. :rtype: None or OrderedDict

frequency_index(frequency)[source]¶

Gets the index of the tf array associated with the input frequency

Parameters:: frequency (float) – The period in seconds
Returns:: frequency_index – The index of the tf array corresponding to the frequency
Return type:: int

property maximum_period¶: return the maximum (longest) period in self.periods

property minimum_period: float¶: return the minimum (shortest) period in self.periods

property num_bands: int¶

Get number of bands associated with TF

Returns:: num_bands – a count of the frequency bands associated with the TF
Return type:: int

property num_channels_in¶: return the number of input channels in the TF

property num_channels_out¶: return the number of output channels in the TF

period_index(period: float) → int[source]¶

Gets the index of the tf array associated with the input period.

Parameters:: period (float) – The period in seconds
Returns:: period_index – The index of the tf array corresponding to the period
Return type:: int

property periods¶

set_tf(regression_estimator, period)[source]¶: Sets TF elements for one band, using contents of regression_estimator object.

property tf¶

property tf_header¶: returns the emtf_header

aurora.transfer_function.emtf_z_file_helpers module¶

This module contains methods associated with legacy EMTF z-file TF format.

Development notes: They extract info needed to setup emtf_z files. These methods can possibly be moved under mt_metadata, or deprecated.

aurora.transfer_function.emtf_z_file_helpers.clip_bands_from_z_file(z_path: str | Path, n_bands_clip: int, output_z_path: str | Path | None = None, n_sensors: int | None = 5)[source]¶

This function clips periods off the end of an EMTF legacy z_file.

Development Notes: It can come in handy 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: int = 5) → list[source]¶

creates a text block like the part of the z-file that holds channel orientations.

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: ZFile, tf_collection: TransferFunctionCollection) → dict[source]¶

method to merge tf data from a tf_collection with a Z-file when there are potentially multiple estimates of TF at the same periods for different decimation levels.

Development Notes: Currently this is only used for the the synthetic test where aurora results are compared against a stored legacy Z-file. 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 (aurora.sandbox.io_helpers.zfile_murphy.ZFile) – Object representing a z-file
tf_collection (aurora.transfer_function.transfer_function_collection) –
.TransferFunctionCollection – Object representing the transfer function returned 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

aurora.transfer_function.kernel_dataset module¶

aurora.transfer_function.transfer_function_collection module¶

This module provides a TransferFunctionCollection container to hold: 1. TransferFunctionHeader 2. Dictionary of TransferFunction Objects

Development Notes:

This class could use substantial updating. There are two main issues to be aware of.

First, the transfer function objects that is “collects” are themselves things that could use substantial updates. This is because the aurora TransferFunction objects to not use the mt_metadata.transfer_function.TF and they should. This is issue #203.

Second, the Collection can have more than one value for a TF at a given frequency or period because the TFs can be estimated from different decimation levels.

A single transfer function object is associated with a station, here called the “local_station”. In a database of TFs could add a column for local_station and one for reference station.

class aurora.transfer_function.transfer_function_collection.TransferFunctionCollection(tf_dict: dict | None = None, processing_config: Processing | None = None)[source]¶

Bases: object

Attributes:

channel_list: Gets all channel names.
header: returns the tf_header (ordered dict) from the first tf in the dict
local_station_id: return the local station id
number_of_decimation_levels: Returns a count of number of decimation levels - assumes that each entry in dict is a separate decimation level.
remote_station_id: return the remote station id
total_number_of_channels: Get a count of all channels (input and output) in the TF
total_number_of_frequencies: Returns int:

Methods

`check_all_channels_present`(channel_nomenclature)	Checks if TF has tipper. If not, fill in the tipper data with NaN and also
`get_merged_dict`(channel_nomenclature)	merges all decimation levels and returns a dict
`rho_phi_plot`(xy_or_yx[, show, aux_data, ...])	One-off plotting method intended only for the synthetic test data for aurora dev

property channel_list: list¶

Gets all channel names.

assumes the first TF in dict is representative of all

Returns:: all_channels – All the channel names for the first TF
Return type:: list

check_all_channels_present(channel_nomenclature) → None[source]¶

Checks if TF has tipper. If not, fill in the tipper data with NaN and also: update the noise covariance matrix so shape is as expected by mt_metadata.
Development Notes:: For testing, at least some Parkfield tests have no hz. Synthetic tests do not (currently) have missing hz.

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

get_merged_dict(channel_nomenclature) → dict[source]¶

merges all decimation levels and returns a dict

Returns:: output – merged tf values - this can be used to assign values to an mt_metadata.transfer_function.TF
Return type:: dict

property header: dict¶: returns the tf_header (ordered dict) from the first tf in the dict

property local_station_id: str¶: return the local station id

property number_of_decimation_levels: int¶: Returns a count of number of decimation levels - assumes that each entry in dict is a separate decimation level.

property remote_station_id: str¶: return the remote station id

One-off plotting method intended only for the synthetic test data for aurora dev

Parameters:

xy_or_yx (str) – Must be “xy” or “yx” – the mode of the TF to plot
show (Optional[bool]) – If True show figure on screen
aux_data (Optional[Union[ZFile, None]]) – If not none, plot the data from the z-file as well as data from self
ttl_str (Optional[str]) – If provided, ttl_str will be appended to the plot title
x_axis_fontsize (int) – Font size for the x-axis
y_axis_fontsize (int) – Font size for the y-axis
ttl_fontsize (int) – Font size for the title
markersize (int) – the marker size for the plot symbols
rho_ylims (list) – The lower and upper limits for the y-axis on rho plot
phi_ylims (list) – The lower and upper limits for the y-axis on phi plot
figures_path (Union[str, pathlib.Path]) – Where to save the figure
figure_basename – What the name of the figure will be. If not given, a default name is assigned

property total_number_of_channels: int¶: Get a count of all channels (input and output) in the TF

property total_number_of_frequencies: int¶: Returns int: Count of number of frequencies over all TFs in dict

Module contents¶

Staging area for functions we want to import directly from transfer_function.

class aurora.transfer_function.TransferFunctionCollection(tf_dict: dict | None = None, processing_config: Processing | None = None)[source]¶

Bases: object

Attributes:

channel_list: Gets all channel names.
header: returns the tf_header (ordered dict) from the first tf in the dict
local_station_id: return the local station id
number_of_decimation_levels: Returns a count of number of decimation levels - assumes that each entry in dict is a separate decimation level.
remote_station_id: return the remote station id
total_number_of_channels: Get a count of all channels (input and output) in the TF
total_number_of_frequencies: Returns int:

Methods

`check_all_channels_present`(channel_nomenclature)	Checks if TF has tipper. If not, fill in the tipper data with NaN and also
`get_merged_dict`(channel_nomenclature)	merges all decimation levels and returns a dict
`rho_phi_plot`(xy_or_yx[, show, aux_data, ...])	One-off plotting method intended only for the synthetic test data for aurora dev

property channel_list: list¶

Gets all channel names.

assumes the first TF in dict is representative of all

Returns:: all_channels – All the channel names for the first TF
Return type:: list

check_all_channels_present(channel_nomenclature) → None[source]¶

Checks if TF has tipper. If not, fill in the tipper data with NaN and also: update the noise covariance matrix so shape is as expected by mt_metadata.
Development Notes:: For testing, at least some Parkfield tests have no hz. Synthetic tests do not (currently) have missing hz.

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

get_merged_dict(channel_nomenclature) → dict[source]¶

merges all decimation levels and returns a dict

Returns:: output – merged tf values - this can be used to assign values to an mt_metadata.transfer_function.TF
Return type:: dict

property header: dict¶: returns the tf_header (ordered dict) from the first tf in the dict

property local_station_id: str¶: return the local station id

property number_of_decimation_levels: int¶: Returns a count of number of decimation levels - assumes that each entry in dict is a separate decimation level.

property remote_station_id: str¶: return the remote station id

One-off plotting method intended only for the synthetic test data for aurora dev

Parameters:

xy_or_yx (str) – Must be “xy” or “yx” – the mode of the TF to plot
show (Optional[bool]) – If True show figure on screen
aux_data (Optional[Union[ZFile, None]]) – If not none, plot the data from the z-file as well as data from self
ttl_str (Optional[str]) – If provided, ttl_str will be appended to the plot title
x_axis_fontsize (int) – Font size for the x-axis
y_axis_fontsize (int) – Font size for the y-axis
ttl_fontsize (int) – Font size for the title
markersize (int) – the marker size for the plot symbols
rho_ylims (list) – The lower and upper limits for the y-axis on rho plot
phi_ylims (list) – The lower and upper limits for the y-axis on phi plot
figures_path (Union[str, pathlib.Path]) – Where to save the figure
figure_basename – What the name of the figure will be. If not given, a default name is assigned

property total_number_of_channels: int¶: Get a count of all channels (input and output) in the TF

property total_number_of_frequencies: int¶: Returns int: Count of number of frequencies over all TFs in dict