mtpy.core.transfer_function package

Subpackages

mtpy.core.transfer_function.z_analysis package

Submodules

mtpy.core.transfer_function.base module

Updated 11/2020 for logging and formating (J. Peacock).

ToDo: add functionality for covariance matrix

class mtpy.core.transfer_function.base.TFBase(tf: ndarray | None = None, tf_error: ndarray | None = None, frequency: ndarray | None = None, tf_model_error: ndarray | None = None, **kwargs: Any)[source]

Bases: object

Generic transfer function object.

Uses xarray as its base container for the data.

Parameters:

tf (np.ndarray, optional) – Transfer function array, by default None
tf_error (np.ndarray, optional) – Transfer function error array, by default None
frequency (np.ndarray, optional) – Frequency array, by default None
tf_model_error (np.ndarray, optional) – Transfer function model error array, by default None
**kwargs (Any) – Additional keyword arguments

property comps: dict[str, list[str]]: Component dictionary with input and output channels.

copy() → TFBase[source]: Copy the object.

property frequency: ndarray

Frequencies for each impedance tensor element.

Returns:: Frequency array in Hz
Return type:: np.ndarray

from_dataframe(dataframe: Any) → None[source]

Fill from a pandas dataframe.

Parameters:: dataframe (Any) – Pandas dataframe with appropriate columns

Notes

Not yet implemented.

from_xarray(dataset: Dataset) → None[source]

Fill from an xarray dataset.

Parameters:: dataset (xr.Dataset) – XArray dataset to load

Notes

Probably needs more validation than currently implemented.

interpolate(new_periods: ndarray, inplace: bool = False, method: str = 'slinear', extrapolate: bool = False, **kwargs)[source]

Interpolate transfer function onto a new period range using SciPy interpolators.

This method individually interpolates the real and imaginary parts of complex data and directly handles each component separately for better accuracy.

Parameters:

new_periods (array_like) – New periods to interpolate onto
inplace (bool, optional) – Interpolate inplace, defaults to False
method (str, optional) – Interpolation method, defaults to ‘pchip’ Options: ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’, ‘pchip’, ‘akima’, ‘spline’, ‘barycentric’, ‘polynomial’, ‘krogh’
extrapolate (bool, optional) – Whether to extrapolate beyond original period range, defaults to False
**kwargs – Additional kwargs passed to scipy.interpolate methods

Returns:

Interpolated transfer function object if inplace=False, otherwise None

Return type:

TFBase or None

property inverse: Dataset

Return the inverse of transfer function.

Returns:: Inverted transfer function dataset
Return type:: xr.Dataset
Raises:: ValueError – If transfer function is a singular matrix

Notes

No error propagation included yet.

property n_periods: int: Number of periods.

property period: ndarray: Periods in seconds.

Rotate transfer function array by angle alpha.

Rotation angle must be given in degrees. All angles are referenced to the coordinate_reference_frame where the rotation angle is clockwise positive, rotating North into East.

Most transfer functions are referenced to an NED coordinate system, which is what MTpy uses as the default.

In the NED coordinate system:: x=North, y=East, z=+down and a positive clockwise rotation is a positive angle. In this coordinate system the rotation matrix is the conventional rotation matrix.
In the ENU coordinate system:: x=East, y=North, z=+up and a positive clockwise rotation is a positive angle. In this coordinate system the rotation matrix is the inverse of the conventional rotation matrix.

Parameters:

alpha (float or int or str or array-like) – Angle to rotate by assuming a clockwise rotation from north in the coordinate_reference_frame (in degrees)
inplace (bool, optional) – Rotate in place. Will add alpha to rotation_angle, by default False
coordinate_reference_frame (str, optional) – Coordinate reference frame. If set to ‘ned’ or ‘+’ then the rotation will be clockwise from north (x1). If set to ‘enu’ or ‘-’ then rotation will be counter-clockwise, by default ‘ned’

Returns:

Rotated transfer function if inplace is False, None otherwise

Return type:

TFBase or None

to_dataframe() → Any[source]

Return a pandas dataframe.

Returns:: Pandas dataframe with appropriate columns
Return type:: Any

Notes

Not yet implemented.

to_xarray() → Dataset[source]

Convert to an xarray dataset.

Returns:: The internal dataset
Return type:: xr.Dataset

mtpy.core.transfer_function.pt module

Phase Tensor

Following Caldwell et al, 2004

Originally written by Stephan Thiel in Matlab translated to Python by Lars Krieger

Revised by J. Peacock 2022 to fit with version 2.

Bases: TFBase

Phase Tensor class.

Methods include reading and writing from and to edi-objects, rotations, combinations of Z instances, as well as calculation of invariants, inverse, amplitude/phase.

Phase tensor is a real array of the form (n_freq, 2, 2) with indices:

phase_tensor_xx: (0,0)
phase_tensor_xy: (0,1)
phase_tensor_yx: (1,0)
phase_tensor_yy: (1,1)

All internal methods are based on Caldwell et al. (2004) and Bibby et al. (2005), which use the canonical cartesian 2D reference (x1, x2). However, all components, coordinates, and angles for in- and outputs are given in the geographical reference frame:

x-axis = North

y-axis = East

z-axis = Down

Therefore, all results from using those methods are consistent (angles are referenced from North rather than x1).

Parameters:

z (np.ndarray, optional) – Impedance tensor array (n_frequency, 2, 2), by default None
z_error (np.ndarray, optional) – Impedance tensor error array (n_frequency, 2, 2), by default None
z_model_error (np.ndarray, optional) – Impedance tensor model error array (n_frequency, 2, 2), by default None
frequency (np.ndarray, optional) – Frequency array (n_frequency), by default None
pt (np.ndarray, optional) – Phase tensor array (n_frequency, 2, 2), by default None
pt_error (np.ndarray, optional) – Phase tensor error array (n_frequency, 2, 2), by default None
pt_model_error (np.ndarray, optional) – Phase tensor model error array (n_frequency, 2, 2), by default None

property alpha: ndarray | None: Principal axis angle (strike) of phase tensor in degrees.

property alpha_error: ndarray | None: Principal axis angle error of phase tensor in degrees.

property alpha_model_error: ndarray | None: Principal axis angle model error of phase tensor in degrees.

property azimuth: ndarray | None: Azimuth angle related to geoelectric strike in degrees.

property azimuth_error: ndarray | None: Azimuth angle error related to geoelectric strike in degrees.

property azimuth_model_error: ndarray | None: Azimuth angle model error related to geoelectric strike in degrees.

property beta: ndarray | None: 3D-dimensionality angle Beta (invariant) of phase tensor in degrees.

property beta_error: ndarray | None: 3D-dimensionality angle error Beta of phase tensor in degrees.

property beta_model_error: ndarray | None: 3D-dimensionality angle model error Beta of phase tensor in degrees.

property det: ndarray | None: Determinant of phase tensor.

property det_error: ndarray | None: Determinant error of phase tensor.

property det_model_error: ndarray | None: Determinant model error of phase tensor.

property eccentricity: ndarray | None: Eccentricity estimation of dimensionality.

property eccentricity_error: ndarray | None: Error in eccentricity estimation.

property eccentricity_model_error: ndarray | None: Model error in eccentricity estimation.

property ellipticity: ndarray | None: Ellipticity of the phase tensor, related to dimensionality.

property ellipticity_error: ndarray | None: Ellipticity error of the phase tensor, related to dimensionality.

property ellipticity_model_error: ndarray | None: Ellipticity model error of the phase tensor, related to dimensionality.

property only1d: ndarray | None

Return phase tensor in 1D form.

If phase tensor is not 1D per se, the diagonal elements are set to zero, the off-diagonal elements keep their signs, but their absolute is set to the mean of the original phase tensor off-diagonal absolutes.

property only2d: ndarray | None

Return phase tensor in 2D form.

If phase tensor is not 2D per se, the diagonal elements are set to zero.

property phimax: ndarray | None

Maximum phase calculated according to Bibby et al. 2005.

Phi_max = Pi2 + Pi1.

property phimax_error: ndarray | None: Maximum phase error.

property phimax_model_error: ndarray | None: Maximum phase model error.

property phimin: ndarray | None

Minimum phase calculated according to Bibby et al. 2005.

Phi_min = Pi2 - Pi1.

property phimin_error: ndarray | None: Minimum phase error.

property phimin_model_error: ndarray | None: Minimum phase model error.

