# Transfer-Function Dataset Accessor (ds.tf)

## Overview

MTpy-v2 stores every MT transfer function as an xarray.Dataset whose data variables (transfer_function, transfer_function_error, transfer_function_model_error) use labelled output, input, and period dimensions. The `tf` accessor is registered on every such dataset so that all derived quantities — impedance, phase tensor, tipper, and correction routines — are reachable through a single, discoverable entry point:

`python ds.tf.<property_or_method> `

The accessor is the single source of truth for transfer-function math. Both the MT object and the MTData collection delegate their core operations (rotate, interpolate, remove_static_shift, remove_distortion) to it.

—

## Architecture

``` xr.Dataset (period × output × input) │ └── .tf ← TFDatasetAccessor (registered via @xr.register_dataset_accessor)

│ ├── Data access │ z(), z_error(), z_model_error() │ tipper(), tipper_error(), tipper_model_error() │ ├── Derived Z quantities (properties, all lazy) │ resistivity, phase │ resistivity_error, phase_error │ resistivity_model_error, phase_model_error │ Per-component aliases: res_xx / res_xy / res_yx / res_yy │ phase_xx / phase_xy / phase_yx / phase_yy │ Determinant variants: det, res_det, phase_det (+ error counterparts) │ ├── Tipper quantities │ t_zx, t_zy (+ error variants) │ tipper_amplitude, tipper_phase, tipper_mag_real/imag, tipper_angle_real/imag │ ├── Phase tensor quantities │ pt_xx / pt_xy / pt_yx / pt_yy (+ error counterparts) │ pt_phimax / pt_phimin, pt_azimuth, pt_skew │ pt_ellipticity, pt_eccentricity, pt_trace, pt_det │ pt_alpha, pt_beta (+ all error counterparts) │ phase_tensor → PhaseTensor object │ invariants → dict of standard PT invariants │ ├── Object converters │ to_z() → Z │ to_tipper() → Tipper │ to_pt() → PhaseTensor │ ├── Builders (write back into the dataset) │ with_z(z_obj) → updates transfer_function* variables │ with_tipper(t_obj) → updates tipper channel block │ with_res_phase(…) → constructs Z from ρ/φ, then writes │ set_resistivity_phase(…) → alias │ set_amp_phase(…) → Tipper setter alias │ set_mag_direction(…) → Tipper setter alias │ ├── Operations (return new Dataset or modify in-place) │ rotate(alpha, coordinate_reference_frame=’ned’, inplace=False) │ interpolate(new_periods, method=’slinear’, inplace=False) │ └── Correction / analysis helpers

remove_ss(ss_x, ss_y, as_dataset=False) remove_distortion(distortion_tensor, as_dataset=False) estimate_dimensionality() estimate_distortion() estimate_depth_of_investigation()

```

### Where the math lives

All numerical formulas are collected in mtpy/core/transfer_function/tf_helpers.py. The legacy Z, Tipper, and PhaseTensor classes import from the same module, so there is exactly one implementation of every formula shared across the entire stack.

—

## Integration with MT and MTData

### MT

The MT object stores its transfer function as self._transfer_function (an xr.Dataset). The accessor is therefore always available as:

`python mt._transfer_function.tf `

The following MT methods delegate entirely to the accessor:

MT method | Accessor call |

|---|—| | mt.rotate(angle) | self._transfer_function.tf.rotate(angle, inplace=True) | | mt.interpolate(periods) | self._transfer_function.tf.interpolate(periods) | | mt.remove_static_shift(sx, sy) | self._transfer_function.tf.remove_ss(sx, sy, as_dataset=True) | | mt.remove_distortion(D) | self._transfer_function.tf.remove_distortion(D, as_dataset=True) |

### MTData

MTData is a tree-backed collection of MT stations stored as xr.Dataset nodes inside an xr.DataTree. The two per-station static helpers that were previously large self-contained routines now delegate to the accessor:

MTData helper | Accessor call |

|---|—| | _rotate_station_dataset(ds, angle, crf) | ds.load().tf.rotate(angle, coordinate_reference_frame=crf) | | _interpolate_station_dataset(ds, periods) | ds.tf.interpolate(periods) |

Bulk methods rotate(), interpolate(), rotate_dask(), interpolate_dask(), and interpolate_lazy() all flow through these helpers and therefore implicitly use the accessor.

—

## Usage Examples

### Accessing derived quantities

```python from mtpy import MT

mt = MT(“path/to/station.edi”) mt.read()

ds = mt._transfer_function # xr.Dataset

# Impedance tensor (complex, shape n_periods × 2 × 2) z_array = ds.tf.z()

# Apparent resistivity and phase (shape n_periods × 2 × 2) rho = ds.tf.resistivity phi = ds.tf.phase

# Off-diagonal components only rho_xy = ds.tf.res_xy # shape (n_periods,) phi_yx = ds.tf.phase_yx

# Determinant resistivity rho_det = ds.tf.res_det

# Phase tensor azimuth azimuth = ds.tf.pt_azimuth ```