property pt: ndarray | None: Phase tensor array.

property pt_error: ndarray | None: Phase tensor error.

property pt_model_error: ndarray | None: Phase tensor model error.

property skew: ndarray | None: 3D-dimensionality skew angle of phase tensor in degrees.

property skew_error: ndarray | None: 3D-dimensionality skew angle error of phase tensor in degrees.

property skew_model_error: ndarray | None: 3D-dimensionality skew angle model error of phase tensor in degrees.

property trace: ndarray | None: Trace of phase tensor.

property trace_error: ndarray | None: Trace error of phase tensor.

property trace_model_error: ndarray | None: Trace model error of phase tensor.

mtpy.core.transfer_function.tipper module

Created on Fri Oct 7 23:25:57 2022

@author: jpeacock

class mtpy.core.transfer_function.tipper.Tipper(tipper: ndarray | None = None, tipper_error: ndarray | None = None, frequency: ndarray | None = None, tipper_model_error: ndarray | None = None)[source]

Bases: TFBase

Tipper class.

Errors are given as standard deviations (sqrt(VAR)).

Parameters:

tipper (np.ndarray, optional) – Tipper array in the shape of [Tx, Ty] (nf, 1, 2), by default None
tipper_error (np.ndarray, optional) – Array of estimated tipper errors in the shape of [Tx, Ty] (nf, 1, 2), by default None
frequency (np.ndarray, optional) – Array of frequencies corresponding to the tipper elements (nf), by default None
tipper_model_error (np.ndarray, optional) – Array of model errors in the shape of [Tx, Ty] (nf, 1, 2), by default None

property amplitude: ndarray | None: Amplitude of tipper.

property amplitude_error: ndarray | None: Amplitude error.

property amplitude_model_error: ndarray | None: Amplitude model error.

property angle_error: ndarray | None: Angle error in degrees.

property angle_imag: ndarray | None: Angle of imaginary component in degrees.

property angle_model_error: ndarray | None: Angle model error in degrees.

property angle_real: ndarray | None: Angle of real component in degrees.

property mag_error: ndarray | None: Magnitude error.

property mag_imag: ndarray | None: Magnitude of imaginary component.

property mag_model_error: ndarray | None: Magnitude model error.

property mag_real: ndarray | None: Magnitude of real component.

property phase: ndarray | None: Phase of tipper in degrees.

property phase_error: ndarray | None: Phase error in degrees.

property phase_model_error: ndarray | None: Phase model error in degrees.

set_amp_phase(r: ndarray, phi: ndarray) → None[source]

Set values for amplitude (r) and phase (phi).

Parameters:

r (np.ndarray) – Amplitude array
phi (np.ndarray) – Phase array in degrees

Notes

Updates the attributes tipper and tipper_error.

set_mag_direction(mag_real: ndarray, ang_real: ndarray, mag_imag: ndarray, ang_imag: ndarray) → None[source]

Compute tipper from magnitude and direction of real and imaginary components.

Parameters:

mag_real (np.ndarray) – Magnitude of real component
ang_real (np.ndarray) – Angle of real component
mag_imag (np.ndarray) – Magnitude of imaginary component
ang_imag (np.ndarray) – Angle of imaginary component

Notes

Updates tipper. No error propagation yet.

property tipper: ndarray | None: Tipper array.

property tipper_error: ndarray | None: Tipper error.

property tipper_model_error: ndarray | None: Tipper model error.

mtpy.core.transfer_function.z module

Z

Container for the Impedance Tensor

Originally written by Jared Peacock Lars Krieger Updated 2022 by J. Peacock to work with new framework

class mtpy.core.transfer_function.z.Z(z: ndarray | None = None, z_error: ndarray | None = None, frequency: ndarray | None = None, z_model_error: ndarray | None = None, units: str = 'mt')[source]

Bases: TFBase

Impedance tensor (Z) class.

Z is a complex array of the form (n_frequency, 2, 2) with indices: - Zxx: (0,0) - Zxy: (0,1) - Zyx: (1,0) - Zyy: (1,1)

All errors are given as standard deviations (sqrt(VAR)).

Parameters:

z (np.ndarray, optional) – Array containing complex impedance values (n_frequency, 2, 2)
z_error (np.ndarray, optional) – Array containing error values (standard deviation) of impedance tensor elements (n_frequency, 2, 2)
frequency (np.ndarray, optional) – Array of frequency values corresponding to impedance tensor elements (n_frequency)
z_model_error (np.ndarray, optional) – Array containing model error values (n_frequency, 2, 2)
units (str, optional) – Units for impedance: ‘mt’ [mV/km/nT] or ‘ohm’ [Ohms], by default ‘mt’

property det: ndarray | None: Determinant of impedance.

property det_error: ndarray | None: Determinant of impedance error.

property det_model_error: ndarray | None: Determinant of impedance model error.

estimate_depth_of_investigation() → Any[source]

Estimate depth of investigation.

Returns:: Depth of investigation results
Return type:: Any

estimate_dimensionality(skew_threshold: float = 5, eccentricity_threshold: float = 0.1) → ndarray[source]

Estimate dimensionality of the impedance tensor.

Based on parameters such as strike and phase tensor eccentricity.

Parameters:

skew_threshold (float, optional) – Skew threshold for 3D determination, by default 5
eccentricity_threshold (float, optional) – Eccentricity threshold for 2D determination, by default 0.1

Returns:

Dimensionality array (1D, 2D, or 3D) for each period

Return type:

np.ndarray

estimate_distortion(n_frequencies: int | None = None, comp: str = 'det', only_2d: bool = False, clockwise: bool = True) → tuple[ndarray, ndarray][source]

Estimate distortion tensor.

Parameters:

n_frequencies (int, optional) – Number of frequencies to use, by default None (uses all)
comp (str, optional) – Component to use for estimation, by default ‘det’
only_2d (bool, optional) – Only use 2D data, by default False
clockwise (bool, optional) – Clockwise rotation, by default True

Returns:

Distortion tensor and distortion error tensor

Return type:

tuple of np.ndarray

property invariants: ZInvariants: Weaver invariants.

property phase: ndarray | None: Phase of impedance.

property phase_det: ndarray | None: Phase determinant.

property phase_error: ndarray | None

Phase error of impedance.

Uncertainty in phase (in degrees) is computed by defining a circle around the z vector in the complex plane. The uncertainty is the absolute angle between the vector to (x,y) and the vector between the origin and the tangent to the circle.

property phase_error_det: ndarray | None: Phase error determinant.

property phase_error_xx: ndarray | None: Phase error of xx component.

property phase_error_xy: ndarray | None: Phase error of xy component.

property phase_error_yx: ndarray | None: Phase error of yx component.

property phase_error_yy: ndarray | None: Phase error of yy component.

property phase_model_error: ndarray | None: Phase model error of impedance.

property phase_model_error_det: ndarray | None: Phase model error determinant.

property phase_model_error_xx: ndarray | None: Phase model error of xx component.

property phase_model_error_xy: ndarray | None: Phase model error of xy component.

property phase_model_error_yx: ndarray | None: Phase model error of yx component.

property phase_model_error_yy: ndarray | None: Phase model error of yy component.

property phase_tensor: PhaseTensor: Phase tensor object based on impedance.

property phase_xx: ndarray | None: Phase of xx component.

property phase_xy: ndarray | None: Phase of xy component.

property phase_yx: ndarray | None: Phase of yx component.

property phase_yy: ndarray | None: Phase of yy component.

remove_distortion(distortion_tensor: np.ndarray | None = None, distortion_error_tensor: np.ndarray | None = None, n_frequencies: int | None = None, comp: str = 'det', only_2d: bool = False, inplace: bool = False) → 'Z' | None[source]

Remove distortion D from observed impedance tensor Z.

Obtain the unperturbed “correct” Z0 from:: Z = D * Z0

Propagation of errors/uncertainties included.

Parameters:

distortion_tensor (np.ndarray, optional) – Real distortion tensor (2, 2), by default None
distortion_error_tensor (np.ndarray, optional) – Real distortion error tensor (2, 2), by default None
n_frequencies (int, optional) – Number of frequencies to use for estimation, by default None
comp (str, optional) – Component to use for estimation, by default ‘det’
only_2d (bool, optional) – Only use 2D data, by default False
inplace (bool, optional) – Update the current object or return a new impedance, by default False

Returns:

Impedance tensor with distortion removed if inplace is False, None otherwise

Return type:

Z or None

Remove static shift by providing correction factors.

Assume the original observed tensor Z is built by a static shift S and an unperturbed “correct” Z0:

Z = S * Z0

Therefore the correct Z will be:: Z0 = S^(-1) * Z

Parameters:

reduce_res_factor_x (float or array-like, optional) – Static shift factor to be applied to x components (z[:, 0, :]). Assumed to be in resistivity scale, by default 1.0
reduce_res_factor_y (float or array-like, optional) – Static shift factor to be applied to y components (z[:, 1, :]). Assumed to be in resistivity scale, by default 1.0
inplace (bool, optional) – Update the current object or return a new impedance, by default False

Returns:

Corrected Z if inplace is False, None otherwise

Return type:

Z or None

property res_det: ndarray | None: Resistivity determinant.

property res_error_det: ndarray | None: Resistivity error determinant.

property res_error_xx: ndarray | None: Resistivity error of xx component.

property res_error_xy: ndarray | None: Resistivity error of xy component.

property res_error_yx: ndarray | None: Resistivity error of yx component.

property res_error_yy: ndarray | None: Resistivity error of yy component.

property res_model_error_det: ndarray | None: Resistivity model error determinant.

property res_model_error_xx: ndarray | None: Resistivity model error of xx component.

property res_model_error_xy: ndarray | None: Resistivity model error of xy component.

property res_model_error_yx: ndarray | None: Resistivity model error of yx component.

property res_model_error_yy: ndarray | None: Resistivity model error of yy component.

property res_xx: ndarray | None: Resistivity of xx component.

property res_xy: ndarray | None: Resistivity of xy component.

property res_yx: ndarray | None: Resistivity of yx component.

property res_yy: ndarray | None: Resistivity of yy component.

property resistivity: ndarray | None: Resistivity of impedance.

property resistivity_error: ndarray | None

Resistivity error of impedance.

By standard error propagation, relative error in resistivity is 2 * relative error in z amplitude.

property resistivity_model_error: ndarray | None: Resistivity model error of impedance.

set_resistivity_phase(resistivity: ndarray, phase: ndarray, frequency: ndarray, res_error: ndarray | None = None, phase_error: ndarray | None = None, res_model_error: ndarray | None = None, phase_model_error: ndarray | None = None) → None[source]

Set values for resistivity and phase with error propagation.

Parameters:

resistivity (np.ndarray) – Resistivity array in Ohm-m (num_frequency, 2, 2)
phase (np.ndarray) – Phase array in degrees (num_frequency, 2, 2)
frequency (np.ndarray) – Frequency array in Hz (num_frequency)
res_error (np.ndarray, optional) – Resistivity error array in Ohm-m (num_frequency, 2, 2), by default None
phase_error (np.ndarray, optional) – Phase error array in degrees (num_frequency, 2, 2), by default None
res_model_error (np.ndarray, optional) – Resistivity model error array in Ohm-m (num_frequency, 2, 2), by default None
phase_model_error (np.ndarray, optional) – Phase model error array in degrees (num_frequency, 2, 2), by default None

property units: str: Impedance units.

property z: ndarray | None: Impedance tensor array (nfrequency, 2, 2).

property z_error: ndarray | None: Error of impedance tensor array as standard deviation.

property z_model_error: ndarray | None: Model error of impedance tensor array as standard deviation.

Module contents

Bases: TFBase

Phase Tensor class.

Methods include reading and writing from and to edi-objects, rotations, combinations of Z instances, as well as calculation of invariants, inverse, amplitude/phase.

Phase tensor is a real array of the form (n_freq, 2, 2) with indices:

phase_tensor_xx: (0,0)
phase_tensor_xy: (0,1)
phase_tensor_yx: (1,0)
phase_tensor_yy: (1,1)

All internal methods are based on Caldwell et al. (2004) and Bibby et al. (2005), which use the canonical cartesian 2D reference (x1, x2). However, all components, coordinates, and angles for in- and outputs are given in the geographical reference frame:

x-axis = North

y-axis = East

z-axis = Down

Therefore, all results from using those methods are consistent (angles are referenced from North rather than x1).

Parameters:

z (np.ndarray, optional) – Impedance tensor array (n_frequency, 2, 2), by default None
z_error (np.ndarray, optional) – Impedance tensor error array (n_frequency, 2, 2), by default None
z_model_error (np.ndarray, optional) – Impedance tensor model error array (n_frequency, 2, 2), by default None
frequency (np.ndarray, optional) – Frequency array (n_frequency), by default None
pt (np.ndarray, optional) – Phase tensor array (n_frequency, 2, 2), by default None
pt_error (np.ndarray, optional) – Phase tensor error array (n_frequency, 2, 2), by default None
pt_model_error (np.ndarray, optional) – Phase tensor model error array (n_frequency, 2, 2), by default None

property alpha: ndarray | None: Principal axis angle (strike) of phase tensor in degrees.

property alpha_error: ndarray | None: Principal axis angle error of phase tensor in degrees.

property alpha_model_error: ndarray | None: Principal axis angle model error of phase tensor in degrees.

property azimuth: ndarray | None: Azimuth angle related to geoelectric strike in degrees.

property azimuth_error: ndarray | None: Azimuth angle error related to geoelectric strike in degrees.

property azimuth_model_error: ndarray | None: Azimuth angle model error related to geoelectric strike in degrees.

property beta: ndarray | None: 3D-dimensionality angle Beta (invariant) of phase tensor in degrees.

property beta_error: ndarray | None: 3D-dimensionality angle error Beta of phase tensor in degrees.

property beta_model_error: ndarray | None: 3D-dimensionality angle model error Beta of phase tensor in degrees.

property det: ndarray | None: Determinant of phase tensor.

property det_error: ndarray | None: Determinant error of phase tensor.

property det_model_error: ndarray | None: Determinant model error of phase tensor.

property eccentricity: ndarray | None: Eccentricity estimation of dimensionality.

property eccentricity_error: ndarray | None: Error in eccentricity estimation.

property eccentricity_model_error: ndarray | None: Model error in eccentricity estimation.

property ellipticity: ndarray | None: Ellipticity of the phase tensor, related to dimensionality.

property ellipticity_error: ndarray | None: Ellipticity error of the phase tensor, related to dimensionality.

property ellipticity_model_error: ndarray | None: Ellipticity model error of the phase tensor, related to dimensionality.

property only1d: ndarray | None

Return phase tensor in 1D form.

If phase tensor is not 1D per se, the diagonal elements are set to zero, the off-diagonal elements keep their signs, but their absolute is set to the mean of the original phase tensor off-diagonal absolutes.

property only2d: ndarray | None

Return phase tensor in 2D form.

If phase tensor is not 2D per se, the diagonal elements are set to zero.

property phimax: ndarray | None

Maximum phase calculated according to Bibby et al. 2005.

Phi_max = Pi2 + Pi1.

property phimax_error: ndarray | None: Maximum phase error.

property phimax_model_error: ndarray | None: Maximum phase model error.

property phimin: ndarray | None

Minimum phase calculated according to Bibby et al. 2005.

Phi_min = Pi2 - Pi1.

property phimin_error: ndarray | None: Minimum phase error.

property phimin_model_error: ndarray | None: Minimum phase model error.

property pt: ndarray | None: Phase tensor array.

property pt_error: ndarray | None: Phase tensor error.

property pt_model_error: ndarray | None: Phase tensor model error.

property skew: ndarray | None: 3D-dimensionality skew angle of phase tensor in degrees.

property skew_error: ndarray | None: 3D-dimensionality skew angle error of phase tensor in degrees.

property skew_model_error: ndarray | None: 3D-dimensionality skew angle model error of phase tensor in degrees.

property trace: ndarray | None: Trace of phase tensor.

property trace_error: ndarray | None: Trace error of phase tensor.

property trace_model_error: ndarray | None: Trace model error of phase tensor.

class mtpy.core.transfer_function.TFDatasetAccessor(xarray_obj: Dataset)[source]

Bases: object

Transfer-function accessor for xarray datasets.

The accessor exposes impedance, tipper, and phase-tensor views from an xr.Dataset with transfer-function variables and provides convenience mutation methods for common MT workflows.

Notes

The underlying dataset is expected to contain transfer-function variables with dimensions ('period', 'output', 'input') and corresponding period coordinates.