### Converting to legacy objects

`python z_obj = ds.tf.to_z() # Z instance t_obj = ds.tf.to_tipper() # Tipper instance pt_obj = ds.tf.to_pt() # PhaseTensor instance `

### Rotating a dataset

```python # Returns a new dataset rotated 30 degrees clockwise (NED convention) rotated_ds = ds.tf.rotate(30)

# In-place rotation ds.tf.rotate(30, inplace=True) ```

### Interpolating to a new period grid

```python import numpy as np

new_periods = np.logspace(-3, 3, 50) interp_ds = ds.tf.interpolate(new_periods)

# The resulting dataset has len(new_periods) entries along the period axis print(interp_ds.tf.z().shape) # (50, 2, 2) ```

### Removing static shift and distortion

```python # Remove static shift: sx applied to Ex row, sy to Ey row corrected_ds = ds.tf.remove_ss(sx=0.8, sy=1.2, as_dataset=True)

# Remove a known distortion tensor import numpy as np D = np.array([[1.1, 0.05], [0.02, 0.95]]) undistorted_ds = ds.tf.remove_distortion(D, as_dataset=True) ```

### Updating impedance values (builder pattern)

```python from mtpy.core.transfer_function.z import Z

# Create or modify a Z object then write it back z_obj = ds.tf.to_z() z_obj.z[:, 0, 0] = 0.0 # zero out Zxx ds.tf.with_z(z_obj, inplace=True) ```

### Builder methods (with_*) end-to-end

```python import numpy as np

# Start from an existing station dataset ds = mt._transfer_function

# 1) Build/update impedance directly with with_z z_obj = ds.tf.to_z() z_obj.z[:, 0, 0] = np.nan # clear Zxx z_obj.z[:, 1, 1] = np.nan # clear Zyy ds1 = ds.tf.with_z(z_obj, inplace=False)

# 2) Build/update tipper directly with with_tipper t_obj = ds1.tf.to_tipper() t_obj.tipper[:, 0, 0] *= 0.95 t_obj.tipper[:, 0, 1] *= 1.05 ds2 = ds1.tf.with_tipper(t_obj, inplace=False)

# 3) Construct impedance from resistivity/phase with with_res_phase rho = ds2.tf.resistivity phi = ds2.tf.phase

# Example transformation: increase off-diagonal rho by 10% rho_mod = rho.copy() rho_mod[:, 0, 1] *= 1.10 rho_mod[:, 1, 0] *= 1.10

ds3 = ds2.tf.with_res_phase(: resistivity=rho_mod, phase=phi, period=ds2.period.values, inplace=False,

)

# Optional aliases (equivalent builder entry points) ds4 = ds3.tf.set_resistivity_phase(

resistivity=ds3.tf.resistivity, phase=ds3.tf.phase, period=ds3.period.values, inplace=False,

)

### Tipper builder aliases

```python # Set tipper from amplitude/phase amp = ds.tf.tipper_amplitude phs = ds.tf.tipper_phase ds_amp = ds.tf.set_amp_phase(amp, phs, inplace=False)

# Set tipper from magnitude/direction pairs mag_real = ds_amp.tf.tipper_mag_real ang_real = ds_amp.tf.tipper_angle_real mag_imag = ds_amp.tf.tipper_mag_imag ang_imag = ds_amp.tf.tipper_angle_imag ds_mag = ds_amp.tf.set_mag_direction(

mag_real, ang_real, mag_imag, ang_imag, inplace=False,

)

### Working via MT

The MT API is the recommended entry point for single-station workflows. All the above operations are available directly:

```python from mtpy import MT

mt = MT(“station.edi”) mt.read()

mt.rotate(30) # rotates in place mt.interpolate(np.logspace(-2, 2, 40)) # returns a new MT mt.remove_static_shift(ss_x=0.8, ss_y=1.2) mt.remove_distortion() ```

### Working via MTData

For multi-station workflows use MTData, which applies the same accessor operations to every station in the collection:

```python from mtpy.core import MTData

md = MTData() md.add_stations(mt_list)

# Rotate all stations by 15 degrees md.rotate(15)

# Interpolate all stations to a shared period grid periods = np.logspace(-3, 3, 60) md.interpolate(periods)

# Access the underlying xarray dataset for one station station_ds = md.get_station(“surveyA/st01”) print(station_ds.tf.res_xy) ```

—

## Testing

The accessor is covered by tests/core/transfer_function/test_tf_accessor.py (26+ test methods) and tests/core/test_mt.py::TestMTAccessorIntegration (14 tests verifying that MT methods correctly round-trip through the accessor).