Examples

>>> ds.tf.validate()
>>> z_obj = ds.tf.to_z()
>>> rotated = ds.tf.rotate(15)

property det: ndarray | None

Determinant of impedance tensor in mt units.

Returns:: Determinant of impedance tensor in mt units.
Return type:: np.ndarray | None

property det_error: ndarray | None

Determinant error from transfer_function_error.

Returns:: Determinant error from transfer_function_error.
Return type:: np.ndarray | None

property det_model_error: ndarray | None

Determinant model error from transfer_function_model_error.

Returns:: Determinant model error from transfer_function_model_error.
Return type:: np.ndarray | None

estimate_depth_of_investigation() → Any[source]

Estimate depth of investigation.

Returns:: Depth-of-investigation result from the underlying Z object.
Return type:: Any

estimate_dimensionality(skew_threshold: float = 5, eccentricity_threshold: float = 0.1) → ndarray[source]

Estimate 1D/2D/3D dimensionality from phase-tensor metrics.

Parameters:

skew_threshold (float, default=5) – Skew threshold (degrees) used to discriminate dimensionality.
eccentricity_threshold (float, default=0.1) – Eccentricity threshold used to discriminate dimensionality.

Returns:

Integer dimensionality classification per period.

Return type:

numpy.ndarray

estimate_distortion(n_frequencies: int | None = None, comp: str = 'det', only_2d: bool = False, clockwise: bool = True) → tuple[ndarray, ndarray][source]

Estimate galvanic distortion tensor.

Parameters:

n_frequencies (int or None, optional) – Number of frequencies to include in the estimate.
comp (str, default="det") – Impedance component selection strategy.
only_2d (bool, default=False) – If True, constrain the estimate to 2D assumptions.
clockwise (bool, default=True) – Rotation-direction convention used internally.

Returns:

Distortion tensor and associated error tensor.

Return type:

tuple of numpy.ndarray

property frequency: ndarray

Frequency array derived from period coordinates.

Returns:: Frequency array derived from period coordinates.
Return type:: np.ndarray

property impedance_units: str

Impedance units for accessor outputs.

Returns:: Impedance units for accessor outputs.
Return type:: str

interpolate(new_periods: ndarray, inplace: bool = False, method: str = 'slinear', extrapolate: bool = False, **kwargs: Any) → Dataset | None[source]

Interpolate transfer-function variables onto new periods.

Interpolation is performed component-by-component for each output/input channel pair.

Parameters:

new_periods (numpy.ndarray) – Target periods in seconds.
inplace (bool, default=False) – If True, mutate the bound dataset and return None.
method (str, default="slinear") – Interpolation method. Supported methods include linear, cubic, nearest, slinear, quadratic, zero, previous, next, pchip, spline, akima, barycentric, polynomial, and krogh.
extrapolate (bool, default=False) – If True, allow values outside source period range.
**kwargs – Additional keyword arguments forwarded to the selected scipy interpolator.

Returns:

Interpolated dataset when inplace=False; otherwise None.

Return type:

xarray.Dataset or None

Examples

>>> periods = np.logspace(-2, 3, 60)
>>> ds_interp = ds.tf.interpolate(periods, method="pchip")
>>> ds.tf.interpolate(periods, inplace=True, extrapolate=True)

property invariants: Any

Impedance invariants object derived from the accessor impedance view.

Returns:: Impedance invariants object derived from the accessor impedance view.
Return type:: Any

property phase: ndarray | None

Impedance phase tensor (degrees) computed directly from Dataset values.

Returns:: Impedance phase tensor (degrees) computed directly from Dataset values.
Return type:: np.ndarray | None

property phase_det: ndarray | None

Phase of determinant in degrees.

Returns:: Phase of determinant in degrees.
Return type:: np.ndarray | None

property phase_error: ndarray | None

Impedance phase error (degrees) computed directly from Dataset values.

Returns:: Impedance phase error (degrees) computed directly from Dataset values.
Return type:: np.ndarray | None

property phase_error_det: ndarray | None

Phase error of determinant in degrees.

Returns:: Phase error of determinant in degrees.
Return type:: np.ndarray | None

property phase_error_xx: ndarray | None

Phase error of the xx impedance component in degrees.

Returns:: Phase error of the xx impedance component in degrees.
Return type:: np.ndarray | None

property phase_error_xy: ndarray | None

Phase error of the xy impedance component in degrees.

Returns:: Phase error of the xy impedance component in degrees.
Return type:: np.ndarray | None

property phase_error_yx: ndarray | None

Phase error of the yx impedance component in degrees.

Returns:: Phase error of the yx impedance component in degrees.
Return type:: np.ndarray | None

property phase_error_yy: ndarray | None

Phase error of the yy impedance component in degrees.

Returns:: Phase error of the yy impedance component in degrees.
Return type:: np.ndarray | None

property phase_model_error: ndarray | None

Impedance phase model error (degrees) computed directly from Dataset values.

Returns:: Impedance phase model error (degrees) computed directly from Dataset values.
Return type:: np.ndarray | None

property phase_model_error_det: ndarray | None

Phase model error of determinant in degrees.

Returns:: Phase model error of determinant in degrees.
Return type:: np.ndarray | None

property phase_model_error_xx: ndarray | None

Phase model error of the xx impedance component in degrees.

Returns:: Phase model error of the xx impedance component in degrees.
Return type:: np.ndarray | None

property phase_model_error_xy: ndarray | None

Phase model error of the xy impedance component in degrees.

Returns:: Phase model error of the xy impedance component in degrees.
Return type:: np.ndarray | None

property phase_model_error_yx: ndarray | None

Phase model error of the yx impedance component in degrees.

Returns:: Phase model error of the yx impedance component in degrees.
Return type:: np.ndarray | None

property phase_model_error_yy: ndarray | None

Phase model error of the yy impedance component in degrees.

Returns:: Phase model error of the yy impedance component in degrees.
Return type:: np.ndarray | None

property phase_tensor: Any

Phase tensor object derived from the accessor impedance view.

Returns:: Phase tensor object derived from the accessor impedance view.
Return type:: Any

property phase_xx: ndarray | None

Phase of the xx impedance component in degrees.

Returns:: Phase of the xx impedance component in degrees.
Return type:: np.ndarray | None

property phase_xy: ndarray | None

Phase of the xy impedance component in degrees.

Returns:: Phase of the xy impedance component in degrees.
Return type:: np.ndarray | None

property phase_yx: ndarray | None

Phase of the yx impedance component in degrees.

Returns:: Phase of the yx impedance component in degrees.
Return type:: np.ndarray | None

property phase_yy: ndarray | None

Phase of the yy impedance component in degrees.

Returns:: Phase of the yy impedance component in degrees.
Return type:: np.ndarray | None

property pt: ndarray | None

Phase tensor array derived from impedance channels.

Returns:: Phase tensor array derived from impedance channels.
Return type:: np.ndarray | None

property pt_alpha: ndarray | None

Principal axis angle of the phase tensor in degrees.

Returns:: Principal axis angle of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_alpha_error: ndarray | None

Principal axis angle error of the phase tensor in degrees.

Returns:: Principal axis angle error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_alpha_model_error: ndarray | None

Principal axis angle model error of the phase tensor in degrees.

Returns:: Principal axis angle model error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_azimuth: ndarray | None

Phase tensor azimuth in degrees.

Returns:: Phase tensor azimuth in degrees.
Return type:: np.ndarray | None

property pt_azimuth_error: ndarray | None

Phase tensor azimuth error in degrees.

Returns:: Phase tensor azimuth error in degrees.
Return type:: np.ndarray | None

property pt_azimuth_model_error: ndarray | None

Phase tensor azimuth model error in degrees.

Returns:: Phase tensor azimuth model error in degrees.
Return type:: np.ndarray | None

property pt_beta: ndarray | None

3D-dimensionality angle of the phase tensor in degrees.

Returns:: 3D-dimensionality angle of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_beta_error: ndarray | None

3D-dimensionality angle error of the phase tensor in degrees.

Returns:: 3D-dimensionality angle error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_beta_model_error: ndarray | None

3D-dimensionality angle model error of the phase tensor in degrees.

Returns:: 3D-dimensionality angle model error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_det: ndarray | None

Determinant of the phase tensor.

Returns:: Determinant of the phase tensor.
Return type:: np.ndarray | None

property pt_det_error: ndarray | None

Determinant error of the phase tensor.

Returns:: Determinant error of the phase tensor.
Return type:: np.ndarray | None

property pt_det_model_error: ndarray | None

Determinant model error of the phase tensor.

Returns:: Determinant model error of the phase tensor.
Return type:: np.ndarray | None

property pt_eccentricity: ndarray | None

Phase tensor eccentricity.

Returns:: Phase tensor eccentricity.
Return type:: np.ndarray | None

property pt_eccentricity_error: ndarray | None

Phase tensor eccentricity error.

Returns:: Phase tensor eccentricity error.
Return type:: np.ndarray | None

property pt_eccentricity_model_error: ndarray | None

Phase tensor eccentricity model error.

Returns:: Phase tensor eccentricity model error.
Return type:: np.ndarray | None

property pt_ellipticity: ndarray | None

Phase tensor ellipticity.

Returns:: Phase tensor ellipticity.
Return type:: np.ndarray | None

property pt_ellipticity_error: ndarray | None

Phase tensor ellipticity error.

Returns:: Phase tensor ellipticity error.
Return type:: np.ndarray | None

property pt_ellipticity_model_error: ndarray | None

Phase tensor ellipticity model error.

Returns:: Phase tensor ellipticity model error.
Return type:: np.ndarray | None

property pt_error: ndarray | None

Phase tensor error array derived from impedance channels.

Returns:: Phase tensor error array derived from impedance channels.
Return type:: np.ndarray | None

property pt_error_xx: ndarray | None

xx component error of the phase tensor.

Returns:: xx component error of the phase tensor.
Return type:: np.ndarray | None

property pt_error_xy: ndarray | None

xy component error of the phase tensor.

Returns:: xy component error of the phase tensor.
Return type:: np.ndarray | None

property pt_error_yx: ndarray | None

yx component error of the phase tensor.

Returns:: yx component error of the phase tensor.
Return type:: np.ndarray | None

property pt_error_yy: ndarray | None

yy component error of the phase tensor.

Returns:: yy component error of the phase tensor.
Return type:: np.ndarray | None

property pt_model_error: ndarray | None

Phase tensor model error array derived from impedance channels.

Returns:: Phase tensor model error array derived from impedance channels.
Return type:: np.ndarray | None

property pt_model_error_xx: ndarray | None

xx component model error of the phase tensor.

Returns:: xx component model error of the phase tensor.
Return type:: np.ndarray | None

property pt_model_error_xy: ndarray | None

xy component model error of the phase tensor.

Returns:: xy component model error of the phase tensor.
Return type:: np.ndarray | None

property pt_model_error_yx: ndarray | None

yx component model error of the phase tensor.

Returns:: yx component model error of the phase tensor.
Return type:: np.ndarray | None

property pt_model_error_yy: ndarray | None

yy component model error of the phase tensor.

Returns:: yy component model error of the phase tensor.
Return type:: np.ndarray | None

property pt_only1d: ndarray | None

Phase tensor expressed in the 1D convenience form.

Returns:: Phase tensor expressed in the 1D convenience form.
Return type:: np.ndarray | None

property pt_only2d: ndarray | None

Phase tensor expressed in the 2D convenience form.

Returns:: Phase tensor expressed in the 2D convenience form.
Return type:: np.ndarray | None

property pt_phimax: ndarray | None

Maximum phase angle of the phase tensor in degrees.

Returns:: Maximum phase angle of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_phimax_error: ndarray | None

Maximum phase angle error of the phase tensor in degrees.

Returns:: Maximum phase angle error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_phimax_model_error: ndarray | None

Maximum phase angle model error of the phase tensor in degrees.

Returns:: Maximum phase angle model error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_phimin: ndarray | None

Minimum phase angle of the phase tensor in degrees.

Returns:: Minimum phase angle of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_phimin_error: ndarray | None

Minimum phase angle error of the phase tensor in degrees.

Returns:: Minimum phase angle error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_phimin_model_error: ndarray | None

Minimum phase angle model error of the phase tensor in degrees.

Returns:: Minimum phase angle model error of the phase tensor in degrees.
Return type:: np.ndarray | None

property pt_skew: ndarray | None

Phase tensor skew in degrees.

Returns:: Phase tensor skew in degrees.
Return type:: np.ndarray | None

property pt_skew_error: ndarray | None

Phase tensor skew error in degrees.

Returns:: Phase tensor skew error in degrees.
Return type:: np.ndarray | None

property pt_skew_model_error: ndarray | None

Phase tensor skew model error in degrees.

Returns:: Phase tensor skew model error in degrees.
Return type:: np.ndarray | None

property pt_trace: ndarray | None

Trace of the phase tensor.

Returns:: Trace of the phase tensor.
Return type:: np.ndarray | None

property pt_trace_error: ndarray | None

Trace error of the phase tensor.

Returns:: Trace error of the phase tensor.
Return type:: np.ndarray | None

property pt_trace_model_error: ndarray | None

Trace model error of the phase tensor.

Returns:: Trace model error of the phase tensor.
Return type:: np.ndarray | None

property pt_xx: ndarray | None

xx component of the phase tensor.

Returns:: xx component of the phase tensor.
Return type:: np.ndarray | None

property pt_xy: ndarray | None

xy component of the phase tensor.

Returns:: xy component of the phase tensor.
Return type:: np.ndarray | None

property pt_yx: ndarray | None

yx component of the phase tensor.

Returns:: yx component of the phase tensor.
Return type:: np.ndarray | None

property pt_yy: ndarray | None

yy component of the phase tensor.

Returns:: yy component of the phase tensor.
Return type:: np.ndarray | None

remove_distortion(distortion_tensor: ndarray | None = None, distortion_error_tensor: ndarray | None = None, n_frequencies: int | None = None, comp: str = 'det', only_2d: bool = False, units: str | None = None, as_dataset: bool = False) → Dataset | Z[source]

Apply galvanic distortion correction using Z.remove_distortion.

Parameters:

distortion_tensor (numpy.ndarray or None, optional) – Distortion tensor estimate.
distortion_error_tensor (numpy.ndarray or None, optional) – Distortion tensor error estimate.
n_frequencies (int or None, optional) – Number of frequencies used for estimation when an explicit tensor is not provided.
comp (str, default="det") – Impedance component selection strategy.
only_2d (bool, default=False) – If True, constrain correction to 2D assumptions.
units (str or None, optional) – Impedance unit system passed to to_z().
as_dataset (bool, default=False) – If True, return corrected transfer-function dataset. If False, return corrected Z object.

Returns:

Corrected result as either dataset or Z object.

Return type:

xarray.Dataset or Z

Apply static-shift correction using Z.remove_ss.

Parameters:

reduce_res_factor_x (float or array-like, optional) – Static-shift correction factor for x-polarized rows.
reduce_res_factor_y (float or array-like, optional) – Static-shift correction factor for y-polarized rows.
units (str, optional) – Impedance unit system passed to to_z().
as_dataset (bool, optional) – If True, return corrected transfer-function dataset. If False, return a corrected Z object.

Returns:

Corrected result as either dataset or Z object.

Return type:

xarray.Dataset or Z

Examples

>>> z_corr = ds.tf.remove_ss(1.1, 0.9)
>>> ds_corr = ds.tf.remove_ss(1.1, 0.9, as_dataset=True)

property res_det: ndarray | None

Apparent resistivity from determinant.

Returns:: Apparent resistivity from determinant.
Return type:: np.ndarray | None

property res_error_det: ndarray | None

Apparent resistivity error from determinant.

Returns:: Apparent resistivity error from determinant.
Return type:: np.ndarray | None

property res_error_xx: ndarray | None

Apparent resistivity error of the xx impedance component.

Returns:: Apparent resistivity error of the xx impedance component.
Return type:: np.ndarray | None

property res_error_xy: ndarray | None

Apparent resistivity error of the xy impedance component.

Returns:: Apparent resistivity error of the xy impedance component.
Return type:: np.ndarray | None

property res_error_yx: ndarray | None

Apparent resistivity error of the yx impedance component.

Returns:: Apparent resistivity error of the yx impedance component.
Return type:: np.ndarray | None

property res_error_yy: ndarray | None

Apparent resistivity error of the yy impedance component.

Returns:: Apparent resistivity error of the yy impedance component.
Return type:: np.ndarray | None

property res_model_error_det: ndarray | None

Apparent resistivity model error from determinant.

Returns:: Apparent resistivity model error from determinant.
Return type:: np.ndarray | None

property res_model_error_xx: ndarray | None

Apparent resistivity model error of the xx impedance component.

Returns:: Apparent resistivity model error of the xx impedance component.
Return type:: np.ndarray | None

property res_model_error_xy: ndarray | None

Apparent resistivity model error of the xy impedance component.

Returns:: Apparent resistivity model error of the xy impedance component.
Return type:: np.ndarray | None

property res_model_error_yx: ndarray | None

Apparent resistivity model error of the yx impedance component.

Returns:: Apparent resistivity model error of the yx impedance component.
Return type:: np.ndarray | None

property res_model_error_yy: ndarray | None

Apparent resistivity model error of the yy impedance component.

Returns:: Apparent resistivity model error of the yy impedance component.
Return type:: np.ndarray | None

property res_xx: ndarray | None

Apparent resistivity of the xx impedance component.

Returns:: Apparent resistivity of the xx impedance component.
Return type:: np.ndarray | None

property res_xy: ndarray | None

Apparent resistivity of the xy impedance component.

Returns:: Apparent resistivity of the xy impedance component.
Return type:: np.ndarray | None

property res_yx: ndarray | None

Apparent resistivity of the yx impedance component.

Returns:: Apparent resistivity of the yx impedance component.
Return type:: np.ndarray | None

property res_yy: ndarray | None

Apparent resistivity of the yy impedance component.

Returns:: Apparent resistivity of the yy impedance component.
Return type:: np.ndarray | None

property resistivity: ndarray | None

Apparent resistivity tensor computed directly from Dataset values.

Returns:: Apparent resistivity tensor computed directly from Dataset values.
Return type:: np.ndarray | None

property resistivity_error: ndarray | None

Apparent resistivity error computed directly from Dataset values.

Returns:: Apparent resistivity error computed directly from Dataset values.
Return type:: np.ndarray | None

property resistivity_model_error: ndarray | None

Apparent resistivity model error computed directly from Dataset values.

Returns:: Apparent resistivity model error computed directly from Dataset values.
Return type:: np.ndarray | None

Rotate available impedance and tipper channels.

Parameters:

alpha (float, int, str, list, tuple, or numpy.ndarray) – Rotation angle(s) passed through to Z.rotate and Tipper.rotate.
inplace (bool, default=False) – If True, mutate the bound dataset and return None.
coordinate_reference_frame (str, default="ned") – Coordinate reference frame used for rotation semantics.

Returns:

Rotated dataset when inplace=False; otherwise None.

Return type:

xarray.Dataset or None

Raises:

ValueError – If no impedance or tipper channels can be identified for rotation.

Examples

>>> ds_rot = ds.tf.rotate(30)
>>> ds.tf.rotate(30, inplace=True)

set_amp_phase(r: ndarray, phi: ndarray, inplace: bool = True) → Dataset | None[source]

Set tipper values from amplitude/phase arrays.

Parameters:

r (numpy.ndarray) – Tipper amplitude values.
phi (numpy.ndarray) – Tipper phase values in degrees.
inplace (bool, default=True) – If True, mutate in place and return None.

Returns:

Updated dataset when inplace=False; otherwise None.

Return type:

xarray.Dataset or None

set_mag_direction(mag_real: ndarray, ang_real: ndarray, mag_imag: ndarray, ang_imag: ndarray, inplace: bool = True) → Dataset | None[source]

Set tipper from magnitude and direction arrays.

Parameters:

mag_real (numpy.ndarray) – Magnitude of real tipper vector.
ang_real (numpy.ndarray) – Direction of real tipper vector in degrees.
mag_imag (numpy.ndarray) – Magnitude of imaginary tipper vector.
ang_imag (numpy.ndarray) – Direction of imaginary tipper vector in degrees.
inplace (bool, default=True) – If True, mutate in place and return None.

Returns:

Updated dataset when inplace=False; otherwise None.

Return type:

xarray.Dataset or None

set_resistivity_phase(resistivity: ndarray, phase: ndarray, frequency: ndarray, res_error: ndarray | None = None, phase_error: ndarray | None = None, res_model_error: ndarray | None = None, phase_model_error: ndarray | None = None, units: str = 'mt', inplace: bool = True) → Dataset | None[source]

Set impedance from resistivity and phase arrays.

This is a convenience wrapper around with_res_phase() with default inplace=True.

Parameters:

resistivity (numpy.ndarray) – Apparent resistivity array.
phase (numpy.ndarray) – Impedance phase array in degrees.
frequency (numpy.ndarray) – Frequency vector.
res_error (numpy.ndarray or None, default=None) – Resistivity error array.
phase_error (numpy.ndarray or None, default=None) – Phase error array.
res_model_error (numpy.ndarray or None, default=None) – Resistivity model-error array.
phase_model_error (numpy.ndarray or None, default=None) – Phase model-error array.
units (str, default="mt") – Impedance units.
inplace (bool, default=True) – If True, mutate in place and return None.

Returns:

Updated dataset when inplace=False; otherwise None.

Return type:

xarray.Dataset or None

property t_zx: ndarray | None

zx component of the tipper.

Returns:: zx component of the tipper.
Return type:: np.ndarray | None

property t_zx_error: ndarray | None

zx component error of the tipper.

Returns:: zx component error of the tipper.
Return type:: np.ndarray | None

property t_zx_model_error: ndarray | None

zx component model error of the tipper.

Returns:: zx component model error of the tipper.
Return type:: np.ndarray | None

property t_zy: ndarray | None

zy component of the tipper.

Returns:: zy component of the tipper.
Return type:: np.ndarray | None

property t_zy_error: ndarray | None

zy component error of the tipper.

Returns:: zy component error of the tipper.
Return type:: np.ndarray | None

property t_zy_model_error: ndarray | None

zy component model error of the tipper.

Returns:: zy component model error of the tipper.
Return type:: np.ndarray | None

tipper() → ndarray[source]

Return tipper tensor values.

Returns:: Complex tipper array with shape (n_period, 1, 2).
Return type:: numpy.ndarray

property tipper_amplitude: ndarray | None

Tipper amplitude derived from the accessor tipper view.

Returns:: Tipper amplitude derived from the accessor tipper view.
Return type:: np.ndarray | None

property tipper_amplitude_error: ndarray | None

Tipper amplitude error derived from the accessor tipper view.

Returns:: Tipper amplitude error derived from the accessor tipper view.
Return type:: np.ndarray | None

property tipper_amplitude_model_error: ndarray | None

Tipper amplitude model error derived from Dataset values.

Returns:: Tipper amplitude model error derived from Dataset values.
Return type:: np.ndarray | None

property tipper_angle_error: ndarray | None

Tipper angle error in degrees derived from Dataset values.

Returns:: Tipper angle error in degrees derived from Dataset values.
Return type:: np.ndarray | None

property tipper_angle_imag: ndarray | None

Tipper imaginary-component angle in degrees.

Returns:: Tipper imaginary-component angle in degrees.
Return type:: np.ndarray | None

property tipper_angle_model_error: ndarray | None

Tipper angle model error in degrees derived from Dataset values.

Returns:: Tipper angle model error in degrees derived from Dataset values.
Return type:: np.ndarray | None

property tipper_angle_real: ndarray | None

Tipper real-component angle in degrees.

Returns:: Tipper real-component angle in degrees.
Return type:: np.ndarray | None

tipper_error() → ndarray[source]

Return tipper standard-deviation errors.

Returns:: Tipper error array with shape (n_period, 1, 2).
Return type:: numpy.ndarray

property tipper_mag_error: ndarray | None

Tipper magnitude error derived from Dataset values.

Returns:: Tipper magnitude error derived from Dataset values.
Return type:: np.ndarray | None

property tipper_mag_imag: ndarray | None

Tipper imaginary-component magnitude.

Returns:: Tipper imaginary-component magnitude.
Return type:: np.ndarray | None

property tipper_mag_model_error: ndarray | None

Tipper magnitude model error derived from Dataset values.

Returns:: Tipper magnitude model error derived from Dataset values.
Return type:: np.ndarray | None

property tipper_mag_real: ndarray | None

Tipper real-component magnitude.

Returns:: Tipper real-component magnitude.
Return type:: np.ndarray | None

tipper_model_error() → ndarray[source]

Return tipper model errors.

Returns:: Tipper model-error array with shape (n_period, 1, 2).
Return type:: numpy.ndarray

property tipper_phase: ndarray | None

Tipper phase in degrees derived from the accessor tipper view.

Returns:: Tipper phase in degrees derived from the accessor tipper view.
Return type:: np.ndarray | None

property tipper_phase_error: ndarray | None

Tipper phase error in degrees derived from the accessor tipper view.

Returns:: Tipper phase error in degrees derived from the accessor tipper view.
Return type:: np.ndarray | None

property tipper_phase_model_error: ndarray | None

Tipper phase model error in degrees derived from Dataset values.

Returns:: Tipper phase model error in degrees derived from Dataset values.
Return type:: np.ndarray | None

to_pt() → PhaseTensor[source]

Build a PhaseTensor object from dataset impedance.

Returns:: PhaseTensor instance computed from impedance values.
Return type:: PhaseTensor

Examples

>>> pt_obj = ds.tf.to_pt()

to_tipper() → Tipper[source]

Build a Tipper object from dataset values.

Returns:: Tipper instance populated from the dataset.
Return type:: Tipper

Examples

>>> tipper_obj = ds.tf.to_tipper()

to_z(units: str | None = None) → Z[source]

Build a Z object from dataset values.

Parameters:: units (str or None, default=None) – Units for the returned Z object. If None, uses self.impedance_units.
Returns:: Z instance populated from the dataset.
Return type:: Z

Examples

>>> z_obj = ds.tf.to_z()
>>> z_obj.rotate(10)

property units: str

Alias for impedance units to match Z API naming.

Returns:: Alias for impedance units to match Z API naming.
Return type:: str

validate() → bool[source]

Validate dataset structure required by the accessor.

Returns:: True when required variables and coordinates are present.
Return type:: bool
Raises:: KeyError – If required transfer-function variables, dimensions, or coordinates are missing.

with_res_phase(resistivity: ndarray, phase: ndarray, frequency: ndarray | None = None, period: ndarray | None = None, res_error: ndarray | None = None, phase_error: ndarray | None = None, res_model_error: ndarray | None = None, phase_model_error: ndarray | None = None, units: str = 'mt', inplace: bool = False) → Dataset[source]

Return a dataset updated from resistivity and phase arrays.

Parameters:

resistivity (numpy.ndarray) – Apparent resistivity array with impedance component shape.
phase (numpy.ndarray) – Impedance phase array in degrees.
frequency (numpy.ndarray or None, default=None) – Frequency vector. If None, uses dataset frequency.
period (numpy.ndarray or None, default=None) – Period vector alternative to frequency.
res_error (numpy.ndarray or None, default=None) – Resistivity error array.
phase_error (numpy.ndarray or None, default=None) – Phase error array.
res_model_error (numpy.ndarray or None, default=None) – Resistivity model-error array.
phase_model_error (numpy.ndarray or None, default=None) – Phase model-error array.
units (str, default="mt") – Impedance units for the intermediate Z representation.
inplace (bool, default=False) – If True, mutate the bound dataset and return it.

Returns:

Updated dataset.

Return type:

xarray.Dataset

Examples

>>> ds2 = ds.tf.with_res_phase(resistivity=res, phase=phs)

Return a dataset with tipper channels updated.

Parameters:

tipper_obj (Tipper or None, default=None) – Source Tipper object. If provided, array arguments are ignored.
tipper (numpy.ndarray or None, default=None) – Tipper array used when tipper_obj is not provided.
tipper_error (numpy.ndarray or None, default=None) – Tipper error array.
tipper_model_error (numpy.ndarray or None, default=None) – Tipper model-error array.
frequency (numpy.ndarray or None, default=None) – Frequency vector for array-mode input.
period (numpy.ndarray or None, default=None) – Period vector alternative to frequency.
inplace (bool, default=False) – If True, mutate the bound dataset and return it.

Returns:

Updated dataset.

Return type:

xarray.Dataset

Examples

>>> updated = ds.tf.with_tipper(tipper=tip, frequency=freq)
>>> ds.tf.with_tipper(tipper_obj=tipper_obj, inplace=True)

Return a dataset with impedance channels updated.

Parameters:

z_obj (Z or None, default=None) – Source Z object. If provided, array arguments are ignored.
z (numpy.ndarray or None, default=None) – Impedance array used when z_obj is not provided.
z_error (numpy.ndarray or None, default=None) – Impedance error array.
z_model_error (numpy.ndarray or None, default=None) – Impedance model-error array.
frequency (numpy.ndarray or None, default=None) – Frequency vector for array-mode input.
period (numpy.ndarray or None, default=None) – Period vector alternative to frequency.
units (str, default="mt") – Units for array-mode impedance input.
inplace (bool, default=False) – If True, mutate the bound dataset and return it.

Returns:

Updated dataset.

Return type:

xarray.Dataset

Raises:

ValueError – If input mode is ambiguous or insufficient.

Examples

>>> updated = ds.tf.with_z(z=new_z, frequency=freq)
>>> ds.tf.with_z(z_obj=z_obj, inplace=True)

z(units: str | None = None) → ndarray[source]

Return impedance tensor values.

Parameters:: units (str or None, default=None) – Output impedance units. If None, uses dataset attribute impedance_units (falling back to "mt").
Returns:: Complex impedance tensor array with shape (n_period, 2, 2).
Return type:: numpy.ndarray

z_error(units: str | None = None) → ndarray[source]

Return impedance standard-deviation errors.

Parameters:: units (str or None, default=None) – Output impedance units. If None, uses dataset attribute impedance_units.
Returns:: Impedance error array with shape (n_period, 2, 2).
Return type:: numpy.ndarray

z_model_error(units: str | None = None) → ndarray[source]

Return impedance model errors.

Parameters:: units (str or None, default=None) – Output impedance units. If None, uses dataset attribute impedance_units.
Returns:: Impedance model-error array with shape (n_period, 2, 2).
Return type:: numpy.ndarray

class mtpy.core.transfer_function.Tipper(tipper: ndarray | None = None, tipper_error: ndarray | None = None, frequency: ndarray | None = None, tipper_model_error: ndarray | None = None)[source]

Bases: TFBase

Tipper class.

Errors are given as standard deviations (sqrt(VAR)).

Parameters:

tipper (np.ndarray, optional) – Tipper array in the shape of [Tx, Ty] (nf, 1, 2), by default None
tipper_error (np.ndarray, optional) – Array of estimated tipper errors in the shape of [Tx, Ty] (nf, 1, 2), by default None
frequency (np.ndarray, optional) – Array of frequencies corresponding to the tipper elements (nf), by default None
tipper_model_error (np.ndarray, optional) – Array of model errors in the shape of [Tx, Ty] (nf, 1, 2), by default None

property amplitude: ndarray | None: Amplitude of tipper.

property amplitude_error: ndarray | None: Amplitude error.

property amplitude_model_error: ndarray | None: Amplitude model error.

property angle_error: ndarray | None: Angle error in degrees.

property angle_imag: ndarray | None: Angle of imaginary component in degrees.

property angle_model_error: ndarray | None: Angle model error in degrees.

property angle_real: ndarray | None: Angle of real component in degrees.

property mag_error: ndarray | None: Magnitude error.

property mag_imag: ndarray | None: Magnitude of imaginary component.

property mag_model_error: ndarray | None: Magnitude model error.

property mag_real: ndarray | None: Magnitude of real component.

property phase: ndarray | None: Phase of tipper in degrees.

property phase_error: ndarray | None: Phase error in degrees.

property phase_model_error: ndarray | None: Phase model error in degrees.

set_amp_phase(r: ndarray, phi: ndarray) → None[source]

Set values for amplitude (r) and phase (phi).

Parameters:

r (np.ndarray) – Amplitude array
phi (np.ndarray) – Phase array in degrees

Notes

Updates the attributes tipper and tipper_error.

set_mag_direction(mag_real: ndarray, ang_real: ndarray, mag_imag: ndarray, ang_imag: ndarray) → None[source]

Compute tipper from magnitude and direction of real and imaginary components.

Parameters:

mag_real (np.ndarray) – Magnitude of real component
ang_real (np.ndarray) – Angle of real component
mag_imag (np.ndarray) – Magnitude of imaginary component
ang_imag (np.ndarray) – Angle of imaginary component

Notes

Updates tipper. No error propagation yet.

property tipper: ndarray | None: Tipper array.

property tipper_error: ndarray | None: Tipper error.

property tipper_model_error: ndarray | None: Tipper model error.

class mtpy.core.transfer_function.Z(z: ndarray | None = None, z_error: ndarray | None = None, frequency: ndarray | None = None, z_model_error: ndarray | None = None, units: str = 'mt')[source]

Bases: TFBase

Impedance tensor (Z) class.

Z is a complex array of the form (n_frequency, 2, 2) with indices: - Zxx: (0,0) - Zxy: (0,1) - Zyx: (1,0) - Zyy: (1,1)

All errors are given as standard deviations (sqrt(VAR)).

Parameters:

z (np.ndarray, optional) – Array containing complex impedance values (n_frequency, 2, 2)
z_error (np.ndarray, optional) – Array containing error values (standard deviation) of impedance tensor elements (n_frequency, 2, 2)
frequency (np.ndarray, optional) – Array of frequency values corresponding to impedance tensor elements (n_frequency)
z_model_error (np.ndarray, optional) – Array containing model error values (n_frequency, 2, 2)
units (str, optional) – Units for impedance: ‘mt’ [mV/km/nT] or ‘ohm’ [Ohms], by default ‘mt’

property det: ndarray | None: Determinant of impedance.

property det_error: ndarray | None: Determinant of impedance error.

property det_model_error: ndarray | None: Determinant of impedance model error.

estimate_depth_of_investigation() → Any[source]

Estimate depth of investigation.

Returns:: Depth of investigation results
Return type:: Any

estimate_dimensionality(skew_threshold: float = 5, eccentricity_threshold: float = 0.1) → ndarray[source]

Estimate dimensionality of the impedance tensor.

Based on parameters such as strike and phase tensor eccentricity.

Parameters:

skew_threshold (float, optional) – Skew threshold for 3D determination, by default 5
eccentricity_threshold (float, optional) – Eccentricity threshold for 2D determination, by default 0.1

Returns:

Dimensionality array (1D, 2D, or 3D) for each period

Return type:

np.ndarray

estimate_distortion(n_frequencies: int | None = None, comp: str = 'det', only_2d: bool = False, clockwise: bool = True) → tuple[ndarray, ndarray][source]

Estimate distortion tensor.

Parameters:

n_frequencies (int, optional) – Number of frequencies to use, by default None (uses all)
comp (str, optional) – Component to use for estimation, by default ‘det’
only_2d (bool, optional) – Only use 2D data, by default False
clockwise (bool, optional) – Clockwise rotation, by default True

Returns:

Distortion tensor and distortion error tensor

Return type:

tuple of np.ndarray

property invariants: ZInvariants: Weaver invariants.

property phase: ndarray | None: Phase of impedance.

property phase_det: ndarray | None: Phase determinant.

property phase_error: ndarray | None

Phase error of impedance.

Uncertainty in phase (in degrees) is computed by defining a circle around the z vector in the complex plane. The uncertainty is the absolute angle between the vector to (x,y) and the vector between the origin and the tangent to the circle.

property phase_error_det: ndarray | None: Phase error determinant.

property phase_error_xx: ndarray | None: Phase error of xx component.

property phase_error_xy: ndarray | None: Phase error of xy component.

property phase_error_yx: ndarray | None: Phase error of yx component.

property phase_error_yy: ndarray | None: Phase error of yy component.

property phase_model_error: ndarray | None: Phase model error of impedance.

property phase_model_error_det: ndarray | None: Phase model error determinant.

property phase_model_error_xx: ndarray | None: Phase model error of xx component.

property phase_model_error_xy: ndarray | None: Phase model error of xy component.

property phase_model_error_yx: ndarray | None: Phase model error of yx component.

property phase_model_error_yy: ndarray | None: Phase model error of yy component.

property phase_tensor: PhaseTensor: Phase tensor object based on impedance.

property phase_xx: ndarray | None: Phase of xx component.

property phase_xy: ndarray | None: Phase of xy component.

property phase_yx: ndarray | None: Phase of yx component.

property phase_yy: ndarray | None: Phase of yy component.

remove_distortion(distortion_tensor: np.ndarray | None = None, distortion_error_tensor: np.ndarray | None = None, n_frequencies: int | None = None, comp: str = 'det', only_2d: bool = False, inplace: bool = False) → 'Z' | None[source]

Remove distortion D from observed impedance tensor Z.

Obtain the unperturbed “correct” Z0 from:: Z = D * Z0

Propagation of errors/uncertainties included.

Parameters:

distortion_tensor (np.ndarray, optional) – Real distortion tensor (2, 2), by default None
distortion_error_tensor (np.ndarray, optional) – Real distortion error tensor (2, 2), by default None
n_frequencies (int, optional) – Number of frequencies to use for estimation, by default None
comp (str, optional) – Component to use for estimation, by default ‘det’
only_2d (bool, optional) – Only use 2D data, by default False
inplace (bool, optional) – Update the current object or return a new impedance, by default False

Returns:

Impedance tensor with distortion removed if inplace is False, None otherwise

Return type:

Z or None

Remove static shift by providing correction factors.

Assume the original observed tensor Z is built by a static shift S and an unperturbed “correct” Z0:

Z = S * Z0

Therefore the correct Z will be:: Z0 = S^(-1) * Z

Parameters:

reduce_res_factor_x (float or array-like, optional) – Static shift factor to be applied to x components (z[:, 0, :]). Assumed to be in resistivity scale, by default 1.0
reduce_res_factor_y (float or array-like, optional) – Static shift factor to be applied to y components (z[:, 1, :]). Assumed to be in resistivity scale, by default 1.0
inplace (bool, optional) – Update the current object or return a new impedance, by default False

Returns:

Corrected Z if inplace is False, None otherwise

Return type:

Z or None

property res_det: ndarray | None: Resistivity determinant.

property res_error_det: ndarray | None: Resistivity error determinant.

property res_error_xx: ndarray | None: Resistivity error of xx component.

property res_error_xy: ndarray | None: Resistivity error of xy component.

property res_error_yx: ndarray | None: Resistivity error of yx component.

property res_error_yy: ndarray | None: Resistivity error of yy component.

property res_model_error_det: ndarray | None: Resistivity model error determinant.

property res_model_error_xx: ndarray | None: Resistivity model error of xx component.

property res_model_error_xy: ndarray | None: Resistivity model error of xy component.

property res_model_error_yx: ndarray | None: Resistivity model error of yx component.

property res_model_error_yy: ndarray | None: Resistivity model error of yy component.

property res_xx: ndarray | None: Resistivity of xx component.

property res_xy: ndarray | None: Resistivity of xy component.

property res_yx: ndarray | None: Resistivity of yx component.

property res_yy: ndarray | None: Resistivity of yy component.

property resistivity: ndarray | None: Resistivity of impedance.

property resistivity_error: ndarray | None

Resistivity error of impedance.

By standard error propagation, relative error in resistivity is 2 * relative error in z amplitude.

property resistivity_model_error: ndarray | None: Resistivity model error of impedance.

set_resistivity_phase(resistivity: ndarray, phase: ndarray, frequency: ndarray, res_error: ndarray | None = None, phase_error: ndarray | None = None, res_model_error: ndarray | None = None, phase_model_error: ndarray | None = None) → None[source]

Set values for resistivity and phase with error propagation.

Parameters:

resistivity (np.ndarray) – Resistivity array in Ohm-m (num_frequency, 2, 2)
phase (np.ndarray) – Phase array in degrees (num_frequency, 2, 2)
frequency (np.ndarray) – Frequency array in Hz (num_frequency)
res_error (np.ndarray, optional) – Resistivity error array in Ohm-m (num_frequency, 2, 2), by default None
phase_error (np.ndarray, optional) – Phase error array in degrees (num_frequency, 2, 2), by default None
res_model_error (np.ndarray, optional) – Resistivity model error array in Ohm-m (num_frequency, 2, 2), by default None
phase_model_error (np.ndarray, optional) – Phase model error array in degrees (num_frequency, 2, 2), by default None

property units: str: Impedance units.

property z: ndarray | None: Impedance tensor array (nfrequency, 2, 2).

property z_error: ndarray | None: Error of impedance tensor array as standard deviation.

property z_model_error: ndarray | None: Model error of impedance tensor array as standard deviation